FGShortRef.pdf describes the key bindings and has a
nice short description of controls for FGFS.

The HTML documentation is a copy of the official
manual. If you would like a nicely printed copy
it is available in PDF form at the the FGFS website

http://flightgear.org/Docs/InstallGuide/getstart.pdf

Configuring 3D Clouds
=====================

3D clouds can be created in two ways:
- By placing individual clouds using a command (e.g. from Nasal)
- Using the global weather function, which reads cloud definition from
  an XML file.

Placing Clouds Individually
===========================

Clouds are created using the "add-cloud" command, passing a property
node defining the location and characterstics of the cloud.

Location is defined by the following properties:

<layer>      - The cloud layer number to add the cloud to. (default 0)
<index>      - A unique identifier for the cloud in the layer. If a cloud
               already exists with this index, the new cloud will not be
               created, and 0 is returned.
<lon-deg>    - Longitude to place the cloud, in degrees (default 0)
<lat-deg>    - Latitude t place the cloud, in degrees (default 0)
<alt-ft>     - Altitude to place the cloud, relative to the layer (!) in ft
               (default 0)
<x-offset-m> - Offset in m from the lon-deg. +ve is south (default 0)
<y-offset-m> - Offset in m from the lat-deg. +ve is east (default 0)

The cloud itself is built up of a number of "sprites" - simple 2D textures
that are always rotated to be facing the viewer. These sprites are handled
by a OpenGL Shader - a small program that is run on your graphics card.

The cloud is defined by the following properties:

<min-cloud-width-m>   - minimum width of the cloud in meters (default 500)
<max-cloud-width-m>   - maximum width of the cloud (default min-cloud-width-m*1.5)
<min-cloud-height-m>  - minimum height of the cloud (default 400)
<max-cloud-height-m>  - maximum height of the cloud (default min-cloud-height-m*1.5)
<texture>             - texture file of sprites to use (default cl_cumulus.png)
<num-textures-x>      - number of cloud textures defined horizontally in the
                        texture file (default 4)
<num-textures-y>      - number of cloud textures defined vertically in the
                        texture file (default 4)
<height-map-texture>  - whether to choose the vertical texture index based on
                        sprite height within the clouds (default false)
<num-sprites>         - Number of sprite to generate for the cloud (default 20)
<min-sprite-width-m>  - minimum width of the sprites used to create the cloud
                        (default 200)
<max-sprite-width-m>  - maximum width of the sprites used to create the cloud
                        (default min-sprite-width-m*1.5)
<min-sprite-height-m> - minimum height of the spites used to create the cloud
                        (default 150)
<max-sprite-height-m> - maximum height of the sprites used to create the cloud
                        (default min-sprite-height-m*1.5)
<z-scale>             - vertical scaling factor to apply to to the sprite after
                        billboarding. A small value would create a sprite that
                        looks squashed when viewed from the side. (default 1.0)
<min-bottom-lighting-factor> - See Shading below (default 1.0)
<max-bottom-lighting-factor> - See Shading below (default min-...-factor + 0.1)
<min-middle-lighting-factor> - See Shading below (default 1.0)
<max-middle-lighting-factor> - See Shading below (default min-...-factor + 0.1)
<min-top-lighting-factor>    - See Shading below (default 1.0)
<max-top-lighting-factor>    - See Shading below (default min-...-factor + 0.1)
<min-shade-lighting-factor>  - See Shading below (default 0.5)
<max-shade-lighting-factor>  - See Shading below (default min-...-factor + 0.1)

Shading
-------

the [min|max]-...-lighting-factor properties allow you to define diffuse lighting
multipliers to the bottom, middle, top, sunny and shaded parts of the cloud. In
each case, individual clouds will have a random multiplier between the min and
max values used to allow for some variation between individual clouds.

The top, middle and bottom lighting factors are applied based on the pixels vertical
positon in the cloud. A linear interpolation is used either between top/middle (if
the pixel is above the middle of the cloud) or middle/bottom (if the pixel is below
the middle of the cloud).

The top factor is also applied to _all_ pixels on the sunny side of the cloud. The
shade factor is applied based on the pixel position away from the sun, linearly
interpolated from top to shade. E.g this is not a straight linear interpolation
from top to shade across the entire cloud.

The final lighting factor is determined by the minimum of the vertical factor and
the sunny/shade factor. Note that this is applied to the individual pixels, not
sprites.

Textures
--------

The texture to use for the sprites is defined in the <texture> tag.
To allow some variation, you can create a texture file containing multiple
sprites in a grid, and define the <num-textures-x/y> tags. The code
decides which texture to use for a given sprite : randomly in the x-direction
and based on the altitude of the sprite within the cloud in the y-direction
if <height-map-texture> is set. Therefore, you should put sprite textures
you want to use for the bottom of your cloud at the bottom of the texture
file, and those you want to use for the top of the cloud at the top of the
texture file.

For example, the following Nasal snippet will create a cloud immediately above the
aircraft at an altitude of 1000 ft above /environment/clouds/layer[0]/elevation-ft :

var p = props.Node.new({ "layer" : 0,
                         "index": 1,
                         "lat-deg": getprop("/position/latitude-deg"),
                         "lon-deg": getprop("/position/longitude-deg"),
                         "alt-ft" : 1000 });
fgcommand("add-cloud", p);

Moving Individual Clouds
========================

Clouds may be moved by using the "move-cloud" command. This takes the following
property arguments.

<layer>      - The cloud layer number containing the cloud to move. (default 0)
<index>      - The unique identifier of the cloud to move.
<lon-deg>    - Longitude to place the cloud, in degrees (default 0)
<lat-deg>    - Latitude t place the cloud, in degrees (default 0)
<alt-ft>     - Altitude to place the cloud, relative to the layer (!) in ft
               (default 0)
<x-offset-m> - Offset in m from the lon-deg. +ve is south (default 0)
<y-offset-m> - Offset in m from the lat-deg. +ve is east (default 0)

Deleting Individual Clouds
===========================

Clouds may be deleted by using the "del-cloud" command. This takes the following
property arguments.

<layer>      - The cloud layer number containing the cloud to delete. (default 0)
<index>      - The unique identifier of the cloud to delete.

Global 3D Clouds
================

The global weather system uses sets of clouds defined in
FG_ROOT/Environment/cloudlayers.xml

The file has 3 distinct sections: layers, cloud boxes and clouds,
described below.

Notes for those editing clouds:
- All distances are in m. Note that this is in contrast to cloud heights
  in METAR etc. which are in ft.
- The XML file is loaded into the properties system, so you can modify
  the settings in-sim, and see the results by re-generating the cloud
  layer. The simplest way to do this is to disable METAR, and control
  the cloud layers using the Clouds dialog, and in particular the coverage.
- Texture files are in .png format, and have a transparent background.
  To make the textures easier to edit, create a black layer behind them,
  so there is some contrast between the background and the white cloud.
  Having a grid based on the texture dimensions also helps, so you don't
  bleed over the edges, which causes ugly sharp horizontal and vertical
  lines.

Clouds
======

The cloud definitions are as described above for placing individual
clouds, but no position information is used (this is defined in the
cloud box and layers below).

Cloud Boxes
===========

The <boxes> section contains definitions of groups of cloads,for example
an entire towering CB mass.

The <boxes> section contains a number of named types, which are referenced
by the <layers> section, described below. Therefore, the names used are
completely user-defined.

Each of the named section consists of one or more <box> section,
defining a particular cloud type

Each <box> section contains the following tags:

<type>   - The cloud to use, defined above
<count>  - The number of clouds to generate (+/- 50%)
<width>  - The x and y within which these clouds should be generated
<height> - The height within which the clouds should be generated
<hdist>  - The horizontal distribution of the clouds within the area.
           Equates to a sum of random distributions. Defaults to 1.
           1 = even distribution, 2 = distributed towards the center.
           3 = very strongly distributed towards the center.
<vdist>  - The vertical distribution of the clouds. As for hdist.


If the  /sim/rendering/clouds3d-density is less than 1.0 (100%), then a
proportional number of clouds will be displayed.

The following example shows a stratus cloud group, which consists of 5
st-large clouds and 5 st-small clouds, distributed in a box 2000mx2000m,
and 100m high, evenly distributed.

    <st>
      <box>
        <type>st-large</type>
        <count>5</count>
        <width>2000</width>
        <height>100</height>
      </box>
      <box>
        <type>st-small</type>
        <count>5</count>
        <width>2000</width>
        <height>100</height>
      </box>
    </st>


Layers
======

The <layers> section contains definitions for a specific layer type.
The layer type is derived from the METAR/Weather settings by FG itself.

Each layer type is a named XML tag, i.e.: ns, sc, st, ac, cb, cu.
If a layer type is not defined, then a 2D layer is used instead.

The layer type contains one or more <cloud> definitions. This
defines a type of cloud box, and a weighting for that type (<count>).

For example, the following XML fragment will produce 3 "cb" cloud boxes
for every 1 "cu":

<cloud>
    <name>cb</name>
    <count>3</count>
</cloud>
<cloud>
    <name>cu</name>
    <count>1</count>
</cloud>

Clouds are randomly distributed across the sky in the x/y plane, but the
height of them is set by the weather conditions, with a random height range
applied, defined by <grid-z-rand>

This document describes how to invoke FlightGear's generic IO subsystem.

FlightGear has a fairly flexible generic IO subsystem that allows you
to "speak" any supported protocol over any supported medium.  The IO
options are configured at runtime via command line options.  You can
specify multiple entries if you like, one per command line option.


The general form of the command line option is as follows:

    --protocol=medium,direction,hz,medium_options,...

    protocol = { native, nmea, garmin, fgfs, rul, pve, ray, etc. }
    medium = { serial, socket, file, etc. }
    direction = { in, out, bi }
    hz = number of times to process channel per second (floating
         point values are ok.


Generic Communication:

    --generic=params

    With this option it is possible to output a pre-configured
    ASCII string or binary sequence  using a predefined separator.
    The configuration is defined in an XML file located in the
    Protocol directory of the base package.

    params can be:
    serial port communication:    serial,dir,hz,device,baud,protocol
    socket communication:         socket,dir,hz,machine,port,style,protocol
    i/o to a file:                file,dir,hz,filename,protocol

    See README.protocol for how to define a generic protocol.


Serial Port Communication:

    --nmea=serial,dir,hz,device,baud

    device = OS device name of serial line to be open()'ed
    baud = {300, 1200, 2400, ..., 230400}

    example to pretend we are a real gps and output to a moving map application:

    --nmea=serial,out,0.5,COM1,4800

    Note that for unix variants you might use a device name like "/dev/ttyS0"


Socket Communication:

    --native=socket,dir,hz,machine,port,style

    machine = machine name or ip address if client (leave empty if server)
    port = port, leave empty to let system choose
    style = tcp or udp

    example to slave one copy of fgfs to another

    fgfs1:  --native=socket,out,30,fgfs2,5500,udp
    fgfs2:  --native=socket,in,30,,5500,udp --fdm=external

    This instructs the first copy of fgfs to send UDP packets in the
    native format to a machine called fgfs2 on port 5500.

    The second copy of fgfs will accept UDP packets (from anywhere) on
    port 5500.  Note the additional --fdm=external option.  This tells
    the second copy of fgfs to not run the normal flight model, but
    instead set the FDM values based on an external source (the
    network in this case.)


File I/O:

    --garmin=file,dir,hz,filename

    filename = file system file name

    example to record a flight path at 10 hz:

    --native=file,out,10,flight1.fgfs

    example to replay your flight

    --native=file,in,10,flight1.fgfs --fdm=external

    You can make the replay from a file loop back to the beginning
    when it reaches the end of the file with the "repeat" flag:

    --generic=file,in,20,flight.out,playback,repeat

    With a numeric argument, FlightGear will exit after that number of repeats.
    --generic=file,in,20,flight.out,playback,repeat,5


Moving Map Example:

    Per Liedman has developed a moving map program called Atlas
    (atlas.sourceforge.net) The initial inspiration and much code came
    from Alexei Novikov.

    The moving map supports NMEA format input either via network or
    via serial port.  Either way will work, but this example
    demonstrates the use of a socket connection.

    Start up fgfs with:

        fgfs --nmea=socket,out,0.5,atas-host-name,5500,udp

    Start up the Atlas program with:

        Atlas --udp=5500 --fgroot=path-to-fg-root --glutfonts

    Once both programs are running, the Atlas program should display
    your current location.  Atlas is a really nifty program with many
    neat options such as the ability to generate and use background
    bitmaps that show the terrain, cities, lakes, oceans, rivers, etc.


HTTP Server Example

    You can now interact with a running copy of FlightGear using your
    web browser.  You can view all the key internal variables and even
    change the ones that are writable.  If you have support in your
    favorite [scripting] language for interacting with an http server,
    you should be able to use this as a mechanism to interface your
    script with FlightGear.

    Start up fgfs with the --httpd=<port#> option:

    For example:

        fgfs --httpd=5500

    Now point your web browser to:

        http://host.domain.name:5500/

    When a value is displayed, you can click on it to bring up a form
    to assign it a new value.


ACMS flight data recorder playback

  fgfs --fdm=acms --generic=file,in,1,<path_to_replay_file>,acms

JSBSim

JSBSim is an ongoing attempt at producing an OO Flight Dynamics Model
(FDM) to replace LaRCsim as the default FDM for FlightGear. It can
also be used standalone.

JSBSim uses config files to represent aircraft, engines, propellers,
etc. Also, the flight control system is described in the config
file. Normally, for use with FlightGear, the config files are named
this way [case is significant]:

<FG_ROOT>/Aircraft/<aircraft name>/<aircraft name>.xml

Engines are named like this:

<FG_ROOT>/Engines/<engine name>.xml

Aircraft and engine config files are present in the FGFS Base package
which must be downloaded. See the FlightGear web site for more
information.

How to run FGFS using JSBSim

All the various FDMs are currently compiled into FGFS. You can specify
which FDM you want at run time. You can also specify which aircraft
you want. Currently, for JSBSim only the X-15 and C-172 aircraft are
available. Here is an example command line used to start up FlightGear
using JSBSim as the FDM:

fgfs --fdm=jsb --aircraft=X15 --units-feet --altitude=60000 --uBody=2000 --wBody=120

or,

fgfs --fdm=jsb --aircraft=c172

[Note: uBody is the forward velocity of the aircraft, wBody is the
downward velocity - from the aircraft point of view. This essentially
means that the aircraft is going forward fast and has an angle of
attack of about 4 degrees or so]

The first command line sets up the initial velocity and altitude to
allow the X15 to glide down. Note that if you fire up the engine, it
will burn for only about two minutes and then run out of fuel - but
you will go very, very fast! The second command line example will
start up the C172 on the end of the runway.

Check out the JSBSim home page at http://jsbsim.sf.net. Please report
any bugs to jsb@hal-pc.org, or apeden@earthlink.net, or post on the
jsbsim web site using the SourceForge bug tracking system for the
project.

JSBSim is written by Jon S. Berndt and Tony Peden with contributions
by other FlightGear programmers, as well.

Replaced by Docs/README.Joystick.html in the base package.

-*- coding: utf-8; fill-column: 72; -*-

Add-ons in FlightGear
=====================

This document explains how add-ons work in FlightGear. The add-on
feature was first added in FlightGear 2017.3. This document describes an
evolution of the framework that appeared in FlightGear 2017.4.


Contents
--------

1. Terminology

2. The addon-metadata.xml file

3. Add-ons and the Property Tree

   a) Add-on metadata
   b) Subtree reserved for add-on developers

4. Resources under the add-on directory

5. Persistent storage location for add-ons

6. Add-on-specific menus and dialogs

   a) Add-on-specific menus
   b) Add-on-specific dialogs

7. How to run code after an add-on is loaded

8. Overview of the C++ API

9. Nasal API

10. Add-on development; in-sim reload of Nasal code


Introduction
------------

fgfs can be passed the --addon=<path> option, where <path> indicates an
add-on directory. Such a directory, when used as the argument of
--addon, receives special treatment :

  1) The add-on directory is added to the list of aircraft paths.

  2) The add-on directory must contain a PropertyList file called
     addon-metadata.xml that gives the name of the add-on, its
     identifier (id), its version and possibly a few other things (see
     details below).

  3) The add-on directory may contain a PropertyList file called
     addon-config.xml, in which case it will be loaded into the Property
     Tree at FlightGear startup, as if it were passed to the --config
     fgfs option.

  4) The add-on directory must contain a Nasal file called
     addon-main.nas. This file will be loaded at startup too, and its
     main() function run in the namespace __addon[ADDON_ID]__, where
     ADDON_ID is the add-on identifier specified in the
     addon-metadata.xml file. The main() function is passed one
     argument: the addons.Addon object (a Nasal ghost, see below)
     corresponding to the add-on being loaded. This operation is done by
     $FG_ROOT/Nasal/addons.nas at the time of this writing.

Also, the Property Tree is populated (under /addons) with information
about registered add-ons. More details will be given below.

The --addon option can be specified zero or more times; each of the
operations indicated above is carried out for every specified add-on in
the order given by the --addon options used: that's what we call add-on
registration order, or add-on load order. In other words, add-ons are
registered and loaded in the order specified by the --addon options
used.


1. Terminology
   ~~~~~~~~~~~

add-on base path

  Path to a directory containing all of the add-on files. This is the
  path passed to the --addon fgfs option, when one wants to load the
  add-on in question.

add-on identifier (id)

  A string such as org.flightgear.addons.ATCChatter or
  user.joe.MyGreatAddon, used to uniquely identify an add-on. The add-on
  identifier is declared in <path>/addon-metadata.xml, where <path> is
  the add-on base path.

add-on registration

  When a --addon option is processed, FlightGear ensures that the add-on
  identifier found in the corresponding addon-metadata.xml file isn't
  already used by an add-on from a previous --addon option on the same
  command line, and stores the add-on metadata inside dedicated C++
  objects. This process is called add-on registration.

add-on loading

  The following sequence of actions:

    a) loading an add-on's addon-main.nas file in the namespace
       __addon[ADDON_ID]__
    b) calling its main() function

  is performed later (see $FG_ROOT/Nasal/addons.nas) and called add-on
  loading.


2. The addon-metadata.xml file
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~

Every add-on must have in its base directory a file called
'addon-metadata.xml'. This section explains how to write this file.

Sample addon-metadata.xml file
==============================

Here is an example of an addon-metadata.xml file, for a hypothetical
add-on called “Flying Turtle” distributed by Joe User:

  <?xml version="1.0" encoding="UTF-8"?>

  <PropertyList>
    <meta>
      <file-type type="string">FlightGear add-on metadata</file-type>
      <format-version type="int">1</format-version>
    </meta>

    <addon>
      <identifier type="string">user.joe.FlyingTurtle</identifier>
      <name type="string">Flying Turtle</name>
      <version type="string">1.0.0rc2</version>

      <authors>
        <author>
          <name type="string">Joe User</name>
          <email type="string">optional_address@example.com</email>
          <url type="string">http://joe.example.com/foobar/</url>
        </author>

        <author>
          <name type="string">Jane Maintainer</name>
          <email type="string">jane@example.com</email>
          <url type="string">https://jane.example.com/</url>
        </author>
      </authors>

      <maintainers>
        <maintainer>
          <name type="string">Jane Maintainer</name>
          <email type="string">jane@example.com</email>
          <url type="string">https://jane.example.com/</url>
        </maintainer>
      </maintainers>

      <short-description type="string">
        Allow flying with new foobar powers.
      </short-description>

      <long-description type="string">
        This add-on enables something really great involving turtles...
      </long-description>

      <localized>
        <fr>
          <short-description type="string">
            Permet de voler avec de nouveaux pouvoirs foobar.
          </short-description>
          <name>
          Tortue volante
          </name>
        </fr>
        <de>
        <short-description type="string">
         Erlaube das Fliegen mit neuen Foobar-Kräften.
          </short-description>
        </de>
      </localized>

      <license>
        <designation type="string">
          GNU GPL version 2 or later
        </designation>

        <file type="string">
          COPYING
        </file>

        <url type="string">
          https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html
        </url>
      </license>

      <min-FG-version type="string">2017.4.0</min-FG-version>
      <max-FG-version type="string">none</max-FG-version>

      <urls>
        <home-page type="string">
          https://example.com/quux
        </home-page>

        <download type="string">
          https://example.com/quux/download
        </download>

        <support type="string">
          https://example.com/quux/support
        </support>

        <code-repository type="string">
          https://example.com/quux/code-repository
        </code-repository>
      </urls>

      <tags>
        <tag type="string">first tag</tag>
        <tag type="string">second tag</tag>
        <tag type="string">etc.</tag>
      </tags>
    </addon>
  </PropertyList>

General rules
=============

We use the terms “field” or “node” interchangeably here to refer to
nodes of the addon-metadata.xml PropertyList file (technically, a field
always has a value, possibly empty, therefore fields are all leaf
nodes).

Leading and trailing whitespace in each field of addon-metadata.xml is
removed. All other whitespace is a priori preserved (this could depend
on the particular field, though).

Most fields are optional. In most cases, omitting a field is the same as
leaving it empty. But don't write empty tag fields, it is really too
ugly. ;-)

Name and id
===========

Nodes: /addon/name and /addon/identifier

The add-on name is the pretty form. It should not be overly long, but
otherwise isn't constrained. On the other hand, the add-on identifier
(id), which serves to uniquely identify an add-on:
  - must contain only ASCII letters (A-Z, a-z) and dots ('.');
  - must be in reverse DNS style (even if the domain doesn't exist),
    e.g., org.flightgear.addons.ATCChatter for an add-on distributed in
    FGAddon, or user.joe.FlyingTurtle for Joe User's “Flying Turtle”
    add-on. Of course, if Joe User owns a domain name and uses it to
    distribute his add-on, he should put it here.

Authors and maintainers
=======================

Nodes: /addon/authors and /addon/maintainers

Authors are people who contributed significantly to the add-on.
Maintainers are people currently in charge of maintaining it.

It is possible to declare any number of authors and any number of
maintainers---the example above shows only one maintainer for shortness,
but this is not a restriction.

For each author and maintainer, you can give a name, an email address
and a URL. The name must be non-empty, but the email address and URL
need not be specified or may be left empty, which is equivalent.
Obviously, if no email address nor URL is given for any maintainer, it
is highly desirable that /addon/urls/support contains a usable URL for
contacting the add-on maintainers.

The data in children nodes of /addon/maintainers may refer either to
real persons or to more abstract entities such as mailing-lists. In case
of a real person, the corresponding URL, if specified, is expected to be
the person's home page. On the other hand, if a declared “maintainer” is
a mailing-list, a good use for the 'url' field is to indicate the
address of a web page from which people can subscribe to the
mailing-list.

Short and long descriptions
===========================

Nodes: /addon/short-description and /addon/long-description

The short description should fit on one line (try not to exceed, say, 78
characters), and in general consist of only one sentence.

The long description is essentially free-form, but only break lines when
you do want a line break at this point. In other words, don't wrap lines
manually in the XML file: this will be automatically done by the
software displaying the add-on description, according to the particular
line width it uses (which can depend on the user's screen or
configuration, etc.). A single \n inside a paragraph (see footnote [1])
means a hard line break. Two \n in a row (i.e., a blank line) should be
used to separate paragraphs. Example:

This is a paragraph.
This is the second line of the same paragraph. It can be very, very, very long and contain several sentences.

This is a different paragraph. Again, don't break lines (i.e., don't press Enter) unless a particular formatting reason makes it necessary. For instance, it is okay to break lines in order to present a list of items, but not for line wrapping.

Licensing terms
===============

Nodes: /addon/license/designation
       /addon/license/file
       /addon/license/url

The /add-on/license/designation node should describe the add-on
licensing terms in a short but accurate way, if possible. If this is not
practically doable, use the value “Custom”. If the add-on is distributed
under several licenses, use the value “Multiple”. In all cases, make
sure the licensing terms are clearly specified in other files of the
add-on (typically, at least README.txt or COPYING). Values for
/add-on/license/designation could be “GNU GPL version 2 or later”, “CC0
1.0 Universal”, “3-clause BSD”, etc.

In most cases, the add-on should contain a file containing the full
license text. Use the /add-on/license/file node to point to this file:
it should contain a file path that is relative to the add-on base
directory. This path must use slash separators ('/'), even if you use
Windows.

The /add-on/license/url node should contain a single URL if there is an
official, stable URL for the license under which the add-on is
distributed. The term “official” here is to be interpreted in the
context of the particular license. For instance, for a GNU license
(GPL2, LGPL2.1, etc.), the URL domain must be gnu.org; for a CC license
(CC0 1.0 Universal, CC-BY-SA 4.0...), it must be creativecommons.org,
etc.

Minimum and maximum FlightGear versions
=======================================

Nodes: /addon/min-FG-version and /addon/max-FG-version

