Merge branch 'fred/effects-doc'

docs-mini/README.effects

@@ -35,6 +35,7 @@ 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
+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.
 
 The proper way to test whether to enable a shader-based technique is:
@@ -48,6 +49,23 @@ The proper way to test whether to enable a shader-based technique is:
 	  </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>
+      <and>
+        <property>/sim/rendering/shader-effects</property>
+	<less-equal>
+	  <value type="float">2.0</value>
+	  <float-property>/sim/rendering/quality-level</float-property>
+	</less-equal>
+	<!-- other predicate conditions -->
+      </and>
+    </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
 Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state
@@ -90,9 +108,7 @@ Values are assigned to technique properties in several ways:
 		Then, in the parameters section of the effect:
 		<parameters>
 			<material>
-      <ambient type="vec4d">
-        0.2 .2 0.2 1.0
-      </ambient>
+				<ambient type="vec4d">0.2 0.2 0.2 1.0</ambient>
 			</material>
 		</parameters>
 
@@ -152,7 +168,12 @@ polygon-mode - children: front, back
 
 program
 		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
 
@@ -171,7 +192,7 @@ texture-unit - has several child properties:
 			wrap-s
 			wrap-t
 			wrap-r
-        The following builtin types are supported:
+		The following built-in types are supported:
 			white - 1 pixel white texture
 			noise - a 3d noise texture
 		environment
@@ -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
 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
@@ -260,3 +322,30 @@ Examples
 
 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.
+