1Users' Guide to FlightGear Hud configuration 2December 22 2000 3Neetha Girish <neetha@ada.ernet.in> 4 5This document describes the reconfigurable HUD of 6FlightGear implemented through XML config files. 7The present reconfigurable HUD code uses most of the code 8of version 0.6.1 vintage and I have adapted the same to provide 9a reconfigurable HUD for fgfs. 10Corrections and additions are welcome. 11 12Some History: 13 14Older versions of FGFS had a hard coded display of HUD. 15This was a less than ideal state of affairs when it came to 16using different aircraft Huds. I remember, somewhere in the 0.6.1 HUD code 17it was written that the HUD code is 'presently' hard coded but ideally should 18be moved into the aircraft configuration dataset, so that when you choose 19an aircraft, its HUD loads. 20This implementation make that possible, all you have to do is to 21create appropriate 'my_aircraft.xml' files in the HUD directory and 22without re-compiling the code you could have 'your_aircraft' HUD, by choosing that 23in the .fgfsrc file or as a command line option as described later. Of course, 24as of now, I have only implemented those HUD instruments in .xml readable form 25as was available in version 0.7.6 + few more used by ADA, Bangalore for our 26aircraft carrier take-off/landing simulation studies <www.flightgear.org/projects/ADA>. 27To use the ADA specific reticles/HUD objects, please contact me/ you can figure it out 28yourself by studying the code. All of them are relevant 'only' if you use the conformal 29climb/dive ladder, since they are all referenced to it. 30The rewrite of Hud display code was done using pre and post release v0.7.6 code 31allowing for configuration of the hud via XML. 32 33The present Configurable Hud implements the entire functionality of 34fgfs HUD (called default HUD) till this date. 35 36Using Default/Custom Hud: 37 38The default HUD location is $FG_ROOT/Huds/Default. 39$FG_ROOT is the place on your filesystem where you installed FG 40data files. Alternate huds can be specified on the command line 41or set as the default in the $HOME/.fgfsrc or $FG_ROOT/preferences.xml 42using a property specification. The command line format is as follows: 43 44--prop:/sim/hud/path=Huds/Default/default.xml 45 46The path description shown is relative to $FG_ROOT. An absolute 47path may also be used for locations outside $FG_ROOT. 48For the custom Hud the path will be Huds/Custom/default.xml 49 50 51Hud - Implementation: 52 53All of the hud configuration files are XML-encoded property lists. 54The root element of each file is always named <PropertyList>. Tags are 55always found in pairs, with the closing tag having a slash prefixing 56the tag name, i.e </PropertyList>. The top level panel configuration 57file is composed of a <name> and zero or more <instruments>. 58Instruments are used by including a <"unique_name"> and a <path> to the 59instruments configuration file. 60Comments are bracketed with <!-- -->. 61 62 Example Top Level Hud Config 63 64<PropertyList> 65 <name>Default Aircraft Hud</name> 66 <instruments> 67 68 <hudladder> <!--unique name --> 69 <path>Huds/Instruments/Default/hudladder.xml</path> 70 </hudladder> 71 72 <hudcard> 73 <path>Huds/Instruments/Default/hudcard.xml</path> 74 </hudcard> 75 76 <instrlabel> 77 <path>Huds/Instruments/Default/instrlabel.xml</path> 78 </instrlabel> 79 80 <fgTBI> 81 <path>Huds/Instruments/Default/fgtbi.xml</path> 82 </fgTBI> 83 84 </instruments> 85</PropertyList> 86 87 88The default location for instrument files is $FG_ROOT/Huds/Instruments/Default. 89The location for custom instrument files is $FG_ROOT/Huds/Instruments/Custom. 90The location for minimal instrument files is $FG_ROOT/Huds/Instruments/Minimal. 91Alternate locations may be specified in the hud configuration, paths 92must be absolute to use files outside $FG_ROOT. 93 94About Instrument Placement: 95 96For the sake of simplicity the FGFS HUD overlay is always 640 x 480 res. 97so all x/y values for instrument placement should fall within these bounds. 98Being an OpenGL program, 0,0 represents the lower left hand corner of the 99screen. 100 101Instrument Implementation: 102 103Instruments are defined in separate configuration files. 104The Instruments are basically classified into 4 types( Each of them an xml file) : 105The Hud Ladder, 106The Hud Card, 107The Hud Label and 108The Turn Bank Indicator 109.... (Note that that the earlier HUD classes/objects have been retained) 110Newer objects may be instantiated using the above classes, Unless a totally 111new object is required). 112 113The Default as well as the Custom directory have the same (in terms of properties) 114set of configuration files (but with different values to suit the aircraft). 115 116We have a Base class - Hud Instrument Item. 117We derive two more base classes - Instrument Scale and Dual Instrument Item from this. 118(This implementation owes its existence to all those who wrote the HUD code for 0.6.1) 119 120The Hud Instrument Label is an instantiable class derived from Hud Instrument Item - 121for displaying alphanumeric labels (altitude, velocity, Mach no and/or anything else 122as long you have a call back function to pass the value using the property 123'data_source'). 124 125The Hud Card is an instantiable class derived from Instrument scale - for displaying 126tapes and gauges (single variable display, for displaying aoa, g's, vsi, 127elevator_posn, etc.). 128 129The Hud Ladder is an instantiable class derived from Dual Instrument Item - for 130displaying pitch reference ladder or climb/dive ladder (two variable display, for 131displaying two types of ladders, the pitch reference ladder or the climb/dive ladder 132as defined by MIL-1787b). 133 134The fgTBI Instrument is an instantiable class derived from Dual Instrument scale 135again - for display of Bank angle and Sideslip (two variable display, for display 136of TSI info, kept different from the two variable ladder object basically because 137of its totally different draw member function). 138 139Most Hud instruments may be instantiated using above. It is proposed to provide all 140Hud objects as defined in MIL-STD-1797A, soon. 141 142Here is how you position 'any' object: 143 144x ____________ x+width 145 | | 146 | | 147y ------------ y+height 148 149this defines the objects position centered about the centroid of above rectangle 150in HUD overlay plane (640x480) coordinates with 0,0 at bottom-left corner. 151 152One more, pixels per degree in the ladder class represents the compression factor of 153the pitch ladder. In case of conformal HUD (climb/dive ladder) it is 154<640/horizontal_fov> or <480/vertical_fov>. In case of pitch reference ladder it is 155<your_no_of vertical_pixels/your_no_of_ladder_degrees>. 156 157Example of Hud Ladder xml file. 158 159<PropertyList> 160 161 <ladders> 162 163 <l1> 164 <name>Pitch Ladder</name> <!-- Name can be Pitch Ladder or Climb/Dive Ladder --> 165 <x>260</x> <!-- x start --> 166 <y>150</y> <!-- y start --> 167 <width>120</width> <!-- x start + width = x end --> 168 <height>180</height> <!-- y start + height = y end --> 169 <compression_factor>2.68</compression_factor> <!-- Pixels per degree --> 170 <loadfn>roll</loadfn> <!-- Name of the function to be called, here 171 get_roll() is called provision made in Hud.cxx --> 172 <loadfn1>pitch</loadfn1> <!-- Name of the function to be called, here get_pitch() 173 is called --> 174 <span_units>45.0</span_units> <!-- Range of the Ladder seen at any instant --> 175 <division_units>10.0</division_units> <!-- Divisions --> 176 <screen_hole>70</screen_hole> <!-- Hole b/w the Ladder Bars --> 177 <lbl_pos>0</lbl_pos> <!-- Label Position to indicate pitch angle on bar --> 178 <enable_frl>false</enable_frl> <!-- To Enable Pitch Reference Symbol (used by us) --> 179 <enable_target_spot>true</enable_target_spot> <!-- To Enable Target Spot Symbol (fgfs uses this) --> 180 <enable_velocity_vector>false</enable_velocity_vector> <!-- To Enable Velocity Vector Symbol (use only with climb/dive ladder) --> 181 <enable_drift_marker>false</enable_drift_marker> <!-- To Enable Drift Marker Symbol (used by us) --> 182 <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) --> 183 <enable_energy_marker>false</enable_energy_marker> <!-- To Enable Energy Marker Symbol (used by us) --> 184 <enable_climb_dive_marker>false</enable_climb_dive_marker> <!-- To Enable Climb/Dive Marker (used by us) --> 185 <enable_glide_slope_marker>false</enable_glide_slope_marker> <!-- To Enable Glide/Slope Marker (tied to climb/dive ladder only) --> 186 <glide_slope>0.0</glide_slope> <!-- Glide slope angle (specify the angle for drawing the reference bar) --> 187 <enable_energy_worm>false</enable_energy_worm> <!-- To Enable Energy worm (used by us) --> 188 <enable_waypoint_marker>false</enable_waypoint_marker> <!-- To Enable Way point Marker (bearing marker) --> 189 <working>true</working> <!-- use this to enable or disable whole object --> 190 </l1> 191 192 </ladders> 193 194</PropertyList> 195 196Before you read this, _____ this is tick_top | | 197 | | | 198 | |__________________| 199 | this is cap_right,tick_left cap_bottom tick_right 200 | 201 _____| this is tick_bottom 202 203Example of Hud Card xml file. 204 205<PropertyList> 206 207 <cards> 208 209 <c1> 210 <name>Gyrocompass</name> 211 <x>220</x> 212 <y>430</y> 213 <width>200</width> 214 <height>28</height> 215 <loadfn>heading</loadfn> <!-- Name of the function to be called, here get_Heading() is called --> 216 <options>4</options> <!-- Read Tape Options Below or Hud.hxx file for details --> 217 <maxValue>360.0</maxValue> <!-- Maximum scale value --> 218 <minValue>0.0</minValue> <!-- Minimum Scale Value --> 219 <disp_scaling>1.0</disp_scaling> <!-- Multiply by this to get numbers shown on scale --> 220 <major_divs>5</major_divs> <!-- major division marker units --> 221 <minor_divs>1</minor_divs> <!-- minor division marker units --> 222 <modulator>360</modulator> <!-- Its a rose, Roll Over Point --> 223 <value_span>25.0</value_span> <!-- Range Shown --> 224 <type>tape</type> <!-- Card type can be "tape" or "gauge" --> 225 <tick_bottom>false</tick_bottom> <!-- Read Ticks and Caps below --> 226 <tick_top>false</tick_top> 227 <tick_right>true</tick_right> 228 <tick_left>true</tick_left> 229 <cap_bottom>true</cap_bottom> 230 <cap_top>false</cap_top> 231 <cap_right>false</cap_right> 232 <cap_left>false</cap_left> 233 <marker_offset>0.0</marker_offset> <!-- Read Marker offset below --> 234 <enable_pointer>true</enable_pointer> <!-- To draw a pointer --> 235 <pointer_type>fixed</pointer_type> <!-- Type of pointer, Fixed or Moving (yet to be implemented) --> 236 <working>true</working> 237 </c1> 238 239 </cards> 240 241</PropertyList> 242 243Tape Options: 244 245HUDS_AUTOTICKS = 0x0001 246HUDS_VERT = 0x0002 247HUDS_HORZ = 0x0000 248HUDS_TOP = 0x0004 249HUDS_BOTTOM = 0x0008 250HUDS_LEFT = HUDS_TOP 251HUDS_RIGHT = HUDS_BOTTOM 252HUDS_BOTH = (HUDS_LEFT | HUDS_RIGHT) 253HUDS_NOTICKS = 0x0010 254HUDS_ARITHTIC = 0x0020 255HUDS_DECITICS = 0x0040 256HUDS_NOTEXT = 0x0080 257HUDS_LEFT | HUDS_VERT = 0x0006 258HUDS_RIGHT | HUDS_VERT = 0x0010 259HUDS_TOP | HUDS_NOTEXT = 0x0084 260HUDS_BOTTOM | HUDS_NOTEXT = 0x0088 261HUDS_VERT | HUDS_LEFT | HUDS_NOTEXT = 0x0086 262HUDS_RIGHT | HUDS_VERT | HUDS_NOTEXT = 0x0090 263 264 265For clarity, I repeat, Ticks and Caps : 266 267 2681. Left Tick ->|_____|<- Right Tick 269 | 270 v 271 Bottom Cap 272 2732. Top Cap 274 | 275 v 276 _____ 277 | | 278 279 2803. Top Tick 281 | 282 v 283 --- 284 | 285 |<- Right Cap 286 | 287 --- 288 | 289 v 290 Bottom Tick 291 2924. --- 293 | 294 Left Cap -> | 295 | 296 --- 297 298Marker Offset : 299 300To Draw pointer on the scale markings. In the case of a our hud with offset 10.0 301The pointer is away from the scale and points at the markings. 302 303 -| - 304 -| - 305 <| -< 306 -| - 307 -| - 308Marker offset = 0.0 Marker offset = 10.0 309 310This should be useful when I implement the fixed tape/moving pointer. 311 312 313Example of a Label xml file. 314 315<PropertyList> 316 317 <labels> 318 319 <i1> 320 <name>machno</name> 321 <x>25</x> 322 <y>130</y> 323 <width>40</width> 324 <height>30</height> 325 <data_source>mach</data_source> <!-- Name of the function to be called, here get_Heading() is called --> 326 <label_format>%4.2f</label_format> <!-- The Label Format --> 327 <pre_label_string>blank</pre_label_string> <!-- String to be written Pre Label --> 328 <post_label_string>NULL</post_label_string> <!-- String to be written Post Label --> 329 <scale_data>1.0</scale_data> 330 <options>4</options> <!-- Read Tape options or Hud.hxx --> 331 <justification>2</justification> <!-- Justify the label, 0=LEFT_JUSTIFY, 1=CENTER_JUSTIFY, 2=RIGHT_JUSTIFY --> 332 <blinking>0</blinking> <!-- Yet to be implemented --> 333 <working>true</working> 334 <latitude>false</latitude> <!-- True if the label is to display Latitude (special label, displays deg.min.sec) --> 335 <longitude>false</longitude> <!-- True if the label is to display Longitude (special label, displays deg.min.sec) --> 336 </i1> 337 338 </labels> 339 340</PropertyList> 341 342 343Example of a Turn Bank Indicator xml file. 344 345<PropertyList> 346 347 <tbis> 348 349 <f1> 350 <name>fgTBI_Instrument</name> 351 <x>290</x> 352 <y>45</y> 353 <width>60</width> 354 <height>10</height> 355 <loadfn>roll</loadfn> <!-- Name of the function to be called, get_roll() is called here. --> 356 <loadfn1>sideslip</loadfn1> <!-- Name of the function to be called, get_sideslip() is called here. --> 357 <maxBankAngle>45.0</maxBankAngle> <!-- Maximum Angle of Bank --> 358 <maxSlipAngle>5.0</maxSlipAngle> <!-- Maximum Angle of Slip --> 359 <gap_width>5</gap_width> <!-- Screen Hole --> 360 <working>true</working> 361 </f1> 362 363 </tbis> 364 365</PropertyList> 366 367I have still got to implement dials (as in MIL-STD-1787b). 368 369REMEMBER IF YOU NEED TO INDICATE ANY OTHER PARAMETER ON THE HUD OTHER THAN WHAT IS PROVIDED AS 370CALLBACK FUNCTIONS (PROPERTY NAMES LISTED BELOW) YOU HAVE TO FIDDLE WITH THE CODE, AS YET. LET ME 371KNOW AND I SHALL INCLUDE THAT. 372 373<loadfn>anzg</loadfn> <!-- Here get_anzg() is called --> 374<loadfn>heading</loadfn> <!-- Here get_heading() is called --> 375<loadfn>aoa</loadfn> <!-- Here get_aoa() is called --> 376<loadfn>climb</loadfn> <!-- Here get_climb() is called --> 377<loadfn>altitude</loadfn> <!-- Here get_altitude() is called --> 378<loadfn>agl</loadfn> <!-- Here get_agl() is called --> 379<loadfn>speed</loadfn> <!-- Here get_speed() is called --> 380<loadfn>view_direction</loadfn> <!-- Here get_view_direction() is called --> 381<loadfn>aileronval</loadfn> <!-- Here get_aileronval() is called --> 382<loadfn>elevatorval</loadfn> <!-- Here get_elevatorval() is called --> 383<loadfn>rudderval</loadfn> <!-- Here get_rudderval() is called --> 384<loadfn>throttleval</loadfn> <!-- Here get_throttleval() is called --> 385<loadfn>aux16</loadfn> <!-- Here get_aux16() is called --> 386<loadfn>aux17</loadfn> <!-- Here get_aux17() is called --> 387<loadfn>aux9</loadfn> <!-- Here get_aux9() is called --> 388<loadfn>aux11</loadfn> <!-- Here get_aux11() is called --> 389<loadfn>aux12</loadfn> <!-- Here get_aux12() is called --> 390<loadfn>aux10</loadfn> <!-- Here get_aux10() is called --> 391<loadfn>aux13</loadfn> <!-- Here get_aux13() is called --> 392<loadfn>aux14</loadfn> <!-- Here get_aux14() is called --> 393<loadfn>aux15</loadfn> <!-- Here get_aux15() is called --> 394<loadfn>aux8</loadfn> <!-- Here get_aux8() is called --> 395<loadfn>ax</loadfn> <!-- Here get_Ax() is called --> 396<loadfn>mach</loadfn> <!-- Here get_mach() is called --> 397<loadfn>framerate</loadfn> <!-- Here get_frame_rate() is called --> 398<loadfn>fov</loadfn> <!-- Here get_fov() is called --> 399<loadfn>vfc_tris_culled</loadfn> <!-- Here get_vfc_tris_culled() is called --> 400<loadfn>vfc_tris_drawn</loadfn> <!-- Here get_vfc_tris_drawn() is called --> 401<loadfn>latitude</loadfn> <!-- Here get_latitude() is called --> 402<loadfn>longitude</loadfn> <!-- Here get_longitude() is called --> 403 404 405 406 407 408 409 410 411 412 413 414 415