413 lines
11 KiB
Text
413 lines
11 KiB
Text
This document describes the *new* HUD system that will be first released
|
|
with fgfs >0.9.10. For the old system see $FG_ROOT/Docs/README.xmlhud.
|
|
Note that the old system is scheduled for removal, and that the new system
|
|
is work in progress. So it's up to you to choose the lower risk. :-)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
###############################################################################
|
|
|
|
|
|
A HUD configuration file may contain 3 types of information:
|
|
|
|
(1) global settings
|
|
(2) HUD instrument definitions
|
|
(3) imports of further HUD config files
|
|
|
|
|
|
|
|
|
|
|
|
(1) global settings ===========================================================
|
|
|
|
These can be used to override settings in the global property tree. Currently
|
|
only bool <enbale-3d> is supported. It allows a HUD to define itself if it is
|
|
a 2D HUD (false) or a 3D HUD (true). 2D HUDs always remain in the screen plane,
|
|
while 3D HUDs always remain in a position relative to the aircraft.
|
|
|
|
Example:
|
|
|
|
<enable-3d>true</enable-3d>
|
|
|
|
|
|
|
|
|
|
|
|
(2) HUD instrument definitions ================================================
|
|
|
|
These define one single HUD "item" (instrument or label), and consist of several
|
|
properties. Some of those are standardized property groups that can be used
|
|
in many places. These shall be explained first.
|
|
|
|
|
|
|
|
(2.1) standardized property groups --------------------------------------------
|
|
|
|
1. <condition> group
|
|
2. input channel group
|
|
3. <option>s
|
|
|
|
|
|
|
|
(2.1.1) <condition> ...........................................................
|
|
|
|
These define conditions that are either "true" or "false". They are used to
|
|
hide/unhide whole items, or to set other item states (blinking on/off) etc.
|
|
You find detailed documentation about them in $FG_ROOT/Docs/README.conditions.
|
|
|
|
|
|
|
|
(2.1.2) input channel groups .................................................
|
|
|
|
These define an input channel to the HUD instrument and serve as interface
|
|
between property system and the instrument. A complete channel definition
|
|
looks like this (defaults in comments):
|
|
|
|
<input>
|
|
<property>/position/altitude-agl-ft</property> <!-- no default -->
|
|
<factor>0.3048</factor> <!-- 1.0 -->
|
|
<offset>2.0</offset> <!-- 0.0 -->
|
|
<damp>1.5</damp> <!-- 0.0 (no damping) -->
|
|
<min>0.0</min> <!-- -infinity -->
|
|
<max>10000</max> <!-- +infinity -->
|
|
</input>
|
|
|
|
Input channels are only called <input> for instruments that only have one
|
|
channel. Other instruments may have two or more channels, called <bank-input>,
|
|
<pitch-input> etc. All of them will have the same member properties and behave
|
|
the same.
|
|
|
|
An input channel will preprocess the raw property value for the HUD instrument.
|
|
The property may be of any type (bool, int, long, float, double, string), but
|
|
not all types will make sense in every situation. The HUD instrument will only
|
|
see the final value, which is calculated as:
|
|
|
|
|
|
v = <property> * <factor> + <offset>
|
|
if (<damp>) v = EWMA_lowpass(v, <damp>)
|
|
if (v < <min>) v = <min>
|
|
if (v > <max>) v = <max>
|
|
|
|
|
|
The EWMA_lowpass filter (Exponentially Weighted Moving Average) is calculated
|
|
like so:
|
|
|
|
|
|
coeff = 1.0 - 1.0 / 10^<damp>
|
|
v = average = (average * coeff) + (v * (1.0 - coeff))
|
|
|
|
|
|
That is, a <damp> value of 0 will cause no damping. A damping value of 1 will
|
|
make a coefficient of 0.9, which means that the resulting value will be 9/10
|
|
of the average plus 1/10 of the new value. A damping value of 2 will make
|
|
a coefficient of 0.99 and hence result in a value of 99/100 the average plus
|
|
1/100 the new value etc. The higher the <damp> value, the more damped will
|
|
the output value be.
|
|
|
|
|
|
|
|
|
|
2.1.3 <option> ................................................................
|
|
|
|
Most HUD instruments accept one or more options from a common set. It will be
|
|
explaind in the respective intrument descriptions which options are actually
|
|
used by that instrument. Possible values are:
|
|
|
|
<option> autoticks </option>
|
|
<option> vertical </option> \___orientation of <tape>
|
|
<option> horizontal </option> /
|
|
<option> top </option> \
|
|
<option> left </option> |___place of numbers in <tape>, <gauge>
|
|
<option> bottom </option> | top/bottom for turn-bank-indicator, etc.
|
|
<option> right </option> /
|
|
<option> both </option> _left/right for vert. and top/bottom for hor.
|
|
<option> noticks </option>
|
|
<option> arithtic </option>
|
|
<option> decitics </option>
|
|
<option> notext </option> ___no numbers on <tape>
|
|
|
|
|
|
Example:
|
|
|
|
<tape>
|
|
<option>left</option>
|
|
<option>vertical</option>
|
|
...
|
|
</tape>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(2.1) properties common to all instruments ------------------------------------
|
|
|
|
All HUD instruments will accept the following common properties (shown on
|
|
a <tape> instrument):
|
|
|
|
|
|
<tape>
|
|
<name>foo tape</name>
|
|
<x>-100</x> <!-- 0 == center -->
|
|
<y>-60</y> <!-- 0 == center -->
|
|
<width>20</width> <!-- 0 -->
|
|
<height>120</height> <!-- 0 -->
|
|
<condition>...</condition> <!-- see section 2.1.1; default: true -->
|
|
...
|
|
</tape>
|
|
|
|
The <name> is only a description for the instrument to make reading the config
|
|
easier. It's output in --log-level=info, but not otherwise used. The coordinates
|
|
define the place and size of the instrument. They are relative to the origin of
|
|
their parent, which is the middle of the HUD/screen by default. Positive <x> are
|
|
on the right, positive <y> in the upper half. The <condition> hides/reveals the
|
|
whole instrument.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(2.2) HUD instruments ---------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
(2.2.1) <label> ...............................................................
|
|
|
|
Draws a formatted string or number.
|
|
|
|
Text:
|
|
<format> ... printf-style format with only one % item. Example: "%2.3lf ft"
|
|
<prefix> ... prefix text \___ in addition to the <format>
|
|
<postfix> ... postfix text /
|
|
<halign> ... one of "left", "center" (default), "right".
|
|
|
|
Box:
|
|
<box> ... draw box around label (default: false)
|
|
<option> ... one of (left|right|top|bottom) ... draw arrow on this side
|
|
<pointer-width> ... size of pointer base
|
|
<pointer-lenfth> ... distance of base--peak
|
|
|
|
<blinking>
|
|
<interval> ... on/off-time in seconds (default: -1 == off)
|
|
<condition>...</condition> ... see secion 2.1.1 (default: true)
|
|
</blinking>
|
|
|
|
TODO:
|
|
<digit> ... number of insignificant digits (those will be printed smaller)
|
|
|
|
|
|
|
|
Example:
|
|
|
|
<label>
|
|
<name>G Load</name>
|
|
<x>-40</x>
|
|
<y>25.5</y>
|
|
<width>1</width>
|
|
<height>1</height>
|
|
|
|
<input>
|
|
<property>/accelerations/pilot/z-accel-fps_sec</property>
|
|
<factor>-0.03108095</factor>
|
|
<damp>1.3</damp>
|
|
</input>
|
|
|
|
<format>%2.1f</format>
|
|
<halign>right</halign>
|
|
<box>true</box>
|
|
<option>bottom</option> <!-- pointer on the lower edge -->
|
|
|
|
<blinking>
|
|
<interval>0.25</interval>
|
|
<condition>
|
|
<or>
|
|
<less-than> <!-- G load > 2.0 -->
|
|
<property>/accelerations/pilot/z-accel-fps_sec</property>
|
|
<value>-64.3481</value>
|
|
</less-than>
|
|
|
|
<greater-than> <!-- G load < -1.0 -->
|
|
<property>/accelerations/pilot/z-accel-fps_sec</property>
|
|
<value>31.17405</value>
|
|
</greater-than>
|
|
</or>
|
|
</condition>
|
|
</blinking>
|
|
</label>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(2.2.2) <tape> ................................................................
|
|
SCALE:
|
|
input
|
|
major-divisions
|
|
minor-divisions
|
|
modulo
|
|
display-span
|
|
|
|
TAPE:
|
|
tick-bottom
|
|
tick-top
|
|
tick-right
|
|
tick-left
|
|
cap-bottom
|
|
cap-top
|
|
cap-right
|
|
cap-left
|
|
marker-offset
|
|
enable-pointer
|
|
zoom
|
|
|
|
pointer-type (moving|fixed)
|
|
tick-type (circle|line)
|
|
tick-length (constant|variable)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(2.2.3) <dial> ................................................................
|
|
SCALE:
|
|
input
|
|
major-divisions
|
|
minor-divisions
|
|
modulo
|
|
display-span
|
|
|
|
TAPE:
|
|
radius
|
|
divisions
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(2.2.4) <gauge> ...............................................................
|
|
SCALE:
|
|
input
|
|
major-divisions
|
|
minor-divisions
|
|
modulo
|
|
display-span
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(2.2.5) <turn-bank-indicator> .................................................
|
|
bank-input
|
|
sideslip-input
|
|
gap-width
|
|
bank-scale
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(2.2.6) <ladder> ..............................................................
|
|
pitch-input
|
|
roll-input
|
|
display-span
|
|
divisions
|
|
screen-hole
|
|
compression-factor
|
|
enable-fuselage-ref-line
|
|
enable-target-spot
|
|
enable-velocity-vector
|
|
enable-drift-marker
|
|
enable-alpha-bracket
|
|
enable-energy-marker
|
|
enable-climb-dive-marker
|
|
enable-glide-slope-marker
|
|
glide-slope
|
|
enable-energy-marker
|
|
enable-waypoint-marker
|
|
enable-zenith
|
|
enable-nadir
|
|
enable-hat
|
|
type (pitch|climb-dive)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(2.2.7) <runway> ..............................................................
|
|
arrow-scale
|
|
arrow-radius
|
|
line-scale
|
|
scale-dist-nm
|
|
outer_stipple
|
|
center-stipple
|
|
arrow-always
|
|
|
|
reads directly:
|
|
/position/altitude-agl-ft,
|
|
/sim/view[0]/config/pitch-pitch-deg
|
|
/sim/view[0]/config/pitch-heading-deg
|
|
|
|
|
|
|
|
|
|
|
|
(2.2.8) <aiming-reticle> ......................................................
|
|
|
|
Draws MIL-STD-1787B aiming reticle. Size of bullet and inner circle are
|
|
determined from <width>. The outer circle radius is changeable at runtime.
|
|
|
|
<active-condition> ... true: stadiametric (4.2.4.4) (default)
|
|
false: standby (4.2.4.5)
|
|
<diameter-input> ... input channel: diameter of outer circle relative to
|
|
inner circle; default: 2.0 (= twice as big)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(3) <import> ==================================================================
|
|
|
|
Imports another HUD config into the current one. This can be a file defining
|
|
a single instrument ($FG_ROOT/Huds/Instruments/*.xml), a set of instruments
|
|
($FG_ROOT/Huds/Sets/*.xml) or a mixture of both (for example a complete HUD
|
|
on its own). The x/y offets moves the reference point for the included items
|
|
relative to the current reference point.
|
|
|
|
<import>
|
|
<path>Huds/Sets/controls.xml</path>
|
|
<x-offset>-100</x-offset>
|
|
<y-offset>70</y-offset>
|
|
</import>
|
|
|
|
Imported files can import further files. This is allowed for up to 10 levels.
|
|
This is an arbitrary number and can easily be changed in the code if necessary.
|
|
|
|
When fgfs is called with --log-level=info, then it outputs a graphical trees
|
|
of all loaded/imported files, with the instruments shown as leafs.
|
|
|