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.
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
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:
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.
40 The proper way to test whether to enable a shader-based technique is:
43 <property>/sim/rendering/shader-effects</property>
45 <value type="float">1.0</value>
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:
64 <active><use>blend/active</use></active>
65 <source>src-alpha</source>
66 <destination>one-minus-src-alpha</destination>
69 So if the blend/active parameter is true blending will be activated
70 using the usual blending equation; otherwise blending is disabled.
72 Values of Technique Attributes
73 ------------------------------
75 Values are assigned to technique properties in several ways:
77 * They can appear directly in the techniques section as a
78 constant. For example:
80 <name>ColorsTex</name>
81 <type>sampler-1d</type>
82 <value type="int">2</value>
84 * The name of a property in the parameters section can be
85 referenced using a "use" clause. For example, in the technique
88 <ambient><use>material/ambient</use></ambient>
90 Then, in the parameters section of the effect:
93 <ambient type="vec4d">
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.
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
113 <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light>
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
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,
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
140 cull-face - front, back, front-back
142 lighting - true, false
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
149 polygon-mode - children: front, back
157 render-bin - (OSG) children: bin-number, bin-name
159 rendering-hint - (OSG) opaque, transparent
161 shade-model - flat, smooth
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:
174 The following builtin types are supported:
175 white - 1 pixel white texture
176 noise - a 3d noise texture
182 type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
185 vertex-program-two-side - true, false
187 vertex-program-point-size - true, false
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.
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
214 Default Effects in Terrain Materials and Models
215 ---------------------------------------
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.
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:
235 * material active, ambient, diffuse, specular, emissive,
236 shininess, color mode
237 * blend active, source, destination
241 * texture type, image, filter, wrap-s, wrap-t
243 Specifying Custom Effects
244 -------------------------
246 You can specify the effects that will be used by FlightGear as the
247 base effect when it creates terrain and model effects.
249 In the terrain materials.xml, an "effect" property specifies the name
252 In model .xml files, A richer syntax is supported. [TO BE DETERMINED]
254 Material animations will be implemented by creating a new effect
255 that inherits from one in a model, overriding the parameters that
261 The Effects directory contains the effects definitions; look there for
262 examples. Effects/crop.eff is a good example of a complex effect.