Use api's with objects instead of scalars.

[flightgear.git] / docs-mini / README.xmlhud

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 -->