--- /dev/null
+Users' Guide to FlightGear Hud configuration
+December 22 2000
+Neetha Girish <neetha@ada.ernet.in>
+
+This document describes the reconfigurable HUD of
+FlightGear implemented through XML config files.
+The present reconfigurable HUD code uses most of the code
+of version 0.6.1 vintage and I have adapted the same to provide
+a reconfigurable HUD for fgfs.
+Corrections and additions are welcome.
+
+Some History:
+
+Older versions of FGFS had a hard coded display of HUD.
+This was a less than ideal state of affairs when it came to
+using different aircraft Huds. I remember, somewhere in the 0.6.1 HUD code
+it was written that the HUD code is 'presently' hard coded but ideally should
+be moved into the aircraft configuration dataset, so that when you choose
+an aircraft, its HUD loads.
+This implementation make that possible, all you have to do is to
+create appropriate 'my_aircraft.xml' files in the HUD directory and
+without re-compiling the code you could have 'your_aircraft' HUD, by choosing that
+in the .fgfsrc file or as a command line option as described later. Of course,
+as of now, I have only implemented those HUD instruments in .xml readable form
+as was available in version 0.7.6 + few more used by ADA, Bangalore for our
+aircraft carrier take-off/landing simulation studies <www.flightgear.org/projects/ADA>.
+To use the ADA specific reticles/HUD objects, please contact me/ you can figure it out
+yourself by studying the code. All of them are relevant 'only' if you use the conformal
+climb/dive ladder, since they are all referenced to it.
+The rewrite of Hud display code was done using pre and post release v0.7.6 code
+allowing for configuration of the hud via XML.
+
+The present Configurable Hud implements the entire functionality of
+fgfs HUD (called default HUD) till this date.
+
+Using Default/Custom Hud:
+
+The default HUD location is $FG_ROOT/Huds/Default.
+$FG_ROOT is the place on your filesystem where you installed FG
+data files. Alternate huds 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/hud/path=Huds/Default/default.xml
+
+The path description shown is relative to $FG_ROOT. An absolute
+path may also be used for locations outside $FG_ROOT.
+For the custom Hud the path will be Huds/Custom/default.xml
+
+
+Hud - Implementation:
+
+All of the hud 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> and zero or more <instruments>.
+Instruments are used by including a <"unique_name"> and a <path> to the
+instruments configuration file.
+Comments are bracketed with <!-- -->.
+
+ Example Top Level Hud Config
+
+<PropertyList>
+ <name>Default Aircraft Hud</name>
+ <instruments>
+
+ <hudladder> <!--unique name -->
+ <path>Huds/Instruments/Default/hudladder.xml</path>
+ </hudladder>
+
+ <hudcard>
+ <path>Huds/Instruments/Default/hudcard.xml</path>
+ </hudcard>
+
+ <instrlabel>
+ <path>Huds/Instruments/Default/instrlabel.xml</path>
+ </instrlabel>
+
+ <fgTBI>
+ <path>Huds/Instruments/Default/fgtbi.xml</path>
+ </fgTBI>
+
+ </instruments>
+</PropertyList>
+
+
+The default location for instrument files is $FG_ROOT/Huds/Instruments/Default.
+The location for custom instrument files is $FG_ROOT/Huds/Instruments/Custom.
+The location for minimal instrument files is $FG_ROOT/Huds/Instruments/Minimal.
+Alternate locations may be specified in the hud configuration, paths
+must be absolute to use files outside $FG_ROOT.
+
+About Instrument Placement:
+
+For the sake of simplicity the FGFS HUD overlay is always 640 x 480 res.
+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.
+
+Instrument Implementation:
+
+Instruments are defined in separate configuration files.
+The Instruments are basically classified into 4 types( Each of them an xml file) :
+The Hud Ladder,
+The Hud Card,
+The Hud Label and
+The Turn Bank Indicator
+.... (Note that that the earlier HUD classes/objects have been retained)
+Newer objects may be instantiated using the above classes, Unless a totally
+new object is required).
+
+The Default as well as the Custom directory have the same (in terms of properties)
+set of configuration files (but with different values to suit the aircraft).
+
+We have a Base class - Hud Instrument Item.
+We derive two more base classes - Instrument Scale and Dual Instrument Item from this.
+(This implementation owes its existence to all those who wrote the HUD code for 0.6.1)
+
+The Hud Instrument Label is an instantiable class derived from Hud Instrument Item - for
+displaying alphanumeric labels (altitude, velocity, Mach no and/or anything else as long you
+have a call back function to pass the value using the property 'data_source').
+
+The Hud Card is an instantiable class derived from Instrument scale - for displaying
+tapes and guages (single variable display, for displaying aoa, g's, vsi, elevator_posn, etc.).
+
+The Hud Ladder is an instantiable class derived from Dual Instrument Item - for displaying
+pitch reference ladder or climb/dive ladder (two variable display, for dislaying two types of
+ladders, the pitch reference ladder or the climb/dive ladder as defined by MIL-1787b).
+
+The fgTBI Instrument is an instantiable class derived from Dual Instrument scale again
+- for display of Bank angle and Sideslip (two variable display, for display of TSI info, kept
+different from the two variable ladder object basically because of its totally different
+draw member function).
+
+Most Hud instruments may be instantiated using above. It is proposed to provide all
+Hud objects as defined in MIL-STD-1797A, soon.
+
+Here is how you position 'any' object:
+
+x ____________ x+width
+ | |
+ | |
+y ------------ y+height
+
+this defines the objects position centered about the centroid of above rectangle
+in HUD overlay plane (640x480) coordinates with 0,0 at bottom-left corner.
+
+One more, pixels per degree in the ladder class represents the compression factor of the
+pitch ladder. In case of conformal HUD (climd/dive ladder) it is <640/horizontal_fov>
+or <480/vertical_fov>. In case of pitch reference ladder it is
+<your_no_of vertical_pixels/your_no_of_ladder_degrees>.
+
+Example of Hud Ladder xml file.
+
+<PropertyList>
+
+ <ladders>
+
+ <l1>
+ <name>Pitch Ladder</name> <!-- Name can be Pitch Ladder or Climb/Dive Ladder -->
+ <x>260</x> <!-- x start -->
+ <y>150</y> <!-- y start -->
+ <width>120</width> <!-- x start + width = x end -->
+ <height>180</height> <!-- y start + height = y end -->
+ <compression_factor>2.68</compression_factor> <!-- Pixels per degree -->
+ <loadfn>roll</loadfn> <!-- Name of the function to be called, here get_roll() is called provision made in Hud.cxx -->
+ <loadfn1>pitch</loadfn1> <!-- Name of the function to be called, here get_pitch() is called -->
+ <span_units>45.0</span_units> <!-- Range of the Ladder seen at any instant -->
+ <division_units>10.0</division_units> <!-- Divisions -->
+ <screen_hole>70</screen_hole> <!-- Hole b/w the Ladder Bars-->
+ <lbl_pos>0</lbl_pos> <!-- Label Position to indicate pitch angle on bar -->
+ <enable_frl>false</enable_frl> <!-- To Enable Pitch Reference Symbol (used by us) -->
+ <enable_target_spot>true</enable_target_spot> <!-- To Enable Target Spot Symbol (fgfs uses this)-->
+ <enable_velocity_vector>false</enable_velocity_vector> <!-- To Enable Velocity Vector Symbol (use only with climb/dive ladder)-->
+ <enable_drift_marker>false</enable_drift_marker> <!-- To Enable Drift Marker Symbol (used by us)-->
+ <enable_alpha_bracket>false</enable_alpha_bracket> <!-- To Enable Alpha Bracket Symbol (used by us, presently hard coded bracket values, alpha values will be moved to xml file)-->
+ <enable_energy_marker>false</enable_energy_marker> <!-- To Enable Energy Marker Symbol (used by us)-->
+ <enable_climb_dive_marker>false</enable_climb_dive_marker> <!-- To Enable Climb/Dive Marker (used by us)-->
+ <enable_glide_slope_marker>false</enable_glide_slope_marker> <!--To Enable Glide/Slope Marker (tied to climb/dive ladder only)-->
+ <glide_slope>0.0</glide_slope> <!-- Glide slope angle (specify the angle for drawing the reference bar)
+ <enable_energy_worm>false</enable_energy_worm> <!-- To Enable Energy worm (used by us)>
+ <enable_waypoint_marker>false</enable_waypoint_marker> <!-- To Enable Way point Marker (bearing marker)-->
+ <working>true</working> <!use this to enable or disbale whole object>
+ </l1>
+
+ </ladders>
+
+</PropertyList>
+
+Before you read this, _____ this is tick_top | |
+ | | |
+ | |__________________|
+ | this is cap_right,tick_left cap_bottom tick_right
+ |
+ _____| this is tick_bottom
+
+Example of Hud Card xml file.
+
+<PropertyList>
+
+ <cards>
+
+ <c1>
+ <name>Gyrocompass</name>
+ <x>220</x>
+ <y>430</y>
+ <width>200</width>
+ <height>28</height>
+ <loadfn>heading</loadfn> <!-- Name of the function to be called, here get_Heading() is called -->
+ <options>4</options> <!-- Read Tape Options Below or Hud.hxx file for details -->
+ <maxValue>360.0</maxValue> <!-- Maximum scale value -->
+ <minValue>0.0</minValue> <!-- Minimum Scale Value -->
+ <disp_scaling>1.0</disp_scaling> <!-- Multiply by this to get numbers shown on scale -->
+ <major_divs>5</major_divs> <!-- major division marker units -->
+ <minor_divs>1</minor_divs> <!-- minor division marker units -->
+ <modulator>360</modulator> <!-- Its a rose, Roll Over Point -->
+ <value_span>25.0</value_span> <!-- Range Shown -->
+ <type>tape</type> <!-- Card type can be "tape" or "guage" -->
+ <tick_bottom>false</tick_bottom> <!-- Read Ticks and Caps below -->
+ <tick_top>false</tick_top>
+ <tick_right>true</tick_right>
+ <tick_left>true</tick_left>
+ <cap_bottom>true</cap_bottom>
+ <cap_top>false</cap_top>
+ <cap_right>false</cap_right>
+ <cap_left>false</cap_left>
+ <marker_offset>0.0</marker_offset> <!-- Read Marker offset below -->
+ <enable_pointer>true</enable_pointer> <!-- To draw a pointer -->
+ <pointer_type>fixed</pointer_type> <!-- Type of pointer, Fixed or Moving (yet to be implemented)-->
+ <working>true</working>
+ </c1>
+
+ </cards>
+
+</PropertyList>
+
+Tape Options:
+
+HUDS_AUTOTICKS = 0x0001
+HUDS_VERT = 0x0002
+HUDS_HORZ = 0x0000
+HUDS_TOP = 0x0004
+HUDS_BOTTOM = 0x0008
+HUDS_LEFT = HUDS_TOP
+HUDS_RIGHT = HUDS_BOTTOM
+HUDS_BOTH = (HUDS_LEFT | HUDS_RIGHT)
+HUDS_NOTICKS = 0x0010
+HUDS_ARITHTIC = 0x0020
+HUDS_DECITICS = 0x0040
+HUDS_NOTEXT = 0x0080
+HUDS_LEFT | HUDS_VERT = 0x0006
+HUDS_RIGHT | HUDS_VERT = 0x0010
+HUDS_TOP | HUDS_NOTEXT = 0x0084
+HUDS_BOTTOM | HUDS_NOTEXT = 0x0088
+HUDS_VERT | HUDS_LEFT | HUDS_NOTEXT = 0x0086
+HUDS_RIGHT | HUDS_VERT | HUDS_NOTEXT = 0x0090
+
+
+For clarity, I repeat, Ticks and Caps :
+
+
+1. Left Tick ->|_____|<- Right Tick
+ |
+ v
+ Bottom Cap
+
+2. Top Cap
+ |
+ v
+ _____
+ | |
+
+
+3. Top Tick
+ |
+ v
+ ---
+ |
+ |<- Right Cap
+ |
+ ---
+ |
+ v
+ Bottom Tick
+
+4. ---
+ |
+ Left Cap -> |
+ |
+ ---
+
+Marker Offset :
+
+To Draw pointer on the scale markings. In the case of a our hud with offset 10.0
+The pointer is away from the scale and points at the markings.
+
+ -| -
+ -| -
+ <| -<
+ -| -
+ -| -
+Marker offset = 0.0 Marker offset = 10.0
+
+This should be useful when I implement the fixed tape/moving pointer.
+
+
+Example of a Label xml file.
+
+<PropertyList>
+
+ <labels>
+
+ <i1>
+ <name>machno</name>
+ <x>25</x>
+ <y>130</y>
+ <width>40</width>
+ <height>30</height>
+ <data_source>mach</data_source> <!-- Name of the function to be called, here get_Heading() is called -->
+ <label_format>%4.2f</label_format> <!-- The Label Format -->
+ <pre_label_string>blank</pre_label_string> <!-- String to be written Pre Label -->
+ <post_label_string>NULL</post_label_string> <!-- String to be written Post Label -->
+ <scale_data>1.0</scale_data>
+ <options>4</options> <!-- Read Tape options or Hud.hxx -->
+ <justification>2</justification> <!-- Justify the label, 0=LEFT_JUSTIFY, 1=CENTER_JUSTIFY, 2=RIGHT_JUSTIFY -->
+ <blinking>0</blinking> <!-- Yet to be implemented -->
+ <working>true</working>
+ <latitude>false</latitude> <!-- True if the label is to display Lattitude (special label, displays deg.min.sec)-->
+ <longitude>false</longitude> <!-- True if the label is to display Longitude (special label, displays deg.min.sec)-->
+ </i1>
+
+ </labels>
+
+</PropertyList>
+
+
+Example of a Turn Bank Indicator xml file.
+
+<PropertyList>
+
+ <tbis>
+
+ <f1>
+ <name>fgTBI_Instrument</name>
+ <x>290</x>
+ <y>45</y>
+ <width>60</width>
+ <height>10</height>
+ <loadfn>roll</loadfn> <!-- Name of the function to be called, get_roll() is called here. -->
+ <loadfn1>sideslip</loadfn1> <!-- Name of the function to be called, get_sideslip() is called here. -->
+ <maxBankAngle>45.0</maxBankAngle> <!-- Maximum Angle of Bank -->
+ <maxSlipAngle>5.0</maxSlipAngle> <!-- Maximum Angle of Slip -->
+ <gap_width>5</gap_width> <!-- Screen Hole -->
+ <working>true</working>
+ </f1>
+
+ </tbis>
+
+</PropertyList>
+
+I have still got to implement dials (as in MIL-STD-1787b).
+
+REMEMBER IF YOU NEED TO INDICATE ANY OTHER PARAMETER ON THE HUD OTHER THAN WHAT IS PROVIDED AS
+CALLBACK FUNCTIONS (PROPERTY NAMES LISTED BELOW) YOU HAVE TO FIDDLE WITH THE CODE, AS YET. LET ME
+KNOW AND I SHALL INCLUDE THAT.
+
+<loadfn>anzg</loadfn> <!-- Here get_anzg() is called -->
+<loadfn>heading</loadfn> <!-- Here get_heading() is called -->
+<loadfn>aoa</loadfn> <!-- Here get_aoa() is called -->
+<loadfn>climb</loadfn> <!-- Here get_climb() is called -->
+<loadfn>altitude</loadfn> <!-- Here get_altitude() is called -->
+<loadfn>agl</loadfn> <!-- Here get_agl() is called -->
+<loadfn>speed</loadfn> <!-- Here get_speed() is called -->
+<loadfn>view_direction</loadfn> <!-- Here get_view_direction() is called -->
+<loadfn>aileronval</loadfn> <!-- Here get_aileronval() is called -->
+<loadfn>elevatorval</loadfn> <!-- Here get_elevatorval() is called -->
+<loadfn>rudderval</loadfn> <!-- Here get_rudderval() is called -->
+<loadfn>throttleval</loadfn> <!-- Here get_throttleval() is called -->
+<loadfn>aux16</loadfn> <!-- Here get_aux16() is called -->
+<loadfn>aux17</loadfn> <!-- Here get_aux17() is called -->
+<loadfn>aux9</loadfn> <!-- Here get_aux9() is called -->
+<loadfn>aux11</loadfn> <!-- Here get_aux11() is called -->
+<loadfn>aux12</loadfn> <!-- Here get_aux12() is called -->
+<loadfn>aux10</loadfn> <!-- Here get_aux10() is called -->
+<loadfn>aux13</loadfn> <!-- Here get_aux13() is called -->
+<loadfn>aux14</loadfn> <!-- Here get_aux14() is called -->
+<loadfn>aux15</loadfn> <!-- Here get_aux15() is called -->
+<loadfn>aux8</loadfn> <!-- Here get_aux8() is called -->
+<loadfn>ax</loadfn> <!-- Here get_Ax() is called -->
+<loadfn>mach</loadfn> <!-- Here get_mach() is called -->
+<loadfn>framerate</loadfn> <!-- Here get_frame_rate() is called -->
+<loadfn>fov</loadfn> <!-- Here get_fov() is called -->
+<loadfn>vfc_tris_culled</loadfn> <!-- Here get_vfc_tris_culled() is called -->
+<loadfn>vfc_tris_drawn</loadfn> <!-- Here get_vfc_tris_drawn() is called -->
+<loadfn>latitude</loadfn> <!-- Here get_latitude() is called -->
+<loadfn>longitude</loadfn> <!-- Here get_longitude() is called -->
+
+
+
+
+
+
+
+
+
+
+
+
projects / flightgear.git / commitdiff