Docs/README.hud

   1 This document describes the *new* HUD system that will be first released
   2 with fgfs >0.9.10. For the old system see $FG_ROOT/Docs/README.xmlhud.
   3 Note that the old system is scheduled for removal, and that the new system
   4 is work in progress. So it's up to you to choose the lower risk.  :-)
   5
   6
   7
   8
   9
  10
  11 ###############################################################################
  12
  13
  14 A HUD configuration file may contain 3 types of information:
  15
  16   (1) global settings
  17   (2) HUD instrument definitions
  18   (3) imports of further HUD config files
  19
  20
  21
  22
  23
  24 (1) global settings ===========================================================
  25
  26 These can be used to override settings in the global property tree. Currently
  27 only bool <enbale-3d> is supported. It allows a HUD to define itself if it is
  28 a 2D HUD (false) or a 3D HUD (true). 2D HUDs always remain in the screen plane,
  29 while 3D HUDs always remain in a position relative to the aircraft.
  30
  31 Example:
  32
  33     <enable-3d>true</enable-3d>
  34
  35
  36
  37
  38
  39 (2) HUD instrument definitions ================================================
  40
  41 These define one single HUD "item" (instrument or label), and consist of several
  42 properties. Some of those are standardized property groups that can be used
  43 in many places. These shall be explained first.
  44
  45
  46
  47 (2.1) standardized property groups --------------------------------------------
  48
  49   1. <condition> group
  50   2. input channel group
  51   3. <option>s
  52
  53
  54
  55 (2.1.1) <condition> ...........................................................
  56
  57 These define conditions that are either "true" or "false". They are used to
  58 hide/unhide whole items, or to set other item states (blinking on/off) etc.
  59 You find detailed documentation about them in $FG_ROOT/Docs/README.conditions.
  60
  61
  62
  63 (2.1.2) input channel groups .................................................
  64
  65 These define an input channel to the HUD instrument and serve as interface
  66 between property system and the instrument. A complete channel definition
  67 looks like this (defaults in comments):
  68
  69   <input>
  70       <property>/position/altitude-agl-ft</property>  <!-- no default -->
  71       <factor>0.3048</factor>                         <!-- 1.0 -->
  72       <offset>2.0</offset>                            <!-- 0.0 -->
  73       <damp>1.5</damp>                                <!-- 0.0 (no damping) -->
  74       <min>0.0</min>                                  <!-- -infinity -->
  75       <max>10000</max>                                <!-- +infinity -->
  76   </input>
  77
  78 Input channels are only called <input> for instruments that only have one
  79 channel. Other instruments may have two or more channels, called <bank-input>,
  80 <pitch-input> etc. All of them will have the same member properties and behave
  81 the same.
  82
  83 An input channel will preprocess the raw property value for the HUD instrument.
  84 The property may be of any type (bool, int, long, float, double, string), but
  85 not all types will make sense in every situation. The HUD instrument will only
  86 see the final value, which is calculated as:
  87
  88
  89   v = <property> * <factor> + <offset>
  90   if (<damp>)     v = EWMA_lowpass(v, <damp>)
  91   if (v < <min>)  v = <min>
  92   if (v > <max>)  v = <max>
  93
  94
  95 The EWMA_lowpass filter (Exponentially Weighted Moving Average) is calculated
  96 like so:
  97
  98
  99   coeff = 1.0 - 1.0 / 10^<damp>
 100   v = average = (average * coeff) + (v * (1.0 - coeff))
 101
 102
 103 That is, a <damp> value of 0 will cause no damping. A damping value of 1 will
 104 make a coefficient of 0.9, which means that the resulting value will be 9/10
 105 of the average plus 1/10 of the new value. A damping value of 2 will make
 106 a coefficient of 0.99 and hence result in a value of 99/100 the average plus
 107 1/100 the new value etc. The higher the <damp> value, the more damped will
 108 the output value be.
 109
 110
 111
 112
 113 2.1.3 <option> ................................................................
 114
 115 Most HUD instruments accept one or more options from a common set. It will be
 116 explaind in the respective intrument descriptions which options are actually
 117 used by that instrument. Possible values are:
 118
 119   <option> autoticks </option>
 120   <option> vertical </option>   \___orientation of <tape>
 121   <option> horizontal </option> /
 122   <option> top </option>          \
 123   <option> left </option>         |___place of numbers in <tape>, <gauge>
 124   <option> bottom </option>       |   top/bottom for turn-bank-indicator, etc.
 125   <option> right </option>        /
 126   <option> both </option>           _left/right for vert. and top/bottom for hor.
 127   <option> noticks </option>
 128   <option> arithtic </option>
 129   <option> decitics </option>
 130   <option> notext </option>       ___no numbers on <tape>
 131
 132
 133 Example:
 134
 135   <tape>
 136       <option>left</option>
 137       <option>vertical</option>
 138       ...
 139   </tape>
 140
 141
 142
 143
 144
 145
 146 (2.1) properties common to all instruments ------------------------------------
 147
 148 All HUD instruments will accept the following common properties (shown on
 149 a <tape> instrument):
 150
 151
 152   <tape>
 153       <name>foo tape</name>
 154       <x>-100</x>                        <!-- 0 == center -->
 155       <y>-60</y>                         <!-- 0 == center -->
 156       <width>20</width>                  <!-- 0 -->
 157       <height>120</height>               <!-- 0 -->
 158       <condition>...</condition>         <!-- see section 2.1.1; default: true -->
 159       ...
 160   </tape>
 161
 162 The <name> is only a description for the instrument to make reading the config
 163 easier. It's output in --log-level=info, but not otherwise used. The coordinates
 164 define the place and size of the instrument. They are relative to the origin of
 165 their parent, which is the middle of the HUD/screen by default. Positive <x> are
 166 on the right, positive <y> in the upper half. The <condition> hides/reveals the
 167 whole instrument.
 168
 169
 170
 171
 172
 173
 174 (2.2) HUD instruments ---------------------------------------------------------
 175
 176
 177
 178
 179 (2.2.1) <label> ...............................................................
 180
 181 Draws a formatted string or number.
 182
 183 Text:
 184   <format>   ... printf-style format with only one % item.  Example:  "%2.3lf ft"
 185   <prefix>   ... prefix text  \___ in addition to the <format>
 186   <postfix>  ... postfix text /
 187   <halign>   ... one of "left", "center" (default), "right".
 188
 189 Box:
 190   <box>      ... draw box around label (default: false)
 191   <option>   ... one of (left|right|top|bottom)  ... draw arrow on this side
 192   <pointer-width>  ... size of pointer base
 193   <pointer-lenfth> ... distance of base--peak
 194
 195   <blinking>
 196       <interval>                  ... on/off-time in seconds (default: -1 == off)
 197       <condition>...</condition>  ... see secion 2.1.1       (default: true)
 198   </blinking>
 199
 200 TODO:
 201   <digit>    ... number of insignificant digits (those will be printed smaller)
 202
 203
 204
 205 Example:
 206
 207   <label>
 208       <name>G Load</name>
 209       <x>-40</x>
 210       <y>25.5</y>
 211       <width>1</width>
 212       <height>1</height>
 213
 214       <input>
 215           <property>/accelerations/pilot/z-accel-fps_sec</property>
 216           <factor>-0.03108095</factor>
 217           <damp>1.3</damp>
 218       </input>
 219
 220       <format>%2.1f</format>
 221       <halign>right</halign>
 222       <box>true</box>
 223       <option>bottom</option>    <!-- pointer on the lower edge -->
 224
 225       <blinking>
 226           <interval>0.25</interval>
 227           <condition>
 228               <or>
 229                   <less-than>      <!-- G load > 2.0 -->
 230                       <property>/accelerations/pilot/z-accel-fps_sec</property>
 231                       <value>-64.3481</value>
 232                   </less-than>
 233
 234                   <greater-than>   <!-- G load < -1.0 -->
 235                       <property>/accelerations/pilot/z-accel-fps_sec</property>
 236                       <value>31.17405</value>
 237                   </greater-than>
 238               </or>
 239           </condition>
 240       </blinking>
 241   </label>
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251 (2.2.2) <tape> ................................................................
 252 SCALE:
 253     input
 254     major-divisions
 255     minor-divisions
 256     modulo
 257     display-span
 258
 259 TAPE:
 260     tick-bottom
 261     tick-top
 262     tick-right
 263     tick-left
 264     cap-bottom
 265     cap-top
 266     cap-right
 267     cap-left
 268     marker-offset
 269     enable-pointer
 270     zoom
 271
 272     pointer-type   (moving|fixed)
 273     tick-type      (circle|line)
 274     tick-length    (constant|variable)
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284 (2.2.3) <dial> ................................................................
 285 SCALE:
 286     input
 287     major-divisions
 288     minor-divisions
 289     modulo
 290     display-span
 291
 292 TAPE:
 293     radius
 294     divisions
 295
 296
 297
 298
 299
 300
 301
 302
 303 (2.2.4) <gauge> ...............................................................
 304 SCALE:
 305     input
 306     major-divisions
 307     minor-divisions
 308     modulo
 309     display-span
 310
 311
 312
 313
 314
 315
 316 (2.2.5) <turn-bank-indicator> .................................................
 317     bank-input
 318     sideslip-input
 319     gap-width
 320     bank-scale
 321
 322
 323
 324
 325
 326
 327
 328
 329 (2.2.6) <ladder> ..............................................................
 330     pitch-input
 331     roll-input
 332     display-span
 333     divisions
 334     screen-hole
 335     compression-factor
 336     enable-fuselage-ref-line
 337     enable-target-spot
 338     enable-velocity-vector
 339     enable-drift-marker
 340     enable-alpha-bracket
 341     enable-energy-marker
 342     enable-climb-dive-marker
 343     enable-glide-slope-marker
 344     glide-slope
 345     enable-energy-marker
 346     enable-waypoint-marker
 347     enable-zenith
 348     enable-nadir
 349     enable-hat
 350     type       (pitch|climb-dive)
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360 (2.2.7) <runway> ..............................................................
 361     arrow-scale
 362     arrow-radius
 363     line-scale
 364     scale-dist-nm
 365     outer_stipple
 366     center-stipple
 367     arrow-always
 368
 369 reads directly:
 370     /position/altitude-agl-ft,
 371     /sim/view[0]/config/pitch-pitch-deg
 372     /sim/view[0]/config/pitch-heading-deg
 373
 374
 375
 376
 377
 378 (2.2.8) <aiming-reticle> ......................................................
 379
 380 Draws MIL-STD-1787B aiming reticle. Size of bullet and inner circle are
 381 determined from <width>. The outer circle radius is changeable at runtime.
 382
 383   <active-condition> ... true:  stadiametric (4.2.4.4)  (default)
 384                          false: standby (4.2.4.5)
 385   <diameter-input>   ... input channel: diameter of outer circle relative to
 386                          inner circle; default: 2.0 (= twice as big)
 387
 388
 389
 390
 391
 392
 393
 394 (3) <import> ==================================================================
 395
 396 Imports another HUD config into the current one. This can be a file defining
 397 a single instrument ($FG_ROOT/Huds/Instruments/*.xml), a set of instruments
 398 ($FG_ROOT/Huds/Sets/*.xml) or a mixture of both (for example a complete HUD
 399 on its own). The x/y offets moves the reference point for the included items
 400 relative to the current reference point.
 401
 402     <import>
 403         <path>Huds/Sets/controls.xml</path>
 404         <x-offset>-100</x-offset>
 405         <y-offset>70</y-offset>
 406     </import>
 407
 408 Imported files can import further files. This is allowed for up to 10 levels.
 409 This is an arbitrary number and can easily be changed in the code if necessary.
 410
 411 When fgfs is called with --log-level=info, then it outputs a graphical trees
 412 of all loaded/imported files, with the instruments shown as leafs.
 413