CVS: source/docs-mini README.effects,1.3,1.4
Frederic Bouvier <[email protected]>
| Newsgroups | gmane.games.flightgear.cvc |
|---|---|
| Message-ID | <[email protected]> |
Update of /var/cvs/FlightGear-0.9/source/docs-mini In directory baron.flightgear.org:/tmp/cvs-serv20571 Modified Files: README.effects Log Message: Synchronize doc Index: README.effects =================================================================== RCS file: /var/cvs/FlightGear-0.9/source/docs-mini/README.effects,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- README.effects 22 Nov 2009 22:23:28 -0000 1.3 +++ README.effects 29 Mar 2010 07:33:46 -0000 1.4 @@ -38,15 +38,15 @@ shader-language - returns the version of GLSL supported, or 0 if there is none. The proper way to test whether to enable a shader-based technique is: - <predicate> - <and> - <property>/sim/rendering/shader-effects</property> - <less-equal> - <value type="float">1.0</value> - <shader-language/> - </less-equal> - </and> - </predicate> + <predicate> + <and> + <property>/sim/rendering/shader-effects</property> + <less-equal> + <value type="float">1.0</value> + <shader-language/> + </less-equal> + </and> + </predicate> A technique can consist of several passes. A pass is basically an Open @@ -60,11 +60,11 @@ effect. For example, effects that support transparent and opaque geometry could have as part of a technique: - <blend> - <active><use>blend/active</use></active> - <source>src-alpha</source> - <destination>one-minus-src-alpha</destination> - </blend> + <blend> + <active><use>blend/active</use></active> + <source>src-alpha</source> + <destination>one-minus-src-alpha</destination> + </blend> So if the blend/active parameter is true blending will be activated using the usual blending equation; otherwise blending is disabled. @@ -75,84 +75,87 @@ Values are assigned to technique properties in several ways: * They can appear directly in the techniques section as a - constant. For example: - <uniform> - <name>ColorsTex</name> - <type>sampler-1d</type> - <value type="int">2</value> - </uniform> - * The name of a property in the parameters section can be - referenced using a "use" clause. For example, in the technique - section: - <material> - <ambient><use>material/ambient</use></ambient> - </material> - Then, in the parameters section of the effect: - <parameters> - <material> - <ambient type="vec4d"> - 0.2 .2 0.2 1.0 - </ambient> - </material> - </parameters> - - It's worth pointing out that the "material" property in a - technique specifies part of OpenGL's state, whereas "material" - in the parameters section is just a name, part of a - hierarchical namespace. - - * A property in the parameters section doesn't need to contain - a constant value; it can also contain a "use" property. Here - the value of the use clause is the name of a node in an - external property tree which will be used as the source of a - value. If the name begins with '/', the node is in - FlightGear's global property tree; otherwise, it is in a local - property tree, usually belonging to a model [NOT IMPLEMENTED - YET]. For example: - <parameters> - <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light> - </parameters> - The type is determined by what is expected by the technique - attribute that will ultimately receive the value. [There is - no way to get vector values out of the main property system - yet; this will be fixed shortly.] Values that are declared - this way are dynamically updated if the property node - changes. + constant. For example: + <uniform> + <name>ColorsTex</name> + <type>sampler-1d</type> + <value type="int">2</value> + </uniform> + * The name of a property in the parameters section can be + referenced using a "use" clause. For example, in the technique + section: + <material> + <ambient><use>material/ambient</use></ambient> + </material> + Then, in the parameters section of the effect: + <parameters> + <material> + <ambient type="vec4d">0.2 0.2 0.2 1.0</ambient> + </material> + </parameters> + + It's worth pointing out that the "material" property in a + technique specifies part of OpenGL's state, whereas "material" + in the parameters section is just a name, part of a + hierarchical namespace. + + * A property in the parameters section doesn't need to contain + a constant value; it can also contain a "use" property. Here + the value of the use clause is the name of a node in an + external property tree which will be used as the source of a + value. If the name begins with '/', the node is in + FlightGear's global property tree; otherwise, it is in a local + property tree, usually belonging to a model [NOT IMPLEMENTED + YET]. For example: + <parameters> + <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light> + </parameters> + The type is determined by what is expected by the technique + attribute that will ultimately receive the value. [There is + no way to get vector values out of the main property system + yet; this will be fixed shortly.] Values that are declared + this way are dynamically updated if the property node + changes. OpenGL Attributes ----------------- The following attributes are currently implemented in techiques: alpha-test - children: active, comparison, reference - Valid values for comparision: - never, less, equal, lequal, greater, notequal, gequal, - always + Valid values for comparision: + never, less, equal, lequal, greater, notequal, gequal, + always blend - children: active, source, destination, source-rgb, - source-alpha, destination-rgb, destination-alpha - Each operand can have the following values: - dst-alpha, dst-color, one, one-minus-dst-alpha, - one-minus-dst-color, one-minus-src-alpha, - one-minus-src-color, src-alpha, src-alpha-saturate, - src-color, constant-color, one-minus-constant-color, - constant-alpha, one-minus-constant-alpha, zero + source-alpha, destination-rgb, destination-alpha + Each operand can have the following values: + dst-alpha, dst-color, one, one-minus-dst-alpha, + one-minus-dst-color, one-minus-src-alpha, + one-minus-src-color, src-alpha, src-alpha-saturate, + src-color, constant-color, one-minus-constant-color, + constant-alpha, one-minus-constant-alpha, zero cull-face - front, back, front-back lighting - true, false material - children: active, ambient, ambient-front, ambient-back, diffuse, - diffuse-front, diffuse-back, specular, specular-front, - specular-back, emissive, emissive-front, emissive-back, shininess, - shininess-front, shininess-back, color-mode + diffuse-front, diffuse-back, specular, specular-front, + specular-back, emissive, emissive-front, emissive-back, shininess, + shininess-front, shininess-back, color-mode polygon-mode - children: front, back - Valid values: - fill, line, point + Valid values: + fill, line, point program - vertex-shader - fragment-shader + vertex-shader + geometry-shader + fragment-shader + attribute + geometry-vertices-out: integer, max number of vertices emitted by geometry shader + geometry-input-type - points, lines, lines-adjacency, triangles, triangles-adjacency + geometry-output-type - points, line-strip, triangle-strip render-bin - (OSG) children: bin-number, bin-name @@ -162,25 +165,25 @@ texture-unit - has several child properties: unit - The number of an OpenGL texture unit - type - This is either an OpenGL texture type or the name of a - builtin texture. Currently supported OpenGL types are 1d, 2d, - 3d which have the following common parameters: + type - This is either an OpenGL texture type or the name of a + builtin texture. Currently supported OpenGL types are 1d, 2d, + 3d which have the following common parameters: image (file name) - filter - mag-filter - wrap-s - wrap-t - wrap-r - The following builtin types are supported: - white - 1 pixel white texture - noise - a 3d noise texture - environment - mode - color + filter + mag-filter + wrap-s + wrap-t + wrap-r + The following built-in types are supported: + white - 1 pixel white texture + noise - a 3d noise texture + environment + mode + color uniform - name - type - float, float-vec3, float-vec4, sampler-1d, sampler-2d, - sampler-3d + name + type - float, float-vec3, float-vec4, sampler-1d, sampler-2d, + sampler-3d vertex-program-two-side - true, false @@ -211,8 +214,49 @@ overrides any default values that might be in the base effect's parameters section. +Generate +-------- + +Often shader effects need tangent vectors to work properly. These +tangent vectors, usually called tangent and binormal, are computed +on the CPU and given to the shader as vertex attributes. These +vectors are computed on demand on the geometry using the effect if +the 'generate' clause is present in the effect file. Exemple : + + <generate> + <tangent type="int">6</tangent> + <binormal type="int">7</binormal> + <normal type="int">8</normal> + </generate> + +Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'. +The integer value of these subnode is the index of the attribute +that will hold the value of the vec3 vector. + +The generate clause is located under PropertyList in the xml file. + +In order to be available for the vertex shader, these data should +be bound to an attribute in the program clause, like this : + + <program> + <vertex-shader>my_vertex_shader</vertex-shader> + <attribute> + <name>my_tangent_attribute</name> + <index>6</index> + </attribute> + <attribute> + <name>my_binormal_attribute</name> + <index>7</index> + </attribute> + </program> + +attribute names are whatever the shader use. The index is the one +declared in the 'generate' clause. So because generate/tangent has +value 6 and my_tangent_attribute has index 6, my_tangent_attribute +holds the tangent value for the vertex. + Default Effects in Terrain Materials and Models ---------------------------------------- +----------------------------------------------- Effects for terrain work in this way: for each material type in materials.xml an effect is created that inherits from a single default @@ -233,12 +277,12 @@ system. The parameters created are: * material active, ambient, diffuse, specular, emissive, - shininess, color mode - * blend active, source, destination - * shade-model - * cull-face - * rendering-hint - * texture type, image, filter, wrap-s, wrap-t + shininess, color mode + * blend active, source, destination + * shade-model + * cull-face + * rendering-hint + * texture type, image, filter, wrap-s, wrap-t Specifying Custom Effects ------------------------- @@ -260,3 +304,30 @@ The Effects directory contains the effects definitions; look there for examples. Effects/crop.eff is a good example of a complex effect. + +Application +----------- + +To apply an effect to a model or part of a model use: + + <effect> + <inherits-from>Effects/light-cone</inherits-from> + <object-name>Cone</object-name> + </effect> + +where <inherits-from> </inherits-from> contains the path to the effect you want to apply. +The effect does not need the file extension. + +NOTE: + +Chrome, although now implemented as an effect, still retains the old method of application: + + <animation> + <type>shader</type> + <shader>chrome</shader> + <texture>glass_shader.png</texture> + <object-name>windscreen</object-name> + </animation> + +in order to maintain backward compatibility. + ------------------------------------------------------------------------------ Download Intel® Parallel Studio Eval Try the new software tools for yourself. Speed compiling, find bugs proactively, and fine-tune applications for parallel performance. See why Intel Parallel Studio got high marks during beta. http://p.sf.net/sfu/intel-sw-dev