Fix line endings
This commit is contained in:
fredb
parent
8b4341f510
commit
4ddd8a8934
1 changed files with 287 additions and 292 deletions
|
|
@ -1,292 +1,287 @@
|
||||||
Effects
|
Effects
|
||||||
-------
|
-------
|
||||||
|
|
||||||
Effects describe the graphical appearance of 3d objects and scenery in
|
Effects describe the graphical appearance of 3d objects and scenery in
|
||||||
FlightGear. The main motivation for effects is to support OpenGL
|
FlightGear. The main motivation for effects is to support OpenGL
|
||||||
shaders and to provide different implementations for graphics hardware
|
shaders and to provide different implementations for graphics hardware
|
||||||
of varying capabilities. Effects are similar to DirectX effects files
|
of varying capabilities. Effects are similar to DirectX effects files
|
||||||
and Ogre3D material scripts.
|
and Ogre3D material scripts.
|
||||||
|
|
||||||
An effect is a property list. The property list syntax is extended
|
An effect is a property list. The property list syntax is extended
|
||||||
with new "vec3d" and "vec4d" types to support common computer graphics
|
with new "vec3d" and "vec4d" types to support common computer graphics
|
||||||
values. Effects are read from files with a ".eff" extension or can be
|
values. Effects are read from files with a ".eff" extension or can be
|
||||||
created on-the-fly by FlightGear at runtime. An effect consists of a
|
created on-the-fly by FlightGear at runtime. An effect consists of a
|
||||||
"parameters" section followed by "technique" descriptions. The
|
"parameters" section followed by "technique" descriptions. The
|
||||||
"parameters" section is a tree of values that describe, abstractly,
|
"parameters" section is a tree of values that describe, abstractly,
|
||||||
the graphical characteristics of objects that use the effect. Techniques
|
the graphical characteristics of objects that use the effect. Techniques
|
||||||
refer to these parameters and use them to set OpenGL state or to set
|
refer to these parameters and use them to set OpenGL state or to set
|
||||||
parameters for shader programs. The names of properties in the
|
parameters for shader programs. The names of properties in the
|
||||||
parameter section can be whatever the effects author chooses, although
|
parameter section can be whatever the effects author chooses, although
|
||||||
some standard parameters are set by FlightGear itself. On the other
|
some standard parameters are set by FlightGear itself. On the other
|
||||||
hand, the properties in the techniques section are all defined by the
|
hand, the properties in the techniques section are all defined by the
|
||||||
FlightGear.
|
FlightGear.
|
||||||
|
|
||||||
Techniques
|
Techniques
|
||||||
----------
|
----------
|
||||||
|
|
||||||
A technique can contain a predicate that describes the OpenGL
|
A technique can contain a predicate that describes the OpenGL
|
||||||
functionality required to support the technique. The first
|
functionality required to support the technique. The first
|
||||||
technique with a valid predicate in the list of techniques is used
|
technique with a valid predicate in the list of techniques is used
|
||||||
to set up the graphics state of the effect. A technique with no
|
to set up the graphics state of the effect. A technique with no
|
||||||
predicate is always assumed to be valid. The predicate is written in a
|
predicate is always assumed to be valid. The predicate is written in a
|
||||||
little expression language that supports the following primitives:
|
little expression language that supports the following primitives:
|
||||||
|
|
||||||
and, or, equal, less, less-equal
|
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
|
||||||
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>
|
<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">1.0</value>
|
||||||
<shader-language/>
|
<shader-language/>
|
||||||
</less-equal>
|
</less-equal>
|
||||||
</and>
|
</and>
|
||||||
</predicate>
|
</predicate>
|
||||||
|
|
||||||
|
|
||||||
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
|
||||||
attributes will be accessable in techniques. State attributes -- that
|
attributes will be accessable in techniques. State attributes -- that
|
||||||
is, technique properties that have children and are not just boolean
|
is, technique properties that have children and are not just boolean
|
||||||
modes -- have an <active> parameter which enables or disables the
|
modes -- have an <active> parameter which enables or disables the
|
||||||
attribute. In this way a technique can declare parameters it needs,
|
attribute. In this way a technique can declare parameters it needs,
|
||||||
but not enable the attribute at all if it is not needed; the decision
|
but not enable the attribute at all if it is not needed; the decision
|
||||||
can be based on a parameter in the parameters section of the
|
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.
|
||||||
|
|
||||||
Values of Technique Attributes
|
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">0.2 0.2 0.2 1.0</ambient>
|
<ambient type="vec4d">0.2 0.2 0.2 1.0</ambient>
|
||||||
</material>
|
</material>
|
||||||
</parameters>
|
</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
|
fragment-shader
|
||||||
|
|
||||||
render-bin - (OSG) children: bin-number, bin-name
|
render-bin - (OSG) children: bin-number, bin-name
|
||||||
|
|
||||||
rendering-hint - (OSG) opaque, transparent
|
rendering-hint - (OSG) opaque, transparent
|
||||||
|
|
||||||
shade-model - flat, smooth
|
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 built-in 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
|
||||||
|
|
||||||
vertex-program-point-size - true, false
|
vertex-program-point-size - true, false
|
||||||
|
|
||||||
Inheritance
|
Inheritance
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
One feature not fully illustrated in the sample below is that
|
One feature not fully illustrated in the sample below is that
|
||||||
effects can inherit from each other. The parent effect is listed in
|
effects can inherit from each other. The parent effect is listed in
|
||||||
the "inherits-from" form. The child effect's property tree is
|
the "inherits-from" form. The child effect's property tree is
|
||||||
overlaid over that of the parent. Nodes that have the same name and
|
overlaid over that of the parent. Nodes that have the same name and
|
||||||
property index -- set by the "n=" attribute in the property tag --
|
property index -- set by the "n=" attribute in the property tag --
|
||||||
are recursively merged. Leaf property nodes from the child have
|
are recursively merged. Leaf property nodes from the child have
|
||||||
precedence. This means that effects that inherit from the example
|
precedence. This means that effects that inherit from the example
|
||||||
effect below could be very short, listing just new
|
effect below could be very short, listing just new
|
||||||
parameters and adding nothing to the techniques section;
|
parameters and adding nothing to the techniques section;
|
||||||
alternatively, a technique could be altered or customized in a
|
alternatively, a technique could be altered or customized in a
|
||||||
child, listing (for example) a different shader program. An example
|
child, listing (for example) a different shader program. An example
|
||||||
showing inheritance Effects/crop.eff, which inherits some if its
|
showing inheritance Effects/crop.eff, which inherits some if its
|
||||||
values from Effects/terrain-default.eff.
|
values from Effects/terrain-default.eff.
|
||||||
|
|
||||||
FlightGear directly uses effects inheritance to assign effects to 3D
|
FlightGear directly uses effects inheritance to assign effects to 3D
|
||||||
models and terrain. As described below, at runtime small effects are
|
models and terrain. As described below, at runtime small effects are
|
||||||
created that contain material and texture values in a "parameters"
|
created that contain material and texture values in a "parameters"
|
||||||
section. These effects inherit from another effect which references
|
section. These effects inherit from another effect which references
|
||||||
those parameters in its "techniques" section. The derived effect
|
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.
|
||||||
|
|
||||||
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
|
||||||
terrain effect, Effects/terrain-default.eff. The parameters section of
|
terrain effect, Effects/terrain-default.eff. The parameters section of
|
||||||
the effect is filled in using the ambient, diffuse, specular,
|
the effect is filled in using the ambient, diffuse, specular,
|
||||||
emissive, shininess, and transparent fields of the material. The
|
emissive, shininess, and transparent fields of the material. The
|
||||||
parameters image, filter, wrap-s, and wrap-t are also initialized from
|
parameters image, filter, wrap-s, and wrap-t are also initialized from
|
||||||
the material xml. Seperate effects are created for each texture
|
the material xml. Seperate effects are created for each texture
|
||||||
variant of a material.
|
variant of a material.
|
||||||
|
|
||||||
Model effects are created by walking the OpenSceneGraph scene graph
|
Model effects are created by walking the OpenSceneGraph scene graph
|
||||||
for a model and replacing nodes (osg::Geode) that have state sets with
|
for a model and replacing nodes (osg::Geode) that have state sets with
|
||||||
node that uses an effect instead. Again, a small effect is created
|
node that uses an effect instead. Again, a small effect is created
|
||||||
with parameters extracted from OSG objects; this effect inherits, by
|
with parameters extracted from OSG objects; this effect inherits, by
|
||||||
default, from Effects/model-default.eff. A larger set of parameters is
|
default, from Effects/model-default.eff. A larger set of parameters is
|
||||||
created for model effects than for terrain because there is more
|
created for model effects than for terrain because there is more
|
||||||
variation possible from the OSG model loaders than from the terrain
|
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
|
||||||
-------------------------
|
-------------------------
|
||||||
|
|
||||||
You can specify the effects that will be used by FlightGear as the
|
You can specify the effects that will be used by FlightGear as the
|
||||||
base effect when it creates terrain and model effects.
|
base effect when it creates terrain and model effects.
|
||||||
|
|
||||||
In the terrain materials.xml, an "effect" property specifies the name
|
In the terrain materials.xml, an "effect" property specifies the name
|
||||||
of the model to use.
|
of the model to use.
|
||||||
|
|
||||||
In model .xml files, A richer syntax is supported. [TO BE DETERMINED]
|
In model .xml files, A richer syntax is supported. [TO BE DETERMINED]
|
||||||
|
|
||||||
Material animations will be implemented by creating a new effect
|
Material animations will be implemented by creating a new effect
|
||||||
that inherits from one in a model, overriding the parameters that
|
that inherits from one in a model, overriding the parameters that
|
||||||
will be animated.
|
will be animated.
|
||||||
|
|
||||||
Examples
|
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
|
Application
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
To apply an effect to a model or part of a model use:
|
To apply an effect to a model or part of a model use:
|
||||||
|
|
||||||
<effect>
|
<effect>
|
||||||
<inherits-from>Effects/light-cone</inherits-from>
|
<inherits-from>Effects/light-cone</inherits-from>
|
||||||
<object-name>Cone</object-name>
|
<object-name>Cone</object-name>
|
||||||
</effect>
|
</effect>
|
||||||
|
|
||||||
where <inherits-from> </inherits-from> contains the path to the effect you want to apply.
|
where <inherits-from> </inherits-from> contains the path to the effect you want to apply.
|
||||||
The effect does not need the file extension.
|
The effect does not need the file extension.
|
||||||
|
|
||||||
NOTE:
|
NOTE:
|
||||||
|
|
||||||
Chrome, although now implemented as an effect, still retains the old method of application:
|
Chrome, although now implemented as an effect, still retains the old method of application:
|
||||||
|
|
||||||
<animation>
|
<animation>
|
||||||
<type>shader</type>
|
<type>shader</type>
|
||||||
<shader>chrome</shader>
|
<shader>chrome</shader>
|
||||||
<texture>glass_shader.png</texture>
|
<texture>glass_shader.png</texture>
|
||||||
<object-name>windscreen</object-name>
|
<object-name>windscreen</object-name>
|
||||||
</animation>
|
</animation>
|
||||||
|
|
||||||
in order to maintain backward compatibility.
|
in order to maintain backward compatibility.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue