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                         mipmap-control - controls how the mipmap levels are computed.
 196                         Each color channel can be computed with different functions
 197                         among average, sum, product, min and max. For example :
 198                                         <function-r>average</function-r>
 199                                         <function-a>min</function-a>
 200                                 function-r - function for red
 201                                 function-g - function for green
 202                                 function-b - function for blue
 203                                 function-a - function for alpha
 204                 The following built-in types are supported:
 205                         white - 1 pixel white texture
 206                         noise - a 3d noise texture
 207                 environment
 208                         mode
 209                         color
 210 uniform
 211                 name
 212                 type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
 213                 sampler-3d
 214
 215 vertex-program-two-side - true, false
 216
 217 vertex-program-point-size - true, false
 218
 219 Inheritance
 220 -----------
 221
 222 One feature not fully illustrated in the sample below is that
 223 effects can inherit from each other. The parent effect is listed in
 224 the "inherits-from" form. The child effect's property tree is
 225 overlaid over that of the parent. Nodes that have the same name and
 226 property index -- set by the "n=" attribute in the property tag --
 227 are recursively merged. Leaf property nodes from the child have
 228 precedence.  This means that effects that inherit from the example
 229 effect below could be very short, listing just new
 230 parameters and adding nothing to the techniques section;
 231 alternatively, a technique could be altered or customized in a
 232 child, listing (for example) a different shader program. An example
 233 showing inheritance Effects/crop.eff, which inherits some if its
 234 values from Effects/terrain-default.eff.
 235
 236 FlightGear directly uses effects inheritance to assign effects to 3D
 237 models and terrain. As described below, at runtime small effects are
 238 created that contain material and texture values in a "parameters"
 239 section. These effects inherit from another effect which references
 240 those parameters in its "techniques" section. The derived effect
 241 overrides any default values that might be in the base effect's
 242 parameters section.
 243
 244 Generate
 245 --------
 246
 247 Often shader effects need tangent vectors to work properly. These
 248 tangent vectors, usually called tangent and binormal, are computed
 249 on the CPU and given to the shader as vertex attributes. These
 250 vectors are computed on demand on the geometry using the effect if
 251 the 'generate' clause is present in the effect file. Exemple :
 252
 253         <generate>
 254                 <tangent type="int">6</tangent>
 255                 <binormal type="int">7</binormal>
 256                 <normal type="int">8</normal>
 257         </generate>
 258
 259 Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'.
 260 The integer value of these subnode is the index of the attribute
 261 that will hold the value of the vec3 vector.
 262
 263 The generate clause is located under PropertyList in the xml file.
 264
 265 In order to be available for the vertex shader, these data should
 266 be bound to an attribute in the program clause, like this :
 267
 268         <program>
 269                 <vertex-shader>my_vertex_shader</vertex-shader>
 270                 <attribute>
 271                         <name>my_tangent_attribute</name>
 272                         <index>6</index>
 273                 </attribute>
 274                 <attribute>
 275                         <name>my_binormal_attribute</name>
 276                         <index>7</index>
 277                 </attribute>
 278         </program>
 279
 280 attribute names are whatever the shader use. The index is the one
 281 declared in the 'generate' clause. So because generate/tangent has
 282 value 6 and my_tangent_attribute has index 6, my_tangent_attribute
 283 holds the tangent value for the vertex.
 284
 285 Default Effects in Terrain Materials and Models
 286 -----------------------------------------------
 287
 288 Effects for terrain work in this way: for each material type in
 289 materials.xml an effect is created that inherits from a single default
 290 terrain effect, Effects/terrain-default.eff. The parameters section of
 291 the effect is filled in using the ambient, diffuse, specular,
 292 emissive, shininess, and transparent fields of the material. The
 293 parameters image, filter, wrap-s, and wrap-t are also initialized from
 294 the material xml. Seperate effects are created for each texture
 295 variant of a material.
 296
 297 Model effects are created by walking the OpenSceneGraph scene graph
 298 for a model and replacing nodes (osg::Geode) that have state sets with
 299 node that uses an effect instead. Again, a small effect is created
 300 with parameters extracted from OSG objects; this effect inherits, by
 301 default, from Effects/model-default.eff. A larger set of parameters is
 302 created for model effects than for terrain because there is more
 303 variation possible from the OSG model loaders than from the terrain
 304 system. The parameters created are:
 305
 306         * material active, ambient, diffuse, specular, emissive,
 307                 shininess, color mode
 308                 * blend active, source, destination
 309                 * shade-model
 310                 * cull-face
 311         * rendering-hint
 312         * texture type, image, filter, wrap-s, wrap-t
 313
 314 Specifying Custom Effects
 315 -------------------------
 316
 317 You can specify the effects that will be used by FlightGear as the
 318 base effect when it creates terrain and model effects.
 319
 320 In the terrain materials.xml, an "effect" property specifies the name
 321 of the model to use.
 322
 323 In model .xml files, A richer syntax is supported. [TO BE DETERMINED]
 324
 325 Material animations will be implemented by creating a new effect
 326 that inherits from one in a model, overriding the parameters that
 327 will be animated.
 328
 329 Examples
 330 --------
 331
 332 The Effects directory contains the effects definitions; look there for
 333 examples. Effects/crop.eff is a good example of a complex effect.
 334
 335 Application
 336 -----------
 337
 338 To apply an effect to a model or part of a model use:
 339
 340         <effect>
 341                 <inherits-from>Effects/light-cone</inherits-from>
 342                 <object-name>Cone</object-name>
 343         </effect>
 344
 345 where <inherits-from> </inherits-from> contains the path to the effect you want to apply.
 346 The effect does not need the file extension.
 347
 348 NOTE:
 349
 350 Chrome, although now implemented as an effect, still retains the old method of application:
 351
 352         <animation>
 353                         <type>shader</type>
 354                         <shader>chrome</shader>
 355                         <texture>glass_shader.png</texture>
 356                         <object-name>windscreen</object-name>
 357         </animation>
 358
 359 in order to maintain backward compatibility.
 360