From b1ddb2a800ec0622e92cf485753ac59fdca57673 Mon Sep 17 00:00:00 2001 From: david Date: Sun, 3 Mar 2002 02:07:21 +0000 Subject: [PATCH] Erik Hofman's documentation for sound configuration, updated and moved from the base package. --- docs-mini/README.xmlsound | 198 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 docs-mini/README.xmlsound diff --git a/docs-mini/README.xmlsound b/docs-mini/README.xmlsound new file mode 100644 index 000000000..f01f19a43 --- /dev/null +++ b/docs-mini/README.xmlsound @@ -0,0 +1,198 @@ +Users Guide to FlightGear sound configuration +Version 0.7.10, Mar 02 2002 +Author: Erik Hofman + +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 + +Sound Architecture: +------------------ +All of the sound configuration files are XML-encoded* property lists. +The root element of each file is always named . Tags are +almost always found in pairs, with the closing tag having a slash +prefixing the tag name, i.e . 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 , a +, a sound file and zero or more and/or +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: + + + + + engine + Sounds/wasp.wav + looped + /engines/engine/running + + /engines/engine/mp-osi + 0.005 + 0.15 + 0.5 + 0.15 + + + /engines/engine/rpm + 0.0012 + 0.3 + 5.0 + 0.3 + + + + + +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 ) 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: +------------------------- + + + 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. + + The value can be defined multiple times, thus anything which is + related may have the same 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. + + Defining it multiple times could lead to unexpected behaviour. + + + This defined th path to the sound file. The path is relative to the + FlightGear root directory but could be specified absolute. + + + 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 . + + + 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. + + + 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. + + + / + 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 values are added together and the + results after property calculations will be miltplied. + A special condition occurs when the value 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. + + + Defins which property supplies the value for the calculation. + The value is treatened as a floating point number. + + + lin: lineair 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. + + + 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 || * + + + The initial value for this sound. This value is also used as an + offset value for calulating the end result. + + + Minimum allowed value. + This is usefull if sounds start to sound funny. Anything lower + will be converted to 0. + + + + Maximum allowed value. + This is usefull if sounds gets to loud. Anything higher will be + truncated to this value. + + + 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]) + + And the end result will be: + + result = offset[0..max] + value[0..max]; + + + +