X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=docs-mini%2FREADME.xmlsound;h=9fa920f89c9d453c4f70885acb28ca7e67813abd;hb=8545e5926a5afbd1299b940a087fcf5c8e19bb90;hp=4b9632340eaf2774ed08bd852bc2cf034c4d9c06;hpb=1c513868b77b38bf90f83d4473f0a436da97fbb8;p=flightgear.git diff --git a/docs-mini/README.xmlsound b/docs-mini/README.xmlsound index 4b9632340..9fa920f89 100644 --- a/docs-mini/README.xmlsound +++ b/docs-mini/README.xmlsound @@ -1,24 +1,9 @@ Users Guide to FlightGear sound configuration -Version 0.7.11, apr 27 2002 -Author: Erik Hofman +Version 0.9.8, October 30, 2005 +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. +FlightGear flight simulator's aircraft sound in XML. Sound Architecture: ------------------ @@ -33,8 +18,8 @@ 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 . ] +[ 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: @@ -71,147 +56,229 @@ 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. +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 + 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). - 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. + - 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. - 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. - 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 + A more sophisticated mechanism to trigger the event is described + in - 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. + + + This defines the type os this sample: - in-transit: the sample plays continuesly, - while the property is changing its value. + 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 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. - 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 or an should be defined. + The value is treated as a floating point number. + + + 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_stop: the number of seconds after the sound has stopped. + + 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. + - 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. - 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 || * + 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. + The initial value for this sound. This value is also used as an + offset value for calculating the end result. - 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. - 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. + + + 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 dimension offset + + + Y dimension offset + + + Z dimension offset + + + + 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 dimension + + + Y dimension + + + Z dimension + + + 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. + + + 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. + + + The gain at the outer edge of the cone. + + + + 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. + + + 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) @@ -223,12 +290,12 @@ Calculations are made the following way (for both pitch and volume): 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]; } }