143 lines
6.4 KiB
Text
143 lines
6.4 KiB
Text
Users Guide to FlightGear panel configuration
|
|
Version 0.5, November 8 2000
|
|
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. 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.
|
|
|
|
|
|
|
|
* 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).
|
|
|