These two nodes are optional and may be omitted unless the add-on is
known not to work with particular FlightGear versions.
/addon/min-FG-version defaults to 2017.4.0 and /addon/max-FG-version to
the special value 'none' (only allowed for /addon/max-FG-version). Apart
from this special case, every non-empty value present in one of these
two fields must be a proper FlightGear version number usable with
simgear::strutils::compare_versions(), for instance '2017.4.1'.

Add-on version
==============

Node: /addon/version

The /addon/version node gives the version of the add-on and must obey a
strict syntax[2], which is a subset of what is described in PEP 440:

  https://www.python.org/dev/peps/pep-0440/

Valid examples are, in increasing sort order:

  1.2.5.dev1      # first development release of 1.2.5
  1.2.5.dev4      # fourth development release of 1.2.5
  1.2.5
  1.2.9
  1.2.10a1.dev2   # second dev release of the first alpha release of 1.2.10
  1.2.10a1        # first alpha release of 1.2.10
  1.2.10b5        # fifth beta release of 1.2.10
  1.2.10rc12      # twelfth release candidate for 1.2.10
  1.2.10
  1.3.0
  2017.4.12a2
  2017.4.12b1
  2017.4.12rc1
  2017.4.12

.devN suffixes can of course be used on beta and release candidates too,
just as with the 1.2.10a1.dev2 example given above for an alpha release.
Note that a development release always sorts before the corresponding
non-development release (e.g., 2017.2.1b5.dev4 comes before 2017.2.1b5).

Translations
============

Certain nodes can be translated based on the active languages within FlightGear.
Especially, the name and descriptions can be translated, by adding them to
a language node beneath 'localized', as show in the example above. Where there is
no translation for a particular value, the default one is used.

Other fields
============

The other nodes of 'addon-metadata.xml' should be self-explanatory. :-)


3. Add-ons and the Property Tree
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

a) Add-on metadata
   ^^^^^^^^^^^^^^^

The most important metadata for each registered add-on is made
accessible in the Property Tree under /addons/by-id/ADDON_ID and the
property /addons/by-id/ADDON_ID/loaded can be checked or listened to, in
order to determine when a particular add-on is loaded. There is also a
Nasal interface to access add-on metadata in a convenient way (see
below).

More precisely, when an add-on is registered, its name, id, base path,
version (converted to a string), loaded status (boolean) and load
sequence number (int) become available in the Property Tree as
/addons/by-id/ADDON_ID/{name,id,path,version,loaded,load-seq-num}. The
loaded status is initially false, and set to true when the add-on
loading phase is complete.

There are also /addons/addon[i]/path nodes where i is 0 for the first
registered add-on, 1 for the second one, etc.


b) Subtree reserved for add-on developers
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For each add-on, the subtree of the global Property Tree starting at
/addons/by-id/ADDON_ID/addon-devel is reserved for the specific needs of
the add-on, where ADDON_ID stands for the add-on identifier. For
instance, developers of the add-on whose identifier is
user.joe.FlyingTurtle can store whatever they want under
/addons/by-id/user.joe.FlyingTurtle/addon-devel with the assurance that
doing this won't clash with properties used by the add-on framework.

Example:

  /addons/by-id/user.joe.FlyingTurtle/addon-devel/some/property and
  /addons/by-id/user.joe.FlyingTurtle/addon-devel/other/property

  could be two properties used for the specific needs of the
  add-on whose identifier is user.joe.FlyingTurtle.

Add-on developers should *not* use other places in the /addons subtree
of the Property Tree for their custom properties.


4. Resources under the add-on directory
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Many functions in FlightGear use files that are located using the
SimGear ResourceManager class. This class allows one to point to files
by relative path in aircraft source files and other places. The resource
manager queries a set of providers, some of which look inside aircraft
paths (starting with the current aircraft), others inside scenery paths,
others under $FG_ROOT, etc. The first file that matches the specified
resource path is used.

One of these providers only handles resource paths with a very specific
syntax, which is:

  [addon=ADDON_ID]path/relative/to/the/addon/directory

  (for instance, [addon=user.joe.FlyingTurtle]images/eject-button.png)

When you use such a syntax in a place that is expected to contain a
resource path, it will only find the specified file under the directory
of the add-on whose identifier is ADDON_ID. This allows one to
specifically target a particular file inside a particular add-on,
instead of crossing fingers and hoping that the specified resource won't
be found by coincidence in another place such as an aircraft directory,
a scenery directory or inside $FG_ROOT (such mistakes can easily happen
when unrelated places use files with rather generic names, such as
button.png, system.xml, etc.).

The [addon=ADDON_ID]relative/path syntax is useful where resources are
specified inside non-Nasal files (e.g., in property-rule configuration
files, which use the XML format). For the particular case of Nasal code,
there is a better way that is explained below (see “Nasal API”): the
resourcePath() method of addons.Addon objects returns a string like
"[addon=ADDON_ID]relative/path" when you pass it the string
"relative/path". This is a good thing to use, because then your Nasal
code doesn't need to know about the particular syntax for
add-on-specific resources and, more interestingly, doesn't have to
hardcode the add-on identifier every time you need to access a resource
inside the add-on directory.

4.1 Resources extending $FG_ROOT
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Add-ons can options supply a special sub-directory which is searched when
FlightGear looks for files normally residing in $FG_ROOT. For example input
configurations, network protocols and other non-aircraft resources. Since
these files cannot use the scheme above, a different approach is used. If
an add-on defines a subdirectory called 'FGData', this is becomes an
additional data directory to be searched for any such standard files. For
security reasons, add-on FGData extensions are searched after the main
$FG_ROOT location, so that an addon cannot maliciously replace a core resource.

Only some files currently support being added via this mechanism, so if you
find a non-working case which would be useful, please request it via the
developer mailing list.


5. Persistent storage location for add-ons
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If an add-on needs to store data that persists across FlightGear
sessions, it can use a specific directory tree whose path is obtained
with addon.storagePath, where 'addon' is an addons.Addon instance. This
corresponds to $FG_HOME/Export/Addons/ADDON_ID, however it is simpler
and better to use addon.storagePath instead of hardcoding and manually
assembling this path in each add-on. Since the directory is likely not
to exist until the add-on creates it, the recommended usage pattern is
the following:

  1) Create the add-on-specific storage directory if it doesn't already
     exist, and optionally get its path at the same time:

       storageDir = addon.createStorageDir();

     Typically, you'll run this in the add-on main() function (at least,
     early enough) if your add-on uses the storage directory. Note that
     there is no need to check yourself whether the directory already
     exists: addon.createStorageDir() does that for you.

  2) At any time, you can get a path to the add-on-specific storage
     directory with:

       storageDir = addon.storagePath

     Accessing addon.storagePath doesn't check for the existence nor the
     type of $FG_HOME/Export/Addons/ADDON_ID, thus it is a bit faster
     than addon.createStorageDir(). Use addon.storagePath whenever you
     know that the directory has already been created.

The features described in this section were added in FlightGear 2018.2.


6. Add-on-specific menus and dialogs
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

a) Add-on-specific menus
   ^^^^^^^^^^^^^^^^^^^^^

Add-ons can easily provide their own menus. If an add-on is loaded that
has a file named 'addon-menubar-items.xml' in its base directory, the
menus described in this file are added to the FlightGear menu bar. The
file should look like this:

<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>
  <meta>
    <file-type type="string">FlightGear add-on menu bar items</file-type>
    <format-version type="int">1</format-version>
  </meta>

  <menubar-items>
    <menu>
      ...
    </menu>

    ...

    <menu>
      ...
    </menu>
  </menubar-items>
</PropertyList>

In this file, each <menu> element must be a valid menu description for
the FlightGear menu system (the FlightGear standard menubar in
$FG_ROOT/gui/menubar.xml provides good examples). Here is an example
that adds one menu with an entry for running some Nasal code and another
entry for opening a custom dialog (see below for add-on-specific dialogs):

    <menu>
      <label>My Menu</label>
      <enabled type="bool">true</enabled>

      <item>
        <label>Run Foobar Nasal</label>
        <binding>
          <command>nasal</command>
          <script>foobar.doBaz();</script>
        </binding>
      </item>

      <item>
        <label>My Foobar Dialog</label>
        <binding>
          <command>dialog-show</command>
          <dialog-name>my-foobar-dialog</dialog-name>
        </binding>
      </item>
    </menu>

This feature was added in FlightGear 2018.2.

  For older versions, one can add menus via addon-config.xml, but it's a
  bit hackish because of the menu index problem.


b) Add-on-specific dialogs
   ^^^^^^^^^^^^^^^^^^^^^^^

As is the case for aircraft, add-ons can provide their own dialogs by
shipping the corresponding XML files in the subfolder gui/dialogs of the
add-on base directory. In other words, with a file like

  <addon-base-path>/gui/dialogs/my-foobar-dialog.xml

starting with:

  <?xml version="1.0" encoding="UTF-8"?>
  <PropertyList>
    <name>my-foobar-dialog</name>

  ...

the following <item> element inside 'addon-menubar-items.xml' (see
above) describes a valid menu entry for showing the custom dialog.

      <item>
        <label>My Foobar Dialog</label>
        <binding>
          <command>dialog-show</command>
          <dialog-name>my-foobar-dialog</dialog-name>
        </binding>
      </item>

See $FG_ROOT/gui/dialogs to get inspiration from FlightGear's standard
dialogs.

This feature was added in FlightGear 2018.2.


7. How to run code after an add-on is loaded
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You may want to set up Nasal code to be run after an add-on is loaded;
here is how to do that:

  var addonId = "user.joe.FlyingTurtle";
  var loadedFlagNode = props.globals.getNode("/addons")
                                    .getChild("by-id", 0, 1)
                                    .getChild(addonId, 0, 1)
                                    .getChild("loaded", 0, 1);

  if (loadedFlagNode.getBoolValue()) {
    logprint(5, addonId ~ " is already loaded");
  } else {
    # Define a function to be called after the add-on is loaded
    var id = setlistener(
      loadedFlagNode,
      func(changedNode, listenedNode) {
        if (listenedNode.getBoolValue()) {
          removelistener(id);
          logprint(5, addonId ~ " is loaded");
        };
      },
      0, 0);
  }


8. Overview of the C++ API
   ~~~~~~~~~~~~~~~~~~~~~~~

The add-on C++ infrastructure mainly relies on the following classes:
AddonManager, Addon and AddonVersion. AddonManager is used to register
add-ons, which later leads to their loading. AddonManager relies on an
std::map<std::string, AddonRef>, where keys are add-on identifiers and
AddonRef is SGSharedPtr<Addon> at the time of this writing (changing it
to another kind of smart pointer should be a mere one-line change). This
map holds the metadata of each registered add-on. Accessor methods are
available for:

  - retrieving the lists of registered and loaded add-ons;

  - checking if a particular add-on has already been registered or
    loaded;

  - for each add-on, obtaining an Addon instance which can be queried
    for its identifier, its name, identifier, version, base path, the
    minimum and maximum FlightGear versions it requires, its base node
    in the Property Tree, its order in the load sequence...

The AddonVersion class handles everything about add-on version numbers:
  - initialization from the individual components or from a string;
  - conversion to a string and output to an std::ostream;
  - access to every component;
  - comparisons using the standard operators: ==, !=, <, <=, >, >=.

Registering an add-on using AddonManager::registerAddon() ensures
uniqueness of the add-on identifier and makes its name, identifier, base
path, version (converted to a string), loaded status (boolean) and load
sequence number (int) available in the Property Tree as
/addons/by-id/ADDON_ID/{name,id,path,version,loaded,load-seq-num}.

Note: if C++ code needs to use the add-on base path, better use
      AddonManager::addonBasePath() or Addon::getBasePath(), whose
      return values can't be tampered with by Nasal code.

AddonManager::registerAddon() fails with a specific exception if the
running FlightGear instance doesn't match the min-FG-version and
max-FG-version requirements declared in the addon-metadata.xml file, as
well as in the obvious other cases (required files such as
addon-metadata.xml not found, invalid syntax in such files, etc.). The
code in options.cxx (fgOptAddon()) catches such exceptions and displays
the appropriate error message with SG_LOG() and
fatalMessageBoxThenExit().


9. Nasal API
   ~~~~~~~~~

The Nasal add-on API all lives in the 'addons' namespace. It gives Nasal
code easy access to add-on metadata, for instance like this:

  var myAddon = addons.getAddon("user.joe.FlyingTurtle");
  print(myAddon.id);
  print(myAddon.name);
  print(myAddon.version.str());

  foreach (var author; myAddon.authors) {
    print(author.name, " ", author.email, " ", author.url);
  }

  foreach (var maintainer; myAddon.maintainers) {
    print(maintainer.name, " ", maintainer.email, " ", maintainer.url);
  }

  print(myAddon.shortDescription);
  print(myAddon.longDescription);
  print(myAddon.licenseDesignation);
  print(myAddon.licenseFile);
  print(myAddon.licenseUrl);
  print(myAddon.basePath);
  print(myAddon.minFGVersionRequired);
  print(myAddon.maxFGVersionRequired);
  print(myAddon.homePage);
  print(myAddon.downloadUrl);
  print(myAddon.supportUrl);
  print(myAddon.codeRepositoryUrl);

  foreach (var tag; myAddon.tags) {
    print(tag);
  }

  print(myAddon.loadSequenceNumber);
  # myAddon.node is a props.Node object for /addons/by-id/ADDON_ID
  print(myAddon.node.getPath());

Among other things, the Nasal add-on API allows one to get the version
of any registered add-on as a ghost and reliably compare it to another
instance of addons.AddonVersion:

  var myAddon = addons.getAddon("user.joe.FlyingTurtle");
  var firstVersionOK = addons.AddonVersion.new("2.12.5rc1");
  # Or alternatively:
  #   var firstVersionOK = addons.AddonVersion.new(2, 12, 5, "rc1");

  if (myAddon.version.lowerThan(firstVersionOK)) {
    ...

Here follows the complete Nasal add-on API, at the time of this writing.
All strings are encoded in UTF-8.

Queries to the AddonManager:

  addons.isAddonRegistered(string addonId) -> bool (1 or 0)
  addons.registeredAddons()                -> vector<addons.Addon>
                                              (in registration/load order)
  addons.isAddonLoaded(string addonId)     -> bool (1 or 0)
  addons.loadedAddons()                    -> vector<addons.Addon>
                                              (in lexicographic order)
  addons.getAddon(string addonId)          -> addons.Addon instance (ghost)

Read-only data members (attributes) of addons.Addon objects:

  id                    the add-on identifier, in reverse DNS style (string)
  name                  the add-on “pretty name” (string)
  version               the add-on version (instance of addons.AddonVersion,
                        ghost)
  authors               the add-on authors (vector of addons.Author ghosts)
  maintainers           the add-on maintainers (vector of addons.Maintainer
                        ghosts)
  shortDescription      the add-on short description (string)
  longDescription       the add-on long description (string)
  licenseDesignation    licensing terms: "GNU GPL version 2 or later",
                        "CC0 1.0 Universal", etc. (string)
  licenseFile           relative, slash-separated path to a file under
                        the add-on base directory containing the license
                        text (string)
  licenseUrl            stable, official URL for the add-on license text
                        (string)
  basePath              path to the add-on base directory (string)
  storagePath           path to the add-on storage directory (string)
                        This is $FG_HOME/Export/Addons/ADDON_ID.
                        [added in FlightGear 2018.2]
  minFGVersionRequired  minimum required FG version for the add-on (string)
  maxFGVersionRequired  max. required FG version... or "none" (string)
  homePage              add-on home page (string)
  downloadUrl           add-on download URL (string)
  supportUrl            add-on support URL (string)
  codeRepositoryUrl     URL pointing to the development repository of
                        the add-on (Git, Subversion, etc.; string)
  tags                  vector containing the add-on tags used to help
                        users find add-ons (vector of strings)
  node                  base node for the add-on in the Property Tree:
                        /addons/by-id/ADDON_ID (props.Node object)
  loadSequenceNumber    0 for the first registered add-on, 1 for the
                        second one, etc. (integer)

Member functions (methods) of addons.Addon objects:

  createStorageDir() -> string
                        Create the add-on storage directory if it
                        doesn't already exist (that is,
                        $FG_HOME/Export/Addons/ADDON_ID). Return its
                        path as a string.
                        [added in FlightGear 2018.2]
  resourcePath(string relPath) -> string
                        Return a resource path suitable for use with the
                        simgear::ResourceManager. 'relPath' must be
                        relative to the add-on base directory, and
                        mustn't start with a '/'. You can use this
                        method for instance to specify an image file for
                        display in a Canvas widget.

                        In you want a full path to the resource file
                        (e.g., for troubleshooting), call resolvepath()
                        with the return value of addons.Addon.resourcePath().

Read-only data members (attributes) of addons.AddonVersion objects:

  majorNumber           non-negative integer
  minorNumber           non-negative integer
  patchLevel            non-negative integer
  suffix                string such as "", "a1", "b2.dev45", "rc12"...

Member functions (methods) of addons.AddonVersion objects:

  new(string version)                           | construct from string

  new(int major, int minor=0, int patchLevel=0, | construct
      string suffix="")                         | from components

  str()                                         | string representation

  equal(addons.AddonVersion other)              |
  nonEqual(addons.AddonVersion other)           | compare to another
  lowerThan(addons.AddonVersion other)          | addons.AddonVersion
  lowerThanOrEqual(addons.AddonVersion other)   | instance
  greaterThan(addons.AddonVersion other)        |
  greaterThanOrEqual(addons.AddonVersion other) |

Read-only data members (attributes) of addons.Author objects:

  name                  author name (non-empty string)
  email                 email address of the author (string)
  url                   home page of the author (string)

Read-only data members (attributes) of addons.Maintainer objects:

  name                  maintainer name (non-empty string)
  email                 email address of the maintainer (string)
  url                   home page of the maintainer, if a person; if the
                        maintainer is a mailing-list, the URL can point
                        to a web page from which people can subscribe to
                        that mailing-list (string)


10. Add-on development; in-sim reload of Nasal code
---------------------------------------------------

!!! WARNING:
!!! The reload feature is meant for developers only, it should not be made
!!! visible to end users. Unexpected side effects may occur due to reload,
!!! if not implemented correctly.
!!! We really don't want users to send bug reports due to reload going wrong.

To make development of add-ons less time consuming, you can reload the
Nasal part of your add-on without having to restart FlightGear. When an
add-on is loaded, setlistener() and maketimer() wrappers are installed
in the add-on's own namespace; these wrappers shadow and call themselves
the standard setlistener() and maketimer() functions. The setlistener()
and maketimer() wrapper functions keep track of every listener and timer
they create. When the add-on is removed (e.g., as part of its reload
sequence), removelistener() is called for each of these listeners, and
each timer has its stop() method called.
_
For the time being, you have to track any other resources outside the
namespace of your add-on by yourself and clean them up in the unload()
function, e.g. delete canvas or close any files you opened.

You can define this unload() function in the addon-main.nas file. When
your add-on is reloaded, its unload() function, if defined, will be
called with one argument: the addons.Addon object (a Nasal ghost)
corresponding to your add-on. unload() is run in the add-on's own
namespace.

In FlightGear Versions before 2020.1 the reload is triggered by setting the
property /addon/by-id/ADDON_ID/reload to true (replace ADDON_ID with your
particular add-on identifier).

!!! Since version 2020.1 reload should be done like this:
!!! fgcommand("addon-reload", props.Node.new({'id': 'ADDON_ID'}));

You can add a menu item to trigger the reload easily, but it should be removed
before publishing your add-on to endusers (see the above warning).

Please have a look at the skeleton add-on at
https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/Skeleton/


Footnotes
---------

[1] \n represents end-of-line in string literals of languages such as C,
    C++, Python and many others. We use this convention here to
    represent the end-of-line character sequence in the XML data.

[2] MAJOR.MINOR.PATCHLEVEL[{a|b|rc}N1][.devN2] where MAJOR, MINOR and
    PATCHLEVEL are non-negative integers, and N1 and N2 are positive
    integers.

The airspeed indicator can be initialized in an instrumentation.xml file.
If not specified, the generic indicator will be loaded
from the Aircraft/Generic/generic-instrumentation.xml.

The normal setup is :

  <airspeed-indicator>
    <name>airspeed-indicator</name>
    <number>0</number>
    <total-pressure>/systems/pitot/total-pressure-inhg</total-pressure>
    <static-pressure>/systems/static/pressure-inhg</static-pressure>
    <has-overspeed-indicator>1</has-overspeed-indicator>
  </airspeed-indicator>

Of course the total and static pressure may be sourced from any other
pitot and static system when defined:

  <airspeed-indicator>
    <name>airspeed-indicator</name>
    <number>1</number>
    <total-pressure>/systems/pitot[1]/total-pressure-inhg</total-pressure>
    <static-pressure>/systems/static[1]/pressure-inhg</static-pressure>
    <has-overspeed-indicator>0</has-overspeed-indicator>
  </airspeed-indicator>

Note that the Aircraft/Generic/generic-systems.xml only initiates one
pitot and one static system, see also README.systems

<total-pressure> is optional --- defaults to "/systems/pitot/total-pressure-inhg"
For supersonic aircraft with an airspeed indicator NOT compensating for
a shockwave in front of the pitot tube (most probably the case), use:
<total-pressure>/systems/pitot/measured-total-pressure-inhg</total-pressure>

<static-pressure> is optional --- defaults to "/systems/static/pressure-inhg"
<has-overspeed-indicator> is optional --- defaults to 0 / off

The <has-overspeed-indicator> provides a property for "barber-pole" animation,
 and is set to 0 / false by default ,

If enabled , these properties should be added in the aircraft -set file,
with that aircraft's correct figures.

    <airspeed-indicator>
        <ias-limit>248.0</ias-limit>
        <mach-limit>0.48</mach-limit>
        <alt-threshold>13200.0</alt-threshold>
    </airspeed-indicator>


The default values are for a Beechcraft B1900D .

<ias-limit> is the aircraft's VNE (never exceed speed) in KIAS

<mach-limit> Mach speed limit.

<alt-threshold> altitude at which these figures were calculated.

Note : <mach-limit> is the mach limit at <alt-threshold>
This was designed for indicated airspeed limits, but could probably be extended
for mach limits.


To initiate additional airspeed indicators, add in your instrumentation
file (for airspeed indicator index 1):

  <airspeed-indicator>
    <name>airspeed-indicator</name>
    <number>1</number>
    <total-pressure>/systems/pitot[1]/total-pressure-inhg</total-pressure>
    <static-pressure>/systems/static[1]/pressure-inhg</static-pressure>
    <has-overspeed-indicator>0</has-overspeed-indicator>
  </airspeed-indicator>

Note: this airspeed indicator sources its pressures from the second
pitot and static system (with index 1).
and in the aircraft -set file:

    <airspeed-indicator n="1">
	  <serviceable type="bool" archive="y">true</serviceable>
    </airspeed-indicator>

And if "has-overspeed-indicator" = 1, the appropriate limits as explained
above in the airspeed-indicator brackets.

AUTOMATIC PUSHBACK FOR FLIGHTGEAR
http://gitlab.com/mdanil/flightgear-autopush

Version 2.0.1

Copyright (c) 2018 Autopush authors:
 Michael Danilov <mike.d.ft402 -eh- gmail.com>
 Joshua Davidson http://github.com/Octal450
 Merspieler http://gitlab.com/merspieler
Some of the code (c) FlightGear
Distribute under the terms of GPLv2.


This project aims to develop a generic pushback for JSBSim and YASim
aircraft, with the following characteristics.

1. Do the pushback procedure automatically.
2. Scale to different aircraft with minimum changes to their logic.
3. Use no computer resources in flight.


INSTALLATION

Minimum FlightGear version: 2018.0

NOTE: these steps cover the minimal testing setup. To get the most
realism out of Autopush, you will have to add logic aircraft-side as
described in the last step.

1. Copy the autopush.config.xml.template into your aircraft directory
and the Goldhofert.xml into <your-airfraft>/Models/Autopush/

2. Set up the pushback logic.

Add the following line under <sim><model> of your set.xml

<autopush include="autopush-config.xml"/>

Rename autopush-config.xml.template to autopush-config.xml and edit
the file as described below.

Alternatively, you can copy the contents of
autopush-config.xml.template to under <sim><model><autopush> of your
set.xml and make these modifications there.

Change the aliases to point to the following data:

steer-cmd-norm   nose wheel steering command norm
yaw              nose wheel steering output norm or angle (see below)
chocks           chocks command bool (or leave it until step 7)
available        pushback availability bool (or leave it until step 7)

Replace the MULTIPLIER in yaw-mult with:

max steering angle  if yaw is norm
1.0                 if yaw is degrees
57.3                if yaw is radians

Replace PITCH with the pushback's pitch relative to aircraft. If your
aircraft's ground pitch varies greatly, you can make an alias to
property with calculated relative pitch.

Replace MIN_RADIUS with the minimum allowed turning radius in m of the
center of the aircraft during pushback procedure.

NOTE: on some aircraft the turning radius is different for taxi and
pushback. Please check the aircraft's literature.

