<HTML><HEAD><TITLE>Users Guide to FlightGear panel configuration</TITLE></HEAD> <BODY> <H1>Users Guide to FlightGear panel configuration</H1> <CITE> Version 0.7.7.2, July 24 2001 Author: John Check </CITE> <ol> <li><A HREF="#history">Some History</A></li> <li><A HREF="#property_manager">About The Property Manager</A></li> <li><A HREF="#xml">XML and The Property Manager</A></li> <li><A HREF="#load_panel">Loading Panels</A></li> <li><A HREF="#window_geometry">Regarding Window Geometry</A></li> <li><A HREF="#panel_architecture">Panel Architecture</A></li> <li><A HREF="#example_panel">Example Top Level Panel Config</A></li> <li><A HREF="#indexed_properties">Indexed Properties</A></li> <li><A HREF="#inclusion">Inclusion</A></li> <li><A HREF="#instrument_architecture">Instrument Architecture</A></li> <li><A HREF="#textures">Textures</A></li> <li><A HREF="#instrument_layers">Instrument Layers</A></li> <li><A HREF="#transformations">Transformations</a></li> <li><A HREF="#conditions">Conditions</A></li> <li><A HREF="#needle_placement">About Transformations and Needle Placement</A></li> <li><A HREF="#interpolation">Interpolation Tables</A></li> <li><A HREF="#actions">Actions</A></li> <li><A HREF="#more_texture">More About Textures</A></li> <li><A HREF="#generating_textures">Generating Textures</A></li> <li><A HREF="#contribute">Contributing Panels</A></li> <li><A HREF="#units">Units</A></li> </ol> <P> This document describes 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. Corrections and additions are encouraged. </P> <HR WIDTH="20%"> <H2><A NAME="history">Some History:</A></H2> <HR WIDTH="20%"> <p> 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 simulation. 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. </P> <P> 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. Some major changes and additions were made during the course of version 0.7.7 necessitating a rewrite and expansion of this document. </P> <HR WIDTH="20%"> <H2><A NAME="property_manager">About The Property Manager:</A></H2> <HR WIDTH="20%"> <p> While intimate knowledge of the property manager is unnecessary to create aircraft panels, some familiarity with the concept is required. FlightGear provides a hierarchical representation of all aspects of the state of the running simulation that is known as the property tree. Some properties, such as velocities, are read only. Others such as the frequencies to which the navcom radios are tuned or the position of control surfaces can be set by various means. </P> <P> FlightGear can optionally provide an interface to these properties for external applications such as Atlas, the moving map program, or even lowly telnet via a network socket. Data can even be routed to a serial port and connected to say, a GPS receiver. Aside from its usefulness in a flight training context, being able to manipulate the property tree on a running copy of FG allows for switching components on the fly, a positive boon for panel authors. To see the property tree start FG with the following command line: </P> <PRE> fgfs --props=socket,bi,5,localhost,5500,tcp </PRE> <br> <P> Then use telnet to connect to localhost on port 5500. You can browse the tree as you would a filesystem. </P> <HR WIDTH="20%"> <H2><A NAME="xml">XML And The Property Manager:</A></H2> <HR WIDTH="20%"> <p> Panel instruments interface with the property tree to get/set values as appropriate. Properties for which FG doesn't yet provide a value can be created by simply making them up. Values can be adjusted using the telnet interface allowing for creation and testing of instruments while code to drive them is being developed. </P> <P> If fact, the XML configuration system allows a user to combine components such as flight data model, aircraft exterior model, heads up display, and of course control panel. Furthermore, such a preconfigured aircraft.xml can be included into a scenario with specific flight conditions. These can be manually specified or a FG session can be saved and/or edited and reloaded later. Options specified in these files can be overridden on the command line. For example: </P> <PRE> --prop:/sim/panel/path=Aircraft/c172/Panels/c172-panel.xml </PRE> <br> <P> passed as an option, would override a panel specified elsewhere. Property tree options all have the same format, specify the node and supply it a value. </P> <p> The order of precedence for options is thus: </p> <pre> Source Location Format ------ -------- ------ command line .fgfsrc ~/ command line options system.fgfsrc $FG_ROOT "" "" preferences.xml $FG_ROOT XML property list </pre> <br> <HR WIDTH="20%"> <H2><A NAME="load_panel">Loading Panels on the fly:</A></H2> <HR WIDTH="20%"> <p> 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. Panels can be switched on the fly by setting the /sim/panel/path property value and reloading. </P> <HR WIDTH="20%"> <H2><A NAME="window_geometry">Regarding Window Geometry:</A></H2> <HR WIDTH="20%"> <p> For the sake of simplicity the FGFS window is always considered to be 1024x768 so all x/y values for instrument placement should relative to these dimensions. Since FG uses OpenGL 0,0 represents the lower left hand corner of the screen. Panels may have a virtual size larger than 1024x768. Vertical scrolling is accomplished with Shift+F5/F6. Horizontal scrolling is via Shift+F7/F8. An offset should be supplied to set the default visible area. It is possible to place items to overlap the 3D viewport. </p> <HR WIDTH="20%"> <H2><A NAME="panel_architecture">Panel Architecture:</A></H2> <HR WIDTH="20%"> <p> All of the panel configuration files are XML-encoded* property lists. The root element of each file is always named <PropertyList>. Tags are almost always found in pairs, with the closing tag having a slash prefixing the tag name, i.e </PropertyList>. The exception is the tag representing an aliased property. In this case a slash is prepended to the closing angle bracket. (see section Aliasing) Properties must have units specified where appropriate. See section "Units" at the end of this doc. </P> <P> The top level panel configuration file is composed of a <name>, a <background> texture and zero or more <instruments>. </P> <p> [ Paths are relative to $FG_ROOT ( the installed location of FGFS data files ). ]<br> [ Absolute paths may be used. Comments are bracketed with <!-- -->. ] </p> <HR WIDTH="20%"> <H2><A NAME="example_panel">Example Top Level Panel Config:</A></H2> <HR WIDTH="20%"> <p> <PRE> <PropertyList> <name>Example Panel</name> <background>Aircraft/c172/Panels/Textures/panel-bg.rgb</background> <w>1024</w> <!-- virtual width --> <h>768</h> <!-- virtual height --> <y-offset>-305</y-offset> <!-- hides the bottom part --> <view-height>172</view-height> <!-- amount of overlap between 2D panel and 3D viewport --> <instruments> <instrument include="../Instruments/clock.xml"> <name>Chronometer</name> <!-- currently optional but strongly recommended --> <x>150</x> <!-- required horizontal placement --> <y>645</y> <!-- required vertical placement --> <w>72</w> <!-- optional width specification --> <h>72</h> <!-- optional height specification --> </instrument> </instruments> </PropertyList> </PRE> <BR> <HR WIDTH="20%"> <H2><A NAME="indexed_properties">Indexed Properties:</A></H2> <HR WIDTH="20%"> <p> The property manager assigns incremental indices to repeated properties with the same parent node, so that </P> <PRE> <PropertyList> <x>1</x> <x>2</x> <x>3</x> </PropertyList> </PRE><BR> <p> shows up as </P> <PRE> /x[0] = 1 /x[1] = 2 /x[2] = 3 </PRE><BR> <p> In fact, the panel I/O code insists that every instrument have the XML element name "instrument", every layer have the name "layer", every text chunk have the name "chunk", every action have the name "action", and every transformation have the name "transformation" -- this makes the XML more regular (so that it can be created in a DTD-driven tool) and also allows us to include other kinds of information (such as doc strings) in the lists without causing confusion. </P> <HR WIDTH="20%"> <H2><A NAME="inclusion">Inclusion:</A></H2> <HR WIDTH="20%"> <p> Inclusion means that a node can include another property list as if it were a part of the current file. To clarify how inclusion works, consider the following examples: </P> <p> If bar.xml contains </P> <PRE> <PropertyList> <a>1</a> <b> <c>2</c> </b> </PropertyList> </PRE><BR> <p> then the declaration </P> <PRE> <foo include="../bar.xml"> </foo> </PRE><br> <p> is exactly equivalent to </P> <PRE> <foo> <a>1</a> <b> <c>2</c> </b> </foo> </PRE> <br> <p> However, it is also possible to selectively override properties in the included file. For example, if the declaration were </p> <PRE> <foo include="../bar.xml"> <a>3</a> </foo> </PRE> <BR> <p> then the property manager would see </P> <PRE> <foo> <a>3</a> <b> <c>2</c> </b> </foo> </PRE> <br> <p> with the original 'a' property's value replaced with 3. </P> <p> Inclusion allows property files to be broken up and reused arbitrarily -- for example, there might be separate texture cropping property lists for commonly-used textures or layers, to avoid repeating the information in each instrument file. </P> <HR WIDTH="20%"> <H2><A NAME="aliasing">Aliasing:</A></H2> <HR WIDTH="20%"> <p> Properties can alias other properties, similar to a symbolic link in Unix. When the target property changes value, the new value will show up in the aliased property as well. For example, </p> <PRE> <PropertyList> <foo>3</foo> <bar alias="/foo"/> </PropertyList> </PRE> <br> <p> will look the same to the application as </p> <PRE> <PropertyList> <foo>3</foo> <bar>3</bar> </PropertyList> </PRE> <br> <p> except that when foo changes value, bar will change too. </p> <p> *IMPORTANT* ----------- The combination of inclusions and aliases is very powerful, because it allows for parameterized property files. However, you must keep in mind that when an instrument is included by reference, its root is *not* the root of the property tree, therefore aliases must be relative. The relative location of the alias' root in the property hierarchy depends on whether the alias is used in a layer, a switch or an action. In lieu of snappy mnemonic, please use the following table. </p> <pre> when alias is used in go up --------- ----- layer 5 ( ../../../../../params/foo ) switch 3 ( ../../../params/foo ) action 3 ( ../../../params/foo ) </pre> <br> <p> As an example of inclusion and aliasing, consider the XML file for the NAVCOM radio, which includes a parameter subtree at the start, like this: </p> <PRE> <PropertyList> <params> <comm-freq-prop>/radios/comm1/frequencies/selected-mhz</comm-freq-prop> <nav-freq-prop>/radios/nav1/frequencies/selected-mhz</nav-freq-prop> </params> ... <chunk> <type>number-value</type> <property alias="../../../../../params/nav-freq-prop"/> </chunk> ... </PropertyList> </PRE> <br> <P> The same instrument file is used for navcomm1 and navcomm2 simply by overriding the parameters at inclusion in the top level panel property list. </P> <pre> <instrument include="../Instruments/navcomm.xml"> <name>NAVCOM 1 radio</name> <params> <comm-freq-prop>/radios/comm1/frequencies/selected-mhz</comm-freq-prop> <nav-freq-prop>/radios/nav1/frequencies/selected-mhz</nav-freq-prop> </params> ..... </instrument> <instrument include="../Instruments/navcomm.xml"> <name>NAVCOM 2 radio</name> <params> <comm-freq-prop>/radios/comm2/frequencies/selected-mhz</comm-freq-prop> <nav-freq-prop>/radios/nav2/frequencies/selected-mhz</nav-freq-prop> </params> ..... </instrument> </PRE> <br> <HR WIDTH="20%"> <H2><A NAME="instrument_architecture">Instrument Architecture:</A></H2> <HR WIDTH="20%"> <p> Instruments are defined in separate configuration files. An instrument consists of a base width and height, one or more stacked layers, and zero or more actions. Base dimensions are specified as follows: </p> <pre> <PropertyList> <!-- remember, all xml files start like this --> <name>Airspeed Indicator</name> <!-- names are good --> <w-base>128</w-base> <!-- required width spec--> <h-base>128</h-base> <!-- required height spec--> <layers> <!-- begins layers section --> </pre> <br> <p> Height and width can be overriden in the top level panel.xml by specifying <w> and <h>. Transformations are caculated against the base size regardless of the display size. This ensures that instruments remain calibrated. </p> <HR WIDTH="20%"> <H2><A NAME="textures">Textures:</A></H2> <HR WIDTH="20%"> <p> FG uses red/green/blue/alpha .rgba files for textures. Dimensions for texture files should be power of 2 with a maximum 8:1 aspect ratio. The lowest common denominator for maximum texture size is 256 pixels. This is due to the limitations of certain video accelerators, most notably those with 3Dfx chipset such as the Voodoo2. </p> <HR WIDTH="20%"> <H2><A NAME="instrument_layers">Instrument Layers**:</A></H2> <HR WIDTH="20%"> <p> The simplest layer is a <texture>. These can be combined in <switch> layers </p> <p> <texture> A texture layer looks like this: </p> <pre> <layer> <!-- creates a layer --> <name>face</name> <texture> <!-- defines it as a texture layer --> <path>Aircraft/c172/Instruments/Textures/faces-2.rgb</path> <x1>0</x1> <!-- lower boundary for texture cropping--> <y1>0.51</y1> <!-- left boundary for texture cropping--> <x2>0.49</x2> <!-- upper boundary for texture cropping--> <y2>1.0</y2> <!-- right boundary for texture cropping--> </texture> <!-- closing texure tag --> </layer> <!-- closing layer tag --> </pre> <br> <p> The texture cropping specification is represented as a decimal. There is a table at the end of this document for converting from pixel coordinates to percentages. </p> <p> This particular layer, being a gauge face has no transformations applied to it. Layers with that aren't static *must* include <w> and <h> parameters to be visible. </p> <p> <type> May be either text or switch.. </p> <p> <type>switch</type> 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/c172/Instruments/brake.xml. </p> <pre> <layer> <name>Brake light</name> <type>switch</type> <!-- define layer as a switch --> <property>/controls/gear/brake-left</property> <!-- tie it to a property --> <layer1> <!-- layer for true state --> <name>on</name> <!-- label to make life easy --> <texture> <!-- layer1 of switch is a texture layer --> <path>Aircraft/c172/Instruments/Textures/brake.rgb</path> <x1>0.25</x1> <y1>0.0</y1> <x2>0.5</x2> <y2>0.095</y2> </texture> <w>64</w> <!-- required width - layer isn't static --> <h>24</h> <!-- required height - layer isn't static --> </layer1> <!-- close layer1 of switch --> <layer2> <!-- layer for false state --> <name>off</name> <texture> <path>Aircraft/c172/Instruments/Textures/brake.rgb</path> <x1>0.0</x1> <y1>0.0</y1> <x2>0.25</x2> <y2>0.095</y2> </texture> <w>64</w> <h>24</h> </layer2> </layer> </pre> <br> <p> Switches can have more than 2 states. This requires nesting one switch inside another. One could make, for example, a 3 color LED by nesting switch layers. </p> <p> <type>text</type> A text layer may be static, as in a label, generated from a property or a combination of both. This example is a switch that contains both static and dynamic text: </p> <pre> <layer1> <!-- switch layer --> <name>display</name> <type>text</type> <!-- type == text --> <point-size>12</point-size> <!-- font size --> <color> <!-- specify rgb values to color text --> <red>1.0</red> <green>0.5</green> <blue>0.0</blue> </color> <!-- close color section --> <chunks> <!-- sections of text are referred to as chunks --> <chunk> <!-- first chunk of text --> <type>number-value</type> <!-- value defines it as dynamic --> <property>/radios/nav1/dme/distance-nm</property> <!-- ties it to a property --> <scale>0.00053995680</scale> <!-- convert between statute and nautical miles? --> <format>%5.1f</format> <!-- define format --> </chunk> </chunks> </layer1> <layer2> <!-- switch layer --> <name>display</name> <type>text</type> <!-- type == text --> <point-size>10</point-size> <!-- font size --> <color> <!-- specify rgb values to color text --> <red>1.0</red> <green>0.5</green> <blue>0.0</blue> </color> <!-- close color section --> <chunks> <!-- sections of text are referred to as chunks --> <chunk> <!-- first chunk of text --> <type>literal</type> <!-- static text --> <text>---.--</text> <!-- fixed value --> </chunk> </chunks> </layer2> </pre> <br> Note that the value to be displayed can be modified using <scale> for multiplication, <offset> for addition, and <truncate>true</truncate> for truncation. The order of operation is always scale-offset-truncation, which may require you to adapt your formula. For instance, the normal conversion from Fahrenheit to Celsius would be C = (F-32)*0.555555556. Because of the order of operation above you must use the formula C = (F*0.55555556)-17.77777777. <br> <HR WIDTH="20%"> <H2><A NAME="conditions">Conditions:</A></H2> <HR WIDTH="20%"> <p> A condition may appear in a binding (for keyboard, joystick, or panel action) or in most parts of a panel configuration file (specifically, for an instrument, layer, transformation, text chunk, or action). If a condition is present, it must succeed for the component to be used (i.e. if the condition fails, the binding will not be fired, the layer will not be drawn, etc.). Conditions are compiled to an efficient internal form and load time. </p> <p> For example, to ensure that a layer is drawn only if the /foo/bar property has the value "active", you would do the following: </p> <pre> <layer> <name>FooBar Layer</name> <condition> <equals> <property>/foo/bar</property> <value>active</value> </equals> </condition> ... </layer> </pre> <p> To draw a different layer when the /foo/bar property does not have the value "active", you could follow with this: </p> <pre> <layer> <name>FooBar Layer</name> <condition> <not-equals> <property>/foo/bar</property> <value>active</value> </not-equals> </condition> ... </layer> </pre> <p> While conditions were originally created for panel designers, they have proven to be very useful for binding input devices (such as the keyboard or joystick), since they effectively allow any key, axis, button, or panel action to act as a modifier for any other key, axis, button, or panel action, and in fact, allow mind-numbingly complicated combinations for people who like them (i.e. Emacs users). </p> <pre> <!-- make 'u' a modifier key --> <!-- could also use property-toggle to make it a toggle modifier --> <key n="117"> <name>u</name> <desc>Special 'u' modifier</desc> <binding> <command>property-assign</command> <property>/modifiers/u</property> <value>1</value> </binding> <mod-up> <binding> <command>property-assign</command> <property>/modifiers/u</property> <value>0</value> </binding> </mod-up> </key> <!-- take different actions based on the u modifier --> <key n="118"> <name>v</name> <binding> <condition> <property>/modifiers/u</property> </condition> <command>property-toggle</command> <property>/foo/bar</property> </binding> <binding> <condition> <not> <property>/modifiers/u</property> </not> </condition> <command>property-toggle</command> <property>/bar/foo</property> </binding> </key> </pre> <p> The <condition> element acts as an implicit 'and' group for everything contained in it. Here are the elements that can appear inside: </p> <pre> <property>[name]</property> - true if the named property returns a true boolean value (i.e. a non-0 numeric value) <and>[condition...]</and> - true if all of the conditions contained in it are true <or>[condition...]</or> - true if any of the conditions contained in it is true <not>[condition]</not> - true if the condition contained in it is false <less-than>...</less-than> <less-than-equals>...</less-than-equals> <equals>...</equals> <not-equals>...</not-equals> <greater-than>...</greater-than> <greater-than-equals>...</greater-than-equals> </pre> <p> - all of these take two child elements; the first, "property", is the property to test; the second argument may be "property" or "value". If it is also "property" (i.e. property[1]), the named property's value will be used; otherwise, the literal value provided will be used - be warned that any string comparison other than equals/not-equals is guaranteed to be flaky </p> <HR WIDTH="20%"> <H2><A NAME="transformations">Transformations:</A></H2> <HR WIDTH="20%"> <p> 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>.</p><p> Offsets are relative to the center of the instrument. A shift without an offset has no effect. For example, let's say we have a texture that is a circle. If we use this texture in two layers, one defined as having a size of 128x128 and the second layer is defined as 64x64 and neither is supplied a shift and offset the net result appears as 2 concentric circles. </p> <HR WIDTH="20%"> <H2><A NAME="needle_placement">About Transformations and Needle Placement:</A></H2> <HR WIDTH="20%"> <p> When describing placement of instrument needles, a transformation offset must be applied to shift the needles 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. </p> <p> This example comes from the altimeter.xml </p> <pre> <layer> <name>long needle (hundreds)</name> <!-- the altimeter has more than one needle --> <texture> <path>Aircraft/c172/Instruments/Textures/misc-1.rgb</path> <x1>0.8</x1> <y1>0.78125</y1> <x2>0.8375</x2> <y2>1.0</y2> </texture> <w>8</w> <h>56</h> <transformations> <!-- begin defining transformations --> <transformation> <!-- start definition of transformation that drives the needle --> <type>rotation</type> <property>/steam/altitude-ft</property> <!-- bind it to a property --> <max>100000.0</max> <!-- upper limit of instrument --> <scale>0.36</scale> <!-- once around == 1000 ft --> </transformation> <!-- close this transformation --> <transformation> <!-- this one shifts the fulcrum of the needle --> <type>y-shift</type> <!-- y-shift relative to needle --> <offset>24.0</offset> <!-- amount of shift --> </transformation> </transformations> </layer> </pre> <br> <p> This needles has its origin in the center of the instrument. If the needles fulcrum was towards the edge of the instrument, the transformations to place the pivot point must precede those which drive the needle, </p> <HR WIDTH="20%"> <H2><A NAME="interpolation">Interpolation Tables:</A></H2> <HR WIDTH="20%"> <p> Non linear transformations are now possible via the use of interpolation tables. </p> <pre> <transformation> ... <interpolation> <entry> <ind>0.0</ind> <!-- raw value --> <dep>0.0</dep> <!-- displayed value --> </entry> <entry> <ind>10.0</ind> <dep>100.0</dep> </entry> <entry> <ind>20.0</ind> <dep>-5.0</dep> </entry> <entry> <ind>30.0</ind> <dep>1000.0</dep> </entry> </interpolation> </transformation> </pre> <br> <p> Of course, interpolation tables are useful for non-linear stuff, as in the above example, but I kind-of like the idea of using them for pretty much everything, including non-trivial linear movement -- many instrument markings aren't evenly spaced, and the interpolation tables are much nicer than the older min/max/scale/offset stuff and should allow for a more realistic panel without adding a full equation parser to the property manager. </p> <p> If you want to try this out, look at the airspeed.xml file in the base package, and uncomment the interpolation table in it for a very funky, non-linear and totally unreliable airspeed indicator. </p> <HR WIDTH="20%"> <H2><A NAME="actions">Actions:</A></H2> <HR WIDTH="20%"> <p> 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. The x/y placement for actions specifies the origin of the lower left corner. In the following example the first action sets up a hotspot 32 pixels wide and 16 pixels high. It lower left corner is placed 96 pixels (relative to the defined base size of the instrument) to the right of the center of the instrument. It is also 32 pixels below the centerline of the instrument. The actual knob texture over which the action is superimposed is 32x32. Omitted here is a second action, bound to the same property, with a positive increment value. This second action is placed to cover the other half of the knob. The result is that clicking on the left half of the knob texture decreases the value and clicking the right half increases the value. Also omitted here is a second pair of actions with the same coordinates but a larger increment value. This second pair is bound to a different mouse button. The net result is that we have both fine and coarse adjustments in the same hotspot, each bound to a different mouse button. </p> <p> These examples come from the radio stack: </p> <pre> <actions> <!-- open the actions section --> <action> <!- first action --> <name>small nav frequency decrease</name> <type>adjust</type> <button>0</button> <!-- bind it to a mouse button --> <x>96</x> <!-- placement relative to instrument center --> <y>-32</y> <w>16</w> <!-- size of hotspot --> <h>32</h> <property>/radios/nav1/frequencies/standby-mhz</property> <!-- bind to a property --> <increment>-0.05</increment> <!-- amount of adjustment per mouse click --> <min>108.0</min> <!-- lower range --> <max>117.95</max> <!-- upper range --> <wrap>1</wrap> <!-- boolean value -- value wraps around when it hits bounds --> </action> <action> <name>swap nav frequencies</name> <type>swap</type> <!-- define type of action --> <button>0</button> <x>48</x> <y>-32</y> <w>32</w> <h>32</h> <property1>/radios/nav1/frequencies/selected-mhz</property1> <!-- properties to toggle between --> <property2>/radios/nav1/frequencies/standby-mhz</property2> </action> <action> <name>ident volume on/off</name> <type>adjust</type> <button>1</button> <x>40</x> <y>-24</y> <w>16</w> <h>16</h> <property>/radios/nav1/ident</property> <!-- this property is for Morse code identification of nav beacons --> <increment>1.0</increment> <!-- the increment equals the max value so this toggles on/off --> <min>0</min> <max>1</max> <wrap>1</wrap> <!-- a shortcut to avoid having separate actions for on/off --> </action> </actions> </pre> <br> <HR WIDTH="20%"> <H2><A NAME="more_texture">More About Textures:</A></H2> <HR WIDTH="20%"> <p> As previously stated, the usual size instrument texture files in FGFS are 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. </p> <p> The following table can be used to calculate texture cropping specifications. </p> <pre> # 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 256 = 1 pixel, 0.00390625 </pre> <br> <p> The displayed size of a texture in pixels is set in the instrument configuration file. The size of the cropped area in pixels is not directly related to the final display size. </p> <p> What that table represents is: </p> <p> 1 / (256 / # of pixels) </p> <p> Take as an example, a section 64 pixels wide on the texture file. 256/64 = 4 1/4 = 0.25 </p> <p> Or lets consider 1 pixel wide 256/1 = 256 1/256 = 0.00390625 </p> <p> If the section starts at the extreme left of the texture, the starting number is 0.0 and the end is 0.25 If the section *doesn't* start at the edge you need to take the starting pixel and calculate an offset. Lets say you start 2 pixels from the edge and you are cropping a section 64 pixels wide... </p> <pre> 256/2 = 128 1/128 = 0.0078125 <- this is the value for a 2 pixel wide offset 0.0078125 <- start at 0.25 <- add value for 64 px wide 0.2571825 <- end at </pre> <br> <HR WIDTH="20%"> <H2><A NAME="generating_textures">Generating Textures:</A></H2> <HR WIDTH="20%"> <p> A common procedure for generating gauge faces is to use a vector graphics package such as xfig, exporting the result as a postscript file. 3D modeling tools may also be used and I prefer them for pretty items 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 can be imported into a graphics manipulation package such as GIMP, et al for final processing. </P> <HR WIDTH="20%"> <H2><A NAME="contribute">Contributing Panels And Instruments</A></H2> <HR WIDTH="20%"> <p> There are two main considerations when contributing panels and instruments. Firstly, original artwork is a major plus since you as the creator can dictate the terms of distribution. All Artwork must have a license compatible with the GPL. Artwork of unverifiable origin is not acceptable. Secondly, texture sizes must meet the lowest common denominator of 256e2 pixels. Artwork from third parties may be acceptable if it meets these criteria. </p> <HR WIDTH="20%"> <H2><A NAME="units">UNITS:</A></H2> <HR WIDTH="20%"> <p> Here is a list of property names including appropriate units: </p> <PRE> /autopilot/locks/nav1 => /autopilot/locks/nav[0] /autopilot/settings/altitude += "-ft" /autopilot/settings/climb-rate += "-fpm" /autopilot/settings/heading-bug += "-deg" /consumables/fuel/tank1/level => /consumables/fuel/tank[0]/level-gal_us /consumables/fuel/tank2/level => /consumables/fuel/tank[1]/level-gal_us /engines/engine0/cht => /engines/engine[0]/cht-degf /engines/engine0/egt => /engines/engine[0]/egt-degf /engines/engine0/fuel-flow => /engines/engine[0]/fuel-flow-gph /engines/engine0/mp => /engines/engine[0]/mp-osi /engines/engine0/rpm => /engines/engine[0]/rpm /environment/clouds/altitude += "-ft" /environment/magnetic-dip += "-deg" /environment/magnetic-variation += "-deg" /environment/visibility += "-m" /environment/wind-down += "-fps" /environment/wind-east += "-fps" /environment/wind-north += "-fps" /orientation/heading += "-deg" /orientation/heading-magnetic += "-deg" /orientation/pitch += "-deg" /orientation/roll += "-deg" /position/altitude += "-ft" /position/altitude-agl += "-ft" /position/latitude += "-deg" /position/longitude += "-deg" /radios/adf/frequencies/selected += "-khz" /radios/adf/frequencies/standby += "-khz" /radios/adf/rotation += "-deg" /radios/nav1/* => /radios/nav[0]/* /radios/nav2/* => /radios/nav[1]/* /radios/nav[*]/dme/distance += "-nm" /radios/nav[*]/frequencies/selected += "-mhz" /radios/nav[*]/frequencies/standby += "-mhz" /radios/nav[*]/radials/actual += "-deg" /radios/nav[*]/radials/selected += "-deg" /sim/model/h-rotation => /sim/model/heading-offset-deg /sim/model/p-rotation => /sim/model/roll-offset-deg /sim/model/r-rotation => /sim/model/pitch-offset-deg /sim/model/x-offset += "-m" /sim/model/y-offset += "-m" /sim/model/z-offset += "-m" /sim/view/goal-offset += "-deg" /sim/view/offset += "-deg" /steam/adf += "-deg" /steam/airspeed += "-kt" /steam/altitude += "-ft" /steam/gyro-compass += "-deg" /steam/gyro-compass-error += "-deg" /steam/mag-compass += "-deg" /steam/vertical-speed += "-fpm" /velocities/airspeed += "-kt" /velocities/side-slip += "-rad" /velocities/speed-down += "-fps" /velocities/speed-east += "-fps" /velocities/speed-north += "-fps" /velocities/uBody += "-fps" /velocities/vBody += "-fps" /velocities/wBody += "-fps" /velocities/vertical-speed += "-fps" </pre> <br> <p> * 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. </P> <p> ** 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). </p> </BODY> </HTML>