fly/fgdata
1
0
Fork 0
Code Activity

Documentation improvements

Browse source 
Rewrote the volume section of xmlsound and add documentation for expressions
This commit is contained in:
Richard Harrison 2020-08-01 16:41:53 +02:00
parent 6ac7b3385e
commit eb5d1029c8
2 changed files with 166 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

107
Docs/README.expressions Normal file
View file

@ -0,0 +1,107 @@
Expressions (or SGExpressions) are a feature of the SimGear library
and provide a nice way of implementing complex math formulas using XML
syntax. They are supported in many systems within the FlightGear code.
Caution: Expressions do not check if your math creates floating point
exceptions (like division by zero conditions, taking the square root
of a negative number, etc.). This can cause undefined behavior and may
result in NaNs or even Cascading NaNs. Usage
Expressions are supported in
* Autopilot configuration files
* Particle system configuration files
* Animations (translate, rotate, scale, range, blend)
* The shader technique
Sample Expressions
This is a sample expression for the euation c = sqrt(a*a + b^2).
Children/arguments are parsed in the order they appear in in the file
(or the order in which they are set via property methods).
<expression>
<sqrt>
<sum>
<product>
<property>/value/a</property>
<property>/value/a</property>
</product>
<pow>
<property>/value/b</property>
<value>2</value>
</pow>
</sum>
</sqrt>
</expression>
Supported elements
NOTE: #c in the table below is the number of child nodes required.
+-------------------+----+--------------------------------------------------+
| Function | #c | Notes |
+-------------------+----+--------------------------------------------------+
| <abs> <fabs> | 1 | |
| <acos> | 1 | |
| <asin> | 1 | |
| <atan2> | 2 | |
| <atan> | 1 | |
| <ceil> | 1 | |
| <clip> | 3 | clipMin, clipMax, expression |
| <cos> | 1 | |
| <cosh> | 1 | |
| <deg2rad> | 1 | |
| <difference> <dif>| 1+ | |
| <div> | 2 | |
| <exp> | 1 | |
| <floor> | 1 | |
| <log10> | 1 | |
| <log> | 1 | |
| <max> | 1+ | |
| <min> | 1+ | |
| <mod> | 2 | |
| <pow> | 2 | |
| <product> <prod> | 1+ | |
| <property> | 0 | Property name e.g.<property>node/value</property>|
| <rad2deg> | 1 | |
| <sin> | 1 | |
| <sinh> | 1 | |
| <sqr> | 1 | |
| <sqrt> | 1 | |
| <sum> | 1+ | |
| <table> | 2+ | <entry><ind> 0.0 </ind><dep> 10 </dep></entry> |
| <tan> | 1 | |
| <tanh> | 1 | |
| <value> | 0 | Constant Value e.g. <value>0</value> |
+-------------------+----+--------------------------------------------------+
Hints and tips
--------------
1. There is no function for rounding, hwoever "Round half up" can be
achieved as follows
<expression>
<floor>
<sum>
<property>your/property/here</property>
<value>0.5</value>
</sum>
</floor>
</expression>
2. Interpolation tables can be useful when a formula cannot be found,
In the example below <ind> is the indepdendant variable and
<dep> is the dependant variable. What this table does is as follows
- values below 0.2 will be 10
- values above 0.2 and between 1.0 will be interpolated between 10
and 0
- values above 1.0 will be 0
<table>
<entry><ind> 0.0 </ind><dep> 10 </dep></entry>
<entry><ind> 0.2 </ind><dep> 10 </dep></entry>
<entry><ind> 1.0 </ind><dep> 0 </dep></entry>
</table>

81
Docs/README.xmlsound
View file

@ -143,20 +143,64 @@ Configuration description:
<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 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.
event.
The volume elements are processed as follows
total_offset = 0
total_volume = 1.0
for each <volume> element:
(a) Use either <property> or <internal> as the base value
(b) apply any <type> function to the value
(c) value = value * factor
(d) value = max(value, <max>)
(e) value = min(value, <min>)
(f) if <factor> was originally negative then use
offset-mode otherwise use normal mode
(normal-mode)
total_offset = total_offset + offset
total_volume = total_volume * value
(offset-mode)
value = value + offset
total_volume = total_volume * value
Then after processing all of the <volume> blocks the total
volume will be determined by
volume = total_offset + total_volume;
<expression>
Defines the AN SGExpression to be used to calculate the volume
or pitch. When an expression is used all other tags in the
volume block are ignored.
Refs: README.expressions
http://wiki.flightgear.org/Expressions
<property>
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.
Property to use for the base value for the calculation.
<factor>
Defines the multiplication factor for the property value.
If factor is negative then it will cause the calculation for
this element to use the offset-mode as defined above. The
negative value for the factor will be converted to positive
<offset>
The offset elements will be summed and added to the to the
calculated volume from all of the volume blocks, except when
using offset-mode in which case the offset is directly added
to the calculated volume within each volume block
<internal>
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.
@ -164,9 +208,12 @@ Configuration description:
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.
Defines the delay after the volume block becomes active.
An example would be to have two sounds that relate to a single
property and the delay-sec element can be used to allow one
sound to start after the end of the first one simply by
setting the delay-sec to the duration of the sample.
<type>
Defines the function that should be used upon the property
@ -190,16 +237,6 @@ Configuration description:
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 calculating the end result.
<random>
Add a bit of randomness to the offset. Only used for pitch.