Replace STOP_DIST with the stopping distance in m from pushback speed.

Add under <nasal> of your set.xml:

 <autopush>
  <file>Nasal/Autopush/autopush.nas</file>
 </autopush>
 <autopush_driver>
  <file>Nasal/Autopush/driver.nas</file>
 </autopush_driver>
 <dynarr>
  <file>Nasal/Autopush/dynarr.nas</file>
 </dynarr>
 <autopush_route>
  <file>Nasal/Autopush/route.nas</file>
 </autopush_route>

Add under <sim><aircraft-data> of your set.xml:

 <path>/sim/model/autopush/route/show</path>
 <path>/sim/model/autopush/route/show-wingtip</path>

3. Connect the force to FDM.

 3.a. JSBSim:

  3.a.1. Add the following under <external_reactions> of your JSBSim
         XML.

 <force name="tractor" frame="BODY">
  <location unit="M">
   <x>FRONT-X</x>
   <y>FRONT-Y</y>
   <z>FRONT-Z</z>
  </location>
  <direction>
   <x>1.0</x>
   <y>0.0</y>
   <z>0.0</z>
  </direction>
 </force>

Replace FRONT-X, FRONT-Y, FRONT-Z with coordinates of your front
bogey.

  3.a.2. Add the following under <fdm><jsbsim><external_reactions> of
         your set.xml.

   <tractor>
    <magnitude alias="/sim/model/autopush/force-lbf"/>
    <x alias="/sim/model/autopush/force-x"/>
    <y alias="/sim/model/autopush/force-y"/>
    <z alias="/sim/model/autopush/force-z"/>
   </tractor>

 3.b. YASim. Add the following under <airplane> of your YASim xml.

 <thruster x="FRONT-X" y="FRONT-Y" z="FRONT-Z" vx="1" vy="0" vz="0" thrust="100000.0">
  <control-input axis="/sim/model/autopush/force-x-yasim" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
 </thruster>
 <thruster x="FRONT-X" y="FRONT-Y" z="FRONT-Z" vx="0" vy="1" vz="0" thrust="100000.0">
  <control-input axis="/sim/model/autopush/force-y-yasim" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
 </thruster>
 <thruster x="FRONT-X" y="FRONT-Y" z="FRONT-Z" vx="0" vy="0" vz="1" thrust="100000.0">
  <control-input axis="/sim/model/autopush/force-z-yasim" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
 </thruster>

Replace FRONT-X, FRONT-Y, FRONT-Z with coordinates of your front
bogey.

4. Add the pushback model to your Model XML:

 <model>
  <name>Pushback</name>
  <path>MODEL</path>
  <offsets>
   <x-m>FRONT-X</x-m>
   <y-m>FRONT-Y</y-m>
   <z-m>FRONT-Z</z-m>
  </offsets>
 </model>

Replace FRONT-X, FRONT-Y, FRONT-Z with coordinates of your front
bogey. Replace MODEL with one of the following file names:

Autopush/Goldhofert.xml  for Goldhofer towbarless pushback

Edit the "SETTINGS" part in the beginning of the Goldhofert.xml to match
your setup.

5. Add gui/dialogs/autopush.xml to your aircraft's menu (see
   FlightGear documentation for editing the menu).

6. If you have a bug tracker, please add a note, that autopush related
   bugs should be reported here:

https://gitlab.com/mdanil/flightgear-autopush/issues

7. Launch the simulator and try Autopush. After making sure it works,
   complete the support by implementing some logic in your aircraft
   and connecting the rest of the interface.

CAUTION.
1. Make sure to HAVE A BACK-UP COPY of your work.
2. If anything is not clear in the instruction below, do not guess --
   contact the authors.

 7.1. When pushback is connected ("/sim/model/autopush/connected"),
      nose wheel steering must actuate at different speed, depending
      on its rollspeed. The exact dependency is different per aircraft
      and used pushback visual, and for most aircraft the only way to
      find it is trial and error until it "looks right":
      - the input must be taken from pushback steering command norm
        (set by autopush-config.xml, default:
        "/controls/flight/rudder");
      - the output must be written to pushback orientation in degrees,
        radians or norm (set by autopush-config.xml, default:
        "/gear/gear[0]/steering-norm").

 7.2. Set or alias (in autopush-config.xml) the availability property
      "/sim/model/autopush/available". It must be false if e.g. the
      aircraft is moving too fast, the front wheel is not touching
      the ground, the aircraft is damaged or is outside of an airport
      etc.

 7.3. Make Autopush remove wheel chocks by setting the alias in
      autopush-config.xml to the chocks property. (default:
      "/controls/gear/wheel-chocks").

 7.4. Optionally, Autopush may be made visible in multiplayer by
      duplicating the properties used in its model.xml into some
      unused MP properties. See the list in

https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/src/MultiPlayer/multiplaymgr.cxx

      around line 215, and then using those properties in the
      "SETTINGS" part of Autopush model.xml.

   After making these changes check the Autopush model.xml's settings
   and make sure they match the setup. Launch the simulator and try
   Autopush.


TUNING

There should normally be no need to change the coefficients, because
the inertia of different aircraft is already taken into account. But
the gear setup may differ enough to require some tuning.

If these settings are changed during simulation, they take effect
after disconnecting and reconnecting the pushback.

Pushback (/sim/model/autopush):

Coefficient  Unit                    Description

K_p          ((km/h)/s)/(km/h)       Proportional coefficient of PID.
                                     Defines the start/stop throttle
                                     and immediate response to speed
                                     difference deltaV = V_set - V.

F_p          (km/h)/s                Proportional clipping.

K_i          ((km/h)/s)/((km/h)*s)   Integral coefficient of PID.
                                     Defines how fast the steady
                                     throttle is ramped during the
                                     push.

F_i          (km/h)/s                Integral clipping.

K_d          -((km/h)/s)/((km/h)/s)  Differential coefficient of PID.
                                     Stabilizes the approaching of
                                     steady throttle.

F_d          (km/h)/s                Differential clipping.

Pushback driver (/sim/model/autopush/driver):

Coefficient  Unit        Description

F_V          km/h        Max towing speed in auto mode.
K_psi        1/deg       Amount of steering per heading correction.
F_psi        1/deg       Max steering per heading correction.
K_deltapsi   -1/(deg/s)  Amount of steering compensation per heading
                         derivative.
F_psi        1/(deg/s)   Max amount of steering compensation per
                         heading derivative.

CHECKLISTS

You can create one or more checklist for an aircraft under /sim/checklists. These
are intended to mimic the checklists of aircraft themselves, and can be found under
the Help->Checklists menu within the simulator.

Tutorials are automatically generated from checklists on startup.

Each checklist is defined as a property tree under /sim/checklists/checklist[n]
or /sim/checklists/group[n]/checklist[m]

with the following tags

<title>       - Name of the checklist
<auto-tutorial> - Whether a tutorial should be automatically generated (true, default)
                  or not (false).
<page>        - Zero or more pages for the checklist containing:
 <item>       - One or more checklist items containing:
  <name>      - name of the checklist item (e.g. Carb Heat), to appear on the left
  <value>     - One or more values for the checklist item, to appear on the right
                hand side
  <marker>    - A tutorial marker (displayed when the user presses the ? button)
                This can be easily placed using the Help->Display Tutorial Marker.
                Contains x-m, y-m, z-m and scale tag.
  <condition> - Optional standard FlightGear condition node that evaluates when the
                checklist item has been completed.
  <binding>   - Zero or more bindings to execute the checklist item.  Allows the user
                to have their virtual co-pilot perform the action if they select the
                ">" button next to the checklist item.

The <page> tag may be omitted for single-page checklists, with the <item> tags
immediately under the <checklist[n]> node.

Tutorial auto-generation of all checklists can be disabled by setting
/sim/checklists/auto-tutorials=false.

Checklists may be grouped under <group> nodes with a <name> tag decribing the
group.  For example

<group>
 <name>Emergency</name>
 <auto-tutorial>false</auto-tutorial>
 <checklist>...
 <checklist>...
</group>
<group>
 <name>Normal</name>
 <auto-tutorial>true</auto-tutorial>
 <checklist>...
 <checklist>...
</group>

See the c172p for an example of this in action (Aircraft/c172p/c172-checklists.xml).

FlightGear Commands Mini-HOWTO

David Megginson
Started: 2002-10-25
Last revised: 2007-12-01


In FlightGear, a *command* represents an action, while a *property*
represents a state.  The trigger for a command can be any kind of user
input, including the keyboard, mouse, joystick, GUI, instrument panel,
or a remote network client.


XML Command Binding Markup
--------------------------

Most of the command-binding in FlightGear is handled through static
XML configuration files such as $FG_ROOT/keyboard.xml for the
keyboard, $FG_ROOT/mice.xml for the mouse, and
$FG_ROOT/gui/menubar.xml for the menubar.  In all of these files, you
reference a command through a binding.  This binding advances the
first throttle by 1%, up to a maximum value of 1.0:

  <binding>
   <command>property-adjust</command>
   <property>/controls/throttle[0]</property>
   <step type="double">0.01</step>
   <max>1.0</max>
  </binding>

A command binding always consists of the XML 'binding' element, with
one subelement named 'command' containing the command name (such as
'property-adjust').  All other subelements are named parameters to the
command: in this case, the parameters are 'property', 'step', and
'max'.  Here is a simpler binding, with no parameters:

  <binding>
   <command>exit</command>
  </binding>

Bindings always appear inside some other kind of markup, depending on
the input type.  For example, here is the binding from keyboard.xml
that links the ESC key to the 'exit' command:

 <key n="27">
  <name>ESC</name>
  <desc>Prompt and quit FlightGear.</desc>
  <binding>
    <command>exit</command>
  </binding>
 </key>

Usually, more than one binding is allowed for a single input trigger,
and bindings are executed in order from first to last. Bindings support
conditions (see README.conditions):

 <key n="113">
  <name>q</name>
  <desc>Test</desc>

  <binding>
   <condition>
    <property>/devices/status/mice/mouse/button[0]</property>
   </condition>
   <command>nasal</command>
   <script>print("mouse button 0 pressed")</script>
  </binding>
 </key>

Keyboard definitions can embed bindings in tags <mod-up> (key released),
<mod-shift>, <mod-ctrl>, <mod-alt>, <mod-meta>, <mod-super>, and <mod-hyper>.
Nesting is supported. Meta, Super, and Hyper modifier tags are for local
use only, and must be supported by the operating system to work.

 <key n="113">
  <name>q</name>
  <desc>Test</desc>
  <binding>
   <command>nasal</command>
   <script>print("q pressed")</script>
  </binding>

  <mod-alt>
   <binding>
    <command>nasal</command>
    <script>print("Alt-q pressed")</script>
   </binding>

   <mod-super>
    <binding>
     <command>nasal</command>
     <script>print("Alt-Super-q pressed")</script>
    </binding>

    <mod-meta>
     <binding>
      <command>nasal</command>
      <script>print("Alt-Super-Meta-q pressed")</script>
     </binding>

    </mod-meta>
   </mod-super>
  </mod-alt>
 </key>



Built-in Commands
-----------------

