flightgear/docs-mini/README.xmlpanel

Users Guide to FlightGear panel configuration
Version 0.6, March 1 2001
Author: John Check <j4strngs@rockfish.net>  

This document is an attempt to describe the configuration of 
FlightGear flight simulator's aircraft panel display via XML. 
The information was culled from the fgfs-devel@flightgear.org 
mailing list and my experiences making alternate panels. I'd 
like  to say thanks to all the developers who  make FGFS happen.
Corrections and additions are encouraged.

Some History:

Older versions of FGFS had a hard coded display of instruments.
This was a less than ideal state of affairs due to FGFS ability
to use different aircraft models. Being primarily developed on
UNIX type systems, a modular approach is taken towards the
aircraft modeling. To date, most alternatives to the default 
Cessna 172 aircraft are the product of research institutions
interested in the flight characteristics and not cosmetics.
The result of this was that one could fly the X-15 or a Boeing 747
but be limited to C172 instrumentation.

A rewrite of the panel display code was done around v0.7.5 by 
developer David Megginson allowing for configuration of the panel
via XML to address this limitation.


Using Custom Panels:

The default panel location is $FG_ROOT/Aircraft/c172/Panels/Default.
$FG_ROOT is the place on your filesystem where you installed FG
data files. Alternate panels can be specified on the command line 
or set as the default in the $HOME/.fgfsrc or $FG_ROOT/preferences.xml 
using a property specification. The command line format is as follows:

--prop:/sim/panel/path=Aircraft/c172/Panels/Default

The path description shown is relative to $FG_ROOT. An absolute
path may also be used for locations outside $FG_ROOT. I would 
recommend copying Panels/Default to Panels/Custom as a starting point
for experimentation. When editing a panel configuration, pressing
Shift +F3 will reload the panel. If your changes don't seem to be taking 
effect, check the console output. It will report the success or failure
of the panel reload*. Editing textures requires restarting FGFS so the
new textures can be loaded.


Panel Architecture:

All of the panel configuration files are XML-encoded* property lists. 
The root element of each file is always named <PropertyList>. Tags are
always found in pairs, with the closing tag having a slash prefixing
the tag name, i.e </PropertyList>. The top level panel configuration 
file is composed of a <name>, a <background> texture and zero or more 
<instruments>. Instruments are used by including a <"unique_name">, a
<path> to the instruments configuration file, <x> and <y> placement
coordinates, and optional <w> and <h> size specifications.
Comments are bracketed with <!-- -->.

    Example Top Level Panel Config

<PropertyList>
 <name>Example Panel</name>
 <background>Aircraft/c172/Panels/Textures/panel-bg.rgb</background>
 <instruments>
  <clock>         <!-- the "unique_name" -->
   <path>Aircraft/c172/Instruments/clock.xml</path>
   <x>110</x>
   <y>320</y>
   <w>72</w>      <!-- optional width specification -->
   <h>72</h>      <!-- optional height specification -->
  </clock>
 </instruments>
</PropertyList>
  
The default location for instrument files is $FG_ROOT/Aircraft/c172/Instruments/.
Alternate locations may be specified in the panel configuration, paths
must be absolute to use files outside $FG_ROOT.

About Instrument Placement:

For the sake of simplicity the FGFS window is always considered to be 1024x768
so all x/y values for instrument placement should fall within these bounds.
Being an OpenGL program, 0,0 represents the lower left hand corner of the
screen. It is possible to place items to overlap the 3D viewport.

Instrument Architecture:

Instruments are defined in separate configuration files. An instrument
consists of a preferred width and height, one or more stacked layers, 
and zero or more actions.

A layer** can be a <texture>, or be of <type> text or switch. A text layer
may be static, as in a label, or generated (if it needs to be dynamic, as 
in an LED display), or a combination of both. 
A switch layer is composed of two or more nested layers and will display
one of the nested layers based on a boolean property. For a simple example 
of a switch see $FG_ROOT/Aircraft/Custom/Instruments/brake.xml. 
Textures used in a switch context *must* have width and height specified to be 
visible. Each layer may contain zero or more transformations.  

A transformation is a rotation, an x-shift, or a y-shift. Transformations 
can be static  or they can be based on properties. Static rotations are 
useful for flipping textures horizontally or vertically. Transformations
based on properties are useful for driving instrument needles. I.E. rotate the
number of degrees equal to the airspeed. X and y shifts are relative to the
center of the instrument. Each specified transformation type takes an <offset>

An action is a hotspot on an instrument where something will happen
when the user clicks the left or center mouse button.  Actions are
always tied to properties: they can toggle a boolean property, adjust
the value of a numeric property, or swap the values of two properties.

About Transformations and Needle Placement:

When describing placement of instrument needles, an transformation offset must 
be applied to shift the needle's fulcrum or else the needle will rotate around it's 
middle. The offset will be of <type> x-shift or y-shift depending on the orientation of 
the needle section in the cropped texture.
Offsets applied to shift the needle from the center of the instrument face must be 
applied *before* the transformation that describes the needle movement.

About Textures:

The texture files used to create the panel instruments are maximum 256x256
pixels, red/green/blue/alpha format. However the mechanism for specifying
texture cropping coordinates is decimal in nature. When calling a section 
of a texture file the 0,0 lower left convention is used.
There is a pair of x/y coordinates defining which section of the texture 
to use. 

The following table can be used to calculate texture cropping specifications.

# of divisions | width in pixels | decimal specification
per axis
        1   =   256 pixels              1
        2   =   128 pixels,             0.5
        4   =   64 pixels,              0.25
        8   =   32 pixels,              0.125
        16  =   16 pixels,              0.0625
        32  =   8 pixels,               0.03125
        64  =   4 pixels,               0.015625
        128 =   2 pixels,               0.0078125

The recommended procedure for generating gauge faces is to use a
vector graphics package such as xfig, exporting the result as a
poscript file. 3D modeling tools may also be used and are prefered
for pretty items that don't require text such as levers, switches,
bezels and so forth. Ideally, the size of the item in the final render
should be of proportions that fit into the recommended pixel widths.
The resulting files should be imported into a graphics manipulation
package such as GIMP, et al for final processing.


*  If there are *any* XML parsing errors, the panel will fail to load, 
   so it's worth downloading a parser like Expat (http://www.jclark.com/xml/)
   for checking your XML. FlightGear will print the location of errors, but
   the messages are a little cryptic right now. 

** NOTE: There is one built-in layer -- for the mag compass ribbon --
   and all other layers are defined in the XML files.  In the future,
   there may also be built-in layers for special things like a
   weather-radar display or a GPS (though the GPS could be handled with
   text properties).