1Effects 2------- 3 4Effects describe the graphical appearance of 3d objects and scenery in 5FlightGear. The main motivation for effects is to support OpenGL 6shaders and to provide different implementations for graphics hardware 7of varying capabilities. Effects are similar to DirectX effects files 8and Ogre3D material scripts. 9 10An effect is a property list. The property list syntax is extended 11with new "vec3d" and "vec4d" types to support common computer graphics 12values. Effects are read from files with a ".eff" extension or can be 13created 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, 16the graphical characteristics of objects that use the effect. Techniques 17refer to these parameters and use them to set OpenGL state or to set 18parameters for shader programs. The names of properties in the 19parameter section can be whatever the effects author chooses, although 20some standard parameters are set by FlightGear itself. On the other 21hand, the properties in the techniques section are all defined by the 22FlightGear. 23 24Techniques 25---------- 26 27A technique can contain a predicate that describes the OpenGL 28functionality required to support the technique. The first 29technique with a valid predicate in the list of techniques is used 30to set up the graphics state of the effect. A technique with no 31predicate is always assumed to be valid. The predicate is written in a 32little expression language that supports the following primitives: 33 34and, or, equal, less, less-equal 35glversion - returns the version number of OpenGL 36extension-supported - returns true if an OpenGL extension is supported 37property - returns the boolean value of a property 38float-property - returns the float value of a property, useful inside equal, less 39 or less-equal nodes 40shader-language - returns the version of GLSL supported, or 0 if there is none. 41 42The proper way to test whether to enable a shader-based technique is: 43 <predicate> 44 <and> 45 <property>/sim/rendering/shader-effects</property> 46 <less-equal> 47 <value type="float">1.0</value> 48 <shader-language/> 49 </less-equal> 50 </and> 51 </predicate> 52 53There is also a property set by the user to indicate what is the level 54of quality desired. This level of quality can be checked in the predicate 55like this : 56 <predicate> 57 <and> 58 <property>/sim/rendering/shader-effects</property> 59 <less-equal> 60 <value type="float">2.0</value> 61 <float-property>/sim/rendering/quality-level</float-property> 62 </less-equal> 63 <!-- other predicate conditions --> 64 </and> 65 </predicate> 66 67The range of /sim/rendering/quality-level is [0..5] 68 * 2.0 is the threshold for relief mapping effects, 69 * 4.0 is the threshold for geometry shader usage. 70 71A technique can consist of several passes. A pass is basically an Open 72Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state 73attributes will be accessable in techniques. State attributes -- that 74is, technique properties that have children and are not just boolean 75modes -- have an <active> parameter which enables or disables the 76attribute. In this way a technique can declare parameters it needs, 77but not enable the attribute at all if it is not needed; the decision 78can be based on a parameter in the parameters section of the 79effect. For example, effects that support transparent and opaque 80geometry could have as part of a technique: 81 82 <blend> 83 <active><use>blend/active</use></active> 84 <source>src-alpha</source> 85 <destination>one-minus-src-alpha</destination> 86 </blend> 87 88So if the blend/active parameter is true blending will be activated 89using the usual blending equation; otherwise blending is disabled. 90 91Values of Technique Attributes 92------------------------------ 93 94Values are assigned to technique properties in several ways: 95 96 * They can appear directly in the techniques section as a 97 constant. For example: 98 <uniform> 99 <name>ColorsTex</name> 100 <type>sampler-1d</type> 101 <value type="int">2</value> 102 </uniform> 103 * The name of a property in the parameters section can be 104 referenced using a "use" clause. For example, in the technique 105 section: 106 <material> 107 <ambient><use>material/ambient</use></ambient> 108 </material> 109 Then, in the parameters section of the effect: 110 <parameters> 111 <material> 112 <ambient type="vec4d">0.2 0.2 0.2 1.0</ambient> 113 </material> 114 </parameters> 115 116 It's worth pointing out that the "material" property in a 117 technique specifies part of OpenGL's state, whereas "material" 118 in the parameters section is just a name, part of a 119 hierarchical namespace. 120 121 * A property in the parameters section doesn't need to contain 122 a constant value; it can also contain a "use" property. Here 123 the value of the use clause is the name of a node in an 124 external property tree which will be used as the source of a 125 value. If the name begins with '/', the node is in 126 FlightGear's global property tree; otherwise, it is in a local 127 property tree, usually belonging to a model [NOT IMPLEMENTED 128 YET]. For example: 129 <parameters> 130 <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light> 131 </parameters> 132 The type is determined by what is expected by the technique 133 attribute that will ultimately receive the value. [There is 134 no way to get vector values out of the main property system 135 yet; this will be fixed shortly.] Values that are declared 136 this way are dynamically updated if the property node 137 changes. 138 139OpenGL Attributes 140----------------- 141 142The following attributes are currently implemented in techiques: 143alpha-test - children: active, comparison, reference 144 Valid values for comparision: 145 never, less, equal, lequal, greater, notequal, gequal, 146 always 147 148alpha-to-coverage - true, false 149 150blend - children: active, source, destination, source-rgb, 151 source-alpha, destination-rgb, destination-alpha 152 Each operand can have the following values: 153 dst-alpha, dst-color, one, one-minus-dst-alpha, 154 one-minus-dst-color, one-minus-src-alpha, 155 one-minus-src-color, src-alpha, src-alpha-saturate, 156 src-color, constant-color, one-minus-constant-color, 157 constant-alpha, one-minus-constant-alpha, zero 158 159cull-face - front, back, front-back 160 161lighting - true, false 162 163material - children: active, ambient, ambient-front, ambient-back, diffuse, 164 diffuse-front, diffuse-back, specular, specular-front, 165 specular-back, emissive, emissive-front, emissive-back, shininess, 166 shininess-front, shininess-back, color-mode 167 168polygon-mode - children: front, back 169 Valid values: 170 fill, line, point 171 172program 173 vertex-shader 174 geometry-shader 175 fragment-shader 176 attribute 177 geometry-vertices-out - integer, max number of vertices emitted by geometry 178 shader 179 geometry-input-type - points, lines, lines-adjacency, triangles, 180 triangles-adjacency 181 geometry-output-type - points, line-strip, triangle-strip 182 183render-bin - (OSG) children: bin-number, bin-name 184 185rendering-hint - (OSG) opaque, transparent 186 187shade-model - flat, smooth 188 189texture-unit - has several child properties: 190 unit - The number of an OpenGL texture unit 191 point-sprite - true, false - Whether this should rendered as a point-sprite 192 type - This is either an OpenGL texture type or the name of a 193 builtin texture. Currently supported OpenGL types are 1d, 2d, 194 3d which have the following common parameters: 195 image (file name) 196 filter - nearest, linear, [nearest|linear]-mipmap-[nearest|linear] 197 mag-filter - nearest, linear, [nearest|linear]-mipmap-[nearest|linear] 198 wrap-s - clamp, clamp-to-border, clamp-to-edge, mirror, repeat 199 wrap-t - clamp, clamp-to-border, clamp-to-edge, mirror, repeat 200 wrap-r - clamp, clamp-to-border, clamp-to-edge, mirror, repeat 201 mipmap-control - control the mipmap on a per-channel basis. Children: 202 function-r - auto, average, sum, product, min, max 203 function-g - auto, average, sum, product, min, max 204 function-b - auto, average, sum, product, min, max 205 function-a - auto, average, sum, product, min, max 206 207 The following built-in types are supported: 208 white - 1 pixel white texture 209 noise - a 3d noise texture. (size parameter defines size of texture) 210 light-sprite - a procedurally generated sprite suitable for point lights 211 cubemap - build a cube-map. Children: 212 images - build from 6 images. Children: [positive|negative]-[x|y|z] 213 image - build from a single cross-image 214 215 environment 216 mode - add, blend, decal, modulate, replace 217 color 218 219 texenv-combine 220 combine-[rgb|alpha] - replace, modulate, add, add-signed, interpolate, subtract, dot3-rgb, dot3-rgba 221 source[0|1|2]-[rgb|alpha] - constant, primary_color, previous, texture, texture[0-7] 222 operand[0|1|2]-[rgb|alpha] -src-color, one-minus-src-color, src-alpha, one-minus-src-alpha 223 scale-[rgb|alpha] 224 constant-color 225 226 texgen 227 mode - object-linear, eye-linear, sphere-map, normal-map, reflection-map 228 planes - s, t, r, q 229 230uniform 231 name 232 type - float, float-vec3, float-vec4, sampler-1d, sampler-2d, 233 sampler-3d 234 235vertex-program-two-side - true, false 236 237vertex-program-point-size - true, false 238 239Inheritance 240----------- 241 242One feature not fully illustrated in the sample below is that 243effects can inherit from each other. The parent effect is listed in 244the "inherits-from" form. The child effect's property tree is 245overlaid over that of the parent. Nodes that have the same name and 246property index -- set by the "n=" attribute in the property tag -- 247are recursively merged. Leaf property nodes from the child have 248precedence. This means that effects that inherit from the example 249effect below could be very short, listing just new 250parameters and adding nothing to the techniques section; 251alternatively, a technique could be altered or customized in a 252child, listing (for example) a different shader program. An example 253showing inheritance Effects/crop.eff, which inherits some if its 254values from Effects/terrain-default.eff. 255 256FlightGear directly uses effects inheritance to assign effects to 3D 257models and terrain. As described below, at runtime small effects are 258created that contain material and texture values in a "parameters" 259section. These effects inherit from another effect which references 260those parameters in its "techniques" section. The derived effect 261overrides any default values that might be in the base effect's 262parameters section. 263 264Generate 265-------- 266 267Often shader effects need tangent vectors to work properly. These 268tangent vectors, usually called tangent and binormal, are computed 269on the CPU and given to the shader as vertex attributes. These 270vectors are computed on demand on the geometry using the effect if 271the 'generate' clause is present in the effect file. Exemple : 272 273 <generate> 274 <tangent type="int">6</tangent> 275 <binormal type="int">7</binormal> 276 <normal type="int">8</normal> 277 </generate> 278 279Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'. 280The integer value of these subnode is the index of the attribute 281that will hold the value of the vec3 vector. 282 283The generate clause is located under PropertyList in the xml file. 284 285In order to be available for the vertex shader, these data should 286be bound to an attribute in the program clause, like this : 287 288 <program> 289 <vertex-shader>my_vertex_shader</vertex-shader> 290 <attribute> 291 <name>my_tangent_attribute</name> 292 <index>6</index> 293 </attribute> 294 <attribute> 295 <name>my_binormal_attribute</name> 296 <index>7</index> 297 </attribute> 298 </program> 299 300attribute names are whatever the shader use. The index is the one 301declared in the 'generate' clause. So because generate/tangent has 302value 6 and my_tangent_attribute has index 6, my_tangent_attribute 303holds the tangent value for the vertex. 304 305Default Effects in Terrain Materials and Models 306----------------------------------------------- 307 308Effects for terrain work in this way: for each material type in 309materials.xml an effect is created that inherits from a single default 310terrain effect, Effects/terrain-default.eff. The parameters section of 311the effect is filled in using the ambient, diffuse, specular, 312emissive, shininess, and transparent fields of the material. The 313parameters image, filter, wrap-s, and wrap-t are also initialized from 314the material xml. Seperate effects are created for each texture 315variant of a material. 316 317Model effects are created by walking the OpenSceneGraph scene graph 318for a model and replacing nodes (osg::Geode) that have state sets with 319node that uses an effect instead. Again, a small effect is created 320with parameters extracted from OSG objects; this effect inherits, by 321default, from Effects/model-default.eff. A larger set of parameters is 322created for model effects than for terrain because there is more 323variation possible from the OSG model loaders than from the terrain 324system. The parameters created are: 325 326 * material active, ambient, diffuse, specular, emissive, 327 shininess, color mode 328 * blend active, source, destination 329 * shade-model 330 * cull-face 331 * rendering-hint 332 * texture type, image, filter, wrap-s, wrap-t 333 334Specifying Custom Effects 335------------------------- 336 337You can specify the effects that will be used by FlightGear as the 338base effect when it creates terrain and model effects. 339 340In the terrain materials.xml, an "effect" property specifies the name 341of the model to use. 342 343In model .xml files, A richer syntax is supported. [TO BE DETERMINED] 344 345Material animations will be implemented by creating a new effect 346that inherits from one in a model, overriding the parameters that 347will be animated. 348 349Examples 350-------- 351 352The Effects directory contains the effects definitions; look there for 353examples. Effects/crop.eff is a good example of a complex effect. 354 355Application 356----------- 357 358To apply an effect to a model or part of a model use: 359 360 <effect> 361 <inherits-from>Effects/light-cone</inherits-from> 362 <object-name>Cone</object-name> 363 </effect> 364 365where <inherits-from> </inherits-from> contains the path to the effect you want to 366apply. The effect does not need the file extension. 367 368NOTE: 369 370Chrome, although now implemented as an effect, still retains the old method of 371application: 372 373 <animation> 374 <type>shader</type> 375 <shader>chrome</shader> 376 <texture>glass_shader.png</texture> 377 <object-name>windscreen</object-name> 378 </animation> 379 380in order to maintain backward compatibility. 381 382Model Hierarchy 383--------------- 384 385There are a large number of techniques used by the models, with complex 386inheritance. Here is a handy list of the techniques, what they are for, and 387where the base technique is defined 388 389Non-Compositor 390 391# Where Defined Summary 3924 model-combined.xml ALS, quality>0, model>0 3935 model-defaults.xml Base ALS 3947 model-combined-deferred.xml Rembrandt, model>0 3959 model-combined.xml quality>0, model>0 39610 model-defaults.xml Base Rembrandt 39711 model-defaults.xml Generic shaders, quality>0 39813 model-defaults.xml Fallback - no predicate 399 400 401Compositor 402 403# Where Defined Summary 4044 model-combined.xml quality>0, model>0 4057 model-combined.xml ALS, quality>0, model>0 4068 model-default.xml generic>0, quality>0 4079 model-default.xml Fallback - no predicate 40819 model-default.xml ALS, basic 409 410 411Scenery Hierarchy 412----------------- 413 414Compositor 415 416# Where defined Summary 4178 terrain-default.xml quality>0, generic>0 4189 terrain-default.xml Fallback - no predicate 41917 terrain-default.xml ALS, landmass=6, transition=6 42018 terrain-default.xml ALS, landmass>3, transition>2 42119 terrain-default.xml ALS, basic 422