As of the last revision date, the following commands were available
from inside FlightGear; the most commonly-used ones are the commands
that operate on property values (FlightGear's internal state):


null - do nothing

script - execute a PSL script
  script: the PSL script to execute

exit - prompt and quit FlightGear

pause - pause/resume the simulation

load - load properties from an XML file
  file: the name of the file to load, relative to the current
    directory (defaults to "fgfs.sav")

save - save properties to an XML file
  file: the name of the file to save, relative to the current
    directory (defaults to "fgfs.sav").

loadxml - load XML file into property tree
  filename: the path & filename of the file to load
  targetnode: the target node within the property tree where to store the XML
  file's structure. If targetnode isn't defined, then the data will be stored
  in a node "data" under the argument branch.

savexml - save property tree node to XML file
  filename: the path & filename for the file to be saved
  sourcenode: the source node within the property tree where the XML file's
  structure is assembled from. If sourcenode isn't defined, then savexml will
  try to save data stored in a node "data" in the argument branch.

panel-load - (re)load the 2D instrument panel
  path: the path of the XML panel file, relative to $FG_ROOT (defaults
    to the value of /sim/panel/path if specified, or
    "Panels/Default/default.xml" as a last resort.

panel-mouse-click - pass a mouse click to the instrument panel
  button: the number of the mouse button (0-based)
  is-down: true if the button is down, false if it is up
  x-pos: the x position of the mouse click
  y-pos: the y position of the mouse click

preferences-load - (re)load preferences
  path: the file name to load preferences from, relative to $FG_ROOT.
    Defaults to "preferences.xml".

view-cycle - cycle to the next viewpoint

screen-capture - capture the screen to a file

tile-cache-reload - reload the scenery tile cache

lighting-update - update FlightGear's lighting

property-toggle - swap a property value between true and false
  property: the name of the property to toggle

property-assign - assign a value to a property
  property[0]: the name of the property that will get the new value.
  value: the new value for the property; or
  property[1]: the name of the property holding the new value.

property-interpolate - assign a value to a property, interpolated
                       over time
  property[0]: the name of the property that will get the new value
               and defines the starting point of the interpolation
  value:       the new value for the property; or
  property[1]: the name of the property holding the new value.
  time:        the time in seconds it takes for the transition from the
               old value to the new value of property[0]; or
  rate:        the ammount of change per second the value of property[0] changes
               to transition to the new value

property-adjust - adjust the value of a property
  property: the name of the property to increment or decrement
  step: the amount of the increment or decrement (defaults to 0)
  offset: input offset distance (used for the mouse; multiplied by
    factor)
  factor: factor for multiplying offset distance (used for the mouse;
    defaults to 1)
  min: the minimum allowed value (default: no minimum)
  max: the maximum allowed value (default: no maximum)
  mask: 'integer' to apply only to the left of the decimal point;
    'decimal' to apply only to the right of the decimal point; 'all'
    to apply to the full value (defaults to 'all')
  wrap: true if the value should be wrapped when it passes min or max;
    both min and max must be specified (defaults to false)

property-multiply - multiply the value of a property
  property: the name of the property to multiply
  factor: the amount by which to multiply (defaults to 1.0)
  min: the minimum allowed value (default: no minimum)
  max: the maximum allowed value (default: no maximum)
  mask: 'integer' to apply only to the left of the decimal point;
    'decimal' to apply only to the right of the decimal point; 'all'
    to apply to the full value (defaults to 'all')
  wrap: true if the value should be wrapped when it passes min or max;
    both min and max must be specified (defaults to false)

property-swap - swap the values of two properties
  property[0]: the name of the first property
  property[1]: the name of the second property

property-scale - set the value of a property based on an axis
  property: the name of the property to set
  setting: the current input setting (usually a joystick axis from -1
    or 0 to 1)
  offset: the offset to shift by, before applying the factor (defaults
    to 0)
  factor: the factor to multiply by (use negative to reverse; defaults
    to 1.0)
  squared: if true will square the resulting value (same as power=2)
  power: the resulting value will be taken to the power of this integer
    value (overrides squared; default=1)

property-cycle - cycle a property through a set of values
  property: the name of the property to cycle
  value[*]: all of the allowed values

dialog-new - create new dialog from the argument branch

dialog-show - show an XML-configured dialog box
  dialog-name - the name of the dialog to show

dialog-close - close the active dialog box

dialog-update - copy values from FlightGear to the active dialog box
  object-name: the name of the GUI object to update (defaults to all
    objects)

dialog-apply - copy values from the active dialog box to FlightGear
  object-name: the name of the GUI object to apply (defaults to all
    objects)

presets-commit - commit preset values from /sim/presets

open-browser - open the web browser and show given file
   path: name of the local file to be opened.
   url: URL to be opened (http://..., ftp://...).

The following commands are temporary, and will soon disappear or be
renamed; do NOT rely on them:

old-save-dialog - offer to save a flight

old-load-dialog - offer to load a flight

old-reinit-dialog - offer to reinit FlightGear

old-hires-snapshot-dialog - save a hires screen shot

old-snapshot-dialog - save a screenshot

old-print-dialog - print the screen (Windows only)

old-pilot-offset-dialog - set pilot offsets graphically

old-hud-alpha-dialog - set the alpha value for the HUD

old-properties-dialog - display the property browser

old-preset-airport-dialog - set the default airport

old-preset-runway-dialog - set the default runway

old-preset-offset-distance-dialog - set the default offset distance

old-preset-altitude-dialog - set the default altitude

old-preset-glidescope-dialog - set the default glidescope

old-preset-airspeed-dialog - set the default airspeed

old-preset-commit-dialog - commit preset values

old-ap-add-waypoint-dialog - add a waypoint to the current route

old-ap-pop-waypoint-dialog - remove a waypoint from the current route

old-ap-clear-dialog - clear the current route

old-ap-adjust-dialog - adjust the autopilot settings

old-lat-lon-format-dialog - toggle the lat/lon format in the HUD


Adding New Commands in C++
--------------------------


To add a new command to FlightGear, you first need to create a
function that takes a single SGPropertyNode const pointer as an
argument:

  void
  do_something (SGPropertyNode * arg)
  {
    something();
  }

Next, you need to register it with the command manager:

  globals->get_commands()->addCommand("something", do_something);

Now, the command "something" is available to any mouse, joystick,
panel, or keyboard bindings.  If the bindings pass any arguments, they
will be children of the SGPropertyNode passed in:

  void
  do_something (const SGPropertyNode * arg)
  {
    something(arg->getStringValue("foo"), arg->getDoubleValue("bar"));
  }

That's pretty-much it.  Apologies in advance for not making things any
more complicated.

CONDITIONS IN FLIGHTGEAR PROPERTY FILES

Written by David Megginson, david@megginson.com
Last modified: $Date$

This document is in the Public Domain and comes with NO WARRANTY!


1. Introduction
---------------

Some FlightGear property files contain conditions, affecting whether
bindings or animations are applied.  For example, the following
binding will apply only when the /sim/input/selected/engine[0]
property is true:

  <binding>
   <condition>
    <property>/sim/input/selected/engine[0]</property>
   </condition>
   <command>property-assign</command>
   <property>/controls/starter[0]</property>
   <value type="bool">true</value>
  </binding>

Conditions always occur within a property subtree named "condition",
which is equivalent to an "and" condition.


2. Comparison Operators
-----------------------

The simplest condition is "property".  It resolves as true when the
specified property has a boolean value of true (i.e. non-zero, etc.)
and false otherwise.  Here is an example:

  <condition>
   <property>/sim/input/selected/engine[0]</property>
  </condition>

For more sophisticated tests, you can use the "less-than",
"less-than-equals", "greater-than", "greater-than-equals", "equals",
and "not-equals" comparison operators.  These all take two operands,
either two "property" operands or one "property" and one "value"
operand, and return true or false depending on the result of the
comparison.  The value of the second operand is always forced to the
type of the first; for example, if you compare a string and a double,
the double will be forced to a string and lexically compared.  If one
of the operands is a property, it is always assumed to be first.  Here
is an example of a comparison that is true only if the RPM of the
engine is less than 1500:

  <condition>
   <less-than>
    <property>/engines/engine[0]/rpm</property>
    <value>1500</value>
   </less-than>
  </condition>


3. Boolean Operators
--------------------

Finally, there are the regular boolean operators "and", "or", and
"not".  Each one surrounds a group of other conditions, and these can
be nested to arbitrary depths.  Here is an example:

  <condition>
   <and>
    <or>
     <less-than>
      <property>/engines/engine[0]/rpm</property>
      <value>1500</value>
     </less-than>
     <greater-than>
      <property>/engines/engine[0]/rpm</property>
      <value>2500</value>
     </greater-than>
    </or>
    <property>/engines/engine[0]/running</property>
   </and>
  </condition>

The top-level "condition" is an implicit "and".


4. Approximating if...else
--------------------------

There is no equivalent to the regular programming 'else' statement in
FlightGear conditions; instead, each condition separately must take
the others into account.  For example, the equivalent of

  if (x == 3) ... else if (y == 5) ... else ...

in FlightGear conditions is

  <condition>
   <equals>
    <property>/x</property>
    <value>3</value>
   </equals>
   <not>
    <equals>
     <property>/y</property>
     <value>5</value>
    </equals>
   </not>
  </condition>

and then

  <condition>
   <equals>
    <property>/y</property>
    <value>5</value>
   </equals>
   <not>
    <equals>
     <property>/x</property>
     <value>3</value>
    </equals>
   </not>
  </condition>

and then

  <condition>
   <not>
    <equals>
     <property>/x</property>
     <value>3</value>
    </equals>
   </not>
   <not>
    <equals>
     <property>/y</property>
     <value>5</value>
    </equals>
   </not>
  </condition>

It's verbose, but it works nicely within existing property-based
formats and provides a lot of flexiblity.


5. Syntax Summary
-----------------

Here's a quick syntax summary:

* <and>...</and>

  Contains one or more subconditions, all of which must be true.

* <condition>...</condition>

  The top-level container for conditions, equivalent to an "and" group

* <equals>...</equals>

  Contains two properties or a property and value, and is true if the
  properties have equivalent values.

* <not-equals>...</not-equals>

  Contains two properties or a property and value, and is true if the
  properties have different values.

* <greater-than>...</greater-than>

  Contains two properties or a property and a value, and is true if
  the second property or the value has a value greater than the first
  property.

* <greater-than-equals>...</greater-than-equals>

  Contains two properties or a property and a value, and is true if
  the second property or the value has a value greater than or equal
  to the first property.

* <less-than>...</less-than>

  Contains two properties or a property and a value, and is true if
  the second property or the value has a value less than the first
  property.

* <less-than-equals>...</less-than-equals>

  Contains two properties or a property and a value, and is true if
  the second property or the value has a value less than or equal
  to the first property.

* <not>...</not>

  Contains one subcondition, which must not be true.

* <not-equals>...</not-equals>

  Contains two properties or a property and value, and is true if the
  properties do not have equivalent values.

* <or>...</or>

  Contains one or more subconditions, at least one of which must be
  true.

* <property>...</property>

  The name of a property to test.

* <value>...</value>

  A literal value in a comparison.

COMMON SETTINGS
==============================================================================

Currently four types of digital filter implementations are supported. They all
serve an individual purpose or are individual implementations of a specific
filter type. Each filter implementation uses the same set of basic configuration
tags and individual configuration elements. These individual elements are
described in the section of the filter.

The InputValue
==============================================================================
Each filter has several driving values, like the input value itself, sometimes
a reference value, a gain value and others. Most of these input values can be
either a constant value or the value of a property. They all use the same syntax
and will be referred to as InputValue in the remaining document.

The complete XML syntax for a InputValue is

<some-element>
  <condition>
    <!-- any condition as defined in README.conditions -->
  </condition>
  <property>/some/property/name</property>
  <value>0.0</value>
  <scale>1.0</value>
  <offset>0.0</offset>
  <max>infinity</max>
  <min>-infinity<min>
  <abs>false</abs>
  <period>
    <min>-180.0</min>
    <max>-180.0</max>
  </period>
</some-element>

The enclosing element <some-element> is the element defined in each filter, like
<input>, <u_min>, <reference> etc. These elements will be described later.
The value of the input is calculated based on the given value, scale and offset as
value * scale + offset
and the result is clipped to min/max, if given.
With the full set of given elements, the InputValue will initialize the named
property to the value given, reduced by the given offset and reverse scaled by
the given scale.

Example:
<input>
  <property>/controls/flight/rudder</property>
  <value>0.0</value>
  <scale>0.5</scale>
  <offset>0.5</offset>
</input>

Will use the property /controls/flight/rudder as the input of the filter. The
property will be initialized at a value of zero and since the property usually is
in the range [-1..+1], the the value of <input> will be in the range
(-1)*0.5+0.5 to (+1)*0.5+0.5 which is [0..1].

The default values for elements not given are:
<value/> : 0.0
<scale/> : 1.0
<offset/>: 0.0
<property/> : none
<min/>   : unclipped
<max/>   : unclipped
<abs/>   : false

Some examples:
<input>
  <property>/position/altitude-ft</property>
  <scale>0.3048</scale>
</input>
Gives the altitude in meters. No initialization of the property is performed, no
offset applied.

<reference>
  <value>0.0</value>
</reference>
A constant reference of zero.

A abbreviated method of defining values exist for using a just constant or a
property. The above example may be written as
<reference>0.0</reference>
Or if the reference is defined in a property
<reference>/some/property/name</reference>
No initialization, scaling or offsetting is performed here.
The logic behind this is: If the text node in the element (the text between the
opening and closing tag) can be converted to a double value, it will be interpreted
as a double value. Otherwise the text will
be interpreted as a property name.
Examples:
<reference>3.1415927</reference>             - The constant of PI (roughly)
<reference>/position/altitude-ft</reference> - The property /position/altitude-ft
<reference>3kings</reference>                - The constant 3. The word kings is
                                               ignored
<reference>food4less</reference>             - The property food4less

The <property> element may also be written as <prop> for backward compatibility.

There may be one or more InputValues for the same input of a filter which may be
bound to conditions. Each InputValue will have its condition checked in the order
of InputValues given in the configuration file. The first InputValue that returns
true for its condition will be evaluated. Chaining a number of InputValues with
conditions and an unconditioned InputValue works like the C language equivalent
if( condition ) {
  // compute value of first element
} else if( condition2 ) {
  // compute value of second element
} else if( condition3 ) {
  // compute value of third element
} else {
  // compute value of last element
}

Example: Set the gain to 3.0 if /autopilot/locks/heading equals dg-heading-hold or
2.0 otherwise.
<digital-filter>
  <gain>
    <condition>
      <equals>
        <property>/autopilot/locks/heading</property>
        <value>dg-heading-hold</value>
      </equals>
    </condition>
    <value>3.0</value>
  <gain>
  <!-- Hint: omit a condition here as a fallthru else condition -->
  </gain>
    <value>2.0</value>
  <gain>
<digital-filter>

If the element <abs> is used and set to the value "true", only the absolute
value of the input (the positive part) is used for further computations. The
abs function is applied after all other computations are completed.

OutputValue
==============================================================================
Each filter drives one to many output properties. No scaling or offsetting is
implemented for the output value, these should be done in the filter itself.
The output properties are defined in the <output/> element by adding <property/>
elements within the <output/> element. For just a single output property, the
<property/> element may be ommited. For backward compatibility, <property/> may
be replaced by <prop/>.  Non-existing properties will be created with type double.

Example: (Multiple output properties)
<output>
  <property>/some/output/property</property>
  <property>/some/other/output/property</property>
  <property>/and/another/output/property</property>
</output>

Example: a single output property
<output>/just/a/single/property</output>

Other Common Settings
==============================================================================
<name>        String      The name of the filter. Used for debug purpose.
Example:
<name>pressure rate filter</name>

<debug>       Boolean     If true, this filter puts out debug information when
                          updated. Example: <debug>false</debug>

<input>       InputValue  The input property driving the filter.
                          Refer to InputValue for details.

<reference>   InputValue  The reference property for filter that need one.
                          Refer to InputValue for details.

<output>      Complex     Each filter can drive one to many output properties.
                          Refer to OutputValue for details.

<u_min>       InputValue  This defines the optional minimum and maximum value the
<u_max>                   output is clamped to. If neither <u_min> nor <u_max>
                          exists, the output is only limited by the internal limit
                          of double precision float computation.  If either <u_min>
                          or <u_max> is given, clamping is activated. A missing min
                          or max value defaults to 0 (zero).
                          Note: <u_min> and <u_max> may also occour within a <config>
                          element. <min> and <max> may be used as a substitude for
                          the corresponding u_xxx element.
<period>      Complex     Define a periodical input or output value. The phase width
                          is defined by the child elements <min> and <max> which are
                          of type InputValue

Example: Limit the pilot's body temperature to a constant minimum of 36 and a
maximum defined in /pilots/max-body-temperature-degc, initialized to 40.0
<u_max>
  <prop>/pilots/max-body-temperature-degc</prop>
  <value>40.0</
</u_max>
<min>
  <value>36.0</value>
</min

Implicit definition of the minimum value of 0 (zero) and defining a maximum of 100.0
<config>
  <u_max>100.0</u_max>
</config>

This defines the input or output as a periodic value with a phase width of 360, like
the compass rose.  Any value reaching the filter's input or leaving the filter at the
output will be transformed to fit into the given range by adding or substracting one
phase width of 360. Values of -270, 90 or 450 applied to this periodical element will
always result in +90. A value of 630, 270 or -90 will be normalized to -90 in the
given example.
<period>
  <min>-180.0</min>
  <max>180.0</max>
</period>


<enable>      Complex     Define a condition to enable or disable the filter. For
                          disabled filters, no output computations are performed.
                          Only enabled filters fill the output properties. The
                          default for undefined conditions is enabled.
                          Several way exist to define a condition. The most simple
                          case is checking a boolean property. For this, just a
                          <prop> element naming this boolean property is needed.
                          The boolean value of the named property defines the
                          enabled state of the filter. To compare the value of a
                          property with a constant, a <prop> and a <value> element
                          define the property name and the value to be compared.
                          The filter is enabled, if the value of the property equals
                          the given value. A case sensitive string compare is
                          performed here.
                          To define more complex conditions, a <condition> element
                          may be used to define any condition described in
                          README.conditions.  If a <condition> element is present
                          and if it contains a valid condition, this conditions has
                          precedence over a given <prop>/<value> condition.
                          The child element <honor-passive>, a boolean flag, may be
                          present within the <enable> element. If this element is
                          true, the property /autopilot/locks/passive-mode is checked
                          and if it is true, the filter output is computed, but the
                          output properties are not set.  The default for
                          honor-passive is false
Example: Check a boolean property, only compute this filter if gear-down is true and
         /autopilot/locks/passive-mode is false
<enable>
  <prop>/gear/gear-down</prop>
  <honor-passive>true</honor-passive>
</enable>

Check a property for equality, only compute this filter if the autopilot is locked
in heading mode.
<enable>
  <prop>/autopilot/locks/heading</prop>
  <value>dg-heading-hold</value>
</enable>

Use a complex condition, only compute this filter if the autopilot is serviceable
and the lock is either dg-heading-hold or nav1-heading-hold
<enable>
  <condition>
    <property>/autopilo/serviceable</property>
    <or>
      <equals>
        <property>/autopilot/locks/heading</property>
        <value>dg-heading-hold</value>
      </equals>
      <equals>
        <property>/autopilot/locks/heading</property>
        <value>nav1-heading-hold</value>
      </equals>
    </or>
  </condition>
</enable>

INDIVIDUAL FILTER CONFIGURATION
==============================================================================

Digital Filter

Six different types of digital filter can be configured inside the autopilot
configuration file. There are four low-pass filter types and two gain filter
types.

The low-pass filter types are:

* Exponential
* Double exponential
* Moving average
* Noise spike filter

The gain filter types are:

* gain
* reciprocal

To add a digital filter, place a <filter> element under the root element. Next to
the global configuration elements described above, the following elements configure
the digital filter:
<filter-time> InputValue  This tag is only applicable for the exponential and
                          double-exponential filter types. It controls the
                          bandwidth  of the filter. The bandwidth in Hz of the
                          filter is: 1/filter-time. So a low-pass filter with a
                          bandwidth of 10Hz would have a filter time of 1/10 = 0.1

<samples>     InputValue  This tag only makes sense for the moving-average filter.
                          It says how many past samples to average.

<max-rate-of-change>
              InputValue  This tag is applicable for the noise-spike filter.
                          It says how much the value is allowed to change per
                          second.

<gain>        InputValue  This is only applicable to the gain and reciprocal filter
                          types. The output for gain filter is computed as input*gain
                          while  the reciprocal filter computes output as gain/input
                          for input values != 0 (zero). Gain may be a constant, a
                          property name defined by a <prop> element within the <gain>
                          element or a  property name initialized to a value by using
                          a <prop> and <value> element.

Example: a pressure-rate-filter implemented as a double exponential low pass filter
         with a bandwith of 10Hz

  <filter>
    <name>pressure-rate-filter</name>
    <debug>false</debug>
    <type>double-exponential</type>
    <enable>
      <prop>/autopilot/locks/pressure-rate-filter</prop>
      <value>true</value>
    </enable>
    <input>/autopilot/internal/pressure-rate</input>
    <output>/autopilot/internal/filtered-pressure-rate</output>
    <filter-time>0.1</filter-time>
  </filter>

This will filter the pressure-rate property. The output will be to a new
property called filtered-pressure-rate. You can select any numerical property
from the property tree. The input property will not be affected by the filter,
it will stay the same as it would if no filter was configured.

Example 2:

  <filter>
    <name>airspeed elevator-trim gain reciprocal filter</name>
    <debug>false</debug>
    <enable>
      <prop>/autopilot/locks/airspeed-elevator-trim-gain</prop>
      <value>true</value>
    </enable>
    <type>reciprocal</type>
    <gain>
      <prop>/autopilot/settings/elevator-trim-airspeed-reciprocal-gain</prop>
      <value>7</value>
    </gain>
    <input>/velocities/airspeed-kt</input>
    <output>/autopilot/internal/elevator-trim-gain</output>
    <u_min>0.005</u_min>
    <u_max>0.02</u_max>
  </filter>

This will use the /velocities/airspeed-kt property to produce a gain factor
that reduces as airspeed increases.  At airspeeds up to 350kt the gain will
be clamped to 0.02, at 700kt the gain will be 0.01 and at 1400kt the gain will
be 0.005.  The gain will be clamped to 0.005 for airspeeds > 1400kt.

The output from this filter could then be used to control the gain in a PID
controller:

  <pid-controller>
    <name>Pitch hold</name>
    <debug>false</debug>
    <enable>
      <prop>/autopilot/locks/pitch</prop>
      <value>true</value>
    </enable>
    <input>
      <prop>/orientation/pitch-deg</prop>
    </input>
    <reference>
      <prop>/autopilot/settings/target-pitch-deg</prop>
    </reference>
    <output>
      <prop>/autopilot/internal/target-elevator-trim-norm</prop>
    </output>
    <config>
      <Ts>0.05</Ts>
      <Kp>
        <prop>/autopilot/internal/elevator-trim-gain</prop>
        <value>0.02</value>
      </Kp>
      <beta>1.0</beta>
      <alpha>0.1</alpha>
      <gamma>0.0</gamma>
      <Ti>2.0</Ti>
      <Td>0.2</Td>
      <u_min>-1.0</u_min>
      <u_max>1.0</u_max>
    </config>
  </pid-controller>

IMPORTANT NOTE: The <Kp> tag in PID controllers has been revised to operate in
the same way as the <gain> elements in filters.  However, the original format
of <Kp> will continue to function as before i.e. <Kp>0.02</Kp> will specify a
fixed and unalterable gain factor, but a warning message will be output.

The gain type filter is similar to the reciprocal filter except that the gain
is applied as a simple factor to the input.
-------------------------------------------------------------------------------
Parameters

<name> The name of the filter. Give it a sensible name!

<debug> If this tag is set to true debugging info will be printed on the
console.

<enable> Encloses the <prop> and <value> tags which are used to enable or
disable the filter. Instead of the <prop> and <value> tags, a <condition>
tag may be used to define a condition. Check README.conditions for more
details about conditions.  Defaults to enabled if unspecified.

<type> The type of filter. This can be exponential, double-exponential,
moving-average, noise-spike, gain or reciprocal.

<input> The input property to be filtered. This should of course be a
numerical property, filtering a text string or a boolean value does not make
sense.

<output> The filtered value. You can make up any new property.

<u_min> The minimum output value from the filter.  Defaults to -infinity.

<u_max> The maximum output value from the filter.  Defaults to +infinity.

These are the tags that are applicable to all filter types. The following tags
are filter specific.

<filter-time> This tag is only applicable for the exponential and
double-exponential filter types. It controls the bandwidth of the filter. The
bandwidth in Hz of the filter is: 1/filter-time. So a low-pass filter with a
bandwidth of 10Hz would have a filter time of 1/10 = 0.1

<samples> This tag only makes sense for the moving-average filter. It says how
many past samples to average.

<max-rate-of-change> This tag is applicable for the noise-spike filter. Is
says how much the value is allowed to change per second.

<gain>  This, and it's enclosed <prop> and <value> tags, are only applicable to
the gain and reciprocal filter types.  The <prop> tag specifies a property node
to hold the gain value and the <value> tag specifies an initial default value.
The gain defaults to 1.0 if unspecified.

The output from the gain filter type is: input * gain.
The output from the reciprocal filter type is: gain / input.

The gain can be changed during run-time by updating the value in the property
node.

Effects
-------

Effects describe the graphical appearance of 3d objects and scenery in
FlightGear. The main motivation for effects is to support OpenGL
shaders and to provide different implementations for graphics hardware
of varying capabilities. Effects are similar to DirectX effects files
and Ogre3D material scripts.

An effect is a property list. The property list syntax is extended
with new "vec3d" and "vec4d" types to support common computer graphics
values. Effects are read from files with a ".eff" extension or can be
created on-the-fly by FlightGear at runtime.  An effect consists of a
"parameters" section followed by "technique" descriptions.  The
"parameters" section is a tree of values that describe, abstractly,
the graphical characteristics of objects that use the effect. Techniques
refer to these parameters and use them to set OpenGL state or to set
parameters for shader programs. The names of properties in the
parameter section can be whatever the effects author chooses, although
some standard parameters  are set by FlightGear itself. On the other
hand, the properties in the techniques section are all defined by the
FlightGear.

Techniques
----------

A technique can contain a predicate that describes the OpenGL
functionality required to support the technique. The first
technique with a valid predicate in the list of techniques is used
to set up the graphics state of the effect. A technique with no
predicate is always assumed to be valid. The predicate is written in a
little expression language that supports the following primitives:

and, or, equal, less, less-equal
glversion - returns the version number of OpenGL
extension-supported - returns true if an OpenGL extension is supported
property - returns the boolean value of a property
float-property - returns the float value of a property, useful inside equal, less
                or less-equal nodes
shader-language - returns the version of GLSL supported, or 0 if there is none.

The proper way to test whether to enable a shader-based technique is:
  <predicate>
    <and>
    <property>/sim/rendering/shader-effects</property>
    <less-equal>
      <value type="float">1.0</value>
      <shader-language/>
    </less-equal>
    </and>
  </predicate>

There is also a property set by the user to indicate what is the level
of quality desired. This level of quality can be checked in the predicate
like this :
    <predicate>
      <and>
        <property>/sim/rendering/shader-effects</property>
  <less-equal>
    <value type="float">2.0</value>
    <float-property>/sim/rendering/quality-level</float-property>
  </less-equal>
  <!-- other predicate conditions -->
      </and>
    </predicate>

The range of /sim/rendering/quality-level is [0..5]
 * 2.0 is the threshold for relief mapping effects,
 * 4.0 is the threshold for geometry shader usage.

A technique can consist of several passes. A pass is basically an Open
Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state
attributes  will be accessable in techniques. State attributes -- that
is, technique properties that have children and are not just boolean
modes -- have an <active> parameter which enables or disables the
attribute. In this way a technique can declare parameters it needs,
but not enable the attribute at all if it is not needed; the decision
can be based on a parameter in the parameters section of the
effect. For example, effects that support transparent and opaque
geometry could have as part of a technique:

    <blend>
    <active><use>blend/active</use></active>
    <source>src-alpha</source>
    <destination>one-minus-src-alpha</destination>
    </blend>

So if the blend/active parameter is true blending will be activated
using the usual blending equation; otherwise blending is disabled.

Values of Technique Attributes
------------------------------

Values are assigned to technique properties in several ways:

  * They can appear directly in the techniques section as a
    constant. For example:
    <uniform>
      <name>ColorsTex</name>
      <type>sampler-1d</type>
      <value type="int">2</value>
    </uniform>
    * The name of a property in the parameters section can be
    referenced using a "use" clause. For example, in the technique
    section:
    <material>
      <ambient><use>material/ambient</use></ambient>
    </material>
    Then, in the parameters section of the effect:
    <parameters>
      <material>
        <ambient type="vec4d">0.2 0.2 0.2 1.0</ambient>
      </material>
    </parameters>

    It's worth pointing out that the "material" property in a
    technique specifies part of OpenGL's state, whereas "material"
    in the parameters section is just a name, part of a
    hierarchical namespace.

    * A property in the parameters section doesn't need to contain
    a constant value; it can also contain a "use" property. Here
    the value of the use clause is the name of a node in an
    external property tree which will be used as the source of a
    value. If the name begins with '/', the node is in
    FlightGear's global property tree; otherwise, it is in a local
    property tree, usually belonging to a model [NOT IMPLEMENTED
    YET]. For example:
    <parameters>
      <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light>
    </parameters>
    The type is determined by what is expected by the technique
    attribute that will ultimately receive the value. [There is
    no way to get vector values out of the main property system
    yet; this will be fixed shortly.] Values that are declared
    this way are dynamically updated if the property node
    changes.

OpenGL Attributes
-----------------

The following attributes are currently implemented in techiques:
alpha-test - children: active, comparison, reference
     Valid values for comparision:
       never, less, equal, lequal, greater, notequal, gequal,
       always

alpha-to-coverage - true, false

blend - children: active, source, destination, source-rgb,
     source-alpha, destination-rgb, destination-alpha
     Each operand can have the following values:
       dst-alpha, dst-color, one, one-minus-dst-alpha,
       one-minus-dst-color, one-minus-src-alpha,
       one-minus-src-color, src-alpha, src-alpha-saturate,
       src-color, constant-color, one-minus-constant-color,
       constant-alpha, one-minus-constant-alpha, zero

cull-face - front, back, front-back

lighting - true, false

material - children: active, ambient, ambient-front, ambient-back, diffuse,
     diffuse-front, diffuse-back, specular, specular-front,
     specular-back, emissive, emissive-front, emissive-back, shininess,
     shininess-front, shininess-back, color-mode

polygon-mode - children: front, back
    Valid values:
        fill, line, point

program
    vertex-shader
    geometry-shader
    fragment-shader
    attribute
    geometry-vertices-out - integer, max number of vertices emitted by geometry
                            shader
    geometry-input-type - points, lines, lines-adjacency, triangles,
                          triangles-adjacency
    geometry-output-type - points, line-strip, triangle-strip

render-bin - (OSG) children: bin-number, bin-name

rendering-hint - (OSG) opaque, transparent

shade-model - flat, smooth

texture-unit - has several child properties:
  unit - The number of an OpenGL texture unit
  point-sprite - true, false - Whether this should rendered as a point-sprite
  type - This is either an OpenGL texture type or the name of a
    builtin texture. Currently supported OpenGL types are 1d, 2d,
    3d which have the following common parameters:
      image (file name)
      filter - nearest, linear, [nearest|linear]-mipmap-[nearest|linear]
      mag-filter - nearest, linear, [nearest|linear]-mipmap-[nearest|linear]
      wrap-s - clamp, clamp-to-border, clamp-to-edge, mirror, repeat
      wrap-t - clamp, clamp-to-border, clamp-to-edge, mirror, repeat
      wrap-r - clamp, clamp-to-border, clamp-to-edge, mirror, repeat
      mipmap-control - control the mipmap on a per-channel basis.  Children:
        function-r - auto, average, sum, product, min, max
        function-g - auto, average, sum, product, min, max
        function-b - auto, average, sum, product, min, max
        function-a - auto, average, sum, product, min, max

    The following built-in types are supported:
      white - 1 pixel white texture
      noise - a 3d noise texture. (size parameter defines size of texture)
      light-sprite - a procedurally generated sprite suitable for point lights
      cubemap - build a cube-map.  Children:
        images - build from 6 images. Children: [positive|negative]-[x|y|z]
        image - build from a single cross-image

  environment
    mode - add, blend, decal, modulate, replace
    color

  texenv-combine
    combine-[rgb|alpha] - replace, modulate, add, add-signed, interpolate, subtract, dot3-rgb, dot3-rgba
    source[0|1|2]-[rgb|alpha] - constant, primary_color, previous, texture, texture[0-7]
    operand[0|1|2]-[rgb|alpha] -src-color, one-minus-src-color, src-alpha, one-minus-src-alpha
    scale-[rgb|alpha]
    constant-color

  texgen
    mode - object-linear, eye-linear, sphere-map, normal-map, reflection-map
    planes - s, t, r, q

uniform
    name
    type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
    sampler-3d

vertex-program-two-side - true, false

vertex-program-point-size - true, false

Inheritance
-----------

One feature not fully illustrated in the sample below is that
effects can inherit from each other. The parent effect is listed in
the "inherits-from" form. The child effect's property tree is
overlaid over that of the parent. Nodes that have the same name and
property index -- set by the "n=" attribute in the property tag --
are recursively merged. Leaf property nodes from the child have
precedence.  This means that effects that inherit from the example
effect below could be very short, listing just new
parameters and adding nothing to the techniques section;
alternatively, a technique could be altered or customized in a
child, listing (for example) a different shader program. An example
showing inheritance Effects/crop.eff, which inherits some if its
values from Effects/terrain-default.eff.

FlightGear directly uses effects inheritance to assign effects to 3D
models and terrain. As described below, at runtime small effects are
created that contain material and texture values in a "parameters"
section. These effects inherit from another effect which references
those parameters in its "techniques" section. The derived effect
overrides any default values that might be in the base effect's
parameters section.

Generate
--------

Often shader effects need tangent vectors to work properly. These
tangent vectors, usually called tangent and binormal, are computed
on the CPU and given to the shader as vertex attributes. These
vectors are computed on demand on the geometry using the effect if
the 'generate' clause is present in the effect file. Exemple :

  <generate>
    <tangent type="int">6</tangent>
    <binormal type="int">7</binormal>
    <normal type="int">8</normal>
  </generate>

Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'.
The integer value of these subnode is the index of the attribute
that will hold the value of the vec3 vector.

The generate clause is located under PropertyList in the xml file.

In order to be available for the vertex shader, these data should
be bound to an attribute in the program clause, like this :

  <program>
    <vertex-shader>my_vertex_shader</vertex-shader>
    <attribute>
      <name>my_tangent_attribute</name>
      <index>6</index>
    </attribute>
    <attribute>
      <name>my_binormal_attribute</name>
      <index>7</index>
    </attribute>
  </program>

attribute names are whatever the shader use. The index is the one
declared in the 'generate' clause. So because generate/tangent has
value 6 and my_tangent_attribute has index 6, my_tangent_attribute
holds the tangent value for the vertex.

Default Effects in Terrain Materials and Models
-----------------------------------------------

Effects for terrain work in this way: for each material type in
materials.xml an effect is created that inherits from a single default
terrain effect, Effects/terrain-default.eff. The parameters section of
the effect is filled in using the ambient, diffuse, specular,
emissive, shininess, and transparent fields of the material. The
parameters image, filter, wrap-s, and wrap-t are also initialized from
the material xml. Seperate effects are created for each texture
variant of a material.

Model effects are created by walking the OpenSceneGraph scene graph
for a model and replacing nodes (osg::Geode) that have state sets with
node that uses an effect instead. Again, a small effect is created
with parameters extracted from OSG objects; this effect inherits, by
default, from Effects/model-default.eff. A larger set of parameters is
created for model effects than for terrain because there is more
variation possible from the OSG model loaders than from the terrain
system. The parameters created are:

  * material active, ambient, diffuse, specular, emissive,
    shininess, color mode
    * blend active, source, destination
    * shade-model
    * cull-face
  * rendering-hint
  * texture type, image, filter, wrap-s, wrap-t

Specifying Custom Effects
-------------------------

You can specify the effects that will be used by FlightGear as the
base effect when it creates terrain and model effects.

In the terrain materials.xml, an "effect" property specifies the name
of the model to use.

In model .xml files, A richer syntax is supported. [TO BE DETERMINED]

Material animations will be implemented by creating a new effect
that inherits from one in a model, overriding the parameters that
will be animated.

Examples
--------

The Effects directory contains the effects definitions; look there for
examples. Effects/crop.eff is a good example of a complex effect.

Application
-----------

To apply an effect to a model or part of a model use:

  <effect>
    <inherits-from>Effects/light-cone</inherits-from>
    <object-name>Cone</object-name>
  </effect>

where <inherits-from> </inherits-from> contains the path to the effect you want to
apply. The effect does not need the file extension.

NOTE:

Chrome, although now implemented as an effect, still retains the old method of
application:

  <animation>
      <type>shader</type>
      <shader>chrome</shader>
      <texture>glass_shader.png</texture>
      <object-name>windscreen</object-name>
  </animation>

in order to maintain backward compatibility.

Model Hierarchy
---------------

There are a large number of techniques used by the models, with complex
inheritance.  Here is a handy list of the techniques, what they are for, and
where the base technique is defined

Non-Compositor

# Where Defined                Summary
4 model-combined.xml           ALS, quality>0, model>0
5 model-defaults.xml           Base ALS
7 model-combined-deferred.xml  Rembrandt, model>0
9  model-combined.xml          quality>0, model>0
10 model-defaults.xml          Base Rembrandt
11 model-defaults.xml          Generic shaders, quality>0
13 model-defaults.xml          Fallback - no predicate


Compositor

# Where Defined                Summary
4 model-combined.xml          quality>0, model>0
7 model-combined.xml          ALS, quality>0, model>0
8 model-default.xml          generic>0, quality>0
9 model-default.xml          Fallback - no predicate
19 model-default.xml         ALS, basic


Scenery Hierarchy
-----------------

Compositor

# Where defined          Summary
8 terrain-default.xml    quality>0, generic>0
9 terrain-default.xml    Fallback - no predicate
17 terrain-default.xml   ALS, landmass=6, transition=6
18 terrain-default.xml   ALS, landmass>3, transition>2
19 terrain-default.xml   ALS, basic

Specifying and Configuring and Aircraft Electrical System
=========================================================

Written by Curtis L. Olson <curt@flightgear.org>

February 3, 2003 - Initial revision.


Introduction
============

The FlightGear electrical system model is an approximation.  We don't
model down to the level of individual electrons, but we do try to
model a rich enough subset of components so that a realistic (from the
pilot's perspective) electrical system may be implemented.  We try to
model enough of the general flow so that typical electrical system
failures can be implimented and so that the pilot can practice
realistic troubleshooting techniques and learn the basic structure and
relationships of the real aircraft electrical system.

An electrical system can be built from 4 major components: suppliers,
buses, outputs, and connectors.  Suppliers are things like batteries
and generators.  Buses collect input from multiple suppliers and feed
multiple outputs.  Outputs are not strictly necessary, but are
included so we can name generic output types and provide a consistent
naming scheme to other FlightGear subsystems.  Finally connectors
connect a supplier to a bus, or a bus to an output, and optionally can
specify a switch property (either a physical switch or a circuit
breaker.)

At run time, the structure specified in the electrical system config
file is parsed and a directional graph (in the computer science sense)
is built.  Each frame, the current is propagated through the system,
starting at the suppliers, flowing through the buses, and finally to
the outputs.  The system follows the path of connectors laid out in
the config file and honors the state of any connector switch.


Suppliers
=========

A supplier entry could look like the following:

  <supplier>
    <name>Battery 1</name>
    <prop>/systems/electrical/suppliers/battery[0]</prop>
    <kind>battery</kind>
    <volts>24</volts>
    <amps>60</amps>   <!-- WAG -->
  </supplier>

<name> can be anything you choose to call this entry.
<prop> is the name of a property that will be updated with the state
       of this supplier.
<kind> can be "battery", "alternator", or "external".
<volts> specifies the volts of the source
<amps> specifies the amps of the source

Currently <volts> and <amps> are not really modeled in detail.  This
is more of a place holder for the future.

For alternators, you must additionally specify:

    <rpm-source>/engines/engine[0]/rpm</rpm-source>

The value of the rpm source determines if the generator is able to
produce power or not.


Buses
=====

A bus entry could look like the following:

  <bus>
    <name>Essential/Cross Feed Bus</name>
    <prop>/systems/electrical/outputs/bus-essential</prop>
    <prop>/systems/electrical/outputs/annunciators</prop>
    <prop>/systems/electrical/outputs/master-switch</prop>
  </bus>

<name> is whatever you choose to call this bus

You can have an arbitrary number of <prop> entries.  Each entry is the
name of a property that will be updated with the value of the current
at that bus.  This allows you to wire devices directly to the bus but
does not allow you to insert a switch or circuit breaker in between.
See "Outputs" and "Connectors" if you want to do that.


Outputs
=======

An output entry could look like the following:

  <output>
    <name>Starter 1 Power</name>
    <prop>/systems/electrical/outputs/starter[0]</prop>
  </output>

An output isn't entirely unlike a bus, but it's nice conceptually to
have a separate entity type.  This enables us to specify a common set
of output property names so that other subsystems can automatically
work with any electrical system that follows the same conventions.  An
output lives on the other side of a switch, so this is how you can
wire in cockpit switches to model things like fuel pump power,
avionics master switch, or any other switch on the panel.

<name> is whatever you choose to call this bus

You can have an arbitrary number of <prop> entries.  Each entry is the
name of a property that will be updated with the value of the current
at that bus.  This allows you to wire devices directly to the bus but
does not allow you to insert a switch or circuit breaker in between.
See "Outputs" and "Connectors" if you want to do that.

Other FlightGear subsystems can monitor the property name associated
with the various outputs to decide how to render an instrument,
whether to run the fuel pump, whether to spin a gyro, or any other
subsystem that cares about electrical power.


Connectors
==========

An connector entry could look like the following:

  <connector>
    <input>Alternator 1</input>
    <output>Virtual Bus 1</output>
    <switch>/controls/switches/master-alt</switch>
    <initial-state>off</initial-state>  <!-- optional tag -->
  </connector>

A connector specifies and input, and output, and any number of
switches that are wired in series.  In other words, all switches need
to be true/on in order for current to get from the input to the output
of the connector.

<input> specifies the <name> of the input.  Typically you would
specify a "supplier" or a "bus".

<output> specifies the <name> of the output.  Typically you would
specify a bus or an output.

You can have an arbitrary number of <switch> entries.  The switches
are wired in series so all of them need to be on (i.e. true) in order
for current to pass to the output.

Note: by default the system forces any listed switches to be true.
The assumption is that not every aircraft or cockpit may impliment
every available switch, so rather than having systems be switched off,
with no way to turn them on, we default to switched on.

This is a problem however with the starter switch which we want to be
initialized to "off".  To solve this problem you can specify
<initial-state>off</initial-state> or
<initial-state>on</initial-state> Switches default to on, so you
really only need to specify this tag if you want the connector's
switch to default to off.


Summary
=======

The electrical system has a lot of power and flexibility to model a
variety of electrical systems.  However, it is not yet perfect or
finished.  One major weakness is that it doesn't yet model degraded
battery or generator power, and it doesn't model the "charge" of the
batteries in case of a generator failure.

-*- coding: utf-8; fill-column: 72; -*-

The Embedded Resources System
=============================

This document gives an overview of FlightGear's embedded resources
system and related classes. For specific information on the C++
functions, the reference documentation is in the corresponding header
files.


Contents
--------

1. The CharArrayStream and ZlibStream classes
2. The “embedded resources” system
3. About the XML resource declaration files
4. The EmbeddedResourceProxy class


Introduction
------------

The embedded resources system allows FlightGear to use data from files
without relying on FG_ROOT to be set. This can be used, for instance, to
grab the contents of XML files at FG build time, from any repository[1],
and use said contents in the C++ code. The term “embedded” is used to
avoid confusion with the ResourceProvider and ResourceManager classes
provided by SimGear, which have nothing to do with the system described
here.

The embedded resources system relies on classes present in
simgear/io/iostreams/{zlibstream.cxx,CharArrayStream.cxx}, which were
implemented as a way to address a concern that embedding a few XML files
in the fgfs binary could use precious memory. The resource compiler
(fgrcc) compresses resources before writing them in C++ form---except
for some extensions, and it's configurable on a per-resource basis
anyway. Then, the EmbeddedResourceManager instance, which lives in the
fgfs process, can decompress them on-the-fly, incrementally,
transparently. So, there is really no reason to worry about memory
consumption, even for several dozens of XML files.

fgrcc is the resource compiler: it turns arbitrary files into C++ code
the EmbeddedResourceManager can make use of, in order to “serve” the
files' contents at runtime. It is named this way, because it fulfills
the same role as Qt's rcc tool. It supports a thin superset of the
XML-based format used by rcc for declaring resources[2][3].
'fgrcc --help' gives a lot of info.


1) The CharArrayStream and ZlibStream classes
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The CharArrayStream* files in simgear/io/iostreams/ implement
CharArrayStreambuf and related IOStreams classes for working with char
arrays, namely:
  - CharArrayStreambuf    subclass of std::streambuf      stream buffer
  - ROCharArrayStreambuf  subclass of CharArrayStreambuf  stream buffer
  - CharArrayIStream      subclass of std::istream        input stream
  - CharArrayOStream      subclass of std::ostream        output stream
  - CharArrayIOStream     subclass of std::iostream       input/output stream

(in the 'simgear' namespace, of course)

CharArrayStreambuf is a stream buffer class allowing to read from, and
write to char arrays (std::strstream has been deprecated since C++98).
Contrary to std::strstream, this class does no dynamic allocation: it is
very simple, strictly staying for both reads and writes within the
bounds of the buffer specified in its constructor. Contrary to
std::stringstream, CharArrayStreambuf allows one to work on an array of
char (that could be static data, on the stack, whatever) without having
to make a whole copy of it.

ROCharArrayStreambuf is a read-only subclass of CharArrayStreambuf
(useful for const-correctness). CharArrayIStream, CharArrayOStream and
CharArrayIOStream are very simple convenience stream classes using
either CharArrayStreambuf or ROCharArrayStreambuf as their associated
stream buffer class.

While these classes can be of general-purpose usefulness, the particular
reason they have been written for is to make the embedded resources
system clean and memory-friendly. Concretely, this system supports both
compressed and uncompressed resources, all of which can be read from
their respective static arrays like this (think pipelines):

static char array
(uncompressed       --------------->      data available via an std::istream
 resource)          CharArrayIStream         or std::streambuf interface
                 or ROCharArrayStreambuf

static char array
(compressed       ---------------> compressed data ------------------->    ditto
 resource)        CharArrayIStream               ZlibDecompressorIStream
                                              or ZlibDecompressorIStreambuf

where ditto = uncompressed data available via an std::istream or
              std::streambuf interface

So, whether the resource data stored in static arrays by fgrcc is
compressed or not, end-user code can read it in uncompressed form using
an std::istream or std::streambuf interface, which means the resource
never needs to be copied in memory a second time. This is particularly
interesting with compressed resources, because:

  1) The in-memory static data is much smaller in general than the
     uncompressed contents, and it's the only one we really have to
     “pay” for if one uses these stream-based interfaces.

  2) The data is transparently decompressed on-demand as the end-user
     code reads from the ZlibDecompressorIStream or
     ZlibDecompressorIStreambuf instance.

In other words, these CharArrayStream classes complement the ones in
zlibstream.cxx and make it easy to implement all kinds of pipelines to
incrementally read or write, and possibly on-the-fly compress or
decompress data from or to in-memory buffers (cf.
writeCompressedDataToBuffer() in
simgear/simgear/embedded_resources/embedded_resources_test.cxx, or
ResourceCodeGenerator::writeEncodedResourceContents() in
flightgear/src/EmbeddedResources/fgrcc.cxx for examples).

Since all of these provide standard IOStreams interfaces, they can be
easily plugged into existing code. For instance, readXML() in
simgear/simgear/xml/easyxml.cxx and readProperties() in
simgear/props/props_io.cxx can incrementally read and parse data from an
std::istream instance, and thus are able to directly read from a
resource containing the compressed version of an XML file.

This incremental stuff is of course really interesting with large
resources... which probably won't be used in FlightGear, in order not to
waste RAM[4][5]. The EmbeddedResourceManager also has a getString()
method to simply get an std::string when you don't care about the fact
that this operation, by std::string design, will necessarily make a copy
of the whole resource contents (in uncompressed form in the case of a
compressed resource). This getString() method should be convenient and
quite acceptable for reasonably-sized resources.

Finally, all of these classes---CharArray*Stream*, the classes in
zlibstream.cxx, the EmbeddedResourceManager and related classes---can
handle text and binary data in exactly the same way (std::string doesn't
care, and neither do the other classes).


2) The “embedded resources” system
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The embedded resources system works this way:

  (1) The fgrcc resource compiler reads an XML file which has almost the
      same syntax[2] as Qt's .qrc files[3] and writes a .cxx file
      containing:
        - static char arrays initialized with resource contents
          (possibly compressed, this is automatic unless explicitly
          specified in the XML file);
        - a function definition containing calls to
          EmbeddedResourceManager::addResource() that register each of
          these resources with the EmbeddedResourceManager instance.

      If you pass the --output-header-file option to fgrcc, it also
      writes a header file that goes with the generated .cxx file. For
      other options, see the output of 'fgrcc --help'.

      It is quite possible to call fgrcc several times, each time with a
      different (XML input file, .cxx/.hxx output files) tuple: for
      instance, one call for resources present in the FlightGear repo,
      and possibly another call for resources in FGData. The point of
      this is that paths in the XML input file should be relative to
      avoid being system-dependent, and fgrcc accepts a --root option to
      indicate what you want them to be relative to, in order to let it
      find the real files. Thus, on a first invocation of fgrcc, one can
      make --root point to a path to the FlightGear repository when
      building, and on the second call use it to indicate a path to the
      FGData repository. Other variations are possible, of course.

      Notes:

        1) The example given here with FGData would *not* freeze the
           FGData location at FG compile time; this is only to allow
           files from FGData to be turned into generated .cxx files
           inside the FG source tree, that will make their contents
           available as embedded resources at runtime.

        2) At the time of this writing, resources from the FlightGear
           repository are compiled at build time, and resources from the
           FGData repository are compiled offline using the
           'rebuild-fgdata-embedded-resources' script[6] (a
           convenience wrapper for fgrcc), before being committed to the
           FlightGear repository.

  (2) SimGear contains an EmbeddedResourceManager class with, among
      others, createInstance() and instance() methods similar to the
      ones of NavDataCache. See [7] for the corresponding code.

      FlightGear creates an EmbeddedResourceManager instance at startup
      and calls the various init functions generated by fgrcc, each of
      which registers the resources present in its containing .cxx file
      (using EmbeddedResourceManager::addResource()).

      End-user FG code can then use EmbeddedResourceManager methods such
      as getResource(), getString(), getStreambuf() and getIStream()
      to access resource contents:
        - getResource() returns an
          std::shared_ptr<const AbstractEmbeddedResource>
        - getString() returns an std::string
        - getStreambuf() returns an std::unique_ptr<std::streambuf>
        - getIStream() returns an std::unique_ptr<std::istream>

      AbstractEmbeddedResource is an abstract base class that you can
      think of as a resource descriptor: it points to (not contains!)
      the resource data (which is normally of static storage class), and
      contains + gives access to metadata such as the compression type
      and resource size (compressed and uncompressed).

     AbstractEmbeddedResource currently has two derived concrete
     classes: RawEmbeddedResource for resources stored as-is
     (uncompressed) and ZlibEmbeddedResource for resources compressed by
     fgrcc. It's quite easy to add new subclasses if wanted, e.g. for
     LZMA compression or other things.

     Resource fetching requires two things:

       - an std::string key (fgrcc manipulates them with SGPath, but the
         EmbeddedResourceManager code in SimGear is so far completely
         agnostic of the kind of data stored in keys; this could be
         changed, though, if we wanted for example to be able to query
         at runtime all available resources in a given “virtual
         directory”);

       - a “locale” name, similar to what FlightGear's XML translation
         files and FGLocale use. We used double quotes here, because
         fgrcc and the EmbeddedResourceManager expect “locale” names to
         be of one of these forms:
           * empty string: default locale, typically but not necessarily
             English (it is “engineering English” in FlightGear, i.e.,
             English written by programmers in the code, before
             translators possibly fix it up :)
           * en, fr, de, es, it...
           * en_GB, en_US, fr_FR, fr_CA, de_DE, de_CH, it_IT...

         There is no encoding part, contrary to POSIX locales, hence the
         use of double quotes around the term “locale” in this context.

     The FGLocale::getPreferredLanguage() method returns the preferred
     “locale” in the form described above, according to user choice
     (from fgfs' --language option) and/or settings (system locale).
     This allows FG to tell the EmbeddedResourceManager the preferred
     “locale” for resource fetching (same syntax as in Qt's rcc tool for
     declaration in the XML file, using the 'lang' attribute on
     'qresource' elements).

     [ Regarding the default locale, the way things are currently set
       up, I would use no 'lang' attribute for resources suitable for
       English in the XML input file for fgrcc, except when a
       country-specific variant is desired (en_GB, en_US, en_AU...). In
       such a case, there should also be a generic variant with no
       'lang' attribute declared for the same resource virtual path.
       This matches what I did for FGLocale::getPreferredLanguage(),
       that maps unset locales and locales such as C and C.UTF-8 to the
       default locale for the EmbeddedResourceManager, which is the
       empty string. This is a matter of policy, of course, and could be
       changed if desired. ]

     The EmbeddedResourceManager class has getLocale() and
     selectLocale() methods to manage the _selected locale_. Each
     resource-fetching method of this class (getResourceOrNullPtr(),
     getResource(), getString(), getStreambuf() and getIStream()) has
     two overloads:
       - one taking only a virtual path (the key mentioned above);
       - one taking a virtual path and a “locale” name.

     (we'll write “locale” without enclosing double-quotes from now on,
     otherwise it gets too painful to read; but we're *not* talking
     about POSIX-style locales ending with an encoding part)

     The first kind of overload uses the selected locale to look up the
     resource, whereas the second kind uses the explicitly specified
     locale. Then resource lookup behaves as one could expect. For
     instance, assuming a resource is looked up for in the "fr_FR"
     locale, then the EmbeddedResourceManager tries in this order:
       - "fr_FR";
       - if no resource has been registered for "fr_FR" with the provided
         virtual path, it then tries with the "fr" locale;
       - if this is also unsuccessful, it finally tries with the default
         locale: "";
       - if this third attempt fails, the resource-fetching method
         throws an sg_exception, except for getResourceOrNullPtr(),
         which returns a null
         std::shared_ptr<const AbstractEmbeddedResource> instead.

     To see how this is used, you can look at
     simgear/simgear/embedded_resources/embedded_resources_test.cxx. The
     only difference with real use is that in this file, resource
     contents and registering calls with the EmbeddedResourceManager
     have been written manually instead of by fgrcc. Apart from
     embedded_resources_test.cxx, here are two examples of client usage
     of the EmbeddedResourceManager:

  (a) With EmbeddedResourceManager::getString():

      #include <simgear/embedded_resources/EmbeddedResourceManager.hxx>
      #include <simgear/debug/logstream.hxx>

      [...]

      const auto& resMgr = simgear::EmbeddedResourceManager::instance();
      SG_LOG(SG_GENERAL, SG_INFO,
             "Resource contents: '" <<
             resMgr->getString("/virtual/path/to/resource") << "'");

  (b) With EmbeddedResourceManager::getIStream():

      #include <cstddef>              // std::size_t
      #include <simgear/io/iostreams/sgstream.hxx>
      #include <simgear/embedded_resources/EmbeddedResourceManager.hxx>

      [...]

      sg_ofstream outFile(SGPath("/tmp/whatever"));
      if (!outFile) {
        <handle open error>
      }

      const auto& resMgr = simgear::EmbeddedResourceManager::instance();
      auto resStream = resMgr->getIStream("/virtual/path/to/resource");
      // One possible way of handling errors from resStream[8]:
      // resStream->exceptions(std::ios_base::badbit);

      constexpr std::size_t bufSize = 4096;
      std::unique_ptr<char[]> buf(new char[bufSize]); // intermediate buffer

      do {
        resStream->read(buf.get(), bufSize);
        outFile.write(buf.get(), resStream->gcount());
      } while (*resStream && outFile); // resStream *points* to an std::istream

      <handle possible errors that might have caused to loop to stop
      prematurely>


3) About the XML resource declaration files
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You may want to read the output of 'fgrcc --help', which explains a few
things, in particular how to write an XML resource declaration file that
fgrcc can use. At the time of this writing, such files are already
present as flightgear/src/EmbeddedResources/FlightGear-resources.xml and
flightgear/src/EmbeddedResources/FGData-resources.xml in the FlightGear
repository. In case you need resources from elsewhere, it's easy to add
other XML resource declaration files:

  1) If you want the .cxx/.hxx resource files to be automatically
     generated as part of the FlightGear build:

     Copy and adapt the add_custom_command() call in
     flightgear/src/Main/CMakeLists.txt[9] that invokes fgrcc on
     flightgear/src/EmbeddedResources/FlightGear-resources.xml.

  2) In flightgear/src/Main/CMakeLists.txt, add paths for your new
     fgrcc-generated .cxx and .hxx files to the SOURCES and HEADERS
     CMake variables for the 'fgfs' target.

  3) Assuming you passed for instance
     --init-func-name=initFoobarEmbeddedResources in step 1, add a call
     to initFoobarEmbeddedResources() after this code in fgMainInit()
     (flightgear/src/Main/main.cxx):

      simgear::EmbeddedResourceManager::createInstance();
      initFlightGearEmbeddedResources();


