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">
  94         0.2 .2 0.2 1.0
  95       </ambient>
  96     </material>
  97   </parameters>
  98
  99         It's worth pointing out that the "material" property in a
 100         technique specifies part of OpenGL's state, whereas "material"
 101         in the parameters section is just a name, part of a
 102         hierarchical namespace.
 103
 104         * A property in the parameters section doesn't need to contain
 105         a constant value; it can also contain a "use" property. Here
 106         the value of the use clause is the name of a node in an
 107         external property tree which will be used as the source of a
 108         value. If the name begins with '/', the node is in
 109         FlightGear's global property tree; otherwise, it is in a local
 110         property tree, usually belonging to a model [NOT IMPLEMENTED
 111         YET]. For example:
 112   <parameters>
 113     <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light>
 114   </parameters>
 115         The type is determined by what is expected by the technique
 116         attribute that will ultimately receive the value. [There is
 117         no way to get vector values out of the main property system
 118         yet; this will be fixed shortly.] Values that are declared
 119         this way are dynamically updated if the property node
 120         changes.
 121
 122 OpenGL Attributes
 123 -----------------
 124
 125 The following attributes are currently implemented in techiques:
 126 alpha-test - children: active, comparison, reference
 127          Valid values for comparision:
 128              never, less, equal, lequal, greater, notequal, gequal,
 129              always
 130
 131 blend - children: active, source, destination, source-rgb,
 132          source-alpha, destination-rgb, destination-alpha
 133          Each operand can have the following values:
 134              dst-alpha, dst-color, one, one-minus-dst-alpha,
 135              one-minus-dst-color, one-minus-src-alpha,
 136              one-minus-src-color, src-alpha, src-alpha-saturate,
 137              src-color, constant-color, one-minus-constant-color,
 138              constant-alpha, one-minus-constant-alpha, zero
 139
 140 cull-face - front, back, front-back
 141
 142 lighting - true, false
 143
 144 material - children: active, ambient, ambient-front, ambient-back, diffuse,
 145          diffuse-front, diffuse-back, specular, specular-front,
 146          specular-back, emissive, emissive-front, emissive-back, shininess,
 147          shininess-front, shininess-back, color-mode
 148
 149 polygon-mode - children: front, back
 150         Valid values:
 151               fill, line, point
 152
 153 program
 154         vertex-shader
 155         fragment-shader
 156
 157 render-bin - (OSG) children: bin-number, bin-name
 158
 159 rendering-hint - (OSG) opaque, transparent
 160
 161 shade-model - flat, smooth
 162
 163 texture-unit - has several child properties:
 164         unit - The number of an OpenGL texture unit
 165         type - This is either an OpenGL texture type or the name of a
 166         builtin texture. Currently supported OpenGL types are 1d, 2d,
 167         3d which have the following common parameters:
 168                 image (file name)
 169                 filter
 170                 mag-filter
 171                 wrap-s
 172                 wrap-t
 173                 wrap-r
 174         The following builtin types are supported:
 175                 white - 1 pixel white texture
 176                 noise - a 3d noise texture
 177         environment
 178                 mode
 179                 color
 180 uniform
 181         name
 182         type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
 183         sampler-3d
 184
 185 vertex-program-two-side - true, false
 186
 187 vertex-program-point-size - true, false
 188
 189 Inheritance
 190 -----------
 191
 192 One feature not fully illustrated in the sample below is that
 193 effects can inherit from each other. The parent effect is listed in
 194 the "inherits-from" form. The child effect's property tree is
 195 overlaid over that of the parent. Nodes that have the same name and
 196 property index -- set by the "n=" attribute in the property tag --
 197 are recursively merged. Leaf property nodes from the child have
 198 precedence.  This means that effects that inherit from the example
 199 effect below could be very short, listing just new
 200 parameters and adding nothing to the techniques section;
 201 alternatively, a technique could be altered or customized in a
 202 child, listing (for example) a different shader program. An example
 203 showing inheritance Effects/crop.eff, which inherits some if its
 204 values from Effects/terrain-default.eff.
 205
 206 FlightGear directly uses effects inheritance to assign effects to 3D
 207 models and terrain. As described below, at runtime small effects are
 208 created that contain material and texture values in a "parameters"
 209 section. These effects inherit from another effect which references
 210 those parameters in its "techniques" section. The derived effect
 211 overrides any default values that might be in the base effect's
 212 parameters section.
 213
 214 Default Effects in Terrain Materials and Models
 215 ---------------------------------------
 216
 217 Effects for terrain work in this way: for each material type in
 218 materials.xml an effect is created that inherits from a single default
 219 terrain effect, Effects/terrain-default.eff. The parameters section of
 220 the effect is filled in using the ambient, diffuse, specular,
 221 emissive, shininess, and transparent fields of the material. The
 222 parameters image, filter, wrap-s, and wrap-t are also initialized from
 223 the material xml. Seperate effects are created for each texture
 224 variant of a material.
 225
 226 Model effects are created by walking the OpenSceneGraph scene graph
 227 for a model and replacing nodes (osg::Geode) that have state sets with
 228 node that uses an effect instead. Again, a small effect is created
 229 with parameters extracted from OSG objects; this effect inherits, by
 230 default, from Effects/model-default.eff. A larger set of parameters is
 231 created for model effects than for terrain because there is more
 232 variation possible from the OSG model loaders than from the terrain
 233 system. The parameters created are:
 234
 235         * material active, ambient, diffuse, specular, emissive,
 236         shininess, color mode
 237         * blend active, source, destination
 238         * shade-model
 239         * cull-face
 240         * rendering-hint
 241         * texture type, image, filter, wrap-s, wrap-t
 242
 243 Specifying Custom Effects
 244 -------------------------
 245
 246 You can specify the effects that will be used by FlightGear as the
 247 base effect when it creates terrain and model effects.
 248
 249 In the terrain materials.xml, an "effect" property specifies the name
 250 of the model to use.
 251
 252 In model .xml files, A richer syntax is supported. [TO BE DETERMINED]
 253
 254 Material animations will be implemented by creating a new effect
 255 that inherits from one in a model, overriding the parameters that
 256 will be animated.
 257
 258 Examples
 259 --------
 260
 261 The Effects directory contains the effects definitions; look there for
 262 examples. Effects/crop.eff is a good example of a complex effect.