fly/flightgear
1
0
Fork 0
Code Activity

Merge branch 'fred/effects-doc'

Browse source
This commit is contained in:
Tim Moore 2010-05-06 11:04:27 +02:00
commit 7f09aa4775
1 changed files with 181 additions and 92 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

271
docs-mini/README.effects
View file

@ -35,19 +35,37 @@ and, or, equal, less, less-equal
glversion - returns the version number of OpenGL glversion - returns the version number of OpenGL
extension-supported - returns true if an OpenGL extension is supported extension-supported - returns true if an OpenGL extension is supported
property - returns the boolean value of a property property - returns the boolean value of a property
float-property - returns the float value of a property, useful inside equal, less or less-equal nodes
shader-language - returns the version of GLSL supported, or 0 if there is none. 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: 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>
There is also a property set by the user to indicate what is the level
of quality desired. This level of quality can be checked in the predicate
like this :
<predicate> <predicate>
<and> <and>
<property>/sim/rendering/shader-effects</property> <property>/sim/rendering/shader-effects</property>
<less-equal> <less-equal>
<value type="float">1.0</value> <value type="float">2.0</value>
<shader-language/> <float-property>/sim/rendering/quality-level</float-property>
</less-equal> </less-equal>
<!-- other predicate conditions -->
</and> </and>
</predicate> </predicate>
The range of /sim/rendering/quality-level is [0..5]
* 2.0 is the threshold for relief mapping effects,
* 4.0 is the threshold for geometry shader usage.
A technique can consist of several passes. A pass is basically an Open A technique can consist of several passes. A pass is basically an Open
Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state
@ -60,11 +78,11 @@ can be based on a parameter in the parameters section of the
effect. For example, effects that support transparent and opaque effect. For example, effects that support transparent and opaque
geometry could have as part of a technique: geometry could have as part of a technique:
<blend> <blend>
<active><use>blend/active</use></active> <active><use>blend/active</use></active>
<source>src-alpha</source> <source>src-alpha</source>
<destination>one-minus-src-alpha</destination> <destination>one-minus-src-alpha</destination>
</blend> </blend>
So if the blend/active parameter is true blending will be activated So if the blend/active parameter is true blending will be activated
using the usual blending equation; otherwise blending is disabled. using the usual blending equation; otherwise blending is disabled.
@ -75,84 +93,87 @@ Values of Technique Attributes
Values are assigned to technique properties in several ways: Values are assigned to technique properties in several ways:
* They can appear directly in the techniques section as a * They can appear directly in the techniques section as a
constant. For example: constant. For example:
<uniform> <uniform>
<name>ColorsTex</name> <name>ColorsTex</name>
<type>sampler-1d</type> <type>sampler-1d</type>
<value type="int">2</value> <value type="int">2</value>
</uniform> </uniform>
* The name of a property in the parameters section can be * The name of a property in the parameters section can be
referenced using a "use" clause. For example, in the technique referenced using a "use" clause. For example, in the technique
section: section:
<material> <material>
<ambient><use>material/ambient</use></ambient> <ambient><use>material/ambient</use></ambient>
</material> </material>
Then, in the parameters section of the effect: Then, in the parameters section of the effect:
<parameters> <parameters>
<material> <material>
<ambient type="vec4d"> <ambient type="vec4d">0.2 0.2 0.2 1.0</ambient>
0.2 .2 0.2 1.0 </material>
</ambient> </parameters>
</material>
</parameters>
It's worth pointing out that the "material" property in a It's worth pointing out that the "material" property in a
technique specifies part of OpenGL's state, whereas "material" technique specifies part of OpenGL's state, whereas "material"
in the parameters section is just a name, part of a in the parameters section is just a name, part of a
hierarchical namespace. hierarchical namespace.
* A property in the parameters section doesn't need to contain * A property in the parameters section doesn't need to contain
a constant value; it can also contain a "use" property. Here 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 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 external property tree which will be used as the source of a
value. If the name begins with '/', the node is in value. If the name begins with '/', the node is in
FlightGear's global property tree; otherwise, it is in a local FlightGear's global property tree; otherwise, it is in a local
property tree, usually belonging to a model [NOT IMPLEMENTED property tree, usually belonging to a model [NOT IMPLEMENTED
YET]. For example: YET]. For example:
<parameters> <parameters>
<chrome-light><use>/rendering/scene/chrome-light</use></chrome-light> <chrome-light><use>/rendering/scene/chrome-light</use></chrome-light>
</parameters> </parameters>
The type is determined by what is expected by the technique The type is determined by what is expected by the technique
attribute that will ultimately receive the value. [There is attribute that will ultimately receive the value. [There is
no way to get vector values out of the main property system no way to get vector values out of the main property system
yet; this will be fixed shortly.] Values that are declared yet; this will be fixed shortly.] Values that are declared
this way are dynamically updated if the property node this way are dynamically updated if the property node
changes. changes.
OpenGL Attributes OpenGL Attributes
----------------- -----------------
The following attributes are currently implemented in techiques: The following attributes are currently implemented in techiques:
alpha-test - children: active, comparison, reference alpha-test - children: active, comparison, reference
Valid values for comparision: Valid values for comparision:
never, less, equal, lequal, greater, notequal, gequal, never, less, equal, lequal, greater, notequal, gequal,
always always
blend - children: active, source, destination, source-rgb, blend - children: active, source, destination, source-rgb,
source-alpha, destination-rgb, destination-alpha source-alpha, destination-rgb, destination-alpha
Each operand can have the following values: Each operand can have the following values:
dst-alpha, dst-color, one, one-minus-dst-alpha, dst-alpha, dst-color, one, one-minus-dst-alpha,
one-minus-dst-color, one-minus-src-alpha, one-minus-dst-color, one-minus-src-alpha,
one-minus-src-color, src-alpha, src-alpha-saturate, one-minus-src-color, src-alpha, src-alpha-saturate,
src-color, constant-color, one-minus-constant-color, src-color, constant-color, one-minus-constant-color,
constant-alpha, one-minus-constant-alpha, zero constant-alpha, one-minus-constant-alpha, zero
cull-face - front, back, front-back cull-face - front, back, front-back
lighting - true, false lighting - true, false
material - children: active, ambient, ambient-front, ambient-back, diffuse, material - children: active, ambient, ambient-front, ambient-back, diffuse,
diffuse-front, diffuse-back, specular, specular-front, diffuse-front, diffuse-back, specular, specular-front,
specular-back, emissive, emissive-front, emissive-back, shininess, specular-back, emissive, emissive-front, emissive-back, shininess,
shininess-front, shininess-back, color-mode shininess-front, shininess-back, color-mode
polygon-mode - children: front, back polygon-mode - children: front, back
Valid values: Valid values:
fill, line, point fill, line, point
program program
vertex-shader vertex-shader
fragment-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 render-bin - (OSG) children: bin-number, bin-name
@ -162,25 +183,25 @@ shade-model - flat, smooth
texture-unit - has several child properties: texture-unit - has several child properties:
unit - The number of an OpenGL texture unit unit - The number of an OpenGL texture unit
type - This is either an OpenGL texture type or the name of a type - This is either an OpenGL texture type or the name of a
builtin texture. Currently supported OpenGL types are 1d, 2d, builtin texture. Currently supported OpenGL types are 1d, 2d,
3d which have the following common parameters: 3d which have the following common parameters:
image (file name) image (file name)
filter filter
mag-filter mag-filter
wrap-s wrap-s
wrap-t wrap-t
wrap-r wrap-r
The following builtin types are supported: The following built-in types are supported:
white - 1 pixel white texture white - 1 pixel white texture
noise - a 3d noise texture noise - a 3d noise texture
environment environment
mode mode
color color
uniform uniform
name name
type - float, float-vec3, float-vec4, sampler-1d, sampler-2d, type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
sampler-3d sampler-3d
vertex-program-two-side - true, false vertex-program-two-side - true, false
@ -211,8 +232,49 @@ those parameters in its "techniques" section. The derived effect
overrides any default values that might be in the base effect's overrides any default values that might be in the base effect's
parameters section. 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 Default Effects in Terrain Materials and Models
--------------------------------------- -----------------------------------------------
Effects for terrain work in this way: for each material type in Effects for terrain work in this way: for each material type in
materials.xml an effect is created that inherits from a single default materials.xml an effect is created that inherits from a single default
@ -233,12 +295,12 @@ variation possible from the OSG model loaders than from the terrain
system. The parameters created are: system. The parameters created are:
* material active, ambient, diffuse, specular, emissive, * material active, ambient, diffuse, specular, emissive,
shininess, color mode shininess, color mode
* blend active, source, destination * blend active, source, destination
* shade-model * shade-model
* cull-face * cull-face
* rendering-hint * rendering-hint
* texture type, image, filter, wrap-s, wrap-t * texture type, image, filter, wrap-s, wrap-t
Specifying Custom Effects Specifying Custom Effects
------------------------- -------------------------
@ -260,3 +322,30 @@ Examples
The Effects directory contains the effects definitions; look there for The Effects directory contains the effects definitions; look there for
examples. Effects/crop.eff is a good example of a complex effect. 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.