4) The EmbeddedResourceProxy class
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SimGear contains an EmbeddedResourceProxy class that allows one to
access real files or embedded resources in a unified way. When using it,
one can switch from one data source to the other with minimal code
changes, possibly even at runtime (in which case there is obviously no
code change at all).

Sample usage (from FlightGear):

  simgear::EmbeddedResourceProxy proxy(globals->get_fg_root(), "/FGData");
  proxy.setUseEmbeddedResources(false); // can also be set via the constructor

  std::string s = proxy.getString("/some/path");
  std::unique_ptr<std::istream> streamp = proxy.getIStream("/some/path");

This example would retrieve contents from the real file
$FG_ROOT/some/path. If true had been passed in the
proxy.setUseEmbeddedResources() call, it would instead have used the
default-locale version of the embedded resource whose virtual path is
/FGData/some/path.

For more information about this class, see [10] and [11].


Footnotes
=========

[1] E.g., FlightGear or FGData, as long as the path to the latter is
    provided to the FG build system, which is currently possible but not
    required (passing '-D FG_DATA_DIR:PATH=...' to CMake when
    configuring the FlightGear build).

[2] The differences with the QRC format[3] are explained in the output
    of 'fgrcc --help'. Here is the relevant excerpt:

,----
| 1. The <!DOCTYPE RCC> declaration at the beginning should be omitted (or
|    replaced with <!DOCTYPE FGRCC>, however such a DTD currently doesn't
|    exist). I suggest to add an XML declaration instead, for instance:
|
|      <?xml version="1.0" encoding="UTF-8"?>
|
| 2. <RCC> and </RCC> must be replaced with <FGRCC> and </FGRCC>,
|    respectively.
|
| 3. The FGRCC format supports a 'compression' attribute for each 'file'
|    element. At the time of this writing, the allowed values for this
|    attribute are 'none', 'zlib' and 'auto'. When set to a value that is
|    not 'auto', this attribute of course bypasses the algorithm for
|    determining whether and how to compress a given resource (algorithm
|    which relies on the file extension).
|
| 4. Resource paths (paths to the real files, not virtual paths) are
|    interpreted relatively to the directory specified with the --root
|    option. If this option is not passed to 'fgrcc', then the default root
|    directory is the one containing INFILE, which matches the behavior of
|    Qt's 'rcc' tool.
`----

[3] http://doc.qt.io/qt-5/resources.html

[4] The main reason why I wrote the classes in
    simgear/simgear/io/iostreams/{CharArrayStream,zlibstream}.cxx is
    thus not to maximize memory-efficiency with very large resources;
    rather, it is to make the implementation of the following parts
    simple, clean and modular:
      - the resource compiler (fgrcc);
      - the EmbeddedResourceManager.

[5] The EmbeddedResourceManager architecture would make it quite easy to
    also support runtime loading of resources from files (a thing the Qt
    resource system supports), but it is not very clear how interesting
    this would be, compared to having the files loaded from $FG_ROOT.
    Well, maybe for large files [apt.dat.gz & Co] that we would want to
    load but not see in the FGData repository at all. But then there
    would be the requirement, of course, that “something” puts the files
    in a clearly-defined, platform-dependent location known to the
    EmbeddedResourceManager.

[6] https://sourceforge.net/p/flightgear/fgmeta/ci/next/tree/python3-flightgear/rebuild-fgdata-embedded-resources

[7] https://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/embedded_resources/

[8] We know that in some buggy C++ implementations, the
    std::ios_base::failure exception can't be caught, at least not under
    its name, due to some ABI compatibility mess:

      https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66145

    However, it stills causes the program to abort, and since this
    error handling technique makes for much more readable and less
    error-prone code, I think it's still a good way to handle IOStreams
    errors even now, unless you really need to *catch* the
    std::ios_base::failure exception.

[9] flightgear/CMakeModules/GenerateFlightgearResources.cmake in my
    'i18n-and-init-work-v2' branch (not merged into 'next' at the time
    of this writing).

[10] https://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/embedded_resources/EmbeddedResourceProxy.hxx

[11] https://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/embedded_resources/embedded_resources_test.cxx

Expressions (or SGExpressions) are a feature of the SimGear library
and provide a nice way of implementing complex math formulas using XML
syntax. They are supported in many systems within the FlightGear code.

Caution: Expressions do not check if your math creates floating point
exceptions (like division by zero conditions, taking the square root
of a negative number, etc.). This can cause undefined behavior and may
result in NaNs or even Cascading NaNs.  Usage

Expressions are supported in

* Autopilot configuration files
* Particle system configuration files
* Animations (translate, rotate, scale, range, blend)
* The shader technique

Sample Expressions

This is a sample expression for the euation c = sqrt(a*a + b^2).

Children/arguments are parsed in the order they appear in in the file
(or the order in which they are set via property methods).

<expression>
  <sqrt>
    <sum>
      <product>
        <property>/value/a</property>
        <property>/value/a</property>
      </product>
      <pow>
        <property>/value/b</property>
        <value>2</value>
      </pow>
    </sum>
  </sqrt>
</expression>

Supported elements

NOTE: #c in the table below is the number of child nodes required.

+-------------------+----+--------------------------------------------------+
| Function          | #c | Notes                                            |
+-------------------+----+--------------------------------------------------+
| <abs> <fabs>      | 1  |                                                  |
| <acos>            | 1  |                                                  |
| <asin>            | 1  |                                                  |
| <atan2>           | 2  |                                                  |
| <atan>            | 1  |                                                  |
| <ceil>            | 1  |                                                  |
| <clip>            | 3  | clipMin, clipMax, expression                     |
| <cos>             | 1  |                                                  |
| <cosh>            | 1  |                                                  |
| <deg2rad>         | 1  |                                                  |
| <difference> <dif>| 1+ |                                                  |
| <div>             | 2  |                                                  |
| <exp>             | 1  |                                                  |
| <floor>           | 1  |                                                  |
| <log10>           | 1  |                                                  |
| <log>             | 1  |                                                  |
| <max>             | 1+ |                                                  |
| <min>             | 1+ |                                                  |
| <mod>             | 2  |                                                  |
| <pow>             | 2  |                                                  |
| <product> <prod>  | 1+ |                                                  |
| <property>        | 0  | Property name e.g.<property>node/value</property>|
| <rad2deg>         | 1  |                                                  |
| <sin>             | 1  |                                                  |
| <sinh>            | 1  |                                                  |
| <sqr>             | 1  |                                                  |
| <sqrt>            | 1  |                                                  |
| <sum>             | 1+ |                                                  |
| <table>           | 2+ | <entry><ind> 0.0 </ind><dep> 10 </dep></entry>   |
| <tan>             | 1  |                                                  |
| <tanh>            | 1  |                                                  |
| <value>           | 0  | Constant Value e.g. <value>0</value>             |
+-------------------+----+--------------------------------------------------+

Hints and tips
--------------

1. There is no function for rounding, hwoever "Round half up" can be
   achieved as follows

  <expression>
    <floor>
      <sum>
        <property>your/property/here</property>
        <value>0.5</value>
      </sum>
    </floor>
  </expression>

2. Interpolation tables can be useful when a formula cannot be found,
   In the example below <ind> is the indepdendant variable and
   <dep> is the dependant variable. What this table does is as follows
   - values below 0.2 will be 10
   - values above 0.2 and between 1.0 will be interpolated between 10
     and 0
   - values above 1.0 will be 0

    <table>
      <entry><ind> 0.0 </ind><dep> 10 </dep></entry>
      <entry><ind> 0.2 </ind><dep> 10 </dep></entry>
      <entry><ind> 1.0 </ind><dep>  0 </dep></entry>
    </table>

fgjs -- a small program for creating a basic FlightGear joystick
        configuration

fgjs requires plib to be installed on your system.  If you've
successfully installed and built FlightGear then you should be
all set

Build instructions
At this point, fgjs has only been built and tested under Linux,
so the makefile is a simple one. cd into the directory in which
the fgjs source resides and type 'make' and, if you are lucky,
all will go well.  You can e-mail me (apeden@earthlink.net) any
changes needed to make it work on other systems.  It's quite
possible that this program will become part of the regular
FlightGear package so

Running
Set up your joystick and make sure it works with js_demo from the
FlightGear distribution.  Upon executing fgjs, it will prompt you
to move the control you wish to use for elevator, ailerons, etc.
Note that when being prompted for an analog control, you can skip
the current one by pressing any button and vice-versa when being
prompted for a button.  You may want to do this if for, as an
example, rudder if you have only one joystick or your joystick
doesn't have as many analog axes as FlightGear supports.

Once you've run with this configuration, you may wish to tune
the dead-band a bit (see fgfsrc.js) as the default, 0.02, may
be too narrow for your particular hardware/taste.


And last, but not least, this thing needs a GUI!!!!  Hopefully,
the joystick handling code and interface code are separate
enough that using that a GUI version could be built using this
source as a starting point.

FlightGear Flight Recorder Mini-HOWTO

Thorsten Brehm
Started in August 2011
Last revised: 2011-09-26


FlightGear provides a customizable flight recorder capable of capturing
any selection of properties described via XML configuration files.
The recorder is currently used for the replay system.


Feature Brief
-------------
* Generic recording system, adaptable to any aircraft/data, provided that
  data is accessible via the property tree. No hard-coded selections or
  assumptions on properties to be recorded.
* Configuration read from XML files or the property tree itself.
* Interpolation method configurable per recorded/replayed signal.
* Adaptable recording resolution per signal.
* Multiple configurations supported.


Quick Start: Basic Configuration
--------------------------------
To configure and adapt the flight recorder, add a "/sim/flight-recorder"
section to your aircraft -set.xml file.

Example:

<sim>

  <!-- ... -->

  <flight-recorder>
    <replay-config type="int">0</replay-config>
    <config n="0"
        include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml">
      <name type="string">My Aircraft's Flight Recorder</name>
      <!-- Custom properties -->
      <signal>
        <type>float</type>
        <property type="string">/controls/gear/nosegear-steering-cmd-norm</property>
        <interpolation>linear</interpolation>
      </signal>
      <!-- More custom signals here -->
    </config>
  </flight-recorder>

      <!-- ... -->

</sim>

Default type for each signal is "float". Default "interpolation" method
is "linear" (for float/double). Default values may be omitted. See
configuration details below.


Generic Configuration Files
---------------------------
Select one of the default configuration files to specify the basic
properties to be recorded. It's not recommended to specify all
properties to be recorded individually.
The following generic files are provided:

* /Aircraft/Generic/flightrecorder/generic-piston-propeller-4.xml
  Matches propeller aircraft with 4 piston engines, 4 tanks,
  3 retractable gear.
  It is the same configuration that was hard-coded for the replay system
  up to FlightGear 2.4.0. To provide backward compatibility this
  configuration is loaded by default, unless an aircraft provides a
  specific flight recorder configuration.

* /Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml
  Matches propeller aircraft with 1 piston engines, 2 tanks, 3 fixed
  gear.

* /Aircraft/Generic/flightrecorder/generic-turboprop-2.xml
  Matches turboprop aircraft with 2 turbines/propellers, 4 tanks,
  3 retractable gear.

* /Aircraft/Generic/flightrecorder/generic-jet.xml
  Matches jet aircraft with 2 jet engines, 4 tanks.

* /Aircraft/Generic/flightrecorder/generic-glider.xml
  Matches gliders (no engines, no tanks, single fixed gear).

* /Aircraft/Generic/flightrecorder/generic-helicopter.xml
  Matches helicopters with main and tail rotor (tested with YASim).

If none of the generic files matches your aircraft, simply use a
configuration which covers more than you need. Alternatively, copy the
contents of one of these generic files to your aircraft, and adapt as
needed (see below).

FDM experts are welcome to add more generic configuration files to
/Aircraft/Generic/flightrecorder - such as YASim-/JSBSim-specific
configurations, and configurations for other types of aircraft
(balloons, airships, ...).


Generic Components
-----------------
The generic configuration files in turn include a set of generic
components. If you copy the contents of a generic file to your aircraft,
you can adapt the components to your needs. See examples.
It is not recommended to copy the contents of the _component_ files to
an aircraft though (causes too much hassle and dependencies).

Engine Selection:
 * /Aircraft/Generic/flightrecorder/components/engine-jet.xml
   Records properties of a single jet engine.
   For multiple jet engines, use "count". Example for 4 jets:
     <signals include="/Aircraft/Generic/flightrecorder/components/engine-jet.xml">
       <count>4</count>
     </signals>

 * /Aircraft/Generic/flightrecorder/components/engine-piston.xml
   Records properties of a single piston engine and propeller.
   For multiple piston engines, use "count" (see "jet" example).

 * /Aircraft/Generic/flightrecorder/components/rotor.xml
   Records properties of a single helicopter rotor (tested with YASim).
   To use this, provide the base property path to the rotor as "prefix".
   Example recording the rotor below "/rotors/main":
     <signals include="/Aircraft/Generic/flightrecorder/components/rotor.xml">
         <prefix type="string">/rotors/main</prefix>
     </signals>

Gear Selection:
 * /Aircraft/Generic/flightrecorder/components/gear-fixed.xml
   Records properties of a single non-retractable gear.
   For multiple fixed gear, use "count" (see "jet" example).

 * /Aircraft/Generic/flightrecorder/components/gear-retractable.xml
   Records properties of a single retractable gear.
   For multiple retractable gear, use "count" (see "jet" example).

Tanks:
 * /Aircraft/Generic/flightrecorder/components/tanks.xml
   Records properties of a single fuel tank.
   For multiple fuel tanks, use "count" (see "jet" example).

Other:
 * /Aircraft/Generic/flightrecorder/components/surfaces.xml
   Records properties of flight control surfaces. Include this
   for aircraft (with wings). Not useful for helicopters,
   balloons, ...

 * /Aircraft/Generic/flightrecorder/components/faults-engines.xml
   Records fault properties of a single engine. Only include this
   if your aircraft supports fault simulation.
   For multiple engines, use "count" (see "jet" example). If used,
   it should be compined with piston or jet engine.

 * /Aircraft/Generic/flightrecorder/components/environment.xml
   Records properties of environment/weather (visibility,
   temperature - but _not_ cloud position...).

 * /Aircraft/Generic/flightrecorder/components/position.xml
   Records properties of a the aircrafts main position (latitude,
   longitude, velocities, ...).
   This is the most important component. Always include this.

 * /Aircraft/Generic/flightrecorder/components/controls.xml
   Records most important flight controls (rudder, aileron,
   elevator, ...). Always include this.


Custom Properties
-----------------
When the generic or component files are not be sufficient to record or
replay aircraft-specific effects, you can add custom properties (signals
to be recorded) to the configuration.
Each signal consits of a recording type/resolution (which does _not_
need to match the actual type in the property tree!), the path to the
property and interpolation type.

Example recording some additional custom properties:
  <sim>
    <flight-recorder>
      <config n="0"
        include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml">
        <!-- Add custom properties here -->
        <signal>
          <type>float</type>
          <property type="string">/controls/gear/nosegear-steering-cmd-norm</property>
        </signal>
        <signal>
          <type>double</type>
          <interpolation>rotational-deg</interpolation>
          <property type="string">/ai/model/carrier/alpha-angle-deg</property>
        </signal>
        <signal>
          <type>bool</type>
          <property type="string">/controls/panel/custom-switch</property>
        </signal>
      </config>
    </flight-recorder>
  </sim>


Signal Configuration
--------------------
Template:
  <signal>
    <type>bool</type>
    <interpolation>angular-deg</interpolation>
    <property type="string">/controls/panel/custom-switch</property>
  </signal>

* type: The signal's type specifies the recording resolution - not the
  type of the original property. The following types are supported:

  - double: 8 byte/sample
  - float:  4 byte/sample (default)
  - int:    4 byte/sample, integer
  - int16:  2 byte/sample, integer
  - int8:   1 byte/sample, integer
  - bool:   1 bit/sample (yes, 1 bit. 8 bools per byte).

  String type is unsupported (too expensive).

* interpolation: Specifies how values are interpolated during replay, i.e.
  when replay is in slow-motion mode and more frames/second are required
  than recorded, or when replaying data from the medium/long term memory.
  Supported methods:
    - discrete: No interpolation. Default for integer/bool types.
    - linear: Standard linear interpolation. Default for float/double.
    - angular-rad (or angular): Angular values in radians (0-2pi).
    - angular-deg: Angular values in degrees (0-360).

* property: Path to the property to be recorded.


Advanced Configuration
----------------------
- Multipe recorder configurations for a single aircraft are supported
  (multiple "<config n=..>" sections for n=0,1,...).
  Active configuration to be used for the replay system is selected via
     /sim/flight-recorder/replay-config (= 0,1,...).
  This can be useful for specific recorders for specific scenarios,
  which should not be used by default. For example, a specific recorder
  configuration could be provided which also records the position of
  an aircraft carrier, of other AI aircraft, ...
  This may also be useful for future use, i.e. to select another flight
  recorded configuration for a different purpose, such as for the
  multiplayer system.

- Flight recorder configuration can be adapted during run-time
  (configuration is visible in the property browser below
  /sim/flight-recorder). However it is necessary to reset (reinit) the
  replay subsystem first - which also erases earlier recordings. It is
  not possible to mix recordings of different configurations on to a
  single "tape".

- Each configuration should be given a name. Useful for a (future)
  selection GUI, when multiple configurations are available.


Optimizing Performance
----------------------
- Recording properties consumes memory and also CPU time. A few
  additional properties don't matter much, but avoid execessive numbers.
  Reduce the resolution (type) of signals to the minimum necessary to
  save space.
- Use "bool" types where possible, they are most efficient.
- Avoid recording with "double" resolution (type "double"). Use "float"
  instead - even if the original property in the property tree is a
  "double" (almost all of them do). "float" precision is almost always
  sufficient for recording/replay purposes, with few exceptions (like
  latitude/longitude properties).
- Use int16/int8 for "small" integer values.


Recording/Replay Limits
-----------------------
- All properties can be recorded, however, only writable properties can
  be replayed. Properties marked as read-only, or tied properties not
  implementing the "set" method cannot be replayed.
- Replaying a property overwrites the property's value. However, other
  sources may also write to the same property - such as Nasal code,
  autopilot rules etc. When multiple sources "fight" over a property's
  value then the last update "wins" - resulting in a dependency to an
  unknown/random sequence. Hence, during deplay, try to disable other
  sources writing to properties which were recorded and should be
  replayed.
  If the other source cannot be disabled, check if you're recording the
  right property. It may be better to record the input properties of the
  other source instead (i.e. the inputs processed by the Nasal or
  autopilot rule).

__end__

FlightGear GUI Mini-HOWTO

David Megginson
Started: 2003-01-20
Last revised: 2003-01-20


FlightGear creates its drop-down menubar and dialog boxes from XML
configuration files under $FG_ROOT/gui.  This document gives a quick
explanation of how to create or modify the menubar and dialogs.  The
toolkit for the FlightGear GUI is PUI, which is part of plib.

All of the XML files use the standard FlightGear PropertyList format.


MENUBAR
-------

FlightGear reads the configuration for its menubar from
$FG_ROOT/gui/menubar.xml.  The file consists of a series of top-level
elements named "menu", each of which defines on of the drop-down
menus, from left to right.  Each menu contains a series of items,
representing the actual items a user can select from the menu, and
each item has a series of bindings that FlightGear will activate when
the user selects the item.

Here's a simplified grammar:

  [menubar] : menu*

  menu : label, item*

  item : label, enabled, binding*

The bindings are standard FlightGear bindings, the same as the ones
used for the keyboard, mouse, joysticks, and the instrument panel.
Any commands allowed in those bindings are allowed here as well.

Here's an example of a simple menubar with a "File" drop-down menu and
a single "Quit" item:

  <PropertyList>

   <menu>
    <label>File</label>

    <item>
     <label>Quit</label>
     <binding>
      <command>exit</command>
     </binding>
    </item>

  </PropertyList>

PUI menus do not allow advanced features like submenus or checkmarks.
The most common command to include in a menu item binding is the
'dialog-show' command, which will open a user-defined dialog box as
described in the next section.


DIALOGS
-------

The configuration files for XML dialogs use a nested structure to set
up dialog boxes.  The top-level always describes a dialog box, and the
lower levels describe the groups and widgets that make it up.  Here is
a simple, "hello world" dialog:

  <PropertyList>

   <name>hello</name>

   <width>150</width>
   <height>100</height>
   <modal>false</modal>
   <draggable>true</draggable>
   <resizable>true</resizable>

   <text>
    <x>10</x>
    <y>50</y>
    <label>Hello, world</label>
    <color>
     <red>1.0</red>
     <green>0.0</green>
     <blue>0.0</blue>
    </color>
   </text>

   <button>
    <x>40</x>
    <y>10</y>
    <legend>Close</legend>
    <binding>
     <command>dialog-close</command>
    </binding>
   </button>

  </PropertyList>

The dialog contains two sub-objects: a text field and a button.  The
button contains one binding, which closes the active dialog when the
user clicks on the button.

Coordinates are pseudo-pixels.  The screen is always assumed to be
1024x768, no matter what the actual resolution is.  The origin is the
bottom left corner of the screen (or parent dialog or group); x goes
from left to right, and y goes from bottom to top.

All objects, including the top-level dialog, accept the following
properties, though they will ignore any that are not relevant:

 x - the X position of the bottom left corner of the object, in
   pseudo-pixels.  The default is to center the dialog.

 y - the Y position of the bottom left corner of the object, in
   pseudo-pixels.  The default is to center the dialog.

 width - the width of the object, in pseudo-pixels.  The default is
   the width of the parent container.

 height - the height of the object, in pseudo-pixels.  The default is
   the width of the parent container.

 border - the border thickness, in pseudo-pixels.  The default is 2.

 color - a subgroup to specify the dialogs color:
  red   - specify the red color component of the color scheme.
  green - specify the green color component of the color scheme.
  blue  - specify the blue color component of the color scheme.
  alpha - specify the alpha color component of the color scheme.

 font - a subgroup to specify a specific font type
  name - the name of the font (excluding it's .txf extension)
  size - size of the font
  slant -  the slant of the font (in pseudo-pixels)

 legend - the text legend to display in the object.

 label - the text label to display near the object.

 property - the name of the FlightGear property whose value will
   be displayed in the object (and possibly modified through it).

 binding - a FlightGear command binding that will be fired when the
   user activates this object (more than one allowed).

 keynum - the key code of a key that can be used to trigger the
   widget bindings via keyboard (e.g. <keynum>97</keynum> for
   the "a" key.

 key - like "keynum", but takes a character ("a", "A", "Shift-a",
   "Shift-A", "Ctrl-a", "%", etc.), or symbolic key name ("Tab",
   "Return" = "Enter", "Esc" = "Escape", "Space", "&amp;" = "and",
   "&lt;", "&gt;", "F1" -- "F12", "Left", "Up", "Right", "Down",
   "PageUp", "PageDn", "Home", "End", "Insert"). Note that you
   can't use "<", ">", and "&" directly.

 default - true if this is the default object for when the user
   presses the [RETURN] key.

 visible - if set to false, hides the whole widget that it is used
   in, along with its children. There's no empty space reserved
   for such widgets. The "visible" property can also be used to hide
   other XML groups from the layouter.

Objects may appear nested within the top-level dialog or a "group"
or a "frame" object.  Here are all the object types allowed, with their
special properties:


dialog
------

The top-level dialog box; the name does not actually appear in the
file, since the root element is named PropertyList.

  name - (REQUIRED) the unique name of the dialog for use with the
    "dialog-show" command.

  modal - true if the dialog is modal (it blocks the rest of the
    program), false otherwise.  The default is false.

  draggable - false if the dialog is not draggable. The default is true.

  resizable - false if the dialog is not resizable. The default is false.

  nasal - Nasal definition block
    open - Nasal script to be executed on dialog open
    close - Nasal script to be executed on dialog close

All Nasal code runs in a dialog namespace. Nasal bindings can
directly access variables and functions defined in an <open> block.
settimer() and setlistener() functions have to be removed manually
in the <close> block if they shouldn't remain active.


Example:

<PropertyList>

 <name>sample</name>
 <width>500</width>
 <height>210</height>
 <modal>false</modal>

 <text>
  ...
 </text>

 <button>
  ...
 </button>

</PropertyList>


group and frame
---------------

A group of subobjects.  This object does not draw anything on the
screen, but all of its children specify their coordinates relative to
the group; using groups makes it easy to move parts of a dialog
around.

A frame is a visual representation of a group and has  a border and an
adjustable background color.

Example:

  <group>
   <x>0</x>
   <y>50</y>

   <text>
    ...
   </text>

   <input>
    ...
   </input>

   <button>
    ...
   </button>

  </group>


input
-----

A simple editable text field.

Example:

  <input>
   <x>10</x>
   <y>60</y>
   <width>200</width>
   <height>25</height>
   <label>sea-level temperature (degC)</label>
   <property>/environment/temperature-sea-level-degc</property>
  </input>


text
----

A non-editable text label.

Example:

  <text>
   <x>10</x>
   <y>200</y>
   <label>Heading</label>
  </text>

  <text>
   <x>10</x>
   <y>200</y>
   <label>-9.9999</label> <!-- placeholder for width -->
   <format>%-0.4f m</format>
   <property>/foo/altitude</property>
  </text>


checkbox
--------

A checkbox, useful for linking to boolean properties.

Example:

  <checkbox>
   <x>150</x>
   <y>200</y>
   <width>12</width>
   <height>12</height>
   <property>/autopilot/locks/heading</property>
  </checkbox>



button
------

A push button, useful for firing command bindings.

  one-shot - true if the button should pop up again after it is
    pushed, false otherwise.  The default is true.

  <button>
   <x>0</x>
   <y>0</y>
   <legend>OK</legend>
   <binding>
    <command>dialog-apply</command>
   </binding>
   <binding>
    <command>dialog-close</command>
   </binding>
   <default>true</default>
  </button>



combo
-----

A pop-up list of selections.

  value - one of the selections available for the combo.  There may be
  any number of "value" fields.

Example:

  <combo>
   <x>10</x>
   <y>50</y>
   <width>200</width>
   <height>25</height>
   <property>/environment/clouds/layer[0]/type</property>
   <value>clear</value>
   <value>mostly-sunny</value>
   <value>mostly-cloudy</value>
   <value>overcast</value>
   <value>cirrus</value>
  </combo>



list
----

like "combo", but displays all values in a scrollable list box with
slider on the right side. Updates the <property> to the selected
entry. On <dialog-update> re-scans the <value> nodes and updates
the list.



airport-list
------------

like "list", but fills the list automatically with all airports known
to FlightGear. Calls bindings on airport selection and returns the
selected entry in <property> on dialog-apply. Interprets <property>
as search term on dialog-update.



property-list
-------------

like "list", but shows a list of properties from the global property
tree. The widget handles navigation in the property tree. It calls its
bindings on property selection and returns the path of the selected
property in <property> on dialog-apply. It's up to the caller to check
if the path belongs to a dir node or a value node. The widget shows
the contents of the dir property given in <property> on dialog-apply.
It does *not* handle setting of property values! Clicking on some
entries with the "control" or "shift" key pressed has a special meaning:

Ctrl +
  "."     ->  toggle verbose mode (shows flags, listeners, dir-values)
  ".."    ->  go to root node
  (bool)  ->  toggle bool value

Shift +
  "."     ->  dump contents of that tree level to the terminal

The flags printed after the node type have the following meaning:

  r       ->  read protected
  w       ->  write protected
  R       ->  trace read operations    (in the terminal window)
  W       ->  trace write operations
  A       ->  archive bit set
  U       ->  user archive bit set
  P       ->  preserved bit set (value is preserved on sim-reset)
  T       ->  property is "tied"

  Ln      ->  number of listeners attached to this node



select
------

A box with arrow buttons that cycle through a list of values.

Example:

  <select>
   <x>10</x>
   <y>50</y>
   <width>200</width>
   <height>25</height>
   <property>/sim/aircraft</property>
   <value>bo105</value>
   <value>ufo</value>
  </select>



slider
------

A horizontal or vertical slider for setting a value.

  vertical - true if the slider should be vertical, false if it should
    be horizontal.  The default is false.

  min - the minimum value for the slider.  The default is 0.0.

  max - the maximum value for the slider.  The default is 1.0.

  step - set to non-null if slider should move in steps.  The default is 0.0 (off).

  pagestep - set to non-null to enable page-stepping.  The default is 0.0 (off).

  fraction - size of the slider handle. Range: 0..1.  The default is 0.0 (minimum).

Example:

  <slider>
   <x>10</x>
   <y>50</y>
   <width>200</width>
   <property>/environment/visibility-m</property>
   <min>5</min>
   <max>50000</max>
  </slider>


dial
----

A circular dial for choosing a direction.

  wrap - true if the dial should wrap around, false otherwise.  The
    default is true.

  min - the minimum value for the dial.  The default is 0.0.

  max - the maximum value for the dial.  The default is 1.0.

Example:

  <dial>
   <x>10</x>
   <y>50</y>
   <width>20</width>
   <property>/environment/wind-from-direction-deg</property>
   <min>0</min>
   <max>360</max>
  </dial>


textbox
-------

The text will be retrieved/buffered from/within a specified
property tree, like:

<textbox>
    <!-- position -->
    <x>100</x>
    <y>100</y>

    <!-- dimensions -->
    <width>200</width>
    <height>400</height>

    <property>/gui/path-to-text-node/contents</property>

    <slider>15</slider> <!--width for slider -->
    <wrap>false</wrap> <!-- don't wrap text; default: true -->
    <top-line>0</top-line <!-- line to show at top, -ve numbers: show last line -->

    <editable>true</editable> <!-- if the puLargeInput is supposed to be editable -->
</textbox>


hrule/vrule
-----------

Draws a horizontal/vertical line that, by default, expands to full width/height.
Its thickness can be set with <pref-height>/<pref-width>.

  <hrule>
    <color>
      <red>1.0</red>
      <green>0.0</green>
      <blue>0.0</blue>
    </color>
    <pref-height>2</pref-height>
  </hrule>




GLOBAL SETTINGS ("THEMES")
--------------------------

FlightGear reads GUI style information from /sim/gui/, which is by default
loaded from file $FG_ROOT/gui/style.xml.  This file contains one <font> and
one <colors> group:


global font settings
--------------------

  <sim>
    <gui>
      <font>
        <name type="string">Helvetica.txf</name>
        <size type="float">15</size>
        <slant type="float">0</slant>
      </font>
    </gui>
  <sim>

<name> can either be the name of a built-in bitmap font (one of:
"FIXED_8x13", "FIXED_9x15", "TIMES_10", "TIMES_24", "HELVETICA_10",
"HELVETICA_12", "HELVETICA_14", "HELVETICA_18", "SANS_12B"), or the
name of a texture font in the $FG_FONT directory. $FG_FONT is by
default set to $FG_ROOT/Fonts/. Properties <size> and <slant> are
only applied to texture fonts, and otherwise ignored.


global color settings
---------------------

These define the color of the splash screen font, and the color of the
GUI elements. All colors are in /sim/gui/colors/ and follow the same
pattern:

  <sim>
    <gui>
      <colors>
        <!-- splash screen font color; ignores <alpha> value -->
        <splash>
          <red type="float">1.0</red>
          <green type="float">0.9</green>
          <blue type="float">0.0</blue>
        </splash>
      </colors>
    </gui>
  </sim>



As listed above, FlightGear implements several GUI elements:

(1)    "dialog"      "group"         "frame"       "hrule"      "vrule"
       "list"        "airport-list"  "input"       "text"       "checkbox"
       "radio"       "button"        "combo"       "slider"     "dial"
       "textbox"     "select"


The underlying plib library uses six colors for each GUI element.
These are:

(2)    "background"  "foreground"    "highlight"
       "label"       "legend"        "misc"


"button", for example, uses the first four colors from (2), while it
ignores "legend" and "misc" color. "text" only uses "label", and ignores
the rest. In some cases the use of colors isn't obvious and you have to
try or look up the plib sources to be sure. GUI colors can be defined
for each of the categories from (1) and (2), and for combinations of
them:

(3)    "button-legend"   "input-misc"    etc.


FlightGear has default colors for (2) built-in. Let's call them (0).
And this is how colors for individual GUI elements are determined,
if, for example, a button is to be drawn:

  For the button's background:
  a. read the hard-coded default "background" color from (0) as base
  b. merge the global "background" color from (2) in (if defined)
  c. merge a global color "button-background" from (3) in (if defined)
  d. merge a specific <color> from the dialog's XML file in (if defined)

  Repeat the four steps for the button's "foreground", "highlight",
  etc. color.




If you write a style file, you'll most likely start with the colors
from (2):

 <sim>
   <gui>
     <colors>
       <background>
         <red type="float">0.6</red>
         <green type="float">0.0</green>
         <blue type="float">0.0</blue>
         <alpha type="float">1.0</alpha>
       </background>

       <foreground>
       ...

This makes all dialogs dark red. But you don't, for example, want buttons
to be red, but yellow. So you define another color for buttons:

       <button>
         <red type="float">1.0</red>
         <green type="float">0.9</green>
         <blue type="float">0.0</blue>
         <alpha type="float">1.0</alpha>
       </button>
       ...

This sets all of a button's six colors (2) to some shades of red. plib
does this automatically. The lower and right border ("foreground") will
be darker, the upper and left border will be lighter ("highlight").
If you aren't happy with plib's choice, you can set each of the colors
explicitly. Let's say, we want the text on the button blue (3):

       <button-legend>
         <red type="float">0.3</red>
         <green type="float">0.3</green>
         <blue type="float">1.0</blue>
         <alpha type="float">1.0</alpha>
       </button-legend>
       ...

To set the cursor color from input fields, you'd define "input-misc",
etc.


You can change colors and font at runtime. Just open the property
browser, go to /sim/gui/colors and change whatever you like. The
new color will only take effect, though, if you re-init the GUI.
There's a menu entry for that, and you can define a key binding
for it:

  <key n="99">
    <name>c</name>
    <desc>Re-init GUI</desc>
    <binding>
      <command>reinit</command>
      <subsystem>gui</subsystem>
    </binding>
  </key>

Note that this will currently close all open dialogs!


__end__

This document describes the *new* HUD system that will be first released
with fgfs >0.9.10. For the old system see $FG_ROOT/Docs/README.xmlhud.
Note that the old system is scheduled for removal, and that the new system
is work in progress. So it's up to you to choose the lower risk.  :-)






###############################################################################


A HUD configuration file may contain 3 types of information:

  (1) global settings
  (2) HUD instrument definitions
  (3) imports of further HUD config files





(1) global settings ===========================================================

These can be used to override settings in the global property tree. Currently
only bool <enbale-3d> is supported. It allows a HUD to define itself if it is
a 2D HUD (false) or a 3D HUD (true). 2D HUDs always remain in the screen plane,
while 3D HUDs always remain in a position relative to the aircraft.

Example:

    <enable-3d>true</enable-3d>





(2) HUD instrument definitions ================================================

These define one single HUD "item" (instrument or label), and consist of several
properties. Some of those are standardized property groups that can be used
in many places. These shall be explained first.



(2.1) standardized property groups --------------------------------------------

  1. <condition> group
  2. input channel group
  3. <option>s



(2.1.1) <condition> ...........................................................

These define conditions that are either "true" or "false". They are used to
hide/unhide whole items, or to set other item states (blinking on/off) etc.
You find detailed documentation about them in $FG_ROOT/Docs/README.conditions.



(2.1.2) input channel groups .................................................

These define an input channel to the HUD instrument and serve as interface
between property system and the instrument. A complete channel definition
looks like this (defaults in comments):

  <input>
      <property>/position/altitude-agl-ft</property>  <!-- no default -->
      <factor>0.3048</factor>                         <!-- 1.0 -->
      <offset>2.0</offset>                            <!-- 0.0 -->
      <damp>1.5</damp>                                <!-- 0.0 (no damping) -->
      <min>0.0</min>                                  <!-- -infinity -->
      <max>10000</max>                                <!-- +infinity -->
  </input>

Input channels are only called <input> for instruments that only have one
channel. Other instruments may have two or more channels, called <bank-input>,
<pitch-input> etc. All of them will have the same member properties and behave
the same.

An input channel will preprocess the raw property value for the HUD instrument.
The property may be of any type (bool, int, long, float, double, string), but
not all types will make sense in every situation. The HUD instrument will only
see the final value, which is calculated as:


  v = <property> * <factor> + <offset>
  if (<damp>)     v = EWMA_lowpass(v, <damp>)
  if (v < <min>)  v = <min>
  if (v > <max>)  v = <max>


The EWMA_lowpass filter (Exponentially Weighted Moving Average) is calculated
like so:


  coeff = 1.0 - 1.0 / 10^<damp>
  v = average = (average * coeff) + (v * (1.0 - coeff))


That is, a <damp> value of 0 will cause no damping. A damping value of 1 will
make a coefficient of 0.9, which means that the resulting value will be 9/10
of the average plus 1/10 of the new value. A damping value of 2 will make
a coefficient of 0.99 and hence result in a value of 99/100 the average plus
1/100 the new value etc. The higher the <damp> value, the more damped will
the output value be.




2.1.3 <option> ................................................................

Most HUD instruments accept one or more options from a common set. It will be
explaind in the respective intrument descriptions which options are actually
used by that instrument. Possible values are:

  <option> autoticks </option>
  <option> vertical </option>   \___orientation of <tape>
  <option> horizontal </option> /
  <option> top </option>          \
  <option> left </option>         |___place of numbers in <tape>, <gauge>
  <option> bottom </option>       |   top/bottom for turn-bank-indicator, etc.
  <option> right </option>        /
  <option> both </option>           _left/right for vert. and top/bottom for hor.
  <option> noticks </option>
  <option> arithtic </option>
  <option> decitics </option>
  <option> notext </option>       ___no numbers on <tape>


Example:

  <tape>
      <option>left</option>
      <option>vertical</option>
      ...
  </tape>






(2.1) properties common to all instruments ------------------------------------

All HUD instruments will accept the following common properties (shown on
a <tape> instrument):


  <tape>
      <name>foo tape</name>
      <x>-100</x>                        <!-- 0 == center -->
      <y>-60</y>                         <!-- 0 == center -->
      <width>20</width>                  <!-- 0 -->
      <height>120</height>               <!-- 0 -->
      <condition>...</condition>         <!-- see section 2.1.1; default: true -->
      ...
  </tape>

The <name> is only a description for the instrument to make reading the config
easier. It's output in --log-level=info, but not otherwise used. The coordinates
define the place and size of the instrument. They are relative to the origin of
their parent, which is the middle of the HUD/screen by default. Positive <x> are
on the right, positive <y> in the upper half. The <condition> hides/reveals the
whole instrument.






(2.2) HUD instruments ---------------------------------------------------------




(2.2.1) <label> ...............................................................

Draws a formatted string or number.

Text:
  <format>   ... printf-style format with only one % item.  Example:  "%2.3lf ft"
  <prefix>   ... prefix text  \___ in addition to the <format>
  <postfix>  ... postfix text /
  <halign>   ... one of "left", "center" (default), "right".

Box:
  <box>      ... draw box around label (default: false)
  <option>   ... one of (left|right|top|bottom)  ... draw arrow on this side
  <pointer-width>  ... size of pointer base
  <pointer-lenfth> ... distance of base--peak

  <blinking>
      <interval>                  ... on/off-time in seconds (default: -1 == off)
      <condition>...</condition>  ... see secion 2.1.1       (default: true)
  </blinking>

TODO:
  <digit>    ... number of insignificant digits (those will be printed smaller)



Example:

  <label>
      <name>G Load</name>
      <x>-40</x>
      <y>25.5</y>
      <width>1</width>
      <height>1</height>

      <input>
          <property>/accelerations/pilot/z-accel-fps_sec</property>
          <factor>-0.03108095</factor>
          <damp>1.3</damp>
      </input>

      <format>%2.1f</format>
      <halign>right</halign>
      <box>true</box>
      <option>bottom</option>    <!-- pointer on the lower edge -->

      <blinking>
          <interval>0.25</interval>
          <condition>
              <or>
                  <less-than>      <!-- G load > 2.0 -->
                      <property>/accelerations/pilot/z-accel-fps_sec</property>
                      <value>-64.3481</value>
                  </less-than>

                  <greater-than>   <!-- G load < -1.0 -->
                      <property>/accelerations/pilot/z-accel-fps_sec</property>
                      <value>31.17405</value>
                  </greater-than>
              </or>
          </condition>
      </blinking>
  </label>









(2.2.2) <tape> ................................................................
SCALE:
    input
    major-divisions
    minor-divisions
    modulo
    display-span

TAPE:
    tick-bottom
    tick-top
    tick-right
    tick-left
    cap-bottom
    cap-top
    cap-right
    cap-left
    marker-offset
    enable-pointer
    zoom

    pointer-type   (moving|fixed)
    tick-type      (circle|line)
    tick-length    (constant|variable)









(2.2.3) <dial> ................................................................
SCALE:
    input
    major-divisions
    minor-divisions
    modulo
    display-span

TAPE:
    radius
    divisions








(2.2.4) <gauge> ...............................................................
SCALE:
    input
    major-divisions
    minor-divisions
    modulo
    display-span






(2.2.5) <turn-bank-indicator> .................................................
    bank-input
    sideslip-input
    gap-width
    bank-scale








(2.2.6) <ladder> ..............................................................
    pitch-input
    roll-input
    display-span
    divisions
    screen-hole
    compression-factor
    enable-fuselage-ref-line
    enable-target-spot
    enable-velocity-vector
    enable-drift-marker
    enable-alpha-bracket
    enable-energy-marker
    enable-climb-dive-marker
    enable-glide-slope-marker
    glide-slope
    enable-energy-marker
    enable-waypoint-marker
    enable-zenith
    enable-nadir
    enable-hat
    type       (pitch|climb-dive)









(2.2.7) <runway> ..............................................................
    arrow-scale
    arrow-radius
    line-scale
    scale-dist-nm
    outer_stipple
    center-stipple
    arrow-always

reads directly:
    /position/altitude-agl-ft,
    /sim/view[0]/config/pitch-pitch-deg
    /sim/view[0]/config/pitch-heading-deg





(2.2.8) <aiming-reticle> ......................................................

Draws MIL-STD-1787B aiming reticle. Size of bullet and inner circle are
determined from <width>. The outer circle radius is changeable at runtime.

  <active-condition> ... true:  stadiametric (4.2.4.4)  (default)
                         false: standby (4.2.4.5)
  <diameter-input>   ... input channel: diameter of outer circle relative to
                         inner circle; default: 2.0 (= twice as big)







(3) <import> ==================================================================

Imports another HUD config into the current one. This can be a file defining
a single instrument ($FG_ROOT/Huds/Instruments/*.xml), a set of instruments
($FG_ROOT/Huds/Sets/*.xml) or a mixture of both (for example a complete HUD
on its own). The x/y offets moves the reference point for the included items
relative to the current reference point.

    <import>
        <path>Huds/Sets/controls.xml</path>
        <x-offset>-100</x-offset>
        <y-offset>70</y-offset>
    </import>

Imported files can import further files. This is allowed for up to 10 levels.
This is an arbitrary number and can easily be changed in the code if necessary.

When fgfs is called with --log-level=info, then it outputs a graphical trees
of all loaded/imported files, with the instruments shown as leafs.

Internals
---------

The core of FlightGear is the property system. This is a tree like internal
representation of global variables. The property system is explained more
in detail later on.

FlightGear' way of doing things is breaking it up into small pieces. There is
(for example) animation code that reacts on property changes. There is also a
Flight Dynamics model (FDM) that (amongst other things) updates properties.
There is a menu system that can display and alter properties. Then we have
sound code that plays sound based on ... properties.

Maybe you see a pattern evolve by now.

All subsystems are almost self containing. Most of the time they only read the
values of some properties, and sometimes they alter other properties. This is
the basic way of communicating between subsystems.


Property System
---------------

The property system is best described as an in-memory LDAP database which holds
the state of global variables. The system has a tree like hierarchy (like a
file system) and has a root node, sub nodes (like subdirectories) and end-nodes
(variables).

All variables are kept internally as raw values and can be converted to any
other supported type (boolean, int, float double and string).

Like a file system, every node can be accessed relative to the current node, or
absolute to the root node.

The property system also allows aliasing nodes to other nodes (like symbolic
linking files or directories to other files or directories) and may be assigned
read-only or read-write.

If necessary it would be possible for parts of the program to hold it's own
property tree, which is inaccessible from the global property tree, by keeping
track of it's own root-node.

Property I/O code allows one to easily read the tree from, or write the tree to
an XML file.


Subsystems
----------

To add a new subsystem you would have to create a derived class from
SGSubsystem and define at least a small set of functions:

    class FGFX : public SGSubsystem
    {
    public:

      FGFX ();
      virtual ~FGFX ();

      virtual void init ();
      virtual void reinit ();
      virtual void bind ();
      virtual void unbind ();
      virtual void update (double dt);
    }

The init() functions should make sure everything is set and ready so the
update() function can be run by the main loop. The reinit() function handles
everything in case of a reset by the user.

The bind() and unbind() functions can be used to tie and untie properties.

After that you can register this class at the subsystem manager:

    globals->add_subsystem("fx", new FGFX);

Now the subsystem manager calls the update() function of this class every
frame. dt is the time (in seconds) elapsed since the last call.


Scripting
---------

The scripting langage Nasal can also read and modify properties but it can also
be incorporated into the menu system. The documentation for Nasal can be found
here:  http://www.plausible.org/nasal/flightgear.html

Start flightgear with
fgfs --jsclient=socket,in,<hz>,,<port>,udp \
     --prop:/jsclient/axis[i]="/property/you/want/to/control" \
     --prop:/jsclient/axis[i+1]="/another/property/you/want/to/control" ...
eg:
# fgfs --aircraft=yf23-yasim --airport=KEMT --jsclient=socket,in,5,,16759,udp \
  --prop:/jsclient/axis[0]="/controls/flight/spoilers" \
  --prop:/jsclient/axis[1]="/radios/comm/volume"

Start the server on the machine with the remote gameport:
JsServer <host> <port>
eg:
# JsServer 192.168.1.1 16759

(JsServer can be started before or after fgfs)

I just commited an implementation of GUI layout management, ported
over from my game project last year*.  What this means is that you no
longer need to position your widgets manually in dialogs, and can
instead lay them out in tables and boxes like the pros do. :) I've
redone a few of the dialogs using the new scheme (I'm especially proud
of the autopilot dialog: http://plausible.org/andy/autopilot-new.png),
so you can see what the possibilities look like.

* FWIW, this is almost the last of my useful code from last spring.
  Nasal and the Plib vertex splitting code are two other bits that
  were useful in isolation.  I also had a terrain engine and stencil
  shadow implementation, but those weren't really production quality.

Basically, the implementation is a preprocessor on top of the existing
dialog properties, which sets x/y/width/height values based on
constraints.  The <group> objects, including the top-level one which
represents the whole dialog, can now have a <layout> property, which
can be "hbox", "vbox", or "table".

The boxes simply lay out their children in order, either top-to-bottom
or left-to-right.  The box name comes from Qt and Gtk, but this is
also the same thing that Java calls a "flow layout", or what the Tk
"packer" does.  You can set "constraint" properties on the children,
to give the layout manager hints as to how to place the children.  For
the boxes, these are:

  equal:   The box manager makes sure that all the widgets with this
           constraint set to true get equal sizes big enough to fit the
           largest one.  This is very useful for button boxes to make
           the "OK" and "Cancel" buttons match, for example.
  stretch: Cells with "stretch" set to true get all the extra space,
           if any, the box has to allocate.  These are useful for
           alignment purposes, especially when combined with <empty>
           "widgets" (which are ignored by the dialog creation code,
           but honored by the layout engine).

The table layout will be a little more familiar to anyone with HTML
experience.  Children of tables get the following constraints:

  row:     The row number containing the upper left corner of the widget.
           Table rows are zero-indexed.
  col:     The column number containing the upper left corner of the widget.
           Table columns are zero-indexed.
  rowspan: The number of rows spanned by the widget. Defaults to one.
  colspan: The number of columns spanned by the widget.  Defaults to
           one.

Inside of each "cell", regardless of parent layout, there are some
constraints that are used to position the widget within the space
available:

  halign:      The horizontal alignment.  Can be "left", "right",
               "center", or "fill" (i.e. stretch to available space).
  valign:      The vertical alignment.  Can be "top", "bottom",
               "center", or "fill".
  padding:     The number of pixels to leave between the edge of the
               cell and the widget.
  pref-height:
  pref-width:  Overrides the default preferred size of the widget.
               Note that this is the size of the widget only, not the
               cell (which includes padding).

Also, the padding values for cells in a group can be set to a default
value with a <default-padding> property on the group widget.

Some will ask why didn't I implement this as part of Pui.  The problem
is the pui just isn't set up for it.  Not only is there no notion of
"preferred" size for a widget, there isn't anything remote like a
"constraint" system for attaching arbitrary values to widgets.  With
the property system, I have that for free (the original code was
written to work with Nasal objects, btw).  I can do the layout with
the properties and on the properties, and our existing dialog code
hardly needs to change at all.

Anyway, give it a try and see if I've broken anything.  Also, note
that some of these changes *do* modify the visual appearance of the
GUI.  I think it looks better, but opinions will no doubt vary.  Shout
if you hate it.

And finally, the text alignment doesn't quite look right with current
plib due to some minor rendering bugs.  Bug Steve to apply the patch I
submitted a week or so ago. :)

Andy

Logging in FlightGear
---------------------

[Note: JSBSim also has its own independent logging facilities, which
are not discussed here.]

FlightGear can log any property values at any interval to one or more
CSV files (which can be read and graphed using spreadsheets like
Gnumeric or Excel).  Logging is defined in the '/logging' subbranch of
the main property tree; under '/logging', each '/log' subbranch
defines a separate log with its own output file and interval.  Here is
a simple example that logs the rudder and aileron settings every
second (1000ms) to the file steering.csv, using a comma (the default,
anyway) as the field delimiter:

<PropertyList>
 <logging>
  <log>
   <enabled>true</enabled>
   <filename>steering.csv</filename>
   <interval-ms>1000</interval-ms>
   <delimiter>,</delimiter>
   <entry>
    <enabled>true</enabled>
    <title>Rudder</title>
    <property>/controls/flight/rudder</property>
   </entry>
   <entry>
    <enabled>true</enabled>
    <title>Ailerons</title>
    <property>/controls/flight/aileron</property>
   </entry>
  </log>
 </logging>
</PropertyList>

Each 'log' subbranch contains a required 'enabled' property, an
optional 'filename' property (defaults to "fg_log.csv"), an optional
'delimiter' property (defaults to a comma), an optional 'interval-ms'
property (defaults to 0, which logs every frame), and a series of
'entry' subbranches.  The 'delimiter' property uses only the first
character of the property value as the delimiter.  Note that the
logger does no escaping, so you must choose a delimiter that will not
appear in the property values (that's not hard, since most of the
values are numeric, but watch for commas in the titles).

Each 'entry' subbranch contains a required 'enabled' property, a
'property' property specifying the name of the property to be logged,
and an optional 'title' property specifying the title to use in the
CSV file (defaults to the full path of the property).  The elapsed
time in milliseconds since the start of the simulation is always
included as the first entry with the title "Time", so there is no need
to include it explicitly.

Here's a sample of the logging output for the above log:

  Time,Rudder,Ailerons
  6522,0.000000,0.000000
  7668,-0.000000,0.000000
  8702,-0.000000,0.000000
  9705,-0.000000,0.000000
  10784,-0.000000,0.000000
  11792,-0.000000,0.000000
  12808,-0.000000,-0.210000
  13826,-0.000000,-0.344000
  14881,-0.000000,-0.066000
  15901,-0.000000,-0.806000
  16943,-0.000000,-0.936000
  17965,-0.000000,-0.534000
  19013,-0.000000,-0.294000
  20044,-0.000000,0.270000
  21090,-0.000000,-1.000000
  22097,-0.000000,-0.168000

Note that the requested interval is only a minimum; most of the time,
the actual interval is slightly longer than the requested one.

The easiest way for an end-user to define logs is to put the log in a
separate XML file (usually under the user's home directory), then
refer to it using the --config option, like this:

  fgfs --config=log-config.xml

The output log files are always relative to the current directory.

--

David Megginson, last updated 2002-02-01

README.materials

This README describes the materials.xml file format. It is targeted at those
wanting to change the appearance of the scenery in FlightGear.

The materials file used by FlightGear is set in the /sim/rendering/materials-files
property.  It is read on startup, and can be reloaded in-sim from the
"Reload Materials" item in the Debug menu.

The materials file consists of one or more <region> elements.  Each <region>
contains one or more geographical <area> elements, defining a rectangle
(lat1/lon1, lat2/lon2), and a set of <material> elements which describes a
single visually distinct terrain material in the FG world which will be used to
render one of more scenery landclasses (for example Grass or Town).  When determining
the material to use for a given landclass at a given lat/lon, the <region> elements
are checked in order and the <condition> element of the materials evaluated.  The
_last_ matching material definition is used.  So more specific regions and materials
definitions should be put towards the bottom of the materials file.

The rest of this document describes the children tags of the <material> entry.

name : Scenery type names that map to this material. These are typically taken
       from landclass definitions created by TerraGear. Multiple scenery types
       may map to a single material. This is recommended to minimize texture
       memory usage.

condition : A condition statement used to activate the material. Note that this
       if evaluated once at start-up.

texture : A relative path to an SGI RGB, PNG or DDS file containing a texture
       for the material. RGB and PNG are recommended for platform compatibility.
       You may define more than one <texture> element, in which case the scenery
       loader will choose one texture for each contiguous set of scenery
       triangles.

texture-set : If using an effect (see below), it may be necessary to define more
       than one texture.  The texture-set element has multiple <texture> element
       children which may then be referenced by the effect. You may define more
       than one <texture-set> element, in which case the scenery loader will
       choose one texture for each contiguous set of scenery triangles.

object-mask : An optional bitmap file used to control random placement of lights,
       buildings and vegetation on the terrain.  The green channel mask is used
       for random vegetation placement, the blue channel for buildings and lights.
       and the red channel controls the rotation of buildings (0.0 is North, 0.5
       is South). Fractional colour values can be used to give a probability of
       placement. Multiple object-masks may be defined to match up with <texture>
       or <texture-set> elements.

effect : The effect to be used for this material. (default:
       Effects/terrain-default)

       ambient, diffuse, specular, emissive, and shininess are copied into the
       parameter section of the effect created for this material.

parameters : Additional parameters to be used in the effect. See README.effects
            for format information.

wrapu : True if the texture should repeat horizontally over a surface, false if
       it should not repeat (default: true).

wrapv : True if the texture should repeat vertically over a surface, false if
       it should not repeat (default: true).

mipmap : True if the texture should be mipmapped, false otherwise. (default: true).

xsize : The horizontal size of a single texture repetition, in meters.

ysize : the vertical size of a single texture repetition, in meters

light-coverage : The coverage of a single point of light in m^2. 0 indicates no
        lights at all. Minimum value is 1000m^2. May be masked by the blue channel
        of an object-mask. Lights are all generated 3m above the surface, and
        have random colour (50% yellow, 35% white, 10% orange, 5% red)

ambient : The ambient light colour for the material, specified as separate
        r, g, b, a components (default: all color components 0.2, alpha 1.0).

diffuse : The diffuse light colour for the material, specified as separate
        r, g, b, a components (default: all color components 0.8, alpha 1.0).

specular : The specular light colour for the material, specified as separate
        r, g, b, a components (default: all color components 0.0, alpha 1.0).

emissive : The emissive light colour for the material, specified as separate
        r, g, b, a components (default: all color components 0.0, alpha 1.0).

solid : Whether the surface is solid from an FDM perspective. If it is not
        solid, it is assumed that the material models a fluid (water) surface.
        (default: true).

friction-factor : The friction factor for that material. The normalized
        factor can be used by a FDM to post-multiply all contact friction forces
        with that factor. That is the more slippery a material is the smaller
        this value should be. (default: 1.0 for Dry concrete/Asphalt).

rolling-friction : the gear rolling rolling-friction coefficient for this
        particular material. (default: 0.02 for Dry concrete/Asphalt).

bumpiness : normalized bumpiness factor for this particular terrain.
        (default: 0.0 for a smooth surface).

load-resistance : a pressure value how much force per surface area this
        surface can carry without deformation. The value should be in N/m^2
        (default: 1e30).

glyph : group that defines one letter/digit/symbol in a font texture
        sub-entries: name, left (default: 0.0), right (default: 1.0)
        (left and right describe the horizontal position in the texture.)

wood-coverage : The coverage of trees in areas marked as woodland in
         m^2. A lower number means a higher density of trees. A value of
         0 indicates no woods. May be masked by the green channel of an
         object-mask. (default: 0)

tree-range-m : The range at which trees become visible. Note that this
         is not absolute, as trees are loaded in blocks. A lower number means
         trees will not become visible until you are closer.

tree-texture : A texture to use for the trees. Typically this will contain around
         8 different trees in a row, duplicate 4 times. From bottom to top, the
         rows contain
         * summer textures
         * summer snow texture
         * winter texture
         * winter snow texture

         Each tree must have space at the top. For a 512x512 texture sheet, this
         should be 8 pixels.  Otherwise subsequent rendering results in "top hats"
         above trees in the distance where the trunk of the tree above in the
         textures sheet bleeds downwards when the mipmaps are generated.

tree-varieties : The number of different trees defined in the tree-texture
         horizontally. (default: 1)

tree-height-m : The average height of the trees. Actual tree height will
         vary by +/- 50%. (default: 0)

tree-width-m : The average width of the tree cover. Actual tree width will
         vary by +/- 50%. (default 0)

tree-max-density-angle-deg : The slope angle at which trees begin to thin out
         as the slope is too steep to support the full coverage. Shallower
         slopes have maximum wood-coverage.  Steeper slopes have fewer trees.
         (default : 45)

tree-zero-density-angle-deg : The angle at which the slope is too steep to
         support significant vegetation.  Steeper slopes have no trees.
         (default : 60)

object-max-density-angle-deg : The angle at which objects and buildings become
         less dense due to a steep slope. (default : 20)

object-zero-density-angle-deg : The angle at which the slope is too steep to build
         on.  No object/buildings will be placed on slopes steeper than this.
         (default : 30)

object-group : A group of random objects to be placed on the surface. Contains
         <range-m> and one or more <object> children.

range-m : The distance at which objects within this object-group become
         visible. Note that for realism, 60% of the objects will become visible
         at <range-m>, 30% at 1.5*<range-m>, and 10% at 2*<range-m>.
         (default: 2000)

object : A set of random objects to be placed. Contains <coverage-m2>, <path>
         and <heading> children.

coverage-m2 : The coverage of a single object in m2. Lower values mean a higher
         density. Minimum value is 1000.

spacing-m : The minimum space between this object and any other on the surface in
         meters. This helps to avoid objects being placed ontop of each other.
         (default 20)

path :   Path relative to FG_ROOT to a model definition, usually .ac or .xml file.
         More than one <path> may be included within the <object> tag, in which
         case a single <path> is chosen at random for each individual object
         placement.

heading-type : Indicator of how the heading of the random objects should be
         determined. Valid values are:
           fixed     - Objects all point North. Default.
           random    - Objects are assigned an individual random heading
           mask      - Rotation is taken from the red channel of the object-mask
           billboard - Object is always rotated to face camera - expensive


Random Buildings
================

Random Buildings come in three sizes, with individual constraints.

Small buildings.  These have different textures on the sides compared to the front
and back.  Small buildings are never deeper than they are wide.

Medium buildings, which are never taller than they are wide.

Large buildings. There are no constraints on their width, depth or height.

building-coverage : The coverage of random buildings in areas marked for random
         objects in m^2. A lower number means a higher density of buildings. A
         value of 0 indicates no buildings. May be masked by the blue channel of an
         object-mask. (default: 0)

building-spacing-m : The minimum spacing between random buildings and other buildings
         or random objects. This helps avoid objects being placed on top of each
         other. (default: 5)

building-small-ratio: Ratio of small buildings. These buildings are 1-3 stories
         in height, and may have a pitched roof. Fraction of small buildings is
         (<building-ratio-small> / (<building-ratio-small> + <building-ratio-medium>
         + <building-ratio-large>). (default: 0.8)

building-medium-ratio : Ratio of medium buildings. These buildings are 3-6 stories
         in height, and have a flat roof. (default: 0.15)

building-large-ratio : Ratio of large buildings. These buildings are 5-10 stories in
         height, and have a flat roof. (default 0.05)

building-small-pitch : Fraction of small buildings with pitched roofs. (default 0.8)
building-medium-pitch : Fraction of small buildings with pitched roofs. (default 0.2)
building-large-pitch : Fraction of small buildings with pitched roofs. (default 0.1)

building-small-min-floors : Min. number of floors for a small building. (default 1)
building-small-max-floors : Max. number of floors for a small building. (default 3)

building-medium-min-floors  : Min. number of floors for a medium building. (default 3)
building-medium-max-floors  : Max. number of floors for a medium building. (default 8)

building-large-min-floors  : Min. number of floors for a medium building. (default 5)
building-large-max-floors  : Max. number of floors for a medium building. (default 20)

building-small-min-width-m : Min. width of small buildings. (default 15)
building-small-max-width-m : Max. width of small buildings. (default 60)
building-small-min-depth-m : Min. depth of small buildings. (default 10)
building-small-max-depth-m : Max. depth of small buildings. (default 20)

building-medium-min-width-m : Min. width of medium buildings. (default 25)
building-medium-max-width-m : Max. width of medium buildings. (default 50)
building-medium-min-depth-m : Min. depth of medium buildings. (default 20)
building-medium-max-depth-m : Max. depth of medium buildings. (default 50)

building-large-min-width-m : Min. width of large buildings. (default 50)
building-large-max-width-m : Max. width of large buildings. (default 75)
building-large-min-depth-m : Min. depth of large buildings. (default 50)
building-large-max-depth-m : Max. depth of large buildings. (default 75)

building-texture : The texture used for all buildings. See Docs/buildings.png for
                   details. (default Texture/buildings.png)

building-lightmap: Emissive texture for all buildings, which is faded in at night to
                   provide illusion of lit windows.  Same texture coordinates and
                   format at building-texture above.

building-range-m: Range at which all buildings are visible.  Beyond this point fewer
                  and fewer buildings are rendered, with no buildings rendered at
                  2*building-range-m (default 10000)

How to compile FlightGear with mingw
====================================


MinGW & MSYS
============

You need to install mingw & msys:

http://www.mingw.org

You need at least:

MinGW: binutils, gcc-core, gcc-g++, mingw-runtime, mingw-utils, w32api
I would recommed the gcc-3.4.4 versions.
MSYS: msys-1.0.10.exe, msys-autoconf, msys-automake, msys-libtool, msys-DTK.

Please read instructions carefully.

Set the follwing environment variables within msys shell.

export CFLAGS="-I/usr/local/include -O2"
export CXXFLAGS="-I/usr/local/include -O2"
export CPPFLAGS=-I/usr/local/include
export LDFLAGS=-L/usr/local/lib

Pthread-win32
=============

http://sources.redhat.com/pthreads-win32/

compile:
make  GCE-inlined

Install:
cp pthread.h sched.h semaphore.h /usr/local/include
cp linpthreadGCE2.a  /usr/local/lib/libpthread.a
cp pthread-GCE.dll /usr/local/bin

patch header:

--- pthread.h   Sat Oct  1 20:56:43 2005
***************
*** 210,218 ****
   * -----------------
   */

! #if HAVE_CONFIG_H
! #include "config.h"
! #endif /* HAVE_CONFIG_H */

  #ifndef NEED_FTIME
  #include <time.h>
--- 210,218 ----
   * -----------------
   */

! //#if HAVE_CONFIG_H
! //#include "config.h"
! //#endif /* HAVE_CONFIG_H */

  #ifndef NEED_FTIME
  #include <time.h>

GLUT
====

use precompiled in order to avoid conflicts with glut32.dll already installed.

http://www.xmission.com/~nate/glut.html
http://www.xmission.com/~nate/glut/glut-3.7.6-bin.zip

The header has to be updated with respect to MINGW.

*** glut.h      Tue Dec 12 22:22:52 2000
--- /local_old/include/GL/glut.h        Thu Aug 18 20:41:15 2005
***************
*** 20,26 ****
     /* XXX This is from Win32's <windef.h> */
  #  ifndef APIENTRY
  #   define GLUT_APIENTRY_DEFINED
! #   if (_MSC_VER >= 800) || defined(_STDCALL_SUPPORTED) || defined(__BORLANDC__) || defined(__LCC__)
  #    define APIENTRY    __stdcall
  #   else
  #    define APIENTRY
--- 20,26 ----
     /* XXX This is from Win32's <windef.h> */
  #  ifndef APIENTRY
  #   define GLUT_APIENTRY_DEFINED
! #   if (_MSC_VER >= 800) || defined(_STDCALL_SUPPORTED) || defined(__BORLANDC__) || defined(__LCC__) || defined(__MINGW32__)
  #    define APIENTRY    __stdcall
  #   else
  #    define APIENTRY


install:
cp glut.h /usr/local/include
cp glut32.dll /usr/local/bin

reimp glut32.lib
cp libglut32.a /usr/local/lib

OpenAL
======

Get OpenAL for instance from Creative

OpenAL win32 package
install Redist


install:

cd libs
reimp  OpenAL32.lib
cp libopenal32.a  /usr/local/lib
cp alut.lib  /usr/local/lib/libalut.a
cd ..
mkdir /usr/local/include/AL
cp Include/* /usr/local/include/AL


zlib-1.2.3
==========

configure --prefix=/usr/local
make
make install

plib-1.6.8
==========
configure --prefix=/usr/local
make
make install

simgear
=======
get simgear from CVS
configure --prefix=/usr/local
make
make  install

flightgear
=========
configure --prefix=/usr/local --with-threads
make
make install

Mini Panels for c172

List of files:

./keyboard.xml - same as release key bindings with "s" added to swap panels.
./preferences.xml - same as release preferences.xml with "panel2" added.
./Aircraft/c172/Panels/c172-panel-mini.xml - mini with sacred six, compass,
	mixture knob, flaps, and control indicators.
./Aircraft/c172/Panels/c172-panel-trans-mini.xml - same mini panel with
	plexiglass (transparent) background.
./Aircraft/c172/Panels/Textures/panel-mini-bg.rgb - grey background.
./Aircraft/c172/Panels/Textures/panel-trans-mini-bg.rgb - transparent background.


USAGE NOTES:

Hitting "s" will switch between the standard panel and the default.

You may choose other panels for the two that get toggled by changing the
preferences or adding command line parameters.

The property for the panels are:
Normal (Primary) panel: /sim/panel/path=<path to xml file>
Mini (Secondary) panel: /sim/panel2/path=<path to xml file>

The new property is /sim/panel2/path,  it does not need to be a mini panel, you
can use whatever you want.

For example: to use the grey mini panel change preferences.xml or add this to
your command line:

runfgfs --prop:/sim/panel2/path=Aircraft/c172/Panels/c172-panel-mini.xml

The commands are of the form:

--multiplay=in | out,Hz,destination address,destination port
--callsign=a_unique_name


Below are some examples of startup commands that demonstrate the use of the
multiplayer facilities.

For two players on a local network or across the internet:
----------------------------------------------------------
Player1:
--multiplay=out,10,192.168.0.3,5500 --multiplay=in,10,192.168.0.2,5501
--callsign=player1

Player2:
--multiplay=out,10,192.168.0.2,5501 --multiplay=in,10,192.168.0.3,5500
--callsign=player2


For multiple players on a local network:
----------------------------------------
Player1:
--multiplay=out,10,255.255.255.255,5500
--multiplay=in,10,255.255.255.255,5500 --callsign=player1

Playern:
--multiplay=out,10,255.255.255.255,5500
--multiplay=in,10,255.255.255.255,5500 --callsign=playern

Note that the callsign is used to identify each player in a multiplayer game
so the callsigns must be unique. The multiplayer code ignores packets that
are sent back to itself, as would occur with broadcasting when the rx and tx
ports are the same.


Multiple players sending to a single player:
--------------------------------------------
Player1:
--multiplay=out,10,192.168.0.2,5500 --callsign=player1

Player2:
--multiplay=out,10,192.168.0.2,5500 --callsign=player2

Player3:
--multiplay=out,10,192.168.0.2,5500 --callsign=player3

Player4 (rx only):
--multiplay=in,10,192.168.0.2,5500 --callsign=player4

This demonstrates that it is possible to have multiple instances of
Flightgear that send to a single instance that displays all the traffic. This
is the sort of implementation that we are considering for use as a tower
visual simulator.


For use with a server:
----------------------
Oliver Schroeder has created a server for multiplayer flightgear use.
The server acts as a packet forwarding mechanism. When it
receives a packet, it sends it to all other active players
in the vicinity (the server is configured to use 100nm by default).

Check out the server homepage <http://www.o-schroeder.de/fg_server/>
for the current status. You can either download the server for
some local use, or join the developers flying at the existing servers.
As with flightgear, the server is free software, released under GPL.

Pigeon <http://pigeond.net> has created a web page monitoring
two such servers, showing the traffic in a Google map environment.
See <http://pigeond.net/flightgear/fg_server_map.html>.

Options needed to enable multiplayer game with a server:
Player1:
--multiplay=out,10,serveraddress,5000 --multiplay=in,10,myaddress,5000
--callsign=player1

Player2:
--multiplay=out,10,serveraddress,5000 --multiplay=in,10,myaddress,5000
--callsign=player2

...

PlayerN:
--multiplay=out,10,serveraddress,5000 --multiplay=in,10,myaddress,5000
--callsign=playerN

Note that if every player using a particular server, such as one of those
listed on the Pigeon's page, needs to have a unique callsign, not
already in use on that server.

If you are sitting behind a NAT'ting firewall, then you need to forward
the incoming traffic on the firewall outer (visible to the internet)
address arriving at the UDP port you use (5000 in the case above)
over to your private LAN address. In this case, use your PRIVATE LAN address
as <myaddress>. Example (if your private LAN address is 10.0.0.1,
in order to play on pigeond.net):

fgfs --multiplay=in,10,10.0.0.1,5000 --multiplay=out,10,pigeond.net,5000
	--callsign=...UNIQUE callsign here...

If you and the server are in the same address space (i.e., both have a public
IP address or both are on the same private LAN), you hopefully don't need to
mess with any firewalls.

If you don't see other players playing on the same server in your flightgear,
check that you have followed the above router configuration guidelines.  Check
that you don't have any LOCAL firewall running on your computer preventing the
flightgear network traffic flow.

Finally, use ethereal(1) or tethereal(1) to capture the UDP traffic on the port
that you are using, and see if you observe both incoming and outgoing packets.

It's a good idea to talk to the IRC channel #flightgear on irc.flightgear.org
while flying on one of the public servers. Also, it makes sense for every user
on the same server to use the same weather setup, e.g., the real weather
METAR feed, selected by setting to true the real-world-weather-fetch and
control-fdm-atmosphere properties.

Further reading (a must if you have a problem):
-----------------------------------------------
[1] The flightgear server homepage <http://fgms.sourceforge.net/>
[2] The wiki howto <http://wiki.flightgear.org/index.php/Howto:_Multiplayer>
[3] If everything else fails, ask for help on
the IRC channel #flightgear on irc.flightgear.org

The Open Scene Graph library, which current FlightGear uses for its 3D
graphics, provides excellent support for multiple views of a
scene. FlightGear uses the osgViewer::Viewer class, which implements a
"master" camera with "slave" cameras that are offset from the master's
position and orientation. FlightGear provides the "camera group"
abstraction which allows the configuration of slave cameras via the
property tree.

Slave cameras can be mapped to windows that are open on different
screens, or all in one window, or a combination of those two schemes,
according to the video hardware capabilities of a machine. It is not
advisable to open more than one window on a single graphics card due
to the added cost of OpenGL context switching between the
windows. Usually, multiple monitors attached to a single graphics card
are mapped to different pieces of the same desktop, so a window can be
opened that spans all the monitors. This is implemented by Nvidia's
TwinView technology and the Matrox TripleHead2Go hardware.

The camera group is configured by the /sim/rendering/camera-group node
in the property tree. It can be set up by, among other things, XML in
preferences.xml or in an XML file specified on the command line with
the --config option.

Here are the XML tags for defining camera groups.

camera-group
For the moment there can be only one camera group. It can contain
window, camera, or gui tags.

 window
 A window defines a graphics window. It can be at the camera-group
 level or defined within a camera. The window contains these tags:

  name - string
  The name of the window which might be displayed in the window's
  title bar. It is also used to refer to a previously defined
  window. A window can contain just a name node, in which case
  the whole window definition refers to a previously defined window.

  host-name - string
  The name of the host on which the window is opened. Usually this is
  empty.

  display - int
  The display number on which the window is opened.

  screen - int
  The screen number on which the window is opened.

  x, y - int
  The location on the screen at which the window is opened. This is in
  the window system coordinates, which usually puts 0,0 at the upper
  left of the screen XXX check this for Windows.

  width, height - int
  The dimensions of the window.

  decoration - bool
  Whether the window manager should decorate the window.

  fullscreen - bool
  Shorthand for a window that occupies the entire screen with no
  decoration.

  overrideRedirect - bool
  Only effective when fullscreen = true.
  Provides an extra hint for Gnome-based linux systems that we insist that
  the full screen window span *all* physical displays, not just the current
  physical display.

 camera
 The camera node contains viewing parameters.

  window
  This specifies the window which displays the camera. Either it
  contains just a name that refers to a previous window definition, or
  it is a full window definition.

  viewport
  The viewport positions a camera within a window. It is most useful
  when several cameras share a window.

   x, y - int
   The position of the lower left corner of the viewport, in y-up
   coordinates.

   width, height - int
   The dimensions of the viewport

  view
  The view node specifies the origin and direction of the camera in
  relation to the whole camera group. The coordinate system is +y up,
  -z forward in the direction of the camera group view. This is the
  same as the OpenGL viewing coordinates.

   x,y,z - double
   Coordinates of the view origin.

   heading-deg, pitch-deg, roll-deg - double
   Orientation of the view in degrees. These are specified using the
   right-hand rule, so a positive heading turns the view to the left,
   a positive roll rolls the view to the left.

  perspective
  This node is one way of specifying the viewing volume camera
  parameters. It corresponds to the OpenGL gluPerspective function.

   fovy-deg - double
   The vertical field-of-view

   aspect-ratio - double
   Aspect ratio of camera rectangle (not the ratio between the
   vertical and horizontal fields of view).

   near, far - double
   The near and far planes, in meters from the camera eye point. Note
   that FlightGear assumes that the far plane is far away, currently
   120km. The far plane specified here will be respected, but the sky
   and other background elements may not be drawn if the view plane is
   closer than 120km.

   offset-x, offset-y - double
   Offsets of the viewing volume specified by the other parameters in
   the near plane, in meters.

  frustum
  This specifies the perspective viewing volume using values for the near
  and far planes and coordinates of the viewing rectangle in the near
  plane.

   left, bottom - double
   right, top - double
   The coordinates of the viewing rectangle.

   near, far - double
   The near and far planes, in meters from the camera eye point.

  ortho
  This specifies an orthographic view. The parameters are the sames as
  the frustum node's.

 gui
 This is a special camera node that displays the 2D GUI.

  viewport
  This specifies the position and dimensions of the GUI within a
  window, *however* at the moment the origin must be at 0,0.

Here's an example that uses a single window mapped across 3
displays. The displays are in a video wall configuration in a
horizontal row.

<PropertyList>
  <sim>
    <rendering>
      <camera-group>
        <window>
          <name>wide</name>
          <host-name type="string"></host-name>
          <display>0</display>
          <screen>0</screen>
          <width>3840</width>
          <height>1024</height>
          <decoration type = "bool">false</decoration>
        </window>
        <camera>
          <window>
            <name>wide</name>
          </window>
          <viewport>
            <x>0</x>
            <y>0</y>
            <width>1280</width>
            <height>1024</height>
          </viewport>
          <view>
            <heading-deg type = "double">0</heading-deg>
          </view>
          <frustum>
            <top>0.133</top>
            <bottom>-0.133</bottom>
            <left>-.5004</left>
            <right>-.1668</right>
            <near>0.4</near>
            <far>120000.0</far>
          </frustum>
        </camera>
        <camera>
          <window>
            <name type="string">wide</name>
          </window>
          <viewport>
            <x>1280</x>
            <y>0</y>
            <width>1280</width>
            <height>1024</height>
          </viewport>
          <view>
            <heading-deg type = "double">0</heading-deg>
          </view>
          <frustum>
            <top>0.133</top>
            <bottom>-0.133</bottom>
            <left>-.1668</left>
            <right>.1668</right>
            <near>0.4</near>
            <far>120000.0</far>
          </frustum>
        </camera>
        <camera>
          <window>
            <name>wide</name>
          </window>
          <viewport>
            <x>2560</x>
            <y>0</y>
            <width>1280</width>
            <height>1024</height>
          </viewport>
          <view>
            <heading-deg type = "double">0</heading-deg>
          </view>
          <frustum>
            <top>0.133</top>
            <bottom>-0.133</bottom>
            <left>.1668</left>
            <right>.5004</right>
            <near>0.4</near>
            <far>120000.0</far>
          </frustum>
        </camera>
        <gui>
          <window>
            <name type="string">wide</name>
          </window>
        </gui>
      </camera-group>
    </rendering>
  </sim>
</PropertyList>

Here's a complete example that uses a seperate window on each
display. The displays are arranged in a shallow arc with the left and
right displays at a 45.3 degree angle to the center display because,
at the assumed screen dimensions, the horizontal field of view of one
display is 45.3 degrees. Each camera has its own window definition;
the center window is given the name "main" so that the GUI definition
can refer to it.  Note that the borders of the displays are not
accounted for.

<PropertyList>
  <sim>
    <rendering>
      <camera-group>
        <camera>
          <window>
            <host-name type="string"></host-name>
            <display>0</display>
            <screen>0</screen>
            <fullscreen type = "bool">true</fullscreen>
          </window>
          <view>
            <heading-deg type = "double">45.3</heading-deg>
          </view>
          <frustum>
            <top>0.133</top>
            <bottom>-0.133</bottom>
            <left>-.1668</left>
            <right>.1668</right>
            <near>0.4</near>
            <far>120000.0</far>
          </frustum>
        </camera>
        <camera>
          <window>
            <name type="string">main</name>
            <host-name type="string"></host-name>
            <display>0</display>
            <screen>1</screen>
            <fullscreen type = "bool">true</fullscreen>
          </window>
          <view>
            <heading-deg type = "double">0</heading-deg>
          </view>
          <frustum>
            <top>0.133</top>
            <bottom>-0.133</bottom>
            <left>-.1668</left>
            <right>.1668</right>
            <near>0.4</near>
            <far>120000.0</far>
          </frustum>
        </camera>
        <camera>
          <window>
            <host-name type="string"></host-name>
            <display>0</display>
            <screen>2</screen>
            <fullscreen type = "bool">true</fullscreen>
          </window>
          <view>
            <heading-deg type = "double">-45.3</heading-deg>
          </view>
          <frustum>
            <top>0.133</top>
            <bottom>-0.133</bottom>
            <left>-.1668</left>
            <right>.1668</right>
            <near>0.4</near>
            <far>120000.0</far>
          </frustum>
        </camera>
        <gui>
          <window>
            <name type="string">main</name>
          </window>
        </gui>
      </camera-group>
    </rendering>
  </sim>
</PropertyList>