docs-mini/README.xmlpanel

   1 Users Guide to FlightGear panel configuration
   2 Version 0.6, March 1 2001
   3 Author: John Check <j4strngs@rockfish.net>
   4
   5 This document is an attempt to describe the configuration of
   6 FlightGear flight simulator's aircraft panel display via XML.
   7 The information was culled from the fgfs-devel@flightgear.org
   8 mailing list and my experiences making alternate panels. I'd
   9 like  to say thanks to all the developers who  make FGFS happen.
  10 Corrections and additions are encouraged.
  11
  12 Some History:
  13
  14 Older versions of FGFS had a hard coded display of instruments.
  15 This was a less than ideal state of affairs due to FGFS ability
  16 to use different aircraft models. Being primarily developed on
  17 UNIX type systems, a modular approach is taken towards the
  18 aircraft modeling. To date, most alternatives to the default
  19 Cessna 172 aircraft are the product of research institutions
  20 interested in the flight characteristics and not cosmetics.
  21 The result of this was that one could fly the X-15 or a Boeing 747
  22 but be limited to C172 instrumentation.
  23
  24 A rewrite of the panel display code was done around v0.7.5 by
  25 developer David Megginson allowing for configuration of the panel
  26 via XML to address this limitation.
  27
  28
  29 Using Custom Panels:
  30
  31 The default panel location is $FG_ROOT/Aircraft/c172/Panels/Default.
  32 $FG_ROOT is the place on your filesystem where you installed FG
  33 data files. Alternate panels can be specified on the command line
  34 or set as the default in the $HOME/.fgfsrc or $FG_ROOT/preferences.xml
  35 using a property specification. The command line format is as follows:
  36
  37 --prop:/sim/panel/path=Aircraft/c172/Panels/Default
  38
  39 The path description shown is relative to $FG_ROOT. An absolute
  40 path may also be used for locations outside $FG_ROOT. I would
  41 recommend copying Panels/Default to Panels/Custom as a starting point
  42 for experimentation. When editing a panel configuration, pressing
  43 Shift +F3 will reload the panel. If your changes don't seem to be taking
  44 effect, check the console output. It will report the success or failure
  45 of the panel reload*. Editing textures requires restarting FGFS so the
  46 new textures can be loaded.
  47
  48
  49 Panel Architecture:
  50
  51 All of the panel configuration files are XML-encoded* property lists.
  52 The root element of each file is always named <PropertyList>. Tags are
  53 always found in pairs, with the closing tag having a slash prefixing
  54 the tag name, i.e </PropertyList>. The top level panel configuration
  55 file is composed of a <name>, a <background> texture and zero or more
  56 <instruments>. Instruments are used by including a <"unique_name">, a
  57 <path> to the instruments configuration file, <x> and <y> placement
  58 coordinates, and optional <w> and <h> size specifications.
  59 Comments are bracketed with <!-- -->.
  60
  61     Example Top Level Panel Config
  62
  63 <PropertyList>
  64  <name>Example Panel</name>
  65  <background>Aircraft/c172/Panels/Textures/panel-bg.rgb</background>
  66  <instruments>
  67   <clock>         <!-- the "unique_name" -->
  68    <path>Aircraft/c172/Instruments/clock.xml</path>
  69    <x>110</x>
  70    <y>320</y>
  71    <w>72</w>      <!-- optional width specification -->
  72    <h>72</h>      <!-- optional height specification -->
  73   </clock>
  74  </instruments>
  75 </PropertyList>
  76
  77 The default location for instrument files is $FG_ROOT/Aircraft/c172/Instruments/.
  78 Alternate locations may be specified in the panel configuration, paths
  79 must be absolute to use files outside $FG_ROOT.
  80
  81 About Instrument Placement:
  82
  83 For the sake of simplicity the FGFS window is always considered to be 1024x768
  84 so all x/y values for instrument placement should fall within these bounds.
  85 Being an OpenGL program, 0,0 represents the lower left hand corner of the
  86 screen. It is possible to place items to overlap the 3D viewport.
  87
  88 Instrument Architecture:
  89
  90 Instruments are defined in separate configuration files. An instrument
  91 consists of a preferred width and height, one or more stacked layers,
  92 and zero or more actions.
  93
  94 A layer** can be a <texture>, or be of <type> text or switch. A text layer
  95 may be static, as in a label, or generated (if it needs to be dynamic, as
  96 in an LED display), or a combination of both.
  97 A switch layer is composed of two or more nested layers and will display
  98 one of the nested layers based on a boolean property. For a simple example
  99 of a switch see $FG_ROOT/Aircraft/Custom/Instruments/brake.xml.
 100 Textures used in a switch context *must* have width and height specified to be
 101 visible. Each layer may contain zero or more transformations.
 102
 103 A transformation is a rotation, an x-shift, or a y-shift. Transformations
 104 can be static  or they can be based on properties. Static rotations are
 105 useful for flipping textures horizontally or vertically. Transformations
 106 based on properties are useful for driving instrument needles. I.E. rotate the
 107 number of degrees equal to the airspeed. X and y shifts are relative to the
 108 center of the instrument. Each specified transformation type takes an <offset>
 109
 110 An action is a hotspot on an instrument where something will happen
 111 when the user clicks the left or center mouse button.  Actions are
 112 always tied to properties: they can toggle a boolean property, adjust
 113 the value of a numeric property, or swap the values of two properties.
 114
 115 About Transformations and Needle Placement:
 116
 117 When describing placement of instrument needles, an transformation offset must
 118 be applied to shift the needle's fulcrum or else the needle will rotate around it's
 119 middle. The offset will be of <type> x-shift or y-shift depending on the orientation of
 120 the needle section in the cropped texture.
 121 Offsets applied to shift the needle from the center of the instrument face must be
 122 applied *before* the transformation that describes the needle movement.
 123
 124 About Textures:
 125
 126 The texture files used to create the panel instruments are maximum 256x256
 127 pixels, red/green/blue/alpha format. However the mechanism for specifying
 128 texture cropping coordinates is decimal in nature. When calling a section
 129 of a texture file the 0,0 lower left convention is used.
 130 There is a pair of x/y coordinates defining which section of the texture
 131 to use.
 132
 133 The following table can be used to calculate texture cropping specifications.
 134
 135 # of divisions | width in pixels | decimal specification
 136 per axis
 137         1   =   256 pixels              1
 138         2   =   128 pixels,             0.5
 139         4   =   64 pixels,              0.25
 140         8   =   32 pixels,              0.125
 141         16  =   16 pixels,              0.0625
 142         32  =   8 pixels,               0.03125
 143         64  =   4 pixels,               0.015625
 144         128 =   2 pixels,               0.0078125
 145
 146 The recommended procedure for generating gauge faces is to use a
 147 vector graphics package such as xfig, exporting the result as a
 148 poscript file. 3D modeling tools may also be used and are prefered
 149 for pretty items that don't require text such as levers, switches,
 150 bezels and so forth. Ideally, the size of the item in the final render
 151 should be of proportions that fit into the recommended pixel widths.
 152 The resulting files should be imported into a graphics manipulation
 153 package such as GIMP, et al for final processing.
 154
 155
 156 *  If there are *any* XML parsing errors, the panel will fail to load,
 157    so it's worth downloading a parser like Expat (http://www.jclark.com/xml/)
 158    for checking your XML. FlightGear will print the location of errors, but
 159    the messages are a little cryptic right now.
 160
 161 ** NOTE: There is one built-in layer -- for the mag compass ribbon --
 162    and all other layers are defined in the XML files.  In the future,
 163    there may also be built-in layers for special things like a
 164    weather-radar display or a GPS (though the GPS could be handled with
 165    text properties).