1Expressions (or SGExpressions) are a feature of the SimGear library
2and provide a nice way of implementing complex math formulas using XML
3syntax. They are supported in many systems within the FlightGear code.
4
5Caution: Expressions do not check if your math creates floating point
6exceptions (like division by zero conditions, taking the square root
7of a negative number, etc.). This can cause undefined behavior and may
8result in NaNs or even Cascading NaNs.  Usage
9
10Expressions are supported in
11
12* Autopilot configuration files
13* Particle system configuration files
14* Animations (translate, rotate, scale, range, blend)
15* The shader technique
16
17Sample Expressions
18
19This is a sample expression for the euation c = sqrt(a*a + b^2).
20
21Children/arguments are parsed in the order they appear in in the file
22(or the order in which they are set via property methods).
23
24<expression>
25  <sqrt>
26    <sum>
27      <product>
28        <property>/value/a</property>
29        <property>/value/a</property>
30      </product>
31      <pow>
32        <property>/value/b</property>
33        <value>2</value>
34      </pow>
35    </sum>
36  </sqrt>
37</expression>
38
39Supported elements
40
41NOTE: #c in the table below is the number of child nodes required.
42
43+-------------------+----+--------------------------------------------------+
44| Function          | #c | Notes                                            |
45+-------------------+----+--------------------------------------------------+
46| <abs> <fabs>      | 1  |                                                  |
47| <acos>            | 1  |                                                  |
48| <asin>            | 1  |                                                  |
49| <atan2>           | 2  |                                                  |
50| <atan>            | 1  |                                                  |
51| <ceil>            | 1  |                                                  |
52| <clip>            | 3  | clipMin, clipMax, expression                     |
53| <cos>             | 1  |                                                  |
54| <cosh>            | 1  |                                                  |
55| <deg2rad>         | 1  |                                                  |
56| <difference> <dif>| 1+ |                                                  |
57| <div>             | 2  |                                                  |
58| <exp>             | 1  |                                                  |
59| <floor>           | 1  |                                                  |
60| <log10>           | 1  |                                                  |
61| <log>             | 1  |                                                  |
62| <max>             | 1+ |                                                  |
63| <min>             | 1+ |                                                  |
64| <mod>             | 2  |                                                  |
65| <pow>             | 2  |                                                  |
66| <product> <prod>  | 1+ |                                                  |
67| <property>        | 0  | Property name e.g.<property>node/value</property>|
68| <rad2deg>         | 1  |                                                  |
69| <sin>             | 1  |                                                  |
70| <sinh>            | 1  |                                                  |
71| <sqr>             | 1  |                                                  |
72| <sqrt>            | 1  |                                                  |
73| <sum>             | 1+ |                                                  |
74| <table>           | 2+ | <entry><ind> 0.0 </ind><dep> 10 </dep></entry>   |
75| <tan>             | 1  |                                                  |
76| <tanh>            | 1  |                                                  |
77| <value>           | 0  | Constant Value e.g. <value>0</value>             |
78+-------------------+----+--------------------------------------------------+
79
80Hints and tips
81--------------
82
831. There is no function for rounding, hwoever "Round half up" can be
84   achieved as follows
85
86  <expression>
87    <floor>
88      <sum>
89        <property>your/property/here</property>
90        <value>0.5</value>
91      </sum>
92    </floor>
93  </expression>
94
952. Interpolation tables can be useful when a formula cannot be found,
96   In the example below <ind> is the indepdendant variable and
97   <dep> is the dependant variable. What this table does is as follows
98   - values below 0.2 will be 10
99   - values above 0.2 and between 1.0 will be interpolated between 10
100     and 0
101   - values above 1.0 will be 0
102
103    <table>
104      <entry><ind> 0.0 </ind><dep> 10 </dep></entry>
105      <entry><ind> 0.2 </ind><dep> 10 </dep></entry>
106      <entry><ind> 1.0 </ind><dep>  0 </dep></entry>
107    </table>
108