Merge branch 'fred/effects-doc' into next

docs-mini/README.effects

@@ -90,9 +90,7 @@ Values are assigned to technique properties in several ways:
 		Then, in the parameters section of the effect:
 		<parameters>
 			<material>
-      <ambient type="vec4d">
+				<ambient type="vec4d">0.2 0.2 0.2 1.0</ambient>
-        0.2 .2 0.2 1.0
-      </ambient>
 			</material>
 		</parameters>
 
@@ -152,7 +150,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 +174,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 +214,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 +304,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.
+