Simplify logic now SGPath::desktop works on Windows.

[flightgear.git] / docs-mini / README.digitalfilters

diff --git a/docs-mini/README.digitalfilters b/docs-mini/README.digitalfilters
index a94c15074edb09ff002f229ed7735552dc6c14f3..9f65b8ae9445bc4edd6a05daef5f64de9b8a34ed 100644 (file)
--- a/docs-mini/README.digitalfilters
+++ b/docs-mini/README.digitalfilters
@@ -1,3 +1,9 @@
+NOTE:
+This manual may contain outdated information. For documentation of the most recent features
+refer to
+http://wiki.flightgear.org/index.php/Howto:_Design_an_autopilot
+http://wiki.flightgear.org/index.php/Autopilot_Configuration_Reference
+
 COMMON SETTINGS
 ==============================================================================
 
@@ -17,16 +23,27 @@ in the remaining document.
 The complete XML syntax for a InputValue is
 
 <some-element>
+  <condition>
+    <!-- any condition as defined in README.conditions -->
+  </condition>
   <property>/some/property/name</property>
   <value>0.0</value>
   <scale>1.0</value>
   <offset>0.0</offset>
+  <max>infinity</max>
+  <min>-infinity<min>
+  <abs>false</abs>
+  <period>
+    <min>-180.0</min>
+    <max>-180.0</max>
+  </period>
 </some-element>
 
 The enclosing element <some-element> is the element defined in each filter, like <input>, <u_min>, 
 <reference> etc. These elements will be described later.
 The value of the input is calculated based on the given value, scale and offset as
-value * scale + offset. 
+value * scale + offset 
+and the result is clipped to min/max, if given.
 With the full set of given elements, the InputValue will initialize the named property to the value
 given, reduced by the given offset and reverse scaled by the given scale.
 
@@ -47,6 +64,9 @@ The default values for elements not given are:
 <scale/> : 1.0
 <offset/>: 0.0
 <property/> : none
+<min/>   : unclipped
+<max/>   : unclipped
+<abs/>   : false
 
 Some examples:
 <input>
@@ -77,9 +97,44 @@ Examples:
 
 The <property> element may also be written as <prop> for backward compatibility.
 
+There may be one or more InputValues for the same input of a filter which may be bound to conditions.
+Each InputValue will have its condition checked in the order of InputValues given in the configuration
+file. The first InputValue that returns true for its condition will be evaluated. Chaining a number
+of InputValues with conditions and an unconditioned InputValue works like the C language equivalent
+if( condition ) {
+  // compute value of first element
+} else if( condition2 ) {
+  // compute value of second element
+} else if( condition3 ) {
+  // compute value of third element
+} else {
+  // compute value of last element
+}
+
+Example: Set the gain to 3.0 if /autopilot/locks/heading equals dg-heading-hold or 2.0 otherwise.
+<digital-filter>
+  <gain>
+    <condition>
+      <equals>
+        <property>/autopilot/locks/heading</property>
+        <value>dg-heading-hold</value>
+      </equals>
+    </condition>
+    <value>3.0</value>
+  <gain>
+  <!-- Hint: omit a condition here as a fallthru else condition -->
+  </gain>
+    <value>2.0</value>
+  <gain>
+<digital-filter>
+
+If the element <abs> is used and set to the value "true", only the absolute value of the input
+(the positive part) is used for further computations. The abs function is applied after all 
+other computations are completed.
+    
 OutputValue           
 ==============================================================================
-Each filter drives one to many output properties. No scaling of offsetting is implemented
+Each filter drives one to many output properties. No scaling or offsetting is implemented
 for the output value, these should be done in the filter itself.
 The output properties are defined in the <output/> element by adding <property/> elements
 within the <output/> element. For just a single output property, the <property/> element
@@ -121,6 +176,9 @@ Example:
                           If either <u_min> or <u_max> is given, clamping is activated. A missing
                           min or max value defaults to 0 (zero).
                           Note: <u_min> and <u_max> may also occour within a <config> element.
+                          <min> and <max> may be used as a substitude for the corresponding u_xxx element.
+<period>      Complex     Define a periodical input or output value. The phase width is defined by the 
+                          child elements <min> and <max> which are of type InputValue
 
 Example: Limit the pilot's body temperature to a constant minimum of 36 and a maximum defined in
          /pilots/max-body-temperature-degc, initialized to 40.0
@@ -128,15 +186,26 @@ Example: Limit the pilot's body temperature to a constant minimum of 36 and a ma
   <prop>/pilots/max-body-temperature-degc</prop>
   <value>40.0</
 </u_max>
-<u_min>
+<min>
   <value>36.0</value>
-</u_min
+</min
 
 Implicit definition of the minimum value of 0 (zero) and defining a maximum of 100.0
 <config>
   <u_max>100.0</u_max>
 </config>
 
+This defines the input or output as a periodic value with a phase width of 360, like 
+the compass rose.  Any value reaching the filter's input or leaving the filter at the 
+output will be transformed to fit into the given range by adding or substracting one phase 
+width of 360. Values of -270, 90 or 450 applied to this periodical element will allways 
+result in +90. A value of 630, 270 or -90 will be normalized to -90 in the given example.
+<period>
+  <min>-180.0</min>
+  <max>180.0</max>
+</period>
+
+
 <enable>      Complex     Define a condition to enable or disable the filter. For disabled
                           filters, no output computations are performed. Only enabled
                           filters fill the output properties. The default for undefined