X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=docs-mini%2FREADME.xmlpanel;h=960dd2e6367620e2ef555b294bf2c251a8ab201e;hb=a7e1054a086dc7de9dd17eecaef923cd793ecdbc;hp=08830190cc1b90022b007891ee4f164289a1e576;hpb=5018278831a8340f3abbc27965b763931159cbf3;p=flightgear.git diff --git a/docs-mini/README.xmlpanel b/docs-mini/README.xmlpanel index 08830190c..960dd2e63 100644 --- a/docs-mini/README.xmlpanel +++ b/docs-mini/README.xmlpanel @@ -1,139 +1,650 @@ Users Guide to FlightGear panel configuration -Version 0.4, October 11 2000 -Author: John Check +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. I'd -like to say thanks to all the developers who make FGFS happen. -Corrections and additions are encouraged. +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. -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. Some major changes and additions were +made during the course of version 0.7.7 necessitating a rewrite and +expansion of this document. -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. +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: -Using Custom Panels: +fgfs --props=socket,bi,5,localhost,5500,tcp -The default panel location is $FG_ROOT/Panels/Default/default.xml. -$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/system.fgfsrc -using a property specification. The format is as follows: +Then use telnet to connect to localhost on port 5500. You can browse +the tree as you would a filesystem. ---prop:/sim/panel/path=Panels/Default/default.xml +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. -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. +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 -Panel Architecture: +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. -All of the panel configuration files are XML-encoded* property lists. +Panel Architecture: +------------------- +All of the panel configuration files are XML-encoded* property lists. The root element of each file is always named . Tags are -always found in pairs, with the closing tag having a slash prefixing -the tag name, i.e . The top level panel configuration -file is composed of a , a texture and zero or more -. Instruments are used by including a <"unique_name">, a - to the instruments configuration file, and placement -coordinates, and optional and size specifications. -Comments are bracketed with . +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) - Example Top Level Panel Config +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. - - Example Panel - Panels/Default/Textures/panel-bg.rgb - - - Instruments/Default/clock.xml - 110 - 320 +[ 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 + + + - -The default location for instrument files is $FG_ROOT/Instruments/Default/. -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. +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 -Instrument Architecture: + + 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 preferred width and height, one or more stacked layers, -and zero or more actions. - -A layer** can be a , or be of 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/Instruments/Default/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 +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. -About Transformations and Needle Placement: +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 + + -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 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. +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. -About Textures: +The following table can be used to calculate texture cropping +specifications. -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. +# 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, +* 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. + 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, @@ -141,4 +652,3 @@ defining which section of the texture to use. weather-radar display or a GPS (though the GPS could be handled with text properties). -