diff --git a/Docs/README.checklists b/Docs/README.checklists index 9c7f500fa..9567e1cff 100644 --- a/Docs/README.checklists +++ b/Docs/README.checklists @@ -6,7 +6,7 @@ the Help->Checklists menu within the simulator. Tutorials are automatically generated from checklists on startup. -Each checklist is defined as a property tree under /sim/checklists/checklist[n] +Each checklist is defined as a property tree under /sim/checklists/checklist[n] with the following tags - Name of the checklist @@ -20,13 +20,13 @@ with the following tags Contains x-m, y-m, z-m and scale tag. <condition> - Optional standard FlightGear condition node that evaluates when the checklist item has been completed. - <binding> - Zero or more bindings to execute the checklist item. Allows the user - to have their virtual co-pilot perform the action if they select the - ">" button next to the checklist item. + <binding> - Zero or more bindings to execute the checklist item. Allows the user + to have their virtual co-pilot perform the action if they select the + ">" button next to the checklist item. The <page> tag may be omitted for single-page checklists, with the <item> tags -immediately under the <checklist[n]> node. - +immediately under the <checklist[n]> node. + See the c172p for an example of this in action (Aircraft/c172p/c172-checklists.xml). diff --git a/Docs/README.digitalfilters b/Docs/README.digitalfilters index dce9a80dd..78449f24b 100644 --- a/Docs/README.digitalfilters +++ b/Docs/README.digitalfilters @@ -1,18 +1,18 @@ COMMON SETTINGS ============================================================================== -Currently four types of digital filter implementations are supported. They all serve an -individual purpose or are individual implementations of a specific filter type. -Each filter implementation uses the same set of basic configuration tags and individual -configuration elements. These individual elements are described in the section of the -filter. +Currently four types of digital filter implementations are supported. They all +serve an individual purpose or are individual implementations of a specific +filter type. Each filter implementation uses the same set of basic configuration +tags and individual configuration elements. These individual elements are +described in the section of the filter. The InputValue ============================================================================== -Each filter has several driving values, like the input value itself, sometimes a reference -value, a gain value and others. Most of these input values can bei either a constant value -or the value of a property. They all use the same syntax and will be referred to as InputValue -in the remaining document. +Each filter has several driving values, like the input value itself, sometimes +a reference value, a gain value and others. Most of these input values can be +either a constant value or the value of a property. They all use the same syntax +and will be referred to as InputValue in the remaining document. The complete XML syntax for a InputValue is @@ -33,13 +33,14 @@ The complete XML syntax for a InputValue is </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 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 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. +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. Example: <input> @@ -49,9 +50,10 @@ Example: <offset>0.5</offset> </input> -Will use the property /controls/flight/rudder as the input of the filter. The property will be initialized -at a value of zero and since the property usually is in the range [-1..+1], the the value of <input> will -be in the range (-1)*0.5+0.5 to (+1)*0.5+0.5 which is [0..1]. +Will use the property /controls/flight/rudder as the input of the filter. The +property will be initialized at a value of zero and since the property usually is +in the range [-1..+1], the the value of <input> will be in the range +(-1)*0.5+0.5 to (+1)*0.5+0.5 which is [0..1]. The default values for elements not given are: <value/> : 0.0 @@ -67,34 +69,38 @@ Some examples: <property>/position/altitude-ft</property> <scale>0.3048</scale> </input> -Gives the altitude in meters. No initialization of the property is performed, no offset applied. +Gives the altitude in meters. No initialization of the property is performed, no +offset applied. <reference> <value>0.0</value> </reference> A constant reference of zero. -A abbreviated method of defining values exist for using a just constant or a property. The above -example may be written as +A abbreviated method of defining values exist for using a just constant or a +property. The above example may be written as <reference>0.0</reference> Or if the reference is defined in a property <reference>/some/property/name</reference> No initialization, scaling or offsetting is performed here. -The logic behind this is: If the text node in the element (the text between the opening and closing tag) -can be converted to a double value, it will be interpreted as a double value. Otherwise the text will +The logic behind this is: If the text node in the element (the text between the +opening and closing tag) can be converted to a double value, it will be interpreted +as a double value. Otherwise the text will be interpreted as a property name. Examples: <reference>3.1415927</reference> - The constant of PI (roughly) <reference>/position/altitude-ft</reference> - The property /position/altitude-ft -<reference>3kings</reference> - The constant 3. The word kings is ignored +<reference>3kings</reference> - The constant 3. The word kings is + ignored <reference>food4less</reference> - The property food4less 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 +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 ) { @@ -105,7 +111,8 @@ if( condition ) { // compute value of last element } -Example: Set the gain to 3.0 if /autopilot/locks/heading equals dg-heading-hold or 2.0 otherwise. +Example: Set the gain to 3.0 if /autopilot/locks/heading equals dg-heading-hold or +2.0 otherwise. <digital-filter> <gain> <condition> @@ -122,18 +129,18 @@ Example: Set the gain to 3.0 if /autopilot/locks/heading equals dg-heading-hold <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. +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 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 -may be ommited. For backward compatibility, <property/> may be replaced by <prop/>. -Nonexisting properties will be created with type double. +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 may be ommited. For backward compatibility, <property/> may +be replaced by <prop/>. Non-existing properties will be created with type double. Example: (Multiple output properties) <output> @@ -151,9 +158,8 @@ Other Common Settings Example: <name>pressure rate filter</name> -<debug> Boolean If true, this filter puts out debug information when updated. -Example: -<debug>false</debug> +<debug> Boolean If true, this filter puts out debug information when + updated. Example: <debug>false</debug> <input> InputValue The input property driving the filter. Refer to InputValue for details. @@ -164,18 +170,21 @@ Example: <output> Complex Each filter can drive one to many output properties. Refer to OutputValue for details. -<u_min> InputValue This defines the optional minimum and maximum value the output -<u_max> is clamped to. If neither <u_min> nor <u_max> exists, the output - is only limited by the internal limit of double precision float computation. - 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 +<u_min> InputValue This defines the optional minimum and maximum value the +<u_max> output is clamped to. If neither <u_min> nor <u_max> + exists, the output is only limited by the internal limit + of double precision float computation. 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 +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 <u_max> <prop>/pilots/max-body-temperature-degc</prop> <value>40.0</ @@ -191,38 +200,41 @@ Implicit definition of the minimum value of 0 (zero) and defining a maximum of 1 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. +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 +always 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 - conditions is enabled. - Several way exist to define a condition. The most simple case - is checking a boolean property. For this, just a <prop> element - naming this boolean property is needed. The boolean value of the - named property defines the enabled state of the filter. - To compare the value of a property with a constant, a <prop> and - a <value> element define the property name and the value to be - compared. The filter is enabled, if the value of the property - equals the given value. A case sensitive string compare is +<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 conditions is enabled. + Several way exist to define a condition. The most simple + case is checking a boolean property. For this, just a + <prop> element naming this boolean property is needed. + The boolean value of the named property defines the + enabled state of the filter. To compare the value of a + property with a constant, a <prop> and a <value> element + define the property name and the value to be compared. + The filter is enabled, if the value of the property equals + the given value. A case sensitive string compare is performed here. - To define more complex conditions, a <condition> element may be - used to define any condition described in README.conditions. - If a <condition> element is present and if it contains a valid - condition, this conditions has precedence over a given <prop>/ - <value> condition. - The child element <honor-passive>, a boolean flag, may be present - within the <enable> element. If this element is true, the property - /autopilot/locks/passive-mode is checked and if it is true, the - filter output is computed, but the output properties are not set. - The default for honor-passive is false + To define more complex conditions, a <condition> element + may be used to define any condition described in + README.conditions. If a <condition> element is present + and if it contains a valid condition, this conditions has + precedence over a given <prop>/<value> condition. + The child element <honor-passive>, a boolean flag, may be + present within the <enable> element. If this element is + true, the property /autopilot/locks/passive-mode is checked + and if it is true, the filter output is computed, but the + output properties are not set. The default for + honor-passive is false Example: Check a boolean property, only compute this filter if gear-down is true and /autopilot/locks/passive-mode is false <enable> @@ -230,14 +242,15 @@ Example: Check a boolean property, only compute this filter if gear-down is true <honor-passive>true</honor-passive> </enable> -Check a property for equality, only compute this filter if the autopilot is locked in heading mode. +Check a property for equality, only compute this filter if the autopilot is locked +in heading mode. <enable> <prop>/autopilot/locks/heading</prop> <value>dg-heading-hold</value> </enable> -Use a complex condition, only compute this filter if the autopilot is serviceable and the lock -is either dg-heading-hold or nav1-heading-hold +Use a complex condition, only compute this filter if the autopilot is serviceable +and the lock is either dg-heading-hold or nav1-heading-hold <enable> <condition> <property>/autopilo/serviceable</property> @@ -279,25 +292,26 @@ To add a digital filter, place a <filter> element under the root element. Next t the global configuration elements described above, the following elements configure the digital filter: <filter-time> InputValue This tag is only applicable for the exponential and - double-exponential filter types. It controls the bandwidth - of the filter. The bandwidth in Hz of the filter is: - 1/filter-time. So a low-pass filter with a bandwidth of - 10Hz would have a filter time of 1/10 = 0.1 + double-exponential filter types. It controls the + bandwidth of the filter. The bandwidth in Hz of the + filter is: 1/filter-time. So a low-pass filter with a + bandwidth of 10Hz would have a filter time of 1/10 = 0.1 <samples> InputValue This tag only makes sense for the moving-average filter. It says how many past samples to average. <max-rate-of-change> InputValue This tag is applicable for the noise-spike filter. - It says how much the value is allowed to change per second. + It says how much the value is allowed to change per + second. -<gain> InputValue This is only applicable to the gain and reciprocal filter types. - The output for gain filter is computed as input*gain while - the reciprocal filter computes output as gain/input for input - values != 0 (zero). Gain may be a constant, a property name - defined by a <prop> element within the <gain> element or a - property name initialized to a value by using a <prop> and - <value> element. +<gain> InputValue This is only applicable to the gain and reciprocal filter + types. The output for gain filter is computed as input*gain + while the reciprocal filter computes output as gain/input + for input values != 0 (zero). Gain may be a constant, a + property name defined by a <prop> element within the <gain> + element or a property name initialized to a value by using + a <prop> and <value> element. Example: a pressure-rate-filter implemented as a double exponential low pass filter with a bandwith of 10Hz diff --git a/Docs/README.effects b/Docs/README.effects index b5efff910..2d965648c 100644 --- a/Docs/README.effects +++ b/Docs/README.effects @@ -35,19 +35,20 @@ and, or, equal, less, less-equal glversion - returns the version number of OpenGL extension-supported - returns true if an OpenGL extension is supported property - returns the boolean value of a property -float-property - returns the float value of a property, useful inside equal, less or less-equal nodes +float-property - returns the float value of a property, useful inside equal, less + or less-equal nodes shader-language - returns the version of GLSL supported, or 0 if there is none. The proper way to test whether to enable a shader-based technique is: - <predicate> - <and> - <property>/sim/rendering/shader-effects</property> - <less-equal> - <value type="float">1.0</value> - <shader-language/> - </less-equal> - </and> - </predicate> + <predicate> + <and> + <property>/sim/rendering/shader-effects</property> + <less-equal> + <value type="float">1.0</value> + <shader-language/> + </less-equal> + </and> + </predicate> There is also a property set by the user to indicate what is the level of quality desired. This level of quality can be checked in the predicate @@ -55,11 +56,11 @@ like this : <predicate> <and> <property>/sim/rendering/shader-effects</property> - <less-equal> - <value type="float">2.0</value> - <float-property>/sim/rendering/quality-level</float-property> - </less-equal> - <!-- other predicate conditions --> + <less-equal> + <value type="float">2.0</value> + <float-property>/sim/rendering/quality-level</float-property> + </less-equal> + <!-- other predicate conditions --> </and> </predicate> @@ -78,11 +79,11 @@ can be based on a parameter in the parameters section of the effect. For example, effects that support transparent and opaque geometry could have as part of a technique: - <blend> - <active><use>blend/active</use></active> - <source>src-alpha</source> - <destination>one-minus-src-alpha</destination> - </blend> + <blend> + <active><use>blend/active</use></active> + <source>src-alpha</source> + <destination>one-minus-src-alpha</destination> + </blend> So if the blend/active parameter is true blending will be activated using the usual blending equation; otherwise blending is disabled. @@ -92,90 +93,92 @@ Values of Technique Attributes Values are assigned to technique properties in several ways: - * They can appear directly in the techniques section as a - constant. For example: - <uniform> - <name>ColorsTex</name> - <type>sampler-1d</type> - <value type="int">2</value> - </uniform> - * The name of a property in the parameters section can be - referenced using a "use" clause. For example, in the technique - section: - <material> - <ambient><use>material/ambient</use></ambient> - </material> - Then, in the parameters section of the effect: - <parameters> - <material> - <ambient type="vec4d">0.2 0.2 0.2 1.0</ambient> - </material> - </parameters> + * They can appear directly in the techniques section as a + constant. For example: + <uniform> + <name>ColorsTex</name> + <type>sampler-1d</type> + <value type="int">2</value> + </uniform> + * The name of a property in the parameters section can be + referenced using a "use" clause. For example, in the technique + section: + <material> + <ambient><use>material/ambient</use></ambient> + </material> + Then, in the parameters section of the effect: + <parameters> + <material> + <ambient type="vec4d">0.2 0.2 0.2 1.0</ambient> + </material> + </parameters> - It's worth pointing out that the "material" property in a - technique specifies part of OpenGL's state, whereas "material" - in the parameters section is just a name, part of a - hierarchical namespace. + It's worth pointing out that the "material" property in a + technique specifies part of OpenGL's state, whereas "material" + in the parameters section is just a name, part of a + hierarchical namespace. - * A property in the parameters section doesn't need to contain - a constant value; it can also contain a "use" property. Here - the value of the use clause is the name of a node in an - external property tree which will be used as the source of a - value. If the name begins with '/', the node is in - FlightGear's global property tree; otherwise, it is in a local - property tree, usually belonging to a model [NOT IMPLEMENTED - YET]. For example: - <parameters> - <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light> - </parameters> - The type is determined by what is expected by the technique - attribute that will ultimately receive the value. [There is - no way to get vector values out of the main property system - yet; this will be fixed shortly.] Values that are declared - this way are dynamically updated if the property node - changes. + * A property in the parameters section doesn't need to contain + a constant value; it can also contain a "use" property. Here + the value of the use clause is the name of a node in an + external property tree which will be used as the source of a + value. If the name begins with '/', the node is in + FlightGear's global property tree; otherwise, it is in a local + property tree, usually belonging to a model [NOT IMPLEMENTED + YET]. For example: + <parameters> + <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light> + </parameters> + The type is determined by what is expected by the technique + attribute that will ultimately receive the value. [There is + no way to get vector values out of the main property system + yet; this will be fixed shortly.] Values that are declared + this way are dynamically updated if the property node + changes. OpenGL Attributes ----------------- The following attributes are currently implemented in techiques: alpha-test - children: active, comparison, reference - Valid values for comparision: - never, less, equal, lequal, greater, notequal, gequal, - always - + Valid values for comparision: + never, less, equal, lequal, greater, notequal, gequal, + always + alpha-to-coverage - true, false blend - children: active, source, destination, source-rgb, - source-alpha, destination-rgb, destination-alpha - Each operand can have the following values: - dst-alpha, dst-color, one, one-minus-dst-alpha, - one-minus-dst-color, one-minus-src-alpha, - one-minus-src-color, src-alpha, src-alpha-saturate, - src-color, constant-color, one-minus-constant-color, - constant-alpha, one-minus-constant-alpha, zero + source-alpha, destination-rgb, destination-alpha + Each operand can have the following values: + dst-alpha, dst-color, one, one-minus-dst-alpha, + one-minus-dst-color, one-minus-src-alpha, + one-minus-src-color, src-alpha, src-alpha-saturate, + src-color, constant-color, one-minus-constant-color, + constant-alpha, one-minus-constant-alpha, zero cull-face - front, back, front-back lighting - true, false material - children: active, ambient, ambient-front, ambient-back, diffuse, - diffuse-front, diffuse-back, specular, specular-front, - specular-back, emissive, emissive-front, emissive-back, shininess, - shininess-front, shininess-back, color-mode + diffuse-front, diffuse-back, specular, specular-front, + specular-back, emissive, emissive-front, emissive-back, shininess, + shininess-front, shininess-back, color-mode polygon-mode - children: front, back - Valid values: - fill, line, point + Valid values: + fill, line, point program - vertex-shader - geometry-shader - fragment-shader - attribute - geometry-vertices-out: integer, max number of vertices emitted by geometry shader - geometry-input-type - points, lines, lines-adjacency, triangles, triangles-adjacency - geometry-output-type - points, line-strip, triangle-strip + vertex-shader + geometry-shader + fragment-shader + attribute + geometry-vertices-out - integer, max number of vertices emitted by geometry + shader + geometry-input-type - points, lines, lines-adjacency, triangles, + triangles-adjacency + geometry-output-type - points, line-strip, triangle-strip render-bin - (OSG) children: bin-number, bin-name @@ -184,26 +187,26 @@ rendering-hint - (OSG) opaque, transparent shade-model - flat, smooth texture-unit - has several child properties: - unit - The number of an OpenGL texture unit - type - This is either an OpenGL texture type or the name of a - builtin texture. Currently supported OpenGL types are 1d, 2d, - 3d which have the following common parameters: - image (file name) - filter - mag-filter - wrap-s - wrap-t - wrap-r - The following built-in types are supported: - white - 1 pixel white texture - noise - a 3d noise texture - environment - mode - color + unit - The number of an OpenGL texture unit + type - This is either an OpenGL texture type or the name of a + builtin texture. Currently supported OpenGL types are 1d, 2d, + 3d which have the following common parameters: + image (file name) + filter + mag-filter + wrap-s + wrap-t + wrap-r + The following built-in types are supported: + white - 1 pixel white texture + noise - a 3d noise texture + environment + mode + color uniform - name - type - float, float-vec3, float-vec4, sampler-1d, sampler-2d, - sampler-3d + name + type - float, float-vec3, float-vec4, sampler-1d, sampler-2d, + sampler-3d vertex-program-two-side - true, false @@ -243,11 +246,11 @@ on the CPU and given to the shader as vertex attributes. These vectors are computed on demand on the geometry using the effect if the 'generate' clause is present in the effect file. Exemple : - <generate> - <tangent type="int">6</tangent> - <binormal type="int">7</binormal> - <normal type="int">8</normal> - </generate> + <generate> + <tangent type="int">6</tangent> + <binormal type="int">7</binormal> + <normal type="int">8</normal> + </generate> Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'. The integer value of these subnode is the index of the attribute @@ -258,17 +261,17 @@ The generate clause is located under PropertyList in the xml file. In order to be available for the vertex shader, these data should be bound to an attribute in the program clause, like this : - <program> - <vertex-shader>my_vertex_shader</vertex-shader> - <attribute> - <name>my_tangent_attribute</name> - <index>6</index> - </attribute> - <attribute> - <name>my_binormal_attribute</name> - <index>7</index> - </attribute> - </program> + <program> + <vertex-shader>my_vertex_shader</vertex-shader> + <attribute> + <name>my_tangent_attribute</name> + <index>6</index> + </attribute> + <attribute> + <name>my_binormal_attribute</name> + <index>7</index> + </attribute> + </program> attribute names are whatever the shader use. The index is the one declared in the 'generate' clause. So because generate/tangent has @@ -296,13 +299,13 @@ created for model effects than for terrain because there is more variation possible from the OSG model loaders than from the terrain system. The parameters created are: - * material active, ambient, diffuse, specular, emissive, - shininess, color mode - * blend active, source, destination - * shade-model - * cull-face - * rendering-hint - * texture type, image, filter, wrap-s, wrap-t + * material active, ambient, diffuse, specular, emissive, + shininess, color mode + * blend active, source, destination + * shade-model + * cull-face + * rendering-hint + * texture type, image, filter, wrap-s, wrap-t Specifying Custom Effects ------------------------- @@ -330,24 +333,25 @@ Application To apply an effect to a model or part of a model use: - <effect> - <inherits-from>Effects/light-cone</inherits-from> - <object-name>Cone</object-name> - </effect> + <effect> + <inherits-from>Effects/light-cone</inherits-from> + <object-name>Cone</object-name> + </effect> -where <inherits-from> </inherits-from> contains the path to the effect you want to apply. -The effect does not need the file extension. +where <inherits-from> </inherits-from> contains the path to the effect you want to +apply. The effect does not need the file extension. NOTE: -Chrome, although now implemented as an effect, still retains the old method of application: +Chrome, although now implemented as an effect, still retains the old method of +application: - <animation> - <type>shader</type> - <shader>chrome</shader> - <texture>glass_shader.png</texture> - <object-name>windscreen</object-name> - </animation> + <animation> + <type>shader</type> + <shader>chrome</shader> + <texture>glass_shader.png</texture> + <object-name>windscreen</object-name> + </animation> in order to maintain backward compatibility. diff --git a/Docs/README.flightrecorder b/Docs/README.flightrecorder index e8a40ebe1..549300a81 100644 --- a/Docs/README.flightrecorder +++ b/Docs/README.flightrecorder @@ -28,27 +28,28 @@ section to your aircraft -set.xml file. Example: - <sim> +<sim> - <!-- ... --> + <!-- ... --> - <flight-recorder> - <replay-config type="int">0</replay-config> - <config n="0" include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml"> - <name type="string">My Aircraft's Flight Recorder</name> - <!-- Custom properties --> - <signal> - <type>float</type> - <property type="string">/controls/gear/nosegear-steering-cmd-norm</property> - <interpolation>linear</interpolation> - </signal> - <!-- More custom signals here --> - </config> - </flight-recorder> + <flight-recorder> + <replay-config type="int">0</replay-config> + <config n="0" + include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml"> + <name type="string">My Aircraft's Flight Recorder</name> + <!-- Custom properties --> + <signal> + <type>float</type> + <property type="string">/controls/gear/nosegear-steering-cmd-norm</property> + <interpolation>linear</interpolation> + </signal> + <!-- More custom signals here --> + </config> + </flight-recorder> - <!-- ... --> + <!-- ... --> - </sim> +</sim> Default type for each signal is "float". Default "interpolation" method is "linear" (for float/double). Default values may be omitted. See @@ -176,36 +177,37 @@ need to match the actual type in the property tree!), the path to the property and interpolation type. Example recording some additional custom properties: - <sim> - <flight-recorder> - <config n="0" include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml"> - <!-- Add custom properties here --> - <signal> - <type>float</type> - <property type="string">/controls/gear/nosegear-steering-cmd-norm</property> - </signal> - <signal> - <type>double</type> - <interpolation>rotational-deg</interpolation> - <property type="string">/ai/model/carrier/alpha-angle-deg</property> - </signal> - <signal> - <type>bool</type> - <property type="string">/controls/panel/custom-switch</property> - </signal> - </config> - </flight-recorder> - </sim> + <sim> + <flight-recorder> + <config n="0" + include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml"> + <!-- Add custom properties here --> + <signal> + <type>float</type> + <property type="string">/controls/gear/nosegear-steering-cmd-norm</property> + </signal> + <signal> + <type>double</type> + <interpolation>rotational-deg</interpolation> + <property type="string">/ai/model/carrier/alpha-angle-deg</property> + </signal> + <signal> + <type>bool</type> + <property type="string">/controls/panel/custom-switch</property> + </signal> + </config> + </flight-recorder> + </sim> Signal Configuration -------------------- Template: - <signal> - <type>bool</type> - <interpolation>angular-deg</interpolation> - <property type="string">/controls/panel/custom-switch</property> - </signal> + <signal> + <type>bool</type> + <interpolation>angular-deg</interpolation> + <property type="string">/controls/panel/custom-switch</property> + </signal> * type: The signal's type specifies the recording resolution - not the type of the original property. The following types are supported: diff --git a/Docs/README.gui b/Docs/README.gui index ad0184943..bda4b94cc 100644 --- a/Docs/README.gui +++ b/Docs/README.gui @@ -499,9 +499,9 @@ property tree, like: <slider>15</slider> <!--width for slider --> <wrap>false</wrap> <!-- don't wrap text; default: true --> - <top-line>0</top-line <!-- show this line at the top; negative numbers: show last line --> + <top-line>0</top-line <!-- line to show at top, -ve numbers: show last line --> - <editable>true</editable> <!-- whether the puLargeInput is supposed to be editable --> + <editable>true</editable> <!-- if the puLargeInput is supposed to be editable --> </textbox> diff --git a/Docs/README.jsclient b/Docs/README.jsclient index 619588ae7..d2e606e54 100644 --- a/Docs/README.jsclient +++ b/Docs/README.jsclient @@ -1,12 +1,15 @@ Start flightgear with -fgfs --jsclient=socket,in,<hz>,,<port>,udp --prop:/jsclient/axis[i]="/property/you/want/to/control" --prop:/jsclient/axis[i+1]="/another/property/you/want/to/control" ... +fgfs --jsclient=socket,in,<hz>,,<port>,udp \ + --prop:/jsclient/axis[i]="/property/you/want/to/control" \ + --prop:/jsclient/axis[i+1]="/another/property/you/want/to/control" ... eg: -# fgfs --aircraft=yf23-yasim --airport=KEMT --jsclient=socket,in,5,,16759,udp --prop:/jsclient/axis[0]="/controls/flight/spoilers" --prop:/jsclient/axis[1]="/radios/comm/volume" - +# fgfs --aircraft=yf23-yasim --airport=KEMT --jsclient=socket,in,5,,16759,udp \ + --prop:/jsclient/axis[0]="/controls/flight/spoilers" \ + --prop:/jsclient/axis[1]="/radios/comm/volume" Start the server on the machine with the remote gameport: JsServer <host> <port> eg: # JsServer 192.168.1.1 16759 -(JsServer can be started before or after fgfs) \ No newline at end of file +(JsServer can be started before or after fgfs) diff --git a/Docs/README.materials b/Docs/README.materials index f6089b914..d4846d602 100644 --- a/Docs/README.materials +++ b/Docs/README.materials @@ -1,71 +1,72 @@ README.materials -This README describes the materials.xml file format. It is targeted at those +This README describes the materials.xml file format. It is targeted at those wanting to change the appearance of the scenery in FlightGear. As is the norm in FG, the materials.xml file is a properties file. However, it is only read on startup, is not part of the main property tree and cannot -be changed at runtime. +be changed at runtime. The properties file consists of a number of <material> entries, each of which -describes a single visually distinct terrain material in the FG world. +describes a single visually distinct terrain material in the FG world. The rest of this document describes the children tags of the <material> entry. -name : Scenery type names that map to this material. These are typically taken +name : Scenery type names that map to this material. These are typically taken from landclass definitions created by TerraGear. Multiple scenery types may map to a single material. This is recommended to minimize texture memory usage. - + condition : A condition statement used to activate the material. Note that this if evaluated once at start-up. - -texture : A relative path to an SGI RGB, PNG or DDS file containing a texture + +texture : A relative path to an SGI RGB, PNG or DDS file containing a texture for the material. RGB and PNG are recommended for platform compatibility. You may define more than one <texture> element, in which case the scenery - loader will choose one texture for each contiguous set of scenery + loader will choose one texture for each contiguous set of scenery triangles. texture-set : If using an effect (see below), it may be necessary to define more than one texture. The texture-set element has multiple <texture> element - children which may then be referenced by the effect. You may define more - than one <texture-set> element, in which case the scenery loader will + children which may then be referenced by the effect. You may define more + than one <texture-set> element, in which case the scenery loader will choose one texture for each contiguous set of scenery triangles. - -object-mask : An optional bitmap file used to control random placement of lights, + +object-mask : An optional bitmap file used to control random placement of lights, buildings and vegetation on the terrain. The green channel mask is used for random vegetation placement, the blue channel for buildings and lights. and the red channel controls the rotation of buildings (0.0 is North, 0.5 - is South). Fractional colour values can be used to give a probability of + is South). Fractional colour values can be used to give a probability of placement. Multiple object-masks may be defined to match up with <texture> or <texture-set> elements. - -effect : The effect to be used for this material. (default: + +effect : The effect to be used for this material. (default: Effects/terrain-default) ambient, diffuse, specular, emissive, and shininess are copied into the parameter section of the effect created for this material. -parameters : Additional parameters to be used in the effect. See README.effects for format information. +parameters : Additional parameters to be used in the effect. See README.effects + for format information. -wrapu : True if the texture should repeat horizontally over a surface, false if +wrapu : True if the texture should repeat horizontally over a surface, false if it should not repeat (default: true). -wrapv : True if the texture should repeat vertically over a surface, false if +wrapv : True if the texture should repeat vertically over a surface, false if it should not repeat (default: true). mipmap : True if the texture should be mipmapped, false otherwise. (default: true). xsize : The horizontal size of a single texture repetition, in meters. - + ysize : the vertical size of a single texture repetition, in meters light-coverage : The coverage of a single point of light in m^2. 0 indicates no lights at all. Minimum value is 1000m^2. May be masked by the blue channel of an object-mask. Lights are all generated 3m above the surface, and have random colour (50% yellow, 35% white, 10% orange, 5% red) - -ambient : The ambient light colour for the material, specified as separate + +ambient : The ambient light colour for the material, specified as separate r, g, b, a components (default: all color components 0.2, alpha 1.0). diffuse : The diffuse light colour for the material, specified as separate @@ -83,8 +84,8 @@ solid : Whether the surface is solid from an FDM perspective. If it is not friction-factor : The friction factor for that material. The normalized factor can be used by a FDM to post-multiply all contact friction forces - with that factor. That is the more slippery a material is the smaller this - value should be. (default: 1.0 for Dry concrete/Asphalt). + with that factor. That is the more slippery a material is the smaller + this value should be. (default: 1.0 for Dry concrete/Asphalt). rolling-friction : the gear rolling rolling-friction coefficient for this particular material. (default: 0.02 for Dry concrete/Asphalt). @@ -100,8 +101,8 @@ glyph : group that defines one letter/digit/symbol in a font texture sub-entries: name, left (default: 0.0), right (default: 1.0) (left and right describe the horizontal position in the texture.) -wood-coverage : The coverage of trees in areas marked as woodland in - m^2. A lower number means a higher density of trees. A value of +wood-coverage : The coverage of trees in areas marked as woodland in + m^2. A lower number means a higher density of trees. A value of 0 indicates no woods. May be masked by the green channel of an object-mask. (default: 0) @@ -116,31 +117,31 @@ tree-texture : A texture to use for the trees. Typically this will contain aroun * summer snow texture * winter texture * winter snow texture - + Each tree must have space at the top. For a 512x512 texture sheet, this - should be 8 pixels. Otherwise subsequent rendering results in "top hats" - above trees in the distance where the trunk of the tree above in the - textures sheet bleeds downwards when the mipmaps are generated. + should be 8 pixels. Otherwise subsequent rendering results in "top hats" + above trees in the distance where the trunk of the tree above in the + textures sheet bleeds downwards when the mipmaps are generated. tree-varieties : The number of different trees defined in the tree-texture horizontally. (default: 1) -tree-height-m : The average height of the trees. Actual tree height will +tree-height-m : The average height of the trees. Actual tree height will vary by +/- 50%. (default: 0) -tree-width-m : The average width of the tree cover. Actual tree width will +tree-width-m : The average width of the tree cover. Actual tree width will vary by +/- 50%. (default 0) - + tree-max-density-angle-deg : The slope angle at which trees begin to thin out - as the slope is too steep to support the full coverage. Shallower + as the slope is too steep to support the full coverage. Shallower slopes have maximum wood-coverage. Steeper slopes have fewer trees. (default : 45) - -tree-zero-density-angle-deg : The angle at which the slope is too steep to - support significant vegetation. Steeper slopes have no trees. + +tree-zero-density-angle-deg : The angle at which the slope is too steep to + support significant vegetation. Steeper slopes have no trees. (default : 60) -object-max-density-angle-deg : The angle at which objects and buildings become +object-max-density-angle-deg : The angle at which objects and buildings become less dense due to a steep slope. (default : 20) object-zero-density-angle-deg : The angle at which the slope is too steep to build @@ -149,100 +150,102 @@ object-zero-density-angle-deg : The angle at which the slope is too steep to bui object-group : A group of random objects to be placed on the surface. Contains <range-m> and one or more <object> children. - -range-m : The distance at which objects within this object-group become + +range-m : The distance at which objects within this object-group become visible. Note that for realism, 60% of the objects will become visible - at <range-m>, 30% at 1.5*<range-m>, and 10% at 2*<range-m>. + at <range-m>, 30% at 1.5*<range-m>, and 10% at 2*<range-m>. (default: 2000) - + object : A set of random objects to be placed. Contains <coverage-m2>, <path> and <heading> children. - + coverage-m2 : The coverage of a single object in m2. Lower values mean a higher density. Minimum value is 1000. - + spacing-m : The minimum space between this object and any other on the surface in meters. This helps to avoid objects being placed ontop of each other. (default 20) - -path : Path relative to FG_ROOT to a model definition, usually .ac or .xml file. + +path : Path relative to FG_ROOT to a model definition, usually .ac or .xml file. More than one <path> may be included within the <object> tag, in which case a single <path> is chosen at random for each individual object placement. -heading-type : Indicator of how the heading of the random objects should be - determined. Valid values are: +heading-type : Indicator of how the heading of the random objects should be + determined. Valid values are: fixed - Objects all point North. Default. random - Objects are assigned an individual random heading mask - Rotation is taken from the red channel of the object-mask billboard - Object is always rotated to face camera - expensive - - + + Random Buildings ================ -Random Buildings come in three sizes, with individual constraints. +Random Buildings come in three sizes, with individual constraints. -Small buildings. These have different textures on the sides compared to the front and back. -Small buildings are never deeper than they are wide. +Small buildings. These have different textures on the sides compared to the front +and back. Small buildings are never deeper than they are wide. Medium buildings, which are never taller than they are wide. Large buildings. There are no constraints on their width, depth or height. - -building-coverage : The coverage of random buildings in areas marked for random objects in - m^2. A lower number means a higher density of buildings. A value of - 0 indicates no buildings. May be masked by the blue channel of an - object-mask. (default: 0) - + +building-coverage : The coverage of random buildings in areas marked for random + objects in m^2. A lower number means a higher density of buildings. A + value of 0 indicates no buildings. May be masked by the blue channel of an + object-mask. (default: 0) + building-spacing-m : The minimum spacing between random buildings and other buildings - or random objects. This helps avoid objects being placed on top of each other. - (default: 5) - + or random objects. This helps avoid objects being placed on top of each + other. (default: 5) + building-small-ratio: Ratio of small buildings. These buildings are 1-3 stories in height, and may have a pitched roof. Fraction of small buildings is (<building-ratio-small> / (<building-ratio-small> + <building-ratio-medium> + <building-ratio-large>). (default: 0.8) - -building-medium-ratio : Ratio of medium buildings. These buildings are 3-6 stories in - height, and have a flat roof. (default: 0.15) - -building-large-ratio : Ratio of large buildings. These buildings are 5-10 stories in + +building-medium-ratio : Ratio of medium buildings. These buildings are 3-6 stories + in height, and have a flat roof. (default: 0.15) + +building-large-ratio : Ratio of large buildings. These buildings are 5-10 stories in height, and have a flat roof. (default 0.05) - + building-small-pitch : Fraction of small buildings with pitched roofs. (default 0.8) building-medium-pitch : Fraction of small buildings with pitched roofs. (default 0.2) building-large-pitch : Fraction of small buildings with pitched roofs. (default 0.1) -building-small-min-floors : Minimum number of floors for a small building. (default 1) -building-small-max-floors : Maximum number of floors for a small building. (default 3) +building-small-min-floors : Min. number of floors for a small building. (default 1) +building-small-max-floors : Max. number of floors for a small building. (default 3) -building-medium-min-floors : Minimum number of floors for a medium building. (default 3) -building-medium-max-floors : Maximum number of floors for a medium building. (default 8) +building-medium-min-floors : Min. number of floors for a medium building. (default 3) +building-medium-max-floors : Max. number of floors for a medium building. (default 8) -building-large-min-floors : Minimum number of floors for a medium building. (default 5) -building-large-max-floors : Maximum number of floors for a medium building. (default 20) +building-large-min-floors : Min. number of floors for a medium building. (default 5) +building-large-max-floors : Max. number of floors for a medium building. (default 20) -building-small-min-width-m : Minimum width of small buildings. (default 15) -building-small-max-width-m : Maximum width of small buildings. (default 60) -building-small-min-depth-m : Minimum depth of small buildings. (default 10) -building-small-max-depth-m : Maximum depty of small buildings. (default 20) +building-small-min-width-m : Min. width of small buildings. (default 15) +building-small-max-width-m : Max. width of small buildings. (default 60) +building-small-min-depth-m : Min. depth of small buildings. (default 10) +building-small-max-depth-m : Max. depth of small buildings. (default 20) -building-medium-min-width-m : Minimum width of medium buildings. (default 25) -building-medium-max-width-m : Maximum width of medium buildings. (default 50) -building-medium-min-depth-m : Minimum depth of medium buildings. (default 20) -building-medium-max-depth-m : Maximum depty of medium buildings. (default 50) +building-medium-min-width-m : Min. width of medium buildings. (default 25) +building-medium-max-width-m : Max. width of medium buildings. (default 50) +building-medium-min-depth-m : Min. depth of medium buildings. (default 20) +building-medium-max-depth-m : Max. depth of medium buildings. (default 50) -building-large-min-width-m : Minimum width of large buildings. (default 50) -building-large-max-width-m : Maximum width of large buildings. (default 75) -building-large-min-depth-m : Minimum depth of large buildings. (default 50) -building-large-max-depth-m : Maximum depty of large buildings. (default 75) +building-large-min-width-m : Min. width of large buildings. (default 50) +building-large-max-width-m : Max. width of large buildings. (default 75) +building-large-min-depth-m : Min. depth of large buildings. (default 50) +building-large-max-depth-m : Max. depth of large buildings. (default 75) -building-texture : The texture used for all buildings. See Docs/buildings.png for details. -(default Texture/buildings.png) +building-texture : The texture used for all buildings. See Docs/buildings.png for + details. (default Texture/buildings.png) -building-lightmap: Emissive texture for all buildings, which is faded in at night to provide -illusion of lit windows. Same texture coordinates and format at building-texture above. +building-lightmap: Emissive texture for all buildings, which is faded in at night to + provide illusion of lit windows. Same texture coordinates and + format at building-texture above. -building-range-m: Range at which all buildings are visible. Beyond this point fewer and fewer - buildings are rendered, with no buildings rendered at 2*building-range-m (default 10000) +building-range-m: Range at which all buildings are visible. Beyond this point fewer + and fewer buildings are rendered, with no buildings rendered at + 2*building-range-m (default 10000) diff --git a/Docs/README.multiplayer b/Docs/README.multiplayer index e65256f9e..8302727da 100644 --- a/Docs/README.multiplayer +++ b/Docs/README.multiplayer @@ -4,33 +4,33 @@ The commands are of the form: --callsign=a_unique_name -Below are some examples of startup commands that demonstrate the use of the +Below are some examples of startup commands that demonstrate the use of the multiplayer facilities. For two players on a local network or across the internet: ---------------------------------------------------------- Player1: ---multiplay=out,10,192.168.0.3,5500 --multiplay=in,10,192.168.0.2,5501 +--multiplay=out,10,192.168.0.3,5500 --multiplay=in,10,192.168.0.2,5501 --callsign=player1 Player2: ---multiplay=out,10,192.168.0.2,5501 --multiplay=in,10,192.168.0.3,5500 +--multiplay=out,10,192.168.0.2,5501 --multiplay=in,10,192.168.0.3,5500 --callsign=player2 For multiple players on a local network: ---------------------------------------- Player1: ---multiplay=out,10,255.255.255.255,5500 +--multiplay=out,10,255.255.255.255,5500 --multiplay=in,10,255.255.255.255,5500 --callsign=player1 Playern: ---multiplay=out,10,255.255.255.255,5500 +--multiplay=out,10,255.255.255.255,5500 --multiplay=in,10,255.255.255.255,5500 --callsign=playern -Note that the callsign is used to identify each player in a multiplayer game -so the callsigns must be unique. The multiplayer code ignores packets that -are sent back to itself, as would occur with broadcasting when the rx and tx +Note that the callsign is used to identify each player in a multiplayer game +so the callsigns must be unique. The multiplayer code ignores packets that +are sent back to itself, as would occur with broadcasting when the rx and tx ports are the same. @@ -48,9 +48,9 @@ Player3: Player4 (rx only): --multiplay=in,10,192.168.0.2,5500 --callsign=player4 -This demonstrates that it is possible to have multiple instances of -Flightgear that send to a single instance that displays all the traffic. This -is the sort of implementation that we are considering for use as a tower +This demonstrates that it is possible to have multiple instances of +Flightgear that send to a single instance that displays all the traffic. This +is the sort of implementation that we are considering for use as a tower visual simulator. @@ -120,6 +120,6 @@ control-fdm-atmosphere properties. Further reading (a must if you have a problem): ----------------------------------------------- [1] The flightgear server homepage <http://fgms.sourceforge.net/> -[2] The flightgear wiki multiplayer howto <http://wiki.flightgear.org/index.php/Howto:_Multiplayer> +[2] The wiki howto <http://wiki.flightgear.org/index.php/Howto:_Multiplayer> [3] If everything else fails, ask for help on the IRC channel #flightgear on irc.flightgear.org diff --git a/Docs/README.osgtext b/Docs/README.osgtext index d9ab3513c..0070d3708 100644 --- a/Docs/README.osgtext +++ b/Docs/README.osgtext @@ -1,103 +1,103 @@ This document describes the syntax for text objects in the scene graph. -Text nodes are configured using XML and may appear within a model description +Text nodes are configured using XML and may appear within a model description file, like other models or the particlesystem. For the anxious reader, here is a complete example of a text node: - <!-- Must be enclosed by a <text/> node - <text> - <!-- It should have a name. Can be used for other animations --> - <name>My first Text</name> - <!-- Use offsets for the initial placement --> - <offsets> - <pitch-deg>0</pitch-deg> - <heading-deg>0</heading-deg> - <roll-deg>0</roll-deg> - <x-m>0</x-m> - <y-m>0</y-m> - <z-m>0</z-m> - </offsets> +<!-- Must be enclosed by a <text/> node +<text> + <!-- It should have a name. Can be used for other animations --> + <name>My first Text</name> + <!-- Use offsets for the initial placement --> + <offsets> + <pitch-deg>0</pitch-deg> + <heading-deg>0</heading-deg> + <roll-deg>0</roll-deg> + <x-m>0</x-m> + <y-m>0</y-m> + <z-m>0</z-m> + </offsets> - <!-- instead of using pitch/heading/roll offset, one may use - axis-alignment --> - <!-- remember: x backwards, y right and z up --> - <axis-alignment>xy-plane</axis-alignment> - <!-- - <axis-alignment>reversed-xy-plane</axis-alignment> - <axis-alignment>xz-plane</axis-alignment> - <axis-alignment>reversed-xz-plane</axis-alignment> - <axis-alignment>yz-plane</axis-alignment> - <axis-alignment>reversed-yz-plane</axis-alignment> - <axis-alignment>screen</axis-alignment> - --> + <!-- instead of using pitch/heading/roll offset, one may use + axis-alignment --> + <!-- remember: x backwards, y right and z up --> + <axis-alignment>xy-plane</axis-alignment> + <!-- + <axis-alignment>reversed-xy-plane</axis-alignment> + <axis-alignment>xz-plane</axis-alignment> + <axis-alignment>reversed-xz-plane</axis-alignment> + <axis-alignment>yz-plane</axis-alignment> + <axis-alignment>reversed-yz-plane</axis-alignment> + <axis-alignment>screen</axis-alignment> + --> - <!-- what type of text to draw, use on of literal, text-value or number-value --> - <!-- A simple constant, never changing string --> - <type type="string">literal</type> - <text type="string">Hello, world!</text> + <!-- what type of text to draw, use on of literal, text-value or number-value --> + <!-- A simple constant, never changing string --> + <type type="string">literal</type> + <text type="string">Hello, world!</text> - <!-- The string value of a property --> - <type type="string">text-value</type> - <property type="string">some/property</property> - <format type="string">%s</format> <!-- the printf() format to display the value --> + <!-- The string value of a property --> + <type type="string">text-value</type> + <property type="string">some/property</property> + <format type="string">%s</format> <!-- the printf() format to display the value --> - <!-- A number from a property --> - <type type="string">number-value</type> - <property type="string">position/latitude-deg</property> - <factor type="double">1.0</factor> <!-- optional, used to scale the propertie's value --> - <offset type="double">0.0</offset> <!-- optional, used to shift the propertie's value --> - <format type="string">%5.2lf</format> <!-- the printf() format to display the value --> - <truncate type="bool">false</truncate> <!-- set to true to truncate to an integer value --> + <!-- A number from a property --> + <type type="string">number-value</type> + <property type="string">position/latitude-deg</property> + <factor type="double">1.0</factor> <!-- optional, scale the propertie's value --> + <offset type="double">0.0</offset> <!-- optional, shift the propertie's value --> + <format type="string">%5.2lf</format> <!-- printf() format to display --> + <truncate type="bool">false</truncate> <!-- truncate to an integer value --> - <layout>left-to-right</layout> <!-- default --> - <!-- - <layout>right-to-left</layout> - <layout>vertical</layout> - --> + <layout>left-to-right</layout> <!-- default --> + <!-- + <layout>right-to-left</layout> + <layout>vertical</layout> + --> - <draw-text type="bool">true</draw-text> <!-- draw the text itself --> - <draw-alignment type="bool">false</draw-alignment> <!-- draw a crosshair at the object center --> - <draw-boundingbox type="bool">false</draw-boundingbox> <!-- draw a bounding box --> + <draw-text type="bool">true</draw-text> <!-- draw the text itself --> + <draw-alignment type="bool">false</draw-alignment> <!-- draw crosshair at object center --> + <draw-boundingbox type="bool">false</draw-boundingbox> <!-- draw a bounding box --> - <font>led.txf</font> <!-- The font file name, relative to data/Fonts --> - <character-size type="double">0.01</character-size> <!-- size (height) im meters --> - <character-aspect-ratio type="double">1.0</character-aspect-ratio> - <max-height>0.012</max-height> <!-- the maximum height of the text --> - <max-width>0.040</max-width> <!-- the maximum width of the text --> - <font-resolution> - <width type="int">32</width> - <height type="int">32</height> - </font-resolution> + <font>led.txf</font> <!-- The font file name, relative to data/Fonts --> + <character-size type="double">0.01</character-size> <!-- size (height) im meters --> + <character-aspect-ratio type="double">1.0</character-aspect-ratio> + <max-height>0.012</max-height> <!-- the maximum height of the text --> + <max-width>0.040</max-width> <!-- the maximum width of the text --> + <font-resolution> + <width type="int">32</width> + <height type="int">32</height> + </font-resolution> - <!-- chose one of the kerning types or omit for default --> - <kerning>default</kerning> - <!-- - <kerning>unfitted</kerning> - <kerning>none</kerning> - --> + <!-- chose one of the kerning types or omit for default --> + <kerning>default</kerning> + <!-- + <kerning>unfitted</kerning> + <kerning>none</kerning> + --> - <alignment>center-center</alignment> <!-- alignment of the text itself --> - <!-- possible values are - <alignment>left-top</alignment> - <alignment>left-center</alignment> - <alignment>left-bottom</alignment> - <alignment>center-top</alignment> - <alignment>center-center</alignment> - <alignment>center-bottom</alignment> - <alignment>right-top</alignment> - <alignment>right-center</alignment> - <alignment>right-bottom</alignment> - <alignment>left-baseline</alignment> - <alignment>center-baseline</alignment> - <alignment>right-baseline</alignment> - <alignment>baseline</alignment> - --> + <alignment>center-center</alignment> <!-- alignment of the text itself --> + <!-- possible values are + <alignment>left-top</alignment> + <alignment>left-center</alignment> + <alignment>left-bottom</alignment> + <alignment>center-top</alignment> + <alignment>center-center</alignment> + <alignment>center-bottom</alignment> + <alignment>right-top</alignment> + <alignment>right-center</alignment> + <alignment>right-bottom</alignment> + <alignment>left-baseline</alignment> + <alignment>center-baseline</alignment> + <alignment>right-baseline</alignment> + <alignment>baseline</alignment> + --> - </text> +</text> -The <text/> node may appear within <model/> or <PropertyList/> nodes. If you place your text directly within -your model file, use <text></text> nodes. You can also put your <text> configuration into a separate file -using the well known include directive: +The <text/> node may appear within <model/> or <PropertyList/> nodes. If you place +your text directly within your model file, use <text></text> nodes. You can also put +your <text> configuration into a separate file using the well known include directive: Your model.xml file: <model> @@ -114,5 +114,6 @@ Your HelloWorld.xml: <!-- etc. - you get the idea --> </PropertyList> -Animation can be applied to text nodes like any other object. To give your text some color, use the material -animation, or translate, rotate, scale or spin your text as you like. +Animation can be applied to text nodes like any other object. To give your text some +color, use the material animation, or translate, rotate, scale or spin your text as +you like. diff --git a/Docs/README.scenery b/Docs/README.scenery index 40b6ba805..988616c1b 100644 --- a/Docs/README.scenery +++ b/Docs/README.scenery @@ -205,11 +205,11 @@ Example: Syntax: - OBJECT_SHARED <object-path> <longitude> <latitude> <elevation-m> <heading-deg> <pitch-deg> <roll-deg> + OBJECT_SHARED <object-path> <lon> <lat> <elev-m> <hdg-deg> <pitch-deg> <roll-deg> The <object-path> is relative to the data directory (FG_ROOT). -<elevation-m> is in meter and relative to mean sea-level (in the fgfs world). -<heading-deg> is in degree, counter-clockwise with North being 0.0. Note +<elev-m> is in meter and relative to mean sea-level (in the fgfs world). +<hdg-deg> is in degree, counter-clockwise with North being 0.0. Note that this differs from about every other place in FlightGear, most notably the /orientation/heading-deg entry in the property system, which is clockwise. <pitch-deg> and <roll-deg> are in degree and optional. diff --git a/Docs/README.sound b/Docs/README.sound index 9c6adbe09..ca22ac045 100644 --- a/Docs/README.sound +++ b/Docs/README.sound @@ -29,7 +29,7 @@ directly you can just add the following line to your ~/.openalrc file: (define speaker-num 4) -To add 4 channel surround sound to IRIX systems that have more than one +To add 4 channel surround sound to IRIX systems that have more than one stereo output you can add the following section to your ~/.openalrc file (for a typical O2 configuration): @@ -45,7 +45,7 @@ or alternatively: -(Note the following section is obsolete as of the July 2004 release of +(Note the following section is obsolete as of the July 2004 release of OpenAL, since your could command OpenAL to use ALSA or Arts directly) ALSA and Arts @@ -96,5 +96,7 @@ snd_page_alloc 11396 2 snd_intel8x0,snd_pcm snd_mpu401_uart 7936 1 snd_intel8x0 snd_rawmidi 24832 1 snd_mpu401_uart snd_seq_device 8324 1 snd_rawmidi -snd 53892 9 snd_pcm_oss,snd_mixer_oss,snd_intel8x0,snd_ac97_codec,snd_pcm,snd_timer,snd_mpu401_uart,snd_rawmidi,snd_seq_device -soundcore 10208 2 snd +snd 53892 9 snd_pcm_oss,snd_mixer_oss,snd_intel8x0, + snd_ac97_codec,snd_pcm,snd_timer,snd_mpu401_uart, + snd_rawmidi,snd_seq_device +soundcore 10208 2 snd diff --git a/Docs/README.submodels b/Docs/README.submodels index 4b447b670..b51c8be23 100644 --- a/Docs/README.submodels +++ b/Docs/README.submodels @@ -1,91 +1,117 @@ <?xml version="1.0"?> -<!-- Submodels are objects which can be dropped or launched from the user - aircraft. The trigger is a boolean property, which you define, which when - "true" causes the submodel to be released/launched. +<!-- - A submodel will create an AIBallistic object which will follow a ballistic - path. By default one submodel will be released when the corresponding - trigger is "true". - - Notes: - 1. This utility is intended for ballistic objects which align to the - trajectory. Drag is applied based on this assumption: no allowance is - for changes in drag for objects which do not conform to this asumption. - made - - 2. While Inertia is calculated properly, Moment of Inertia and rotational - aerodynamic damping are simulated. It is assumed that the object is a cylinder - of uniform density - if your object does not conform to this, there will be - inaccuracies. - - 3. The program does not calculate windage for ballistic objects well. While - adequate for smoke effects, etc., for bullets, bombs, droptanks this is probably - best left at "False". Since the effects of wind on various ballistic objects is - uncertain, there is no plan to change this situation. - - 4. Submodels can be ensted to any depth, thus a submodel on expiry or impact etc, - can launch a child submodel, which in turn can launch a submodel. and so on. This - is the basis for Persistent Contrails, but any use is possible. +Submodels are objects which can be dropped or launched from the user +aircraft. The trigger is a boolean property, which you define, which when +"true" causes the submodel to be released/launched. - The initial conditions (IC) define the object's starting point (relative - to the user aircraft's "reported position"), and its initial speed and - direction (relative to the user aircraft). If you want to release many - similar objects with similar IC, then you may use the <repeat>, <delay> - and <count> properties to define this. The allowed properties are: +A submodel will create an AIBallistic object which will follow a ballistic +path. By default one submodel will be released when the corresponding +trigger is "true". + +Notes: + 1. This utility is intended for ballistic objects which align to the + trajectory. Drag is applied based on this assumption: no allowance is + for changes in drag for objects which do not conform to this asumption. + made + + 2. While Inertia is calculated properly, Moment of Inertia and rotational + aerodynamic damping are simulated. It is assumed that the object is a cylinder + of uniform density - if your object does not conform to this, there will be + inaccuracies. + + 3. The program does not calculate windage for ballistic objects well. While + adequate for smoke effects, etc., for bullets, bombs, droptanks this is probably + best left at "False". Since the effects of wind on various ballistic objects is + uncertain, there is no plan to change this situation. + + 4. Submodels can be ensted to any depth, thus a submodel on expiry or impact etc, + can launch a child submodel, which in turn can launch a submodel. and so on. This + is the basis for Persistent Contrails, but any use is possible. + +The initial conditions (IC) define the object's starting point (relative +to the user aircraft's "reported position"), and its initial speed and +direction (relative to the user aircraft). If you want to release many +similar objects with similar IC, then you may use the <repeat>, <delay> +and <count> properties to define this. The allowed properties are: <name> The name of the submodel. <model> The path to the visual model. -<trigger> The property which will act as the trigger. If this tag is not included, the submodels will be released continuously, provided <count> is set to -1. +<trigger> The property which will act as the trigger. If this tag is not + included, the submodels will be released continuously, provided + <count> is set to -1. <speed> Initial speed, in feet/sec, relative to user aircraft. -<speed-prop> The property containing the Initial speed, in feet/sec, relative to user aircraft. If this path is found, <speed> will be overwritten. +<speed-prop> The property containing the Initial speed, in feet/sec, relative to + user aircraft. If this path is found, <speed> will be overwritten. <repeat> Set "true" if you want multiple releases of this submodel. <delay> Time, in seconds, between repeated releases. <count> Number of submodels available for multiple release. -1 defines an unlimited number. <slaved> If true, the submodel is slaved to the parent model. -<x-offset> Submodel's initial fore/aft position (in feet), relative to user aircraft. Fore is positive. -<y-offset> Submodel's initial left/right position (in feet), relative to user aircraft. Right is positive. -<z-offset> Submodel's initial up/down position (in feet), relative to user aircraft. Up is positive. +<x-offset> Submodel's initial fore/aft position (in feet), relative to user + aircraft. Fore is positive. +<y-offset> Submodel's initial left/right position (in feet), relative to user + aircraft. Right is positive. +<z-offset> Submodel's initial up/down position (in feet), relative to user + aircraft. Up is positive. <yaw-offset> Submodel's initial azimuth, in degrees, relative to user aircraft'snose. Right is positive. -<pitch-offset> Submodel's initial elevation, in degrees, relative to user aircraft's pitch. Up is positive. +<pitch-offset> Submodel's initial elevation, in degrees, relative to user aircraft's + pitch. Up is positive. <life> Life span in seconds. Default is 900.0. <buoyancy> In ft/sec/sec. Works opposite acceleration of gravity. - For example, if set to 32 the submodel will feel no + For example, if set to 32 the submodel will feel no gravity. If greater than 32 the object will rise. Default is 0. -<wind> Set to true if you want the submodel to react to the wind. Default is "false". -<cd> The Coeffient of Drag. Varies with submodel shape - 0.295 for a bullet, 0.045 for an airfoil. Enter an appropriate value. Defaults to 0.295. -<random> When this is true the Cd is varied by +- 5%. Useful for smoke or contrails. -<eda> Effective drag area (sq ft). Usually the cross-sectional area of the submodel normal to the airflow. -<weight> The weight of the submodel (lbs). NOT set to 0 on submodel release. You may wish to set this value to 0 by means of key bindings or Nasal script. - Defaults to 0.25. -<contents> The path to the contents of a submodel. The contents must be in lbs. Intended for use with drop tanks. The property value will be set to 0 on release of the submodel: do not also set to 0 elsewhere e.g. in key bindings. Defaults to 0. -<random> Varies CD by +- 10%, initial azimuth by +- 10 degs, and life by <randomness> -<randomness> If <random> is true, <randomness> is applied to <life>. 0 > Value < 1 are valid. - Defaults to 0.5. +<wind> Set to true if you want the submodel to react to the wind. Default + is "false". +<cd> The Coeffient of Drag. Varies with submodel shape - 0.295 for a + bullet, 0.045 for an airfoil. Enter an appropriate value. Defaults to + 0.295. +<random> When this is true the Cd is varied by +- 5%. Useful for smoke or + contrails. +<eda> Effective drag area (sq ft). Usually the cross-sectional area of the + submodel normal to the airflow. +<weight> The weight of the submodel (lbs). NOT set to 0 on submodel release. + You may wish to set this value to 0 by means of key bindings or Nasal + script. Defaults to 0.25. +<contents> The path to the contents of a submodel. The contents must be in lbs. + Intended for use with drop tanks. The property value will be set to + 0 on release of the submodel: do not also set to 0 elsewhere e.g. in + key bindings. Defaults to 0. +<random> Varies CD by +- 10%, initial azimuth by +- 10 degs, and life by + <randomness> +<randomness> If <random> is true, <randomness> is applied to <life>. 0 > Value < 1 + are valid. Defaults to 0.5. <no-roll> If true the submodel does not roll. -<impact> If true, the impact location (lat/lon) on the terrain is calculated. The Material - (e.g Grass)of the terrain, load resistance, and impact velocity. Altitude agl is calculated. -<collision> If true, collisions with other objects is tested. If a collision is detected then - the position data are written to the "Report Node". -<fuze-range> Used in detecting collisions. The distance in feet between an object and a submodel - at which a collision is deemed to have occurred. -<expiry> If true, the current position of the submodel is written to the "Report Node" when the submodel life expires. -<impact-reports> Defines a "Report Node". When an impact happens, then the path of the submodel will be written to this node. - An attached listener function can evaluate the impact properties. If unset, - reports go to /ai/models/model-impact. +<impact> If true, the impact location (lat/lon) on the terrain is calculated. + The Material (e.g Grass)of the terrain, load resistance, and impact + velocity. Altitude agl is calculated. +<collision> If true, collisions with other objects is tested. If a collision is + detected then the position data are written to the "Report Node". +<fuze-range> Used in detecting collisions. The distance in feet between an object + and a submodel at which a collision is deemed to have occurred. +<expiry> If true, the current position of the submodel is written to the + "Report Node" when the submodel life expires. +<impact-reports> Defines a "Report Node". When an impact happens, then the path of + the submodel will be written to this node. An attached listener + function can evaluate the impact properties. If unset, reports go to + /ai/models/model-impact. ***** experimental **** -<external-force> If true the submodel is subjected to an external force<force-path> A string describing the property where the magnitude, azimuth and elevation of the external force is to be found. The following child properties are instantiated: - ~/force-lb" - ~/force-azimuth-deg - ~/force-elevation-deg - -You will have to set these values by some means (Nasal script etc.) to make use of this utility +<external-force> If true the submodel is subjected to an external force +<force-path> A string describing the property where the magnitude, azimuth and + elevation of the external force are to be found. The following child + properties are instantiated: + ~/force-lb + ~/force-azimuth-deg + ~/force-elevation-deg + +You will have to set these values by some means (Nasal script etc.) to make use of this +utility. <PropertyList> @@ -120,8 +146,8 @@ You will have to set these values by some means (Nasal script etc.) to make use <pitch-offset>1.8</pitch-offset> <life>2.0</life> </submodel> - - <submodel> + + <submodel> <name>droptank-l</name> <model>Aircraft/Hunter/Models/droptank-100gal.ac</model> <trigger>controls/armament/station[0]/jettison-all</trigger> @@ -140,7 +166,7 @@ You will have to set these values by some means (Nasal script etc.) to make use <contents>consumables/fuel/tank[2]/level-lbs</contents> </submodel> - <submodel> + <submodel> <name>droptank-r</name> <model>Aircraft/Hunter/Models/droptank-100gal.ac</model> <trigger>controls/armament/station[1]/jettison-all</trigger> diff --git a/Docs/README.tutorials b/Docs/README.tutorials index 2fffa5794..2d17e02bb 100644 --- a/Docs/README.tutorials +++ b/Docs/README.tutorials @@ -19,11 +19,8 @@ around each tutorial. This is then included like so: <tutorials include="foo-tutorials.xml"/> </sim> - - - - - +Finally, tutorials are automatically generated from any valid checklists +on startup. See README.checklists for details. == TUTORIAL STRUCTURE ========================================================= @@ -33,114 +30,116 @@ A tutorial has this structure, where some of the elements are described in detail below: - <tutorial> - <name>...</name> mandatory; short identifier, also shown in the - tutorial selection dialog - <description>...</description> mandatory; longer description for the dialog - <audio-dir>...</audio-dir> optional; defines where to load sound samples - <timeofday>noon</timeofday> optional; defines daytime; any of "dawn", - "morning", "noon", "afternoon", - "evening", "dusk", "midnight", "real" - - <step-time> optional; period between each step being executed. Default 5 - <exit-time> optional; period between exit/abort conditions being checked. Default 1 - +<tutorial> + <name>...</name> mandatory; short identifier, also shown in the + tutorial selection dialog + <description>...</description> mandatory; longer description for the dialog + <audio-dir>...</audio-dir> optional; defines where to load sound samples + <timeofday>noon</timeofday> optional; defines daytime; any of "dawn", + "morning", "noon", "afternoon", + "evening", "dusk", "midnight", "real" + + <step-time> optional; period between each step being executed. + Default 5 + <exit-time> optional; period between exit/abort conditions being + checked. Default 1 + + <nasal> + ... optional; initial Nasal code; see below + </nasal> + + <models> + ... optional; scenery objects; see below + </models> + + <targets> + ... optional; targets; see below + </targets> + + <presets> + ... optional; initial simulator state; see below + </presets> + + + <init> optional; initial settings; see below + <set> + ... optional; property settings; allowed multiple + </set> times + <view> + ... optional; view settings + </view> + <marker> + ... optional; marker coordinates + </marker> + <nasal> + ... optional; Nasal code + </nasal> + </init> + + <step> mandatory; well, not really, but if there's not + at least one <step>, then the whole tutorial + won't do anything; see below for details + + <message>...</message> optional; message to be displayed/spoken when + <step> is entered; allowed multiple times, in + which case one is chosen at random + + <audio>...</audio> optional; file name of *.wav sample to be played; + may be used multiple times (random) + <set> + ... optional; allowed several times + </set> + <view> + ... optional + </view> + <marker> + ... optional + </marker> + <nasal> + ... optional; Nasal code that is executed when the + </nasal> step is entered + + <wait>10</wait> optional; wait period after initial messages etc. + + <error> optional; allowed several times + <message>..</message> optional; text displayed/spoken + <audio>...</audio> optional; name of *.wav sample to be played + + <condition> + ... optional, but one should be there to make sense + </condition> see $FG_ROOT/Docs/README.conditions + + <nasal> + ... optional; Nasal code that is executed when the + </nasal> error condition was fulfilled + </error> + + <exit> optional; defines when to leave this <step> + <condition> see $FG_ROOT/Docs/README.conditions + ... + </condition> + + <nasal> + ... optional; Nasal code that is executed when the + </nasal> exit condition was met + </exit> + </step> + + + <end> optional; final settings & actions; see below + <message>...</message> optional; multiple times (random) + <audio>...</audio> optional; multiple times (random) + <set> + ... optional + </set> + <view> + ... optional + </view> <nasal> - ... optional; initial Nasal code; see below + ... optional </nasal> - - <models> - ... optional; scenery objects; see below - </models> - - <targets> - ... optional; targets; see below - </targets> - - <presets> - ... optional; initial simulator state; see below - </presets> - - - <init> optional; initial settings; see below - <set> - ... optional; property settings; allowed multiple - </set> times - <view> - ... optional; view settings - </view> - <marker> - ... optional; marker coordinates - </marker> - <nasal> - ... optional; Nasal code - </nasal> - </init> - - <step> mandatory; well, not really, but if there's not - at least one <step>, then the whole tutorial - won't do anything; see below for details - - <message>...</message> optional; message to be displayed/spoken when - <step> is entered; allowed multiple times, in - which case one is chosen at random - - <audio>...</audio> optional; file name of *.wav sample to be played; - may be used multiple times (random) - <set> - ... optional; allowed several times - </set> - <view> - ... optional - </view> - <marker> - ... optional - </marker> - <nasal> - ... optional; Nasal code that is executed when the - </nasal> step is entered - - <wait>10</wait> optional; wait period after initial messages etc. - - <error> optional; allowed several times - <message>..</message> optional; text displayed/spoken - <audio>...</audio> optional; name of *.wav sample to be played - - <condition> - ... optional, but one should be there to make sense - </condition> see $FG_ROOT/Docs/README.conditions - - <nasal> - ... optional; Nasal code that is executed when the - </nasal> error condition was fulfilled - </error> - - <exit> optional; defines when to leave this <step> - <condition> see $FG_ROOT/Docs/README.conditions - ... - </condition> - - <nasal> - ... optional; Nasal code that is executed when the - </nasal> exit condition was met - </exit> - </step> - - - <end> optional; final settings & actions; see below - <message>...</message> optional; multiple times (random) - <audio>...</audio> optional; multiple times (random) - <set> - ... optional - </set> - <view> - ... optional - </view> - <nasal> - ... optional - </nasal> - </end> - </tutorial> + </end> +</tutorial> diff --git a/Docs/README.xmlhud b/Docs/README.xmlhud index 5d17c4ae2..edac8c4bc 100644 --- a/Docs/README.xmlhud +++ b/Docs/README.xmlhud @@ -117,21 +117,24 @@ We have a Base class - Hud Instrument Item. We derive two more base classes - Instrument Scale and Dual Instrument Item from this. (This implementation owes its existence to all those who wrote the HUD code for 0.6.1) -The Hud Instrument Label is an instantiable class derived from Hud Instrument Item - for -displaying alphanumeric labels (altitude, velocity, Mach no and/or anything else as long you -have a call back function to pass the value using the property 'data_source'). +The Hud Instrument Label is an instantiable class derived from Hud Instrument Item - +for displaying alphanumeric labels (altitude, velocity, Mach no and/or anything else +as long you have a call back function to pass the value using the property +'data_source'). The Hud Card is an instantiable class derived from Instrument scale - for displaying -tapes and gauges (single variable display, for displaying aoa, g's, vsi, elevator_posn, etc.). +tapes and gauges (single variable display, for displaying aoa, g's, vsi, +elevator_posn, etc.). -The Hud Ladder is an instantiable class derived from Dual Instrument Item - for displaying -pitch reference ladder or climb/dive ladder (two variable display, for displaying two types of -ladders, the pitch reference ladder or the climb/dive ladder as defined by MIL-1787b). +The Hud Ladder is an instantiable class derived from Dual Instrument Item - for +displaying pitch reference ladder or climb/dive ladder (two variable display, for +displaying two types of ladders, the pitch reference ladder or the climb/dive ladder +as defined by MIL-1787b). -The fgTBI Instrument is an instantiable class derived from Dual Instrument scale again -- for display of Bank angle and Sideslip (two variable display, for display of TSI info, kept -different from the two variable ladder object basically because of its totally different -draw member function). +The fgTBI Instrument is an instantiable class derived from Dual Instrument scale +again - for display of Bank angle and Sideslip (two variable display, for display +of TSI info, kept different from the two variable ladder object basically because +of its totally different draw member function). Most Hud instruments may be instantiated using above. It is proposed to provide all Hud objects as defined in MIL-STD-1797A, soon. @@ -146,9 +149,9 @@ y ------------ y+height this defines the objects position centered about the centroid of above rectangle in HUD overlay plane (640x480) coordinates with 0,0 at bottom-left corner. -One more, pixels per degree in the ladder class represents the compression factor of the -pitch ladder. In case of conformal HUD (climb/dive ladder) it is <640/horizontal_fov> -or <480/vertical_fov>. In case of pitch reference ladder it is +One more, pixels per degree in the ladder class represents the compression factor of +the pitch ladder. In case of conformal HUD (climb/dive ladder) it is +<640/horizontal_fov> or <480/vertical_fov>. In case of pitch reference ladder it is <your_no_of vertical_pixels/your_no_of_ladder_degrees>. Example of Hud Ladder xml file. @@ -164,8 +167,10 @@ Example of Hud Ladder xml file. <width>120</width> <!-- x start + width = x end --> <height>180</height> <!-- y start + height = y end --> <compression_factor>2.68</compression_factor> <!-- Pixels per degree --> - <loadfn>roll</loadfn> <!-- Name of the function to be called, here get_roll() is called provision made in Hud.cxx --> - <loadfn1>pitch</loadfn1> <!-- Name of the function to be called, here get_pitch() is called --> + <loadfn>roll</loadfn> <!-- Name of the function to be called, here + get_roll() is called provision made in Hud.cxx --> + <loadfn1>pitch</loadfn1> <!-- Name of the function to be called, here get_pitch() + is called --> <span_units>45.0</span_units> <!-- Range of the Ladder seen at any instant --> <division_units>10.0</division_units> <!-- Divisions --> <screen_hole>70</screen_hole> <!-- Hole b/w the Ladder Bars --> diff --git a/Docs/README.xmlpanel b/Docs/README.xmlpanel index 960dd2e63..2ca66a9bf 100644 --- a/Docs/README.xmlpanel +++ b/Docs/README.xmlpanel @@ -142,9 +142,11 @@ New Style Example Top Level Panel Config: <w>1024</w> <!-- virtual width --> <h>768</h> <!-- virtual height --> <y-offset>-305</y-offset> <!-- hides the bottom part --> - <view-height>172</view-height> <!-- amount of overlap between 2D panel and 3D viewport --> + <view-height>172</view-height> <!-- amount of overlap between 2D panel + and 3D viewport --> - <instruments> <!-- from here down is where old and new styles break compatibility --> + <instruments> <!-- from here down is where old and new + styles break compatibility --> <instrument include="../Instruments/clock.xml"> <name>Chronometer</name> <!-- currently optional but strongly recommended --> @@ -362,21 +364,21 @@ $FG_ROOT/Aircraft/c172/Instruments/brake.xml. <layer> <name>Brake light</name> - <type>switch</type> <!-- define layer as a switch --> - <property>/controls/brakes</property> <!-- tie it to a property --> - <layer1> <!-- layer for true state --> - <name>on</name> <!-- label to make life easy --> - <texture> <!-- layer1 of switch is a texture layer --> + <type>switch</type> <!-- define layer as a switch --> + <property>/controls/brakes</property> <!-- tie it to a property --> + <layer1> <!-- layer for true state --> + <name>on</name> <!-- label to make life easy --> + <texture> <!-- layer1 of switch is a texture layer --> <path>Aircraft/c172/Instruments/Textures/brake.rgb</path> <x1>0.25</x1> <y1>0.0</y1> <x2>0.5</x2> <y2>0.095</y2> </texture> - <w>64</w> <!-- required width - layer isn't static --> - <h>24</h> <!-- required height - layer isn't static --> - </layer1> <!-- close layer1 of switch --> - <layer2> <!-- layer for false state --> + <w>64</w> <!-- required width - layer isn't static --> + <h>24</h> <!-- required height - layer isn't static --> + </layer1> <!-- close layer1 of switch --> + <layer2> <!-- layer for false state --> <name>off</name> <texture> <path>Aircraft/c172/Instruments/Textures/brake.rgb</path> @@ -399,40 +401,40 @@ A text layer may be static, as in a label, generated from a property or a combination of both. This example is a switch that contains both static and dynamic text: - <layer1> <!-- switch layer --> - <name>display</name> - <type>text</type> <!-- type == text --> - <point-size>12</point-size> <!-- font size --> - <color> <!-- specify rgb values to color text --> - <red>1.0</red> - <green>0.5</green> - <blue>0.0</blue> - </color> <!-- close color section --> - <chunks> <!-- sections of text are referred to as chunks --> - <chunk> <!-- first chunk of text --> - <type>number-value</type> <!-- value defines it as dynamic --> - <property>/radios/nav1/dme/distance</property> <!-- ties it to a property --> - <scale>0.00053995680</scale> <!-- convert between statute and nautical miles? --> - <format>%5.1f</format> <!-- define format --> - </chunk> - </chunks> - </layer1> - <layer2> <!-- switch layer --> - <name>display</name> - <type>text</type> <!-- type == text --> - <point-size>10</point-size> <!-- font size --> - <color> <!-- specify rgb values to color text --> - <red>1.0</red> - <green>0.5</green> - <blue>0.0</blue> - </color> <!-- close color section --> - <chunks> <!-- sections of text are referred to as chunks --> - <chunk> <!-- first chunk of text --> - <type>literal</type> <!-- static text --> - <text>---.--</text> <!-- fixed value --> - </chunk> - </chunks> - </layer2> + <layer1> <!-- switch layer --> + <name>display</name> + <type>text</type> <!-- type == text --> + <point-size>12</point-size> <!-- font size --> + <color> <!-- specify rgb values to color text --> + <red>1.0</red> + <green>0.5</green> + <blue>0.0</blue> + </color> <!-- close color section --> + <chunks> <!-- sections of text are referred to as chunks --> + <chunk> <!-- first chunk of text --> + <type>number-value</type> <!-- value defines it as dynamic --> + <property>/radios/nav1/dme/distance</property> <!-- ties it to a property --> + <scale>0.00053995680</scale> <!-- convert between statute and nautical miles? --> + <format>%5.1f</format> <!-- define format --> + </chunk> + </chunks> + </layer1> + <layer2> <!-- switch layer --> + <name>display</name> + <type>text</type> <!-- type == text --> + <point-size>10</point-size> <!-- font size --> + <color> <!-- specify rgb values to color text --> + <red>1.0</red> + <green>0.5</green> + <blue>0.0</blue> + </color> <!-- close color section --> + <chunks> <!-- sections of text are referred to as chunks --> + <chunk> <!-- first chunk of text --> + <type>literal</type> <!-- static text --> + <text>---.--</text> <!-- fixed value --> + </chunk> + </chunks> + </layer2> Transformations: @@ -464,7 +466,7 @@ cropped texture. This example comes from the altimeter.xml <layer> - <name>long needle (hundreds)</name> <!-- the altimeter has more than one needle --> + <name>long needle (hundreds)</name> <!-- the altimeter has more than one needle --> <texture> <path>Aircraft/c172/Instruments/Textures/misc-1.rgb</path> <x1>0.8</x1> @@ -474,16 +476,17 @@ This example comes from the altimeter.xml </texture> <w>8</w> <h>56</h> - <transformations> <!-- begin defining transformations --> - <transformation> <!-- start definition of transformation that drives the needle --> + <transformations> <!-- begin defining transformations --> + <transformation> <!-- start definition of + transformation that drives the needle --> <type>rotation</type> - <property>/steam/altitude</property> <!-- bind it to a property --> - <max>100000.0</max> <!-- upper limit of instrument --> - <scale>0.36</scale> <!-- once around == 1000 ft --> - </transformation> <!-- close this transformation --> - <transformation> <!-- this one shifts the fulcrum of the needle --> - <type>y-shift</type> <!-- y-shift relative to needle --> - <offset>24.0</offset> <!-- amount of shift --> + <property>/steam/altitude</property> <!-- bind it to a property --> + <max>100000.0</max> <!-- upper limit of instrument --> + <scale>0.36</scale> <!-- once around == 1000 ft --> + </transformation> <!-- close this transformation --> + <transformation> <!-- shift the fulcrum of the needle --> + <type>y-shift</type> <!-- y-shift relative to needle --> + <offset>24.0</offset> <!-- amount of shift --> </transformation> </transformations> </layer> @@ -570,7 +573,7 @@ These examples come from the radio stack: <increment>-0.05</increment> <!-- amount of adjustment per mouse click --> <min>108.0</min> <!-- lower range --> <max>117.95</max> <!-- upper range --> - <wrap>1</wrap> <!-- boolean value -- value wraps around when it hits bounds --> + <wrap>1</wrap> <!-- value wraps around when it hits bounds --> </action> <action> <name>swap nav frequencies</name> @@ -580,8 +583,8 @@ These examples come from the radio stack: <y>-32</y> <w>32</w> <h>32</h> - <property1>/radios/nav1/frequencies/selected</property1> <!-- properties to toggle between --> - <property2>/radios/nav1/frequencies/standby</property2> + <property1>/radios/nav1/frequencies/selected</property1> <!-- properties to + <property2>/radios/nav1/frequencies/standby</property2> toggle between --> </action> <action> <name>ident volume on/off</name> @@ -591,11 +594,13 @@ These examples come from the radio stack: <y>-24</y> <w>16</w> <h>16</h> - <property>/radios/nav1/ident</property> <!-- this property is for Morse code identification of nav beacons --> - <increment>1.0</increment> <!-- the increment equals the max value so this toggles on/off --> + <property>/radios/nav1/ident</property> <!-- Morse code ID of nav beacons --> + <increment>1.0</increment> <!-- the increment equals the max value + so this toggles on/off --> <min>0</min> <max>1</max> - <wrap>1</wrap> <!-- a shortcut to avoid having separate actions for on/off --> + <wrap>1</wrap> <!-- a shortcut to avoid having separate + actions for on/off --> </action> </actions> @@ -635,7 +640,7 @@ How do I get my panels/instruments into the base package? ------------------------------------------------------- Cash bribes always help ;) Seriously though, there are two main considerations. Firstly, original artwork is a major plus since you -as the creator can dictate the terms of distribution.All Artwork must +as the creator can dictate the terms of distribution. All Artwork must have a license compatible with the GPL. Artwork of unverifiable origin is not acceptable. Secondly, texture sizes must meet the lowest common denominator of 256e2 pixels. Artwork from third parties diff --git a/Docs/README.xmlparticles b/Docs/README.xmlparticles index 88e2ef011..61f9c8a1f 100644 --- a/Docs/README.xmlparticles +++ b/Docs/README.xmlparticles @@ -2,7 +2,8 @@ Document started 27/01/2008 by Tiago Gusmão Updated 02/02/2008 to reflect syntax changes Updated 03/02/2008 to add trails (connected particles) -This is a short specification/tutorial to define particle systems in FlightGear using XML +This is a short specification/tutorial to define particle systems in +FlightGear using XML Meaningless example (what i had accumulated due to tests): @@ -56,16 +57,16 @@ Meaningless example (what i had accumulated due to tests): <z-max-deg-sec>0</z-max-deg-sec> </rotation-speed> </shooter> - + <counter> <particles-per-sec> <value>1</value> <spread>0</spread> </particles-per-sec> </counter> - + <align>billboard</align> - + <particle> <start> <color> @@ -132,10 +133,12 @@ Note: offset (result = (prop*factor)+offset ) in the usual way - <particlesystem> = the base tag - <type>string</type> can be "normal" or "trail", normal is the usual quad particles, trail is a string of connected line shapes by default. - <offsets> = this places the source of the particles (the emitter) in relation to the perhaps already offset model (see model-howto.html for details) + <type>string</type> = can be "normal" or "trail", normal is the usual quad + particles, trail is a string of connected line shapes + by default. + <offsets> = this places the source of the particles (the emitter) in relation + to the perhaps already offset model (see model-howto.html for details) <x-m>float</x-m> <y-m>float</y-m> <z-m>float</z-m> @@ -143,21 +146,30 @@ offset (result = (prop*factor)+offset ) in the usual way <roll-deg>float</roll-deg> <heading-deg>float</heading-deg> </offsets> - <condition> =a typical condition that if not true stops particles from being emitted (PPS=0) - .... + <condition> = a typical condition that if not true stops particles from being + .... emitted (PPS=0) </condition> - <name>string</name> = the name of the particle system (so it can be referenced by normal animations) - <attach>string</attach> = can be "world" or "local". "world means the particles aren't "physically linked" to the model (necessary for use outside moving models), "local" means the opposite (can be used for static objects or inside moving objects) + <name>string</name> = the name of the particle system (so it can be referenced + by normal animations) + <attach>string</attach> = can be "world" or "local". "world means the particles + aren't "physically linked" to the model (necessary for + use outside moving models), "local" means the opposite + (can be used for static objects or inside moving objects) <texture>string</texture> = the texture path relative to the XML file location <emissive>bool</emissive> = self-explanatory <lighting>bool</lighting> = yet to be tested, but seems obvious <align>string</align> = can be "billboard" or "fixed" <placer> = where particles are born - <type>string</type> = can be "sector" (inside a circle), "segments"(user-defined segments) and "point" (default) - *<radius-min-m>float</radius-min-m> = only for sector, inner radius at which particles appear - *<radius-max-m>float</radius-max-m> = only for sector, outer radius at which particles appear - *<phi-min-deg>float</phi-min-deg> = only for sector, starting angle of the slide at which particles appear - *<phi-max-deg>float</phi-max-deg> = only for sector, ending angle of the slide at which particles appear + <type>string</type> = can be "sector" (inside a circle), "segments"(user-defined + segments) and "point" (default) + *<radius-min-m>float</radius-min-m> = only for sector, inner radius at which + particles appear + *<radius-max-m>float</radius-max-m> = only for sector, outer radius at which + particles appear + *<phi-min-deg>float</phi-min-deg> = only for sector, starting angle of the + slide at which particles appear + *<phi-max-deg>float</phi-max-deg> = only for sector, ending angle of the slide + at which particles appear <segments> = only for segments, encloses sequential points that form segments <vertex> = specifies one point, put as many as you want <x-m>float</x-m> @@ -174,10 +186,12 @@ offset (result = (prop*factor)+offset ) in the usual way *<theta-min-deg>float</theta-min-deg> = horizontal angle limits of the particle cone *<theta-max-deg>float</theta-max-deg> *<phi-min-deg>float</phi-min-deg> = vertical angle limits of the particle cone - *<phi-max-deg>float</phi-max-deg> for an illustration of theta/phi see http://www.cs.clemson.edu/~malloy/courses/3dgames-2007/tutor/web/particles/particles.html + *<phi-max-deg>float</phi-max-deg> for an illustration of theta/phi see + http://www.cs.clemson.edu/~malloy/courses/3dgames-2007/tutor/web/particles/particles.html <speed-mps> = the scalar velocity (meter per second) <VALUEORPROP/> = see note - *<spread> the "tolerance" in each direction so values are in the range [value-spread, value+spread] + *<spread> = the "tolerance" in each direction so values are in the range + [value-spread, value+spread] </speed-mps> <rotation-speed> = the range of initial rotational speed of the particles *<x-min-deg-sec>float</x-min-deg-sec> @@ -191,7 +205,8 @@ offset (result = (prop*factor)+offset ) in the usual way <counter> <particles-per-sec> <VALUEORPROP/> = see note - *<spread> the "tolerance" in each direction so values are in the range [value-spread, value+spread] + *<spread> = the "tolerance" in each direction so values are in the range + [value-spread, value+spread] </particles-per-sec> </counter> <particle> = defines the particle properties @@ -220,23 +235,42 @@ offset (result = (prop*factor)+offset ) in the usual way *<life-sec> = the time the particles will be alive, in seconds <VALUEORPROP/> *</life-sec> - *<radius-m>float</radius-m> = each particles is physically treated as a sphere with this radius + *<radius-m>float</radius-m> = each particles is physically treated as a sphere + with this radius *<mass-kg>float</mass-kg> = mass in KG </particle> <program> = defines external forces acting upon a particle <fluid>string<fluid> = can be "air" or "water" <gravity>bool</gravity> = can be "true" or "false". uses standard gravity - <wind>bool</wind> = can be "true" or "false". uses user position wind (not the model position, but shouldn't be noticeable, you want to disabled it when using local attach) + <wind>bool</wind> = can be "true" or "false". uses user position wind (not the + model position, but shouldn't be noticeable, you want to + disabled it when using local attach) </program> </particles> Remarks: - Don't forget you can use existing animations with particles, so if you want to direct or translate the emitter, just use translate, rotate, spin and so on (other animations might have interesting effects too I guess) - Particle XML should be compatible with plib, as the tags will be ignored (you might get some warning if you attach them to animations though) - Try not to use a lot of particles in a way that fills the screen, that will demand lots of fill rate and hurt FPS - If you don't use any properties nor conditions, your particle system doesn't need to use a callback a so it's slightly better on the CPU (mostly useful for static models) - If your particle lifetime is too big you might run out of particles temporarily (still being investigated) - Use mass and size(radius) to adjust the reaction to gravity and wind (mass/size = density) - Although at the moment severe graphical bugs can be seen in the trails, they are usable. - Consider your options correctly! You should consider giving them no initial velocity and most important, no spread, otherwise particles will race and the trail will fold. Start simple (no velocities and forces) and work your way up. - +* Don't forget you can use existing animations with particles, so if you want to + direct or translate the emitter, just use translate, rotate, spin and so on + (other animations might have interesting effects too I guess) + +* Particle XML should be compatible with plib, as the tags will be ignored (you + might get some warning if you attach them to animations though) + +* Try not to use a lot of particles in a way that fills the screen, that will demand + lots of fill rate and hurt FPS + +* If you don't use any properties nor conditions, your particle system doesn't need + to use a callback a so it's slightly better on the CPU (mostly useful for static models) + +* If your particle lifetime is too big you might run out of particles temporarily + (still being investigated) + +* Use mass and size(radius) to adjust the reaction to gravity and wind + (mass/size = density) + +* Although at the moment severe graphical bugs can be seen in the trails, + they are usable. + +* Consider your options correctly! You should consider giving them no initial + velocity and most important, no spread, otherwise particles will race and the + trail will fold. Start simple (no velocities and forces) and work your way up. diff --git a/Docs/README.yasim b/Docs/README.yasim index d3a93d0d5..ac5f61bf4 100644 --- a/Docs/README.yasim +++ b/Docs/README.yasim @@ -370,9 +370,9 @@ gear: Defines a landing gear. Accepts <control> subelements to map are not active on runways. Defaults to "0". You can not exclude all gears in the solving process. -launchbar: Defines a catapult launchbar or strop. The default acceleration - provided by the catapult is 25m/s^2. This can be - modified by the use of the control axis LACCEL. +launchbar: Defines a catapult launchbar or strop. The default acceleration + provided by the catapult is 25m/s^2. This can be + modified by the use of the control axis LACCEL. x,y,z: The location of the mount point of the launch bar or strop on the aircraft. length: The length of the launch bar from mount point to tip @@ -464,7 +464,7 @@ control-input: INCIDENCE - The incidence angle of a wing. FLAP0 - The flap0 deflection of a wing. FLAP1 - The flap1 deflection of a wing. - FLAP[0/1]EFFECTIVENESS - a multiplier for flap lift, but not drag + FLAP[0/1]EFFECTIVENESS - a multiplier for flap lift, but not drag (useful for blown flaps) SLAT - The slat extension of a wing. SPOILER - The spoiler extension for a wing. @@ -473,7 +473,7 @@ control-input: COLLECTIVE - The collective input of a rotor ROTORENGINEON - If not equal zero the rotor is rotating WINCHRELSPEED - The relative winch speed - LACCEL - The acceleration provided by the catapult. + LACCEL - The acceleration provided by the catapult. {... and many more, see FGFDM.cpp ...} invert: Negate the value of the property before setting on the object. @@ -528,7 +528,7 @@ hitch: A hitch, can be used for winch-start (in gliders) or aerotow (in gliders and motor aircrafts) or for external cargo with helicopter. You can do aerotow over the net via multiplayer (see j3 and bocian as an example). - + name: the name of the hitch. must be aerotow if you want to do aerotow via multiplayer. You will find many properties at /sim/hitches/name. Most of them are directly tied to @@ -559,7 +559,7 @@ winch: The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag. max-tow-length: min-tow-length: - initial-tow-length: all are in m. The initial tow length also + initial-tow-length: all are in m. The initial tow length also defines the length/search radius used for the mp-autoconnect feature max-winch-speed: in m/s