diff --git a/docs-mini/README.effects b/docs-mini/README.effects
index 60b30386a..f6d2b3159 100644
--- a/docs-mini/README.effects
+++ b/docs-mini/README.effects
@@ -1,3 +1,6 @@
+Effects
+-------
+
Effects describe the graphical appearance of 3d objects and scenery in
FlightGear. The main motivation for effects is to support OpenGL
shaders and to provide different implementations for graphics hardware
@@ -10,13 +13,16 @@ 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
"parameters" section followed by "technique" descriptions. The
"parameters" section is a tree of values that describe, abstractly,
-the graphical appearence 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
-parameters for shader programs.
+parameters for shader programs. The names of properties in the
+parameter section can be whatever the effects author chooses, although
+some standard parameters are set by FlightGear itself. On the other
+hand, the properties in the techniques section are all defined by the
+FlightGear.
-Parameters can be declared to have a dynamic variance, which means
-that if their value is changed the corresponding value in the
-technique will be changed too. [TO BE IMPLEMENTED]
+Techniques
+----------
A technique can contain a predicate that describes the OpenGL
functionality required to support the technique. The first
@@ -29,22 +35,131 @@ and, or, equal, less, less-equal
glversion - returns the version number of OpenGL
extension-supported - returns true if an OpenGL extension is supported
property - returns the boolean value of a property
+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:
+
+
+ /sim/rendering/shader-effects
+
+ 1.0
+
+
+
+
+
A technique can consist of several passes. A pass is basically an Open
Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state
-attributes will be setable in a technique. The following are
-are currently implemented:
-lighting - true, false
-shade-model - flat, smooth
+attributes will be accessable in techniques. State attributes -- that
+is, technique properties that have children and are not just boolean
+modes -- have an parameter which enables or disables the
+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
+can be based on a parameter in the parameters section of the
+effect. For example, effects that support transparent and opaque
+geometry could have as part of a technique:
+
+
+
+ src-alpha
+ one-minus-src-alpha
+
+
+So if the blend/active parameter is true blending will be activated
+using the usual blending equation; otherwise blending is disabled.
+
+Values of Technique Attributes
+------------------------------
+
+Values are assigned to technique properties in several ways:
+
+ * They can appear directly in the techniques section as a
+ constant. For example:
+
+ ColorsTex
+ sampler-1d
+ 2
+
+ * The name of a property in the parameters section can be
+ referenced using a "use" clause. For example, in the technique
+ section:
+
+
+
+ Then, in the parameters section of the effect:
+
+
+
+ 0.2 .2 0.2 1.0
+
+
+
+
+ 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:
+
+
+
+ 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
+
+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
+
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
+
+polygon-mode - children: front, back
+ Valid values:
+ fill, line, point
+
+program
+ vertex-shader
+ fragment-shader
+
+render-bin - (OSG) children: bin-number, bin-name
+
rendering-hint - (OSG) opaque, transparent
-render-bin - children: bin-number, bin-name
-material - children: 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
-blend - true, false
-alpha-test - true, false
+
+shade-model - flat, smooth
+
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
@@ -62,16 +177,17 @@ texture-unit - has several child properties:
environment
mode
color
-program
- vertex-shader
- fragment-shader
uniform
name
type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
sampler-3d
-polygon-mode
-front - fill, line, point
-back - fill, line, point
+
+vertex-program-two-side - true, false
+
+vertex-program-point-size - true, false
+
+Inheritance
+-----------
One feature not fully illustrated in the sample below is that
effects can inherit from each other. The parent effect is listed in
@@ -83,164 +199,64 @@ precedence. This means that effects that inherit from the example
effect below could be very short, listing just new
parameters and adding nothing to the techniques section;
alternatively, a technique could be altered or customized in a
-child, listing (for example) a different shader program. Terrain
-materials work in this way: for each material type in materials.xml
-an effect is created that inherits from a single default terrain
-effect. The parameters section of the effect is filled in using the
-ambient, diffuse, specular, emissive, shininess, and transparent
-fields of the material. Seperate effects are created for each texture
+child, listing (for example) a different shader program. An example
+showing inheritance Effects/crop.eff, which inherits some if its
+values from Effects/terrain-default.eff.
+
+FlightGear directly uses effects inheritance to assign effects to 3D
+models and terrain. As described below, at runtime small effects are
+created that contain material and texture values in a "parameters"
+section. These effects inherit from another effect which references
+those parameters in its "techniques" section. The derived effect
+overrides any default values that might be in the base effect's
+parameters section.
+
+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
+terrain effect, Effects/terrain-default.eff. The parameters section of
+the effect is filled in using the ambient, diffuse, specular,
+emissive, shininess, and transparent fields of the material. The
+parameters image, filter, wrap-s, and wrap-t are also initialized from
+the material xml. Seperate effects are created for each texture
variant of a material.
+Model effects are created by walking the OpenSceneGraph scene graph
+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
+with parameters extracted from OSG objects; this effect inherits, by
+default, from Effects/model-default.eff. A larger set of parameters is
+created for model effects than for terrain because there is more
+variation possible from the OSG model loaders than from the terrain
+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
+
+Specifying Custom Effects
+-------------------------
+
+You can specify the effects that will be used by FlightGear as the
+base effect when it creates terrain and model effects.
+
+In the terrain materials.xml, an "effect" property specifies the name
+of the model to use.
+
+In model .xml files, A richer syntax is supported. [TO BE DETERMINED]
+
Material animations will be implemented by creating a new effect
that inherits from one in a model, overriding the parameters that
will be animated.
+Examples
+--------
-
-
- city
-
-
-
-
- 0.0 0.0 0.0 1.0
-
-
- .5 .5 .5 1.0
-
-
- 0.3 0.3 0.3 1.0
-
-
- 0.0 0.0 0.0 1.0
-
- 1.2
-
-
- city.png
- linear-mipmap-linear
-
- clamp
- clamp-to-edge
-
-
- normalized
-
-
- detail.png
- linear-mipmap-linear
-
- clamp
- clamp-to-edge
-
-
- normalized
-
- .05
- 0 0 1 1.5708
-
-
-
-
-
-
- 2.0
-
-
-
- GL_ARB_shader_objects
- GL_ARB_shading_language_100
- GL_ARB_vertex_shader
- GL_ARB_fragment_shader
-
-
-
-
- true
-
-
-
-
-
-
-
- 0
-
-
-
-
-
-
-
-
-
- 1
-
-
-
-
-
-
-
-
-
- bumpHeight
- float
-
-
-
- patternRotation
- float-vec4
-
-
-
- baseTexture
- sampler-2d
- 0
-
-
- detailTexture
- sampler-2d
- 1
-
-
-
-
- "Shaders/util.vert"
-
-
- "Shaders/foo.vert"
-
-
- "Shaders/foo.frag"
-
-
-
-
-
-
-
- true
-
-
-
-
-
-
- 0
-
-
-
-
-
-
-
-
-
-
-
-
+The Effects directory contains the effects definitions; look there for
+examples. Effects/crop.eff is a good example of a complex effect.