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