docs-mini/README.effects

   1 Effects
   2 -------
   3
   4 Effects describe the graphical appearance of 3d objects and scenery in
   5 FlightGear. The main motivation for effects is to support OpenGL
   6 shaders and to provide different implementations for graphics hardware
   7 of varying capabilities. Effects are similar to DirectX effects files
   8 and Ogre3D material scripts.
   9
  10 An effect is a property list. The property list syntax is extended
  11 with new "vec3d" and "vec4d" types to support common computer graphics
  12 values. Effects are read from files with a ".eff" extension or can be
  13 created on-the-fly by FlightGear at runtime.  An effect consists of a
  14 "parameters" section followed by "technique" descriptions.  The
  15 "parameters" section is a tree of values that describe, abstractly,
  16 the graphical characteristics of objects that use the effect. Techniques
  17 refer to these parameters and use them to set OpenGL state or to set
  18 parameters for shader programs. The names of properties in the
  19 parameter section can be whatever the effects author chooses, although
  20 some standard parameters  are set by FlightGear itself. On the other
  21 hand, the properties in the techniques section are all defined by the
  22 FlightGear.
  23
  24 Techniques
  25 ----------
  26
  27 A technique can contain a predicate that describes the OpenGL
  28 functionality required to support the technique. The first
  29 technique with a valid predicate in the list of techniques is used
  30 to set up the graphics state of the effect. A technique with no
  31 predicate is always assumed to be valid. The predicate is written in a
  32 little expression language that supports the following primitives:
  33
  34 and, or, equal, less, less-equal
  35 glversion - returns the version number of OpenGL
  36 extension-supported - returns true if an OpenGL extension is supported
  37 property - returns the boolean value of a property
  38 float-property - returns the float value of a property, useful inside equal, less or less-equal nodes
  39 shader-language - returns the version of GLSL supported, or 0 if there is none.
  40
  41 The proper way to test whether to enable a shader-based technique is:
  42         <predicate>
  43           <and>
  44                 <property>/sim/rendering/shader-effects</property>
  45                 <less-equal>
  46                   <value type="float">1.0</value>
  47                   <shader-language/>
  48                 </less-equal>
  49           </and>
  50         </predicate>
  51
  52 There is also a property set by the user to indicate what is the level
  53 of quality desired. This level of quality can be checked in the predicate
  54 like this :
  55     <predicate>
  56       <and>
  57         <property>/sim/rendering/shader-effects</property>
  58         <less-equal>
  59           <value type="float">2.0</value>
  60           <float-property>/sim/rendering/quality-level</float-property>
  61         </less-equal>
  62         <!-- other predicate conditions -->
  63       </and>
  64     </predicate>
  65
  66 The range of /sim/rendering/quality-level is [0..5]
  67  * 2.0 is the threshold for relief mapping effects,
  68  * 4.0 is the threshold for geometry shader usage.
  69
  70 A technique can consist of several passes. A pass is basically an Open
  71 Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state
  72 attributes  will be accessable in techniques. State attributes -- that
  73 is, technique properties that have children and are not just boolean
  74 modes -- have an <active> parameter which enables or disables the
  75 attribute. In this way a technique can declare parameters it needs,
  76 but not enable the attribute at all if it is not needed; the decision
  77 can be based on a parameter in the parameters section of the
  78 effect. For example, effects that support transparent and opaque
  79 geometry could have as part of a technique:
  80
  81           <blend>
  82                 <active><use>blend/active</use></active>
  83                 <source>src-alpha</source>
  84                 <destination>one-minus-src-alpha</destination>
  85           </blend>
  86
  87 So if the blend/active parameter is true blending will be activated
  88 using the usual blending equation; otherwise blending is disabled.
  89
  90 Values of Technique Attributes
  91 ------------------------------
  92
  93 Values are assigned to technique properties in several ways:
  94
  95         * They can appear directly in the techniques section as a
  96                 constant. For example:
  97                 <uniform>
  98                         <name>ColorsTex</name>
  99                         <type>sampler-1d</type>
 100                         <value type="int">2</value>
 101                 </uniform>
 102                 * The name of a property in the parameters section can be
 103                 referenced using a "use" clause. For example, in the technique
 104                 section:
 105                 <material>
 106                         <ambient><use>material/ambient</use></ambient>
 107                 </material>
 108                 Then, in the parameters section of the effect:
 109                 <parameters>
 110                         <material>
 111                                 <ambient type="vec4d">0.2 0.2 0.2 1.0</ambient>
 112                         </material>
 113                 </parameters>
 114
 115                 It's worth pointing out that the "material" property in a
 116                 technique specifies part of OpenGL's state, whereas "material"
 117                 in the parameters section is just a name, part of a
 118                 hierarchical namespace.
 119
 120                 * A property in the parameters section doesn't need to contain
 121                 a constant value; it can also contain a "use" property. Here
 122                 the value of the use clause is the name of a node in an
 123                 external property tree which will be used as the source of a
 124                 value. If the name begins with '/', the node is in
 125                 FlightGear's global property tree; otherwise, it is in a local
 126                 property tree, usually belonging to a model [NOT IMPLEMENTED
 127                 YET]. For example:
 128                 <parameters>
 129                         <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light>
 130                 </parameters>
 131                 The type is determined by what is expected by the technique
 132                 attribute that will ultimately receive the value. [There is
 133                 no way to get vector values out of the main property system
 134                 yet; this will be fixed shortly.] Values that are declared
 135                 this way are dynamically updated if the property node
 136                 changes.
 137
 138 OpenGL Attributes
 139 -----------------
 140
 141 The following attributes are currently implemented in techiques:
 142 alpha-test - children: active, comparison, reference
 143                  Valid values for comparision:
 144                          never, less, equal, lequal, greater, notequal, gequal,
 145                          always
 146
 147 blend - children: active, source, destination, source-rgb,
 148                  source-alpha, destination-rgb, destination-alpha
 149                  Each operand can have the following values:
 150                          dst-alpha, dst-color, one, one-minus-dst-alpha,
 151                          one-minus-dst-color, one-minus-src-alpha,
 152                          one-minus-src-color, src-alpha, src-alpha-saturate,
 153                          src-color, constant-color, one-minus-constant-color,
 154                          constant-alpha, one-minus-constant-alpha, zero
 155
 156 cull-face - front, back, front-back
 157
 158 lighting - true, false
 159
 160 material - children: active, ambient, ambient-front, ambient-back, diffuse,
 161                  diffuse-front, diffuse-back, specular, specular-front,
 162                  specular-back, emissive, emissive-front, emissive-back, shininess,
 163                  shininess-front, shininess-back, color-mode
 164
 165 polygon-mode - children: front, back
 166                 Valid values:
 167                           fill, line, point
 168
 169 program
 170                 vertex-shader
 171                 geometry-shader
 172                 fragment-shader
 173                 attribute
 174                 geometry-vertices-out: integer, max number of vertices emitted by geometry shader
 175                 geometry-input-type - points, lines, lines-adjacency, triangles, triangles-adjacency
 176                 geometry-output-type - points, line-strip, triangle-strip
 177
 178 render-bin - (OSG) children: bin-number, bin-name
 179
 180 rendering-hint - (OSG) opaque, transparent
 181
 182 shade-model - flat, smooth
 183
 184 texture-unit - has several child properties:
 185         unit - The number of an OpenGL texture unit
 186                 type - This is either an OpenGL texture type or the name of a
 187                 builtin texture. Currently supported OpenGL types are 1d, 2d,
 188                 3d which have the following common parameters:
 189                 image (file name)
 190                         filter
 191                         mag-filter
 192                         wrap-s
 193                         wrap-t
 194                         wrap-r
 195                 The following built-in types are supported:
 196                         white - 1 pixel white texture
 197                         noise - a 3d noise texture
 198                 environment
 199                         mode
 200                         color
 201 uniform
 202                 name
 203                 type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
 204                 sampler-3d
 205
 206 vertex-program-two-side - true, false
 207
 208 vertex-program-point-size - true, false
 209
 210 Inheritance
 211 -----------
 212
 213 One feature not fully illustrated in the sample below is that
 214 effects can inherit from each other. The parent effect is listed in
 215 the "inherits-from" form. The child effect's property tree is
 216 overlaid over that of the parent. Nodes that have the same name and
 217 property index -- set by the "n=" attribute in the property tag --
 218 are recursively merged. Leaf property nodes from the child have
 219 precedence.  This means that effects that inherit from the example
 220 effect below could be very short, listing just new
 221 parameters and adding nothing to the techniques section;
 222 alternatively, a technique could be altered or customized in a
 223 child, listing (for example) a different shader program. An example
 224 showing inheritance Effects/crop.eff, which inherits some if its
 225 values from Effects/terrain-default.eff.
 226
 227 FlightGear directly uses effects inheritance to assign effects to 3D
 228 models and terrain. As described below, at runtime small effects are
 229 created that contain material and texture values in a "parameters"
 230 section. These effects inherit from another effect which references
 231 those parameters in its "techniques" section. The derived effect
 232 overrides any default values that might be in the base effect's
 233 parameters section.
 234
 235 Generate
 236 --------
 237
 238 Often shader effects need tangent vectors to work properly. These
 239 tangent vectors, usually called tangent and binormal, are computed
 240 on the CPU and given to the shader as vertex attributes. These
 241 vectors are computed on demand on the geometry using the effect if
 242 the 'generate' clause is present in the effect file. Exemple :
 243
 244         <generate>
 245                 <tangent type="int">6</tangent>
 246                 <binormal type="int">7</binormal>
 247                 <normal type="int">8</normal>
 248         </generate>
 249
 250 Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'.
 251 The integer value of these subnode is the index of the attribute
 252 that will hold the value of the vec3 vector.
 253
 254 The generate clause is located under PropertyList in the xml file.
 255
 256 In order to be available for the vertex shader, these data should
 257 be bound to an attribute in the program clause, like this :
 258
 259         <program>
 260                 <vertex-shader>my_vertex_shader</vertex-shader>
 261                 <attribute>
 262                         <name>my_tangent_attribute</name>
 263                         <index>6</index>
 264                 </attribute>
 265                 <attribute>
 266                         <name>my_binormal_attribute</name>
 267                         <index>7</index>
 268                 </attribute>
 269         </program>
 270
 271 attribute names are whatever the shader use. The index is the one
 272 declared in the 'generate' clause. So because generate/tangent has
 273 value 6 and my_tangent_attribute has index 6, my_tangent_attribute
 274 holds the tangent value for the vertex.
 275
 276 Default Effects in Terrain Materials and Models
 277 -----------------------------------------------
 278
 279 Effects for terrain work in this way: for each material type in
 280 materials.xml an effect is created that inherits from a single default
 281 terrain effect, Effects/terrain-default.eff. The parameters section of
 282 the effect is filled in using the ambient, diffuse, specular,
 283 emissive, shininess, and transparent fields of the material. The
 284 parameters image, filter, wrap-s, and wrap-t are also initialized from
 285 the material xml. Seperate effects are created for each texture
 286 variant of a material.
 287
 288 Model effects are created by walking the OpenSceneGraph scene graph
 289 for a model and replacing nodes (osg::Geode) that have state sets with
 290 node that uses an effect instead. Again, a small effect is created
 291 with parameters extracted from OSG objects; this effect inherits, by
 292 default, from Effects/model-default.eff. A larger set of parameters is
 293 created for model effects than for terrain because there is more
 294 variation possible from the OSG model loaders than from the terrain
 295 system. The parameters created are:
 296
 297         * material active, ambient, diffuse, specular, emissive,
 298                 shininess, color mode
 299                 * blend active, source, destination
 300                 * shade-model
 301                 * cull-face
 302         * rendering-hint
 303         * texture type, image, filter, wrap-s, wrap-t
 304
 305 Specifying Custom Effects
 306 -------------------------
 307
 308 You can specify the effects that will be used by FlightGear as the
 309 base effect when it creates terrain and model effects.
 310
 311 In the terrain materials.xml, an "effect" property specifies the name
 312 of the model to use.
 313
 314 In model .xml files, A richer syntax is supported. [TO BE DETERMINED]
 315
 316 Material animations will be implemented by creating a new effect
 317 that inherits from one in a model, overriding the parameters that
 318 will be animated.
 319
 320 Examples
 321 --------
 322
 323 The Effects directory contains the effects definitions; look there for
 324 examples. Effects/crop.eff is a good example of a complex effect.
 325
 326 Application
 327 -----------
 328
 329 To apply an effect to a model or part of a model use:
 330
 331         <effect>
 332                 <inherits-from>Effects/light-cone</inherits-from>
 333                 <object-name>Cone</object-name>
 334         </effect>
 335
 336 where <inherits-from> </inherits-from> contains the path to the effect you want to apply.
 337 The effect does not need the file extension.
 338
 339 NOTE:
 340
 341 Chrome, although now implemented as an effect, still retains the old method of application:
 342
 343         <animation>
 344                         <type>shader</type>
 345                         <shader>chrome</shader>
 346                         <texture>glass_shader.png</texture>
 347                         <object-name>windscreen</object-name>
 348         </animation>
 349
 350 in order to maintain backward compatibility.
 351