X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=docs-mini%2FREADME.xmlpanel;h=960dd2e6367620e2ef555b294bf2c251a8ab201e;hb=d254b2a331df0062dd5fd9c1014da71bed753c63;hp=bb524aef8aad97db7cb6364d0a9583654d42a309;hpb=38b0d2b1519e7ebb5998fb03d6ed376deda9d30b;p=flightgear.git diff --git a/docs-mini/README.xmlpanel b/docs-mini/README.xmlpanel index bb524aef8..960dd2e63 100644 --- a/docs-mini/README.xmlpanel +++ b/docs-mini/README.xmlpanel @@ -1,92 +1,654 @@ Users Guide to FlightGear panel configuration -First Draft -Author: John Check - -This document is an attempt to describe the configuration via -XML of FlightGear flight simulator's aircraft panel display. -The information was culled from the fgfs-devel@flightgear.org -mailing list. I'd like to say thanks to all the developers who -make FGFS happen and forgive me for any errors with regards to -who did what. I'd like to reguest that anybody who should be -mentioned give me a heads up so I can credit them properly. -Corrections and additions are encouraged. - -History: -Older versions of FGFS had a hardcoded 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 alternatatives 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. - -The Basics: - -David Megginson wrote: - -> To get started, here's a basic, mostly-architectural outline: -> -> 1. All configuration files are XML-encoded property lists. The root -> element is always named . None of the properties is -> mixed in with the main FlightGear properties (they're all separate -> lists). -> -> 2. There is a single, top-level configuration file for each panel. -> There is also a top-level configuration file for each instrument (I -> may also add configuration files for cropped textures, to enabled -> better reuse of common textures like needles and knobs). -> -> 3. A panel is composed of a background texture and zero or more -> instruments. The panel sets the position of each instrument and may -> also override the instrument's preferred size (the default panel does -> not do so, but if you want an altimeter covering a quarter of the -> screen, go for it!). -> -> 4. An instrument consists of a preferred width and height, one or more -> stacked layers, and zero or more actions. It is defined in a separate -> file. -> -> 5. A layer can be a texture (with alpha areas so that lower textures -> show through), text (static, generated, or both), or a switch between -> two other layers based on a boolean property. Each layer contains -> zero or more transformations. -> -> 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). -> -> 6. A transformation is a rotation, an x-shift, or a y-shift. -> Transformations can be static (rotate 90 degrees) or they can be based -> on properties (rotate the number of degrees equal to the airspeed -> times something plus something else, etc.). -> -> 7. An action is a hotspot on an instrument where something will happen -> when the user clicks the left or centre 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. -> -> 8. You can find panel configuration files under $FG_ROOT/Panels/ and -> instrument configuration files under $FG_ROOT/Instruments/. -> -> 9. If there are *any* XML parsing errors, the panel will fail to load -> (them's the XML rules), so it's worth downloading a parser like Expat -> (http://www.jclark.com/xml/) so that you can check your XML. -> FlightGear will print the location of errors, but the messages are a -> little cryptic right now. -> -> 10. You can set the relative location of the top-level XML panel file -> (under $FG_ROOT) using the "/sim/panel" property. The default is -> $FG_ROOT/Panels/Default/default.xml. - -To do: - -Add some examples. -Integrate additonal questions and answers from the list. +Version 0.7.7, May 16 2001 +Author: John Check + +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. 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 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. + +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. + + +About The Property Manager: +-------------------------- +While not absolutely necessary in order to create aircraft panels, +some familiarity with the property manager is beneficial.... +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. 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 placed on 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: + +fgfs --props=socket,bi,5,localhost,5500,tcp + +Then use telnet to connect to localhost on port 5500. You can browse +the tree as you would a filesystem. + +XML and the Property Manager: +---------------------------- +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. + +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: + +--prop:/sim/panel/path=Aircraft/c172/Panels/c172-panel.xml + +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. + +The order of precedence for options is thus: + +Source Location Format +------ -------- ------ +command line +.fgfsrc Users home directory. command line options +system.fgfsrc $FG_ROOT "" "" +preferences.xml $FG_ROOT XML property list + + +Loading Panels on the fly: +------------------------- +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. + +Regarding Window Geometry: +------------------------- +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. + +Panel Architecture: +------------------- +All of the panel configuration files are XML-encoded* property lists. +The root element of each file is always named . Tags are +almost always found in pairs, with the closing tag having a slash +prefixing the tag name, i.e . The exception is the tag +representing an aliased property. In this case a slash is prepended to +the closing angle bracket. (see section Aliasing) + +The top level panel configuration file is composed of a , a + texture and zero or more .Earlier versions +required instruments to have a unique name and a path specification +pointing to the instruments configuration file. + +[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ] +[ Absolute paths may be used.Comments are bracketed with . ] + +Old style instrument call in top level panel.xml: +------------------------------------------------ + + Aircraft/c172/Instruments/clock.xml + 110 + 320 + 72 + 72 + + +The difference between the old and new styles, while subtle, is rather +drastic. The old and new methods are indeed incompatible. I cover the +old style only to acknowledge the incompatibility. This section will +be removed after the next official FGFS release. + +New Style Example Top Level Panel Config: +---------------------------------------- + + Example Panel + Aircraft/c172/Panels/Textures/panel-bg.rgb + 1024 + 768 + -305 + 172 + + + + + Chronometer + 150 + 645 + 72 + 72 + + + + + + + +Indexed Properties +------------------ +This is a lot to do with the compatibility break so lets get it out of +the way. The property manager now assigns incremental indices to +repeated properties with the same parent node, so that + + + 1 + 2 + 3 + + +shows up as + + /x[0] = 1 + /x[1] = 2 + /x[2] = 3 + +This means that property files no longer need to make up a separate +name for each item in a list of instruments, layers, actions, +transformations, or text chunks. In fact, the new panel I/O code now +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. + +Inclusion: +---------- +The property manager now supports file inclusion and aliasing. +Inclusion means that a node can include another property file as if it +were a part of the current file. To clarify how inclusion works, +consider the following examples: + +If bar.xml contains + + + 1 + + 2 + + + +then the declaration + + + + +is exactly equivalent to + + + 1 + + 2 + + + +However, it is also possible to selectively override properties in the +included file. For example, if the declaration were + + + 3 + + +then the property manager would see + + + 3 + + 2 + + + +with the original 'a' property's value replaced with 3. + +This new inclusion feature allows property files to be broken up and +reused arbitrarily -- for example, there might be separate cropping +property lists for commonly-used textures or layers, to avoid +repeating the information in each instrument file. + + +Aliasing +-------- +Properties can now 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, + + + 3 + + + +will look the same to the application as + + + 3 + 3 + + +except that when foo changes value, bar will change too. + + +The combination of inclusions and aliases is very powerful, because it +allows for parameterized property files. For example, the XML file for +the NAVCOM radio can include a parameter subtree at the start, like +this: + + + + /radios/comm1/frequencies/selected + /radios/nav1/frequencies/selected + + + ... + + + number-value + + + + ... + + +Now, the same instrument file can be used for navcomm1 and navcomm2, +for example, simply by overriding the parameters at inclusion: + + + + /radios/comm1/frequencies/selected + /radios/nav1/frequencies/selected + + + + + + /radios/comm2/frequencies/selected + /radios/nav2/frequencies/selected + + + +Instrument Architecture: +----------------------- +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: + + + Airspeed Indicator + 128 + 128 + + +Height and width can be overriden in the top level panel.xml by +specifying and . Transformations are caculated against the base +size regardless of the display size. This ensures that instruments +remain calibrated + +Textures: +-------- +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. + +Instrument Layers**: +------------------- +The simplest layer is a . These can be combined in layers + + +A texture layer looks like this: + + + face + + Aircraft/c172/Instruments/Textures/faces-2.rgb + 0 + 0.51 + 0.49 + 1.0 + + + +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. + +This particular layer, being a gauge face has no transformations +applied to it. Layers with that aren't static *must* include and + parameters to be visible. + + May be either text or switch.. + +switch +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. + + + Brake light + switch + /controls/brakes + + on + + Aircraft/c172/Instruments/Textures/brake.rgb + 0.25 + 0.0 + 0.5 + 0.095 + + 64 + 24 + + + off + + Aircraft/c172/Instruments/Textures/brake.rgb + 0.0 + 0.0 + 0.25 + 0.095 + + 64 + 24 + + + +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. + +text +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: + + + display + text + 12 + + 1.0 + 0.5 + 0.0 + + + + number-value + /radios/nav1/dme/distance + 0.00053995680 + %5.1f + + + + + display + text + 10 + + 1.0 + 0.5 + 0.0 + + + + literal + ---.-- + + + + + +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 +. 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 texure 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. + + +About Transformations and Needle Placement: +------------------------------------------ + +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 x-shift +or y-shift depending on the orientation of the needle section in the +cropped texture. + +This example comes from the altimeter.xml + + + long needle (hundreds) + + Aircraft/c172/Instruments/Textures/misc-1.rgb + 0.8 + 0.78125 + 0.8375 + 1.0 + + 8 + 56 + + + rotation + /steam/altitude + 100000.0 + 0.36 + + + y-shift + 24.0 + + + + +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, + +Interpolation +------------- +Non linear transformations are now possible via the use of +interpolation tables. + + + ... + + + 0.0 + 0.0 + + + 10.0 + 100.0 + + + 20.0 + -5.0 + + + 30.0 + 1000.0 + + + + +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. + +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. + + +Actions: +------- +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. + +These examples come from the radio stack: + + + small nav frequency decrease + adjust + + 96 + -32 + 16 + 32 + /radios/nav1/frequencies/standby + -0.05 + 108.0 + 117.95 + 1 + + + swap nav frequencies + swap + + 48 + -32 + 32 + 32 + /radios/nav1/frequencies/selected + /radios/nav1/frequencies/standby + + + ident volume on/off + adjust + + 40 + -24 + 16 + 16 + /radios/nav1/ident + 1.0 + 0 + 1 + 1 + + + +More About Textures: +------------------- +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. + +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 + +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. + +How do I get my panels/instruments into the base package? +------------------------------------------------------- +Cash bribes always help ;) Seriously though, there are two main +considerations. 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. + +* 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). +