fly/fgdata
1
0
Fork 0
Code Activity

Sync with the source code.

Browse source
This commit is contained in:
ehofman 2004-08-21 08:57:29 +00:00
parent d57e589fde
commit ab9e651503
7 changed files with 1291 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
Docs/README.IO
View file

@ -15,6 +15,50 @@ The general form of the command line option is as follows:
hz = number of times to process channel per second (floating hz = number of times to process channel per second (floating
point values are ok. point values are ok.
Generic Communction:
--generic=params
With this option it is possible to output a pre-configured
ASCII string using a predefined seperator. The configuration is
defined in an XML file located in the Protocol directiory of
the base package.
params can be:
serial port communication: serial,dir,hz,device,baud,protocol
socket communication: socket,dir,hz,machine,port,style,protocol
output to a file: file,dir,hz,filename,protocol
The confinfiguration file is defined as follows:
<?xml version="1.0"?>
<PropertyList>
<generic>
<output>
<seperator>\n</seperator>
<chunk>
<name>speed</name> <!-- for readabillity -->
<type>int</type> <!-- one of: bool,int,float,string -->
<format>V=%d</format> <!-- output format string -->
<node>/velocities/speed</node> <!-- location of the value -->
<offset>0.0</offset> <!-- add this to the value -->
<factor>1.0</factor> <!-- multiply by this value -->
</chunk>
<chunk>
...
</chunk>
...
</output>
</generic>
</PropertyList>
Serial Port Communication: Serial Port Communication:
--nmea=serial,dir,hz,device,baud --nmea=serial,dir,hz,device,baud

1
Docs/README.Joystick Normal file
View file

@ -0,0 +1 @@
Replaced by Docs/README.Joystick.html in the base package.

72
Docs/README.multiplayer Normal file
View file

@ -0,0 +1,72 @@
The commands are of the form:
--multiplay=in | out,Hz,destination address,destination port
--callsign=a_unique_name
Below are some examples of startup commands that demonstrate the use of the
multiplayer facilities.
For two players on a local network or across the internet:
----------------------------------------------------------
Player1:
--multiplay=out,10,192.168.0.3,5500 --multiplay=in,10,192.168.0.2,5501
--callsign=player1
Player2:
--multiplay=out,10,192.168.0.2,5501 --multiplay=in,10,192.168.0.3,5500
--callsign=player2
For multiple players on a local network:
----------------------------------------
Player1:
--multiplay=out,10,255.255.255.255,5500
--multiplay=in,10,255.255.255.255,5500 --callsign=player1
Playern:
--multiplay=out,10,255.255.255.255,5500
--multiplay=in,10,255.255.255.255,5500 --callsign=playern
Note that the callsign is used to identify each player in a multiplayer game
so the callsigns must be unique. The multiplayer code ignores packets that
are sent back to itself, as would occur with broadcasting when the rx and tx
ports are the same.
Multiple players sending to a single player:
--------------------------------------------
Player1:
--multiplay=out,10,192.168.0.2,5500 --callsign=player1
Player2:
--multiplay=out,10,192.168.0.2,5500 --callsign=player2
Player3:
--multiplay=out,10,192.168.0.2,5500 --callsign=player3
Player4 (rx only):
--multiplay=in,10,192.168.0.2,5500 --callsign=player4
This demonstrates that it is possible to have multiple instances of
Flightgear that send to a single instance that displays all the traffic. This
is the sort of implementation that we are considering for use as a tower
visual simulator.
For use with a server (when one is created):
--------------------------------------------
Player1:
--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5500
--callsign=player1
Player2:
--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5501
--callsign=player2
Playern:
--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5502
--callsign=playern
The server would simply act as a packet forwarding mechanism. When it
receives a packet, it sends it to all other active players.

62
Docs/README.sound Normal file
View file

@ -0,0 +1,62 @@
ALSA surround sound (5.1) setup
-------------------------------------
(taken from http://floam.ascorbic.com/how-to/alsa5.1)
Make a ~/.openalrc, we are telling OpenAL that we want surround sound and
we want to use ALSA instead of OSS.
(define speaker-num 4)
(define devices '(alsa))
(define alsa-out-device "surround40:0,0")
ALSA and Arts
-------------------------------------
I'm using kernel 2.6.5 with alsa, my sound module is snd-intel8x0. When I ran
fgfs, I'd get quite 'choppy' sound (wasn't smooth, there'd be a couple of
breaks in the sound every second or so). Running arts, and starting fgfs with
"artsdsp fgfs" (from the artsdsp website: "When an application is run under
artsdsp all accesses to the /dev/dsp audio device are intercepted and mapped
into aRts API calls. While the device emulation is not perfect, most
applications work this way, albeit with some degradation in performance and
latency.") would improve the situation, but it seemed to still be choppy.
This command:
echo "fgfs 0 0 direct" >/proc/asound/card0/pcm0p/oss
(from the alsa kernel OSS emulation website:
"The direct option is used, as mentioned above, to bypass the automatic
conversion and useful for MMAP-applications")
made my sound work beautifully when fgfs was run with artsdsp. Running without
artsdsp however (with artsd suspended or killed), would give me no sound at all
(which I find a bit strange)
The following websites might help people with similar troubles:
http://www.alsa-project.org/~iwai/OSS-Emulation.html
http://www.arts-project.org/doc/handbook/artsdsp.html
Computer info:
kernel 2.6.5
flightgear 0.9.4
simgear 0.3.5
plib 1.8.3
soundcard is onboard an asus p4p800-e deluxe mobo (using snd-intel8x0), alsa, related modules from lsmod:
Module Size Used by
snd_pcm_oss 53252 1
snd_mixer_oss 19968 1 snd_pcm_oss
snd_intel8x0 33476 1
snd_ac97_codec 63492 1 snd_intel8x0
snd_pcm 97408 2 snd_pcm_oss,snd_intel8x0
snd_timer 26112 1 snd_pcm
snd_page_alloc 11396 2 snd_intel8x0,snd_pcm
snd_mpu401_uart 7936 1 snd_intel8x0
snd_rawmidi 24832 1 snd_mpu401_uart
snd_seq_device 8324 1 snd_rawmidi
snd 53892 9 snd_pcm_oss,snd_mixer_oss,snd_intel8x0,snd_ac97_codec,snd_pcm,snd_timer,snd_mpu401_uart,snd_rawmidi,snd_seq_device
soundcore 10208 2 snd

654
Docs/README.xmlpanel Normal file
View file

@ -0,0 +1,654 @@
Users Guide to FlightGear panel configuration
Version 0.7.7, May 16 2001
Author: John Check <j4strngs@rockfish.net>
This document is an attempt to describe the configuration of
FlightGear flight simulator's aircraft panel display via XML. The
information was culled from the fgfs-devel@flightgear.org mailing list
and my experiences making alternate panels. Corrections and additions
are encouraged.
Some History:
------------
Older versions of FGFS had a hard coded display of instruments. This
was a less than ideal state of affairs due to FGFS ability to use
different aircraft models. Being primarily developed on UNIX type
systems, a modular approach is taken towards the simulation. To date,
most alternatives to the default Cessna 172 aircraft are the product
of research institutions interested in the flight characteristics and
not cosmetics. The result of this was that one could fly the X-15 or
a Boeing 747 but be limited to C172 instrumentation.
A rewrite of the panel display code was done around v0.7.5 by
developer David Megginson allowing for configuration of the panel via
XML to address this limitation. Some major changes and additions were
made during the course of version 0.7.7 necessitating a rewrite and
expansion of this document.
About The Property Manager:
--------------------------
While not absolutely necessary in order to create aircraft panels,
some familiarity with the property manager is beneficial....
FlightGear provides a hierarchical representation of all aspects of
the state of the running simulation that is known as the property
tree. Some properties, such as velocities are read only. Others such
as the frequencies to which the navcom radios are tuned or the
position of control surfaces can be set by various means. FlightGear
can optionally provide an interface to these properties for external
applications such as Atlas, the moving map program, or even lowly
telnet, via a network socket. Data can even be placed on a serial port
and connected to, say a GPS receiver. Aside from its usefulness in a
flight training context, being able to manipulate the property tree on
a running copy of FG allows for switching components on the fly, a
positive boon for panel authors. To see the property tree start FG
with the following command line:
fgfs --props=socket,bi,5,localhost,5500,tcp
Then use telnet to connect to localhost on port 5500. You can browse
the tree as you would a filesystem.
XML and the Property Manager:
----------------------------
Panel instruments interface with the property tree to get/set values
as appropriate. Properties for which FG doesn't yet provide a value
can be created by simply making them up. Values can be adjusted using
the telnet interface allowing for creation and testing of instruments
while code to drive them is being developed.
If fact, the XML configuration system allows a user to combine
components such as flight data model, aircraft exterior model, heads
up display, and of course control panel. Furthermore, such a
preconfigured aircraft.xml can be included into a scenario with
specific flight conditions. These can be manually specified or a FG
session can be saved and/or edited and reloaded later. Options
specified in these files can be overridden on the command line. For
example:
--prop:/sim/panel/path=Aircraft/c172/Panels/c172-panel.xml
passed as an option, would override a panel specified elsewhere.
Property tree options all have the same format, specify the node and
supply it a value.
The order of precedence for options is thus:
Source Location Format
------ -------- ------
command line
.fgfsrc Users home directory. command line options
system.fgfsrc $FG_ROOT "" ""
preferences.xml $FG_ROOT XML property list
Loading Panels on the fly:
-------------------------
When editing a panel configuration, pressing Shift +F3 will reload the
panel. If your changes don't seem to be taking effect, check the
console output. It will report the success or failure of the panel
reload*. Editing textures requires restarting FGFS so the new textures
can be loaded. Panels can be switched on the fly by setting the
/sim/panel/path property value and reloading.
Regarding Window Geometry:
-------------------------
For the sake of simplicity the FGFS window is always considered to be
1024x768 so all x/y values for instrument placement should relative to
these dimensions. Since FG uses OpenGL 0,0 represents the lower left
hand corner of the screen. Panels may have a virtual size larger than
1024x768. Vertical scrolling is accomplished with
Shift+F5/F6. Horizontal scrolling is via Shift+F7/F8. An offset should
be supplied to set the default visible area. It is possible to place
items to overlap the 3D viewport.
Panel Architecture:
-------------------
All of the panel configuration files are XML-encoded* property lists.
The root element of each file is always named <PropertyList>. Tags are
almost always found in pairs, with the closing tag having a slash
prefixing the tag name, i.e </PropertyList>. The exception is the tag
representing an aliased property. In this case a slash is prepended to
the closing angle bracket. (see section Aliasing)
The top level panel configuration file is composed of a <name>, a
<background> texture and zero or more <instruments>.Earlier versions
required instruments to have a unique name and a path specification
pointing to the instruments configuration file.
[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
[ Absolute paths may be used.Comments are bracketed with <!-- -->. ]
Old style instrument call in top level panel.xml:
------------------------------------------------
<clock> <!-- required "unique_name" -->
<path>Aircraft/c172/Instruments/clock.xml</path>
<x>110</x> <!-- required horizontal placement -->
<y>320</y> <!-- required vertical placement -->
<w>72</w> <!-- optional width specification -->
<h>72</h> <!-- optional height specification -->
</clock>
The difference between the old and new styles, while subtle, is rather
drastic. The old and new methods are indeed incompatible. I cover the
old style only to acknowledge the incompatibility. This section will
be removed after the next official FGFS release.
New Style Example Top Level Panel Config:
----------------------------------------
<PropertyList>
<name>Example Panel</name>
<background>Aircraft/c172/Panels/Textures/panel-bg.rgb</background>
<w>1024</w> <!-- virtual width -->
<h>768</h> <!-- virtual height -->
<y-offset>-305</y-offset> <!-- hides the bottom part -->
<view-height>172</view-height> <!-- amount of overlap between 2D panel and 3D viewport -->
<instruments> <!-- from here down is where old and new styles break compatibility -->
<instrument include="../Instruments/clock.xml">
<name>Chronometer</name> <!-- currently optional but strongly recommended -->
<x>150</x> <!-- required horizontal placement -->
<y>645</y> <!-- required vertical placement -->
<w>72</w> <!-- optional width specification -->
<h>72</h> <!-- optional height specification -->
</instrument>
</instruments>
</PropertyList>
Indexed Properties
------------------
This is a lot to do with the compatibility break so lets get it out of
the way. The property manager now assigns incremental indices to
repeated properties with the same parent node, so that
<PropertyList>
<x>1</x>
<x>2</x>
<x>3</x>
</PropertyList>
shows up as
/x[0] = 1
/x[1] = 2
/x[2] = 3
This means that property files no longer need to make up a separate
name for each item in a list of instruments, layers, actions,
transformations, or text chunks. In fact, the new panel I/O code now
insists that every instrument have the XML element name "instrument",
every layer have the name "layer", every text chunk have the name
"chunk", every action have the name "action", and every transformation
have the name "transformation" -- this makes the XML more regular (so
that it can be created in a DTD-driven tool) and also allows us to
include other kinds of information (such as doc strings) in the lists
without causing confusion.
Inclusion:
----------
The property manager now supports file inclusion and aliasing.
Inclusion means that a node can include another property file as if it
were a part of the current file. To clarify how inclusion works,
consider the following examples:
If bar.xml contains
<PropertyList>
<a>1</a>
<b>
<c>2</c>
</b>
</PropertyList>
then the declaration
<foo include="../bar.xml">
</foo>
is exactly equivalent to
<foo>
<a>1</a>
<b>
<c>2</c>
</b>
</foo>
However, it is also possible to selectively override properties in the
included file. For example, if the declaration were
<foo include="../bar.xml">
<a>3</a>
</foo>
then the property manager would see
<foo>
<a>3</a>
<b>
<c>2</c>
</b>
</foo>
with the original 'a' property's value replaced with 3.
This new inclusion feature allows property files to be broken up and
reused arbitrarily -- for example, there might be separate cropping
property lists for commonly-used textures or layers, to avoid
repeating the information in each instrument file.
Aliasing
--------
Properties can now alias other properties, similar to a symbolic link
in Unix. When the target property changes value, the new value will
show up in the aliased property as well. For example,
<PropertyList>
<foo>3</foo>
<bar alias="/foo"/>
</PropertyList>
will look the same to the application as
<PropertyList>
<foo>3</foo>
<bar>3</bar>
</PropertyList>
except that when foo changes value, bar will change too.
The combination of inclusions and aliases is very powerful, because it
allows for parameterized property files. For example, the XML file for
the NAVCOM radio can include a parameter subtree at the start, like
this:
<PropertyList>
<params>
<comm-freq-prop>/radios/comm1/frequencies/selected</comm-freq-prop>
<nav-freq-prop>/radios/nav1/frequencies/selected</comm-freq-prop>
</params>
...
<chunk>
<type>number-value</type>
<property alias="/params/nav-freq-prop"/>
</chunk>
...
</PropertyList>
Now, the same instrument file can be used for navcomm1 and navcomm2,
for example, simply by overriding the parameters at inclusion:
<instrument include="../Instruments/navcomm.xml">
<params>
<comm-freq-prop>/radios/comm1/frequencies/selected</comm-freq-prop>
<nav-freq-prop>/radios/nav1/frequencies/selected</comm-freq-prop>
</params>
</instrument>
<instrument include="../Instruments/navcomm.xml">
<params>
<comm-freq-prop>/radios/comm2/frequencies/selected</comm-freq-prop>
<nav-freq-prop>/radios/nav2/frequencies/selected</comm-freq-prop>
</params>
</instrument>
Instrument Architecture:
-----------------------
Instruments are defined in separate configuration files. An instrument
consists of a base width and height, one or more stacked layers, and
zero or more actions. Base dimensions are specified as follows:
<PropertyList> <!-- remember, all xml files start like this -->
<name>Airspeed Indicator</name> <!-- names are good -->
<w-base>128</w-base> <!-- required width spec-->
<h-base>128</h-base> <!-- required height spec-->
<layers> <!-- begins layers section -->
Height and width can be overriden in the top level panel.xml by
specifying <w> and <h>. Transformations are caculated against the base
size regardless of the display size. This ensures that instruments
remain calibrated
Textures:
--------
FG uses red/green/blue/alpha .rgba files for textures. Dimensions for
texture files should be power of 2 with a maximum 8:1 aspect ratio.
The lowest common denominator for maximum texture size is 256 pixels.
This is due to the limitations of certain video accelerators, most
notably those with 3Dfx chipset such as the Voodoo2.
Instrument Layers**:
-------------------
The simplest layer is a <texture>. These can be combined in <switch> layers
<texture>
A texture layer looks like this:
<layer> <!-- creates a layer -->
<name>face</name>
<texture> <!-- defines it as a texture layer -->
<path>Aircraft/c172/Instruments/Textures/faces-2.rgb</path>
<x1>0</x1> <!-- lower boundary for texture cropping-->
<y1>0.51</y1> <!-- left boundary for texture cropping-->
<x2>0.49</x2> <!-- upper boundary for texture cropping-->
<y2>1.0</y2> <!-- right boundary for texture cropping-->
</texture> <!-- closing texure tag -->
</layer> <!-- closing layer tag -->
The texture cropping specification is represented as a decimal. There
is a table at the end of this document for converting from pixel
coordinates to percentages.
This particular layer, being a gauge face has no transformations
applied to it. Layers with that aren't static *must* include <w> and
<h> parameters to be visible.
<type> May be either text or switch..
<type>switch</type>
A switch layer is composed of two or more nested layers and will
display one of the nested layers based on a boolean property. For a
simple example of a switch see
$FG_ROOT/Aircraft/c172/Instruments/brake.xml.
<layer>
<name>Brake light</name>
<type>switch</type> <!-- define layer as a switch -->
<property>/controls/brakes</property> <!-- tie it to a property -->
<layer1> <!-- layer for true state -->
<name>on</name> <!-- label to make life easy -->
<texture> <!-- layer1 of switch is a texture layer -->
<path>Aircraft/c172/Instruments/Textures/brake.rgb</path>
<x1>0.25</x1>
<y1>0.0</y1>
<x2>0.5</x2>
<y2>0.095</y2>
</texture>
<w>64</w> <!-- required width - layer isn't static -->
<h>24</h> <!-- required height - layer isn't static -->
</layer1> <!-- close layer1 of switch -->
<layer2> <!-- layer for false state -->
<name>off</name>
<texture>
<path>Aircraft/c172/Instruments/Textures/brake.rgb</path>
<x1>0.0</x1>
<y1>0.0</y1>
<x2>0.25</x2>
<y2>0.095</y2>
</texture>
<w>64</w>
<h>24</h>
</layer2>
</layer>
Switches can have more than 2 states. This requires nesting one switch
inside another. One could make, for example, a 3 color LED by nesting
switch layers.
<type>text</type>
A text layer may be static, as in a label, generated from a property
or a combination of both. This example is a switch that contains both
static and dynamic text:
<layer1> <!-- switch layer -->
<name>display</name>
<type>text</type> <!-- type == text -->
<point-size>12</point-size> <!-- font size -->
<color> <!-- specify rgb values to color text -->
<red>1.0</red>
<green>0.5</green>
<blue>0.0</blue>
</color> <!-- close color section -->
<chunks> <!-- sections of text are referred to as chunks -->
<chunk> <!-- first chunk of text -->
<type>number-value</type> <!-- value defines it as dynamic -->
<property>/radios/nav1/dme/distance</property> <!-- ties it to a property -->
<scale>0.00053995680</scale> <!-- convert between statute and nautical miles? -->
<format>%5.1f</format> <!-- define format -->
</chunk>
</chunks>
</layer1>
<layer2> <!-- switch layer -->
<name>display</name>
<type>text</type> <!-- type == text -->
<point-size>10</point-size> <!-- font size -->
<color> <!-- specify rgb values to color text -->
<red>1.0</red>
<green>0.5</green>
<blue>0.0</blue>
</color> <!-- close color section -->
<chunks> <!-- sections of text are referred to as chunks -->
<chunk> <!-- first chunk of text -->
<type>literal</type> <!-- static text -->
<text>---.--</text> <!-- fixed value -->
</chunk>
</chunks>
</layer2>
Transformations:
---------------
A transformation is a rotation, an x-shift, or a
y-shift. Transformations can be static or they can be based on
properties. Static rotations are useful for flipping textures
horizontally or vertically. Transformations based on properties are
useful for driving instrument needles. I.E. rotate the number of
degrees equal to the airspeed. X and y shifts are relative to the
center of the instrument. Each specified transformation type takes an
<offset>. Offsets are relative to the center of the instrument. A
shift without an offset has no effect. For example, let's say we have
a texure that is a circle. If we use this texture in two layers, one
defined as having a size of 128x128 and the second layer is defined as
64x64 and neither is supplied a shift and offset the net result
appears as 2 concentric circles.
About Transformations and Needle Placement:
------------------------------------------
When describing placement of instrument needles, a transformation
offset must be applied to shift the needles fulcrum or else the needle
will rotate around it's middle. The offset will be of <type> x-shift
or y-shift depending on the orientation of the needle section in the
cropped texture.
This example comes from the altimeter.xml
<layer>
<name>long needle (hundreds)</name> <!-- the altimeter has more than one needle -->
<texture>
<path>Aircraft/c172/Instruments/Textures/misc-1.rgb</path>
<x1>0.8</x1>
<y1>0.78125</y1>
<x2>0.8375</x2>
<y2>1.0</y2>
</texture>
<w>8</w>
<h>56</h>
<transformations> <!-- begin defining transformations -->
<transformation> <!-- start definition of transformation that drives the needle -->
<type>rotation</type>
<property>/steam/altitude</property> <!-- bind it to a property -->
<max>100000.0</max> <!-- upper limit of instrument -->
<scale>0.36</scale> <!-- once around == 1000 ft -->
</transformation> <!-- close this transformation -->
<transformation> <!-- this one shifts the fulcrum of the needle -->
<type>y-shift</type> <!-- y-shift relative to needle -->
<offset>24.0</offset> <!-- amount of shift -->
</transformation>
</transformations>
</layer>
This needles has its origin in the center of the instrument. If the
needles fulcrum was towards the edge of the instrument, the
transformations to place the pivot point must precede those which
drive the needle,
Interpolation
-------------
Non linear transformations are now possible via the use of
interpolation tables.
<transformation>
...
<interpolation>
<entry>
<ind>0.0</ind> <!-- raw value -->
<dep>0.0</dep> <!-- displayed value -->
</entry>
<entry>
<ind>10.0</ind>
<dep>100.0</dep>
</entry>
<entry>
<ind>20.0</ind>
<dep>-5.0</dep>
</entry>
<entry>
<ind>30.0</ind>
<dep>1000.0</dep>
</entry>
</interpolation>
</transformation>
Of course, interpolation tables are useful for non-linear stuff, as in
the above example, but I kind-of like the idea of using them for
pretty much everything, including non-trivial linear movement -- many
instrument markings aren't evenly spaced, and the interpolation tables
are much nicer than the older min/max/scale/offset stuff and should
allow for a more realistic panel without adding a full equation parser
to the property manager.
If you want to try this out, look at the airspeed.xml file in the base
package, and uncomment the interpolation table in it for a very funky,
non-linear and totally unreliable airspeed indicator.
Actions:
-------
An action is a hotspot on an instrument where something will happen
when the user clicks the left or center mouse button. Actions are
always tied to properties: they can toggle a boolean property, adjust
the value of a numeric property, or swap the values of two properties.
The x/y placement for actions specifies the origin of the lower left
corner. In the following example the first action sets up a hotspot
32 pixels wide and 16 pixels high. It lower left corner is placed 96
pixels (relative to the defined base size of the instrument) to the
right of the center of the instrument. It is also 32 pixels below the
centerline of the instrument. The actual knob texture over which the
action is superimposed is 32x32. Omitted here is a second action,
bound to the same property, with a positive increment value. This
second action is placed to cover the other half of the knob. The
result is that clicking on the left half of the knob texture decreases
the value and clicking the right half increases the value. Also
omitted here is a second pair of actions with the same coordinates but
a larger increment value. This second pair is bound to a different
mouse button. The net result is that we have both fine and coarse
adjustments in the same hotspot, each bound to a different mouse
button.
These examples come from the radio stack:
<actions> <!-- open the actions section -->
<action> <!- first action -->
<name>small nav frequency decrease</name>
<type>adjust</type>
<button>0</button> <!-- bind it to a mouse button -->
<x>96</x> <!-- placement relative to instrument center -->
<y>-32</y>
<w>16</w> <!-- size of hotspot -->
<h>32</h>
<property>/radios/nav1/frequencies/standby</property> <!-- bind to a property -->
<increment>-0.05</increment> <!-- amount of adjustment per mouse click -->
<min>108.0</min> <!-- lower range -->
<max>117.95</max> <!-- upper range -->
<wrap>1</wrap> <!-- boolean value -- value wraps around when it hits bounds -->
</action>
<action>
<name>swap nav frequencies</name>
<type>swap</type> <!-- define type of action -->
<button>0</button>
<x>48</x>
<y>-32</y>
<w>32</w>
<h>32</h>
<property1>/radios/nav1/frequencies/selected</property1> <!-- properties to toggle between -->
<property2>/radios/nav1/frequencies/standby</property2>
</action>
<action>
<name>ident volume on/off</name>
<type>adjust</type>
<button>1</button>
<x>40</x>
<y>-24</y>
<w>16</w>
<h>16</h>
<property>/radios/nav1/ident</property> <!-- this property is for Morse code identification of nav beacons -->
<increment>1.0</increment> <!-- the increment equals the max value so this toggles on/off -->
<min>0</min>
<max>1</max>
<wrap>1</wrap> <!-- a shortcut to avoid having separate actions for on/off -->
</action>
</actions>
More About Textures:
-------------------
As previously stated, the usual size instrument texture files in FGFS
are 256x256 pixels, red/green/blue/alpha format. However the mechanism
for specifying texture cropping coordinates is decimal in nature. When
calling a section of a texture file the 0,0 lower left convention is
used. There is a pair of x/y coordinates defining which section of
the texture to use.
The following table can be used to calculate texture cropping
specifications.
# of divisions | width in pixels | decimal specification
per axis
1 = 256 pixels 1
2 = 128 pixels, 0.5
4 = 64 pixels, 0.25
8 = 32 pixels, 0.125
16 = 16 pixels, 0.0625
32 = 8 pixels, 0.03125
64 = 4 pixels, 0.015625
128 = 2 pixels, 0.0078125
A common procedure for generating gauge faces is to use a vector
graphics package such as xfig, exporting the result as a postscript
file. 3D modeling tools may also be used and I prefer them for pretty
items such as levers, switches, bezels and so forth. Ideally, the
size of the item in the final render should be of proportions that fit
into the recommended pixel widths. The resulting files can be
imported into a graphics manipulation package such as GIMP, et al for
final processing.
How do I get my panels/instruments into the base package?
-------------------------------------------------------
Cash bribes always help ;) Seriously though, there are two main
considerations. Firstly, original artwork is a major plus since you
as the creator can dictate the terms of distribution.All Artwork must
have a license compatible with the GPL. Artwork of unverifiable
origin is not acceptable. Secondly, texture sizes must meet the
lowest common denominator of 256e2 pixels. Artwork from third parties
may be acceptable if it meets these criteria.
* If there are *any* XML parsing errors, the panel will fail to load,
so it's worth downloading a parser like Expat (http://www.jclark.com/xml/)
for checking your XML. FlightGear will print the location of errors, but
the messages are a little cryptic right now.
** NOTE: There is one built-in layer -- for the mag compass ribbon --
and all other layers are defined in the XML files. In the future,
there may also be built-in layers for special things like a
weather-radar display or a GPS (though the GPS could be handled with
text properties).

272
Docs/README.xmlsound Normal file
View file

@ -0,0 +1,272 @@
Users Guide to FlightGear sound configuration
Version 0.7.11, apr 27 2002
Author: Erik Hofman <erik@ehofman.com>
This document is an attempt to describe the configuration of
FlightGear flight simulator's aircraft sound via XML.
Some History:
------------
Older versions of FGFS had a hard coded audio layer. This was a
than ideal state of affairs due to FGFS ability to use different
aircraft models. Being primarily developed on UNIX type systems, a
modular approach is taken towards the simulation. To date, most
alternatives to the default Cessna 172 aircraft are the product
of research institutions interested in the flight characteristics and
not cosmetics. The result of this was that one could fly the X-15 or
a Boeing 747 but be limited to C172 sounds.
A rewrite of the sound code was done around v0.7.10 by Erik Hofman
allowing for configuration of the sounds via XML to address this
limitation.
Sound Architecture:
------------------
All of the sound configuration files are XML-encoded* property lists.
The root element of each file is always named <PropertyList>. Tags are
almost always found in pairs, with the closing tag having a slash
prefixing the tag name, i.e </PropertyList>. The exception is the tag
representing an aliased property. In this case a slash is prepended to
the closing angle bracket. (see section Aliasing)
The top level sound configuration file is composed of a <fx>, a
<name>, a <path> sound file and zero or more <volume> and/or <pitch>
definitions.
[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
[ Absolute paths may be used.Comments are bracketed with <!-- -->. ]
A limited sound configuration file would look something like this:
<PropertyList>
<fx>
<engine>
<name>engine</name>
<path>Sounds/wasp.wav</path>
<mode>looped</mode>
<condition>
<property>/engines/engine/running</property>
</condition>
<volume>
<property>/engines/engine/mp-osi</property>
<factor>0.005</factor>
<min>0.15</min>
<max>0.5</max>
<offset>0.15</offset>
</volume>
<pitch>
<property>/engines/engine/rpm</property>
<factor>0.0012</factor>
<min>0.3</min>
<max>5.0</max>
<offset>0.3</offset>
</pitch>
</engine>
</fx>
</PropertyList>
This would define an engine sound event handler for a piston engine driven
aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
and is named wasp.wav. The event is started when the property
/engines/engine/running becomes non zero.
When that happens, the sound will be played looped (see <mode>) until the
property returns zero again. As you can see the volume is mp-osi dependant,
and the pitch of the sound depents on the engine rpm.
Configuration description:
-------------------------
<fx>
Named FX subtree living under /sim/sound
< ... >
This is the event seperator. The text inside the brackets
can be anything. Bit it is adviced to give it a meaningfull name
like: crank, engine, rumble, gear, squeal, flap, wind or stall
The value can be defined multiple times, thus anything which is
related may have the same name (grouping them together).
<name>
This defines the name of the event. This name is used internally
and, although it can me defined multiple times in the same file,
should normally have an unique value.
Multiple definitions of the same name will allow multiple sections
to interfere in the starting and stopping of the sample.
This method can't be used to controll the pitch or volume of the
sample, but instead multiple volume or pitch section should be
included inside the same event.
The types "raise" and "fall" will stop the playback of the sample
regardless of any other event. This means that when the type "raise"
is supplied, sample playback will stop when the event turns false.
Using the type "fall" will stop playback when the event turns true.
IMPORTANT:
If the trigger is used for anything else but stopping the sound
at a certain event, all sections with the same name *should* have
exactly the same sections for everything but property and type.
In the case of just stopping the sample at a certain event, the
sections for path, volume and pitch may be omitted.
<path>
This defined th path to the sound file. The path is relative to the
FlightGear root directory but could be specified absolute.
<condition>
Define a condition that triggers the event.
For a complete description of the FlightGear conditions,
please read docs-mini/README.conditions
An event should define either a condition or a property.
<property>
Define which property triggers the event, and reffers to a node
in the FlightGear property tree. Action is taken when the property
is non zero.
A more sophisticated mechanism to trigger the event is described
in <condition>
<mode>
This defines how the sample should be played:
once: the sample is played once.
this is the default.
looped: the sample plays continuesly,
until the event turns false.
in-transit: the sample plays continuesly,
while the property is changing its value.
<volume> / <pitch>
Volume or Pitch definition. Currently there may be up to 5
volume and up to 5 pitch definitions defined within one sound
event. Normally all offset values are added together and the
results after property calculations will be miltplied.
A special condition occurs when the value of factor is negative,
in which case the offset doesn't get added to the other offset values
but instead will be used in the multiplication section.
<property>
Defins which property supplies the value for the calculation.
Either a <property> or an <internal> should be defined.
The value is treatened as a floating point number.
<internal>
Defins which internal variable should be used for the calculation.
The value is treatened as a floating point number.
The following internals are available at this time:
dt_play: the number of seconds since the sound started playing.
dt_stop: the number of seconds after the sound has stopped.
<type>
Defines the function that should be used upon the property
before it is used for calculating the net result:
lin: lineair handling of the property value.
this is the default.
ln: convert the property value to a natural logarithmic
value before scaling it. Anything below 1 will return
zero.
log: convert the property value to a true logarithmic
value before scaling it. Anything below 1 will return
zero.
inv: inverse lineair handling (1/x).
abs: absolute handling of the value (always positive).
sqrt: calculate the square root of the absolute value
before scaling it.
<factor>
Defines the multiplication factor for the property value.
A special condition is when scale is defined as a negative
value. In this case the result of |<scale>| * <property) will be
subtracted from <default>
<offset>
The initial value for this sound. This value is also used as an
offset value for calulating the end result.
<min>
Minimum allowed value.
This is usefull if sounds start to sound funny. Anything lower
will be truncated to this value.
<max>
Maximum allowed value.
This is usefull if sounds gets to loud. Anything higher will be
truncated to this value.
<position>
Specify the position of the sounds source relative to the
pilot's ears. The coordinate system used is a right hand
coordinate system where -X = left, +X = right, -Y = down, +Y =
up, -Z = forward, +Z = aft. Distances are in meters.
<x>
X dimension offset
<y>
Y dimension offset
<z>
Z dimension offset
<reference-dist>
Set a reference distance of sound in meters. This is the
distance where the gain/volume will be halved. This can be
useful for limiting cockpit sounds to the cockpit.
<max-dist>
Set the maximum audible distance for the sound in meters.
This can be useful for limiting cockpit sounds to the cockpit.
Creating a configrationfile:
---------------------------
To make things easy, there is a default falue for most entries to allow a
sane configuration when a certain entry is omitted.
Default values are:
type: lin
factor: 1.0
offset: 0.0 for volume, 1.0 for pitch
min: 0.0
max: 0.0 (don't check)
Calculations are made the following way (for both pitch and volume):
value = 0;
offs = 0;
for (n = 0; n < max; n++) {
if (factor < 0)
{
value += offset[n] - abs(factor[n]) * function(property[n]);
}
else
{
value += factor[n] * function(property[n]);
offs += offset[n];
}
}
volume = offs + value;
where function can be one of: lin, ln, log, inv, abs or sqrt

186
Docs/README.xmlsyntax Normal file
View file

@ -0,0 +1,186 @@
XML IN FIFTEEN MINUTES OR LESS
Written by David Megginson, david@megginson.com
Last modified: $Date$
This document is in the Public Domain and comes with NO WARRANTY!
1. Introduction
---------------
FlightGear uses XML for much of its configuration. This document
provides a minimal introduction to XML syntax, concentrating only on
the parts necessary for writing and understanding FlightGear
configuration files. For a full description, read the XML
Recommendation at
http://www.w3.org/TR/
This document describes general XML syntax. Most of the XML
configuration files in FlightGear use a special format called
"Property Lists" -- a separate document will describe the specific
features of the property-list format.
2. Elements and Attributes
--------------------------
An XML document is a tree structure with a single root, much like a
file system or a recursive, nested list structure (for LISP fans).
Every node in the tree is called an _element_: the start and end of
every element is marked by a _tag_: the _start tag_ appears at the
beginning of the element, and the _end tag_ appears at the end.
Here is an example of a start tag:
<foo>
Here is an example of an end tag:
</foo>
Here is an example of an element:
<foo>Hello, world!</foo>
The element in this example contains only data element, so it is a
leaf node in the tree. Elements may also contain other elements, as
in this example:
<bar>
<foo>Hello, world!</foo>
<foo>Goodbye, world!</foo>
</bar>
This time, the 'bar' element is a branch that contains other, nested
elements, while the 'foo' elements are leaf elements that contain only
data. Here's the tree in ASCII art (make sure you're not using a
proportional font):
bar +-- foo -- "Hello, world!"
|
+-- foo -- "Goodbye, world!"
There is always one single element at the top level: it is called the
_root element_. Elements may never overlap, so something like this is
always wrong (try to draw it as a tree diagram, and you'll understand
why):
<a><b></a></b>
Every element may have variables, called _attributes_, attached to
it. The attribute consists of a simple name=value pair in the start
tag:
<foo type="greeting">Hello, world!</foo>
Attribute values must be quoted with '"' or "'" (unlike in HTML), and
no two attributes may have the same name.
There are rules governing what can be used as an element or attribute
name. The first character of a name must be an alphabetic character
or '_'; subsequent characters may be '_', '-', '.', an alphabetic
character, or a numeric character. Note especially that names may not
begin with a number.
3. Data
-------
Some characters in XML documents have special meanings, and must
always be escaped when used literally:
< &lt;
& &amp;
Other characters have special meanings only in certain contexts, but
it still doesn't hurt to escape them:
> &gt;
' &apos;
" &quot;
Here is how you would escape "x < 3 && y > 6" in XML data:
x &lt; 3 &amp;&amp; y &gt; 6
Most control characters are forbidden in XML documents: only tab,
newline, and carriage return are allowed (that means no ^L, for
example). Any other character can be included in an XML document as a
character reference, by using its Unicode value; for example, the
following represents the French word "cafe" with an accent on the
final 'e':
caf&#233;
By default, 8-bit XML documents use UTF-8, **NOT** ISO 8859-1 (Latin
1), so it's safest always to use character references for characters
above position 127 (i.e. for non-ASCII).
Whitespace always counts in XML documents, though some specific
applications (like property lists) have rules for ignoring it in some
contexts.
4. Comments
-----------
You can add a comment anywhere in an XML document except inside a tag
or declaration using the following syntax:
<!-- comment -->
The comment text must not contain "--", so be careful about using
dashes.
5. XML Declaration
------------------
Every XML document may begin with an XML declaration, starting with
"<?xml" and ending with "?>". Here is an example:
<?xml version="1.0" encoding="UTF-8"?>
The XML declaration must always give the XML version, and it may also
specify the encoding (and other information, not discussed here).
UTF-8 is the default encoding for 8-bit documents; you could also try
<?xml version="1.0" encoding="ISO-8859-1"?>
to get ISO Latin 1, but some XML parsers might not support that
(FlightGear's does, for what it's worth).
6. Other Stuff
--------------
There are other kinds of things allowed in XML documents. You don't
need to use them for FlightGear, but in case anyone leaves one lying
around, it would be useful to be able to recognize it.
XML documents may contain different kinds of declarations starting
with "<!" and ending with ">":
<!DOCTYPE html SYSTEM "html.dtd">
<!ELEMENT foo (#PCDATA)>
<!ENTITY myname "John Smith">
and so on. They may also contain processing instructions, which look
a bit like the XML declaration:
<?foo processing instruction?>
Finally, they may contain references to _entities_, like the ones used
for escaping special characters, but with different names (we're
trying to avoid these in FlightGear):
&chapter1;
&myname;
Enjoy.