]> git.mxchange.org Git - flightgear.git/blob - docs-mini/README.effects
Fix merge noise
[flightgear.git] / 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