Users Guide to FlightGear sound configuration
-Version 0.7.11, apr 27 2002
-Author: Erik Hofman <erik@ehofman.com>
+Version 0.9.8, October 30, 2005
+Author: Erik Hofman <erik at ehofman dot 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.
+FlightGear flight simulator's aircraft sound in XML.
Sound Architecture:
------------------
<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 <!-- -->. ]
+[ Paths are relative to $FG_ROOT (the root of the installed base package .) ]
+[ Absolute paths may be used. Comments are bracketed with <!-- -->. ]
A limited sound configuration file would look something like this:
/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.
+property returns zero again. As you can see the volume is mp-osi dependent,
+and the pitch of the sound depends on the engine rpm.
Configuration description:
-------------------------
<fx>
- Named FX subtree living under /sim/sound
+ 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
+ This is the event separator. The text inside the brackets
+ can be anything. Bit it is advised to give it a meaningful 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).
+ 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.
-
+ 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 control 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.
+ 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
+ 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.
+ 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.
+ Define which property triggers the event, and refers 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>
+ A more sophisticated mechanism to trigger the event is described
+ in <condition>
<mode>
- This defines how the sample should be played:
+ This defines how the sample should be played:
- once: the sample is played once.
- this is the default.
+ once: the sample is played once.
+ this is the default.
- looped: the sample plays continuesly,
- until the event turns false.
+ looped: the sample plays continuously,
+ until the event turns false.
+
+ in-transit: the sample plays continuously,
+ while the property is changing its value.
- in-transit: the sample plays continuesly,
- while the property is changing its value.
+ <type>
+ This defines the type os this sample:
+
+ fx: this is the default type and doesn't need to be defined.
+
+ avionics: sounds set to this type don't have a position and
+ orientation but are treated as if it's mounted to
+ the aircraft panel. it's up to the user to define
+ if it can always be heard or only when in cockpit
+ view.
<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.
+ 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 multiplied.
+ 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.
+ Defines which property supplies the value for the calculation.
+
Either a <property> or an <internal> should be defined.
+ The value is treated 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:
+ Defines which internal variable should be used for the calculation.
+ The value is treated 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_play: the number of seconds since the sound started playing.
- dt_stop: the number of seconds after the sound has stopped.
-
- random: a random number between 0.0 and 1.0
+ dt_stop: the number of seconds after the sound has stopped.
+ <delay-sec>
+ Delay after which the sound starts playing. This is useful to let
+ a property start two sounds at the same time, where the second is
+ delayed until the first stopped playing.
+
<type>
- Defines the function that should be used upon the property
- before it is used for calculating the net result:
+ 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.
+ lin: linear 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.
+ 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.
+ 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).
+ inv: inverse linear handling (1/x).
- abs: absolute handling of the value (always positive).
+ abs: absolute handling of the value (always positive).
- sqrt: calculate the square root of the absolute value
- before scaling it.
+ 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>
+ 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.
+ The initial value for this sound. This value is also used as an
+ offset value for calculating the end result.
<min>
- Minimum allowed value.
- This is usefull if sounds start to sound funny. Anything lower
- will be truncated to this value.
+ Minimum allowed value.
+ This is useful 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.
+ Maximum allowed value.
+ This is useful if sounds gets to loud. Anything higher will be
+ truncated to this value.
+
+ <position>
+ Specify the position of the sounds source relative to the
+ aircraft center. The coordinate system used is a left hand
+ coordinate system where +Y = left, -Y = right, -Z = down, +Z =
+ up, -X = forward, +X = aft. Distances are in meters.
+ The volume calculation due to distance and orientation of the
+ sounds source ONLY work on mono samples!
+
+ <x>
+ X dimension offset
+
+ <y>
+ Y dimension offset
+
+ <z>
+ Z dimension offset
+
+
+ <orientation>
+ Specify the orientation of the sounds source.
+
+ The zero vector is default, indicating that a Source is not directional.
+ Specifying a non-zero vector will make the Source directional in
+ the X,Y,Z direction
+
+ <x>
+ X dimension
+
+ <y>
+ Y dimension
+
+ <z>
+ Z dimension
+
+ <inner-angle>
+ The inner edge of the audio cone in degrees (0.0 - 180.0).
+ Any sound withing that angle will be played at the current gain.
+
+ <outer-angle>
+ The outer edge of the audio cone in degrees (0.0 - 180.0).
+ Any sound beyond the outer cone will be played at "outer-gain" volume.
+
+ <outer-gain>
+ The gain at the outer edge of the cone.
+
+
+ <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:
----------------------------
+Creating a configuration file:
+------------------------------
-To make things easy, there is a default falue for most entries to allow a
+To make things easy, there is a default value 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)
+type: lin
+factor: 1.0
+offset: 0.0 for volume, 1.0 for pitch
+min: 0.0
+max: 0.0 (don't check)
for (n = 0; n < max; n++) {
if (factor < 0)
{
- value += offset[n] - abs(factor[n]) * function(property[n]);
+ value += offset[n] - abs(factor[n]) * function(property[n]);
}
else
{
- value += factor[n] * function(property[n]);
- offs += offset[n];
+ value += factor[n] * function(property[n]);
+ offs += offset[n];
}
}
projects / flightgear.git / blobdiff