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