Users Guide to FlightGear sound configuration
-Version 0.7.10, Mar 02 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.
-
-About The Property Manager:
---------------------------
-The
+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:
<name>engine</name>
<path>Sounds/wasp.wav</path>
<mode>looped</mode>
- <property>/engines/engine/running</property>
+ <condition>
+ <property>/engines/engine/running</property>
+ </condition>
<volume>
<property>/engines/engine/mp-osi</property>
<factor>0.005</factor>
/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:
-------------------------
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, stall or click.
+ 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.
+ 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 have a unique value unless you realy know what you're doing.
+ should normally have an unique value.
- Defining it multiple times could lead to unexpected behaviour.
+ 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.
+
+ <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.
-
- The value is converted to an integer value (anything less than 0.5 is
- is considered to be 0) and handled if it were a boolean value
- (0 = false, anything else = true).
-
- The triger depends on the value of <type>.
-
- <type>
- This specifies how the event is triggered.
- There are multiple options:
-
- level: events are active if the value is true.
- this is the default behaviour.
-
- inverted: events are active if the value is false.
-
- flipflop: events are triggered on state changes.
- this is only usefull for samples which are played
- once.
+ 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>
<mode>
This defines how the sample should be played:
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 <factor> value is negative,
+ 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.
- 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 threated as a floating point number.
+
+ <internal>
+ Defines which internal variable should be used for the calculation.
+ The value is threated 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>
- lin: lineair handling of the property value.
+ Defines the function that should be used upon the property
+ before it is used for calculating the net result:
+
+ lin: linear handling of the property value.
this is the default.
- ln: convert the property value to a natural logarithmic
- value before scaling it.
-
- log: convert the property value to a true logarithmic
- value before scaling it.
+ ln: convert the absolute property value to a natural
+ logarithmic value before scaling it.
+ Anything below 1 will return zero.
+
+ log: convert the absolute property value to a true
+ logarithmic value before scaling it.
+ Anything below 1 will return zero.
+
+ inv: inverse linear 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.
<offset>
The initial value for this sound. This value is also used as an
- offset value for calulating the end result.
+ offset value for calculating the end result.
<min>
Minimum allowed value.
- This is usefull if sounds start to sound funny. Anything lower
- will be converted to 0.
+ 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
+ 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
+ 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
+
+
+ <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.
+
+ <x>
+ X dimension angle (0.0 - 360.0)
+
+ <y>
+ Y dimension angle (0.0 - 360.0)
+
+ <z>
+ Z dimension angle (0.0 - 360.0)
+
+ <inner-cone>
+ The inner edge of the audio cone in degrees (0.0 - 360.0).
+ Any sound withing that angle will be played at the current gain.
+
+ <outer-cone>
+ The outer edge of the audio cone in degrees (0.0 - 360.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 configration file:
+----------------------------
+
+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)
+
- Calculations are made the following way
- (function can be one of: none, ln or log ):
-
- if (scale < 0) {
- value[i] = offset[n] - abs(scale[n]) * function(property[n])
- offset[i] = 0;
- } else
- value[i] = scale[n] * function(property[n])
+Calculations are made the following way (for both pitch and volume):
- And the end result will be:
-
- result = offset[0..max] + value[0..max];
-
+ 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
projects / flightgear.git / blobdiff