Changes between Version 4 and Version 5 of MaterialSystem

Timestamp:

2012-04-15 16:11:11 (13 months ago)

Author:

Philip

Comment:

shader programs

MaterialSystem

@@ -25 +25 @@
 Various XML files can contain conditionals, which are typically attributes of the form `if="..."`. These are C-preprocessor-style boolean expressions that can use the current set of defines, e.g.:
 {{{
-<alternative ... if="CFG_FORCE_ALPHATEST"/>
+#!xml
+<alternative material="..." if="CFG_FORCE_ALPHATEST"/>
 <require context="MODE_SHADOWCAST || MODE_SILHOUETTEOCCLUDER"/>
 <whatever if="(FOO || !(BAR && BAZ)) && QUX > 100"/>
@@ -152 +153 @@
  * `<depth func="..."/>` - equivalent to `glDepthFunc(func)`. `func` can be the same values as `<alpha func>`.
  * `<depth mask="..."/>` - equivalent to `glDepthMask(mask)`. `mask` can be `true` or `false`.
+
+== Shader programs ==
+
+GLSL shaders are in [source:ps/trunk/binaries/data/mods/public/shaders/glsl shaders/glsl/].
+ARB shaders are in [source:ps/trunk/binaries/data/mods/public/shaders/arb shaders/arb/].
+Fixed-function 'shaders' are in [source:ps/trunk/source/graphics/ShaderProgramFFP.cpp ShaderProgramFFP.cpp] and will be discussed later.
+
+ARB shaders are defined by an XML file like:
+{{{
+#!xml
+<?xml version="1.0" encoding="utf-8"?>
+<program type="arb">
+    <vertex file="arb/model_common.vp">
+        <uniform name="sunColor" loc="0" type="vec3"/>
+        <uniform name="shadowTransform" loc="1" type="mat4"/>
+        <uniform if="USE_INSTANCING" name="instancingTransform" loc="5" type="mat4"/>
+        <stream name="pos"/>
+        <stream name="normal"/>
+        <stream name="uv0"/>
+    </vertex>
+    <fragment file="arb/model_common.fp">
+        <uniform name="baseTex" loc="0" type="sampler2D"/>
+        <uniform name="shadowTex" loc="1" type="sampler2DShadow"/>
+        <uniform name="losTex" loc="2" type="sampler2D"/>
+
+        <uniform if="USE_OBJECTCOLOR" name="objectColor" loc="0" type="vec3"/>
+        <uniform if="USE_PLAYERCOLOR" name="playerColor" loc="0" type="vec3"/>
+        <uniform name="sunColor" loc="1" type="vec3"/>
+    </fragment>
+</program>
+}}}
+
+GLSL shaders are defined by an XML file like:
+{{{
+#!xml
+<?xml version="1.0" encoding="utf-8"?>
+<program type="glsl">
+    <vertex file="glsl/model_common.vs">
+        <stream name="pos"/>
+        <stream name="normal"/>
+        <stream name="uv0"/>
+        <attrib name="a_vertex" semantics="gl_Vertex"/>
+        <attrib name="a_normal" semantics="gl_Normal"/>
+        <attrib name="a_uv0" semantics="gl_MultiTexCoord0"/>
+        <attrib name="a_skinJoints" semantics="CustomAttribute0" if="USE_GPU_SKINNING"/>
+        <attrib name="a_skinWeights" semantics="CustomAttribute1" if="USE_GPU_SKINNING"/>
+    </vertex>
+    <fragment file="glsl/model_common.fs"/>
+</program>
+}}}
+
+`<program>` must contain a `<vertex file="...">` and `<fragment file="...">`, referring to the ARB/GLSL source files. The vertex and fragment shaders are loaded and linked to create the complete program.
+
+`<program>` can contain zero or more `<define name="..." value="..."/>`, which will apply to its vertex/fragment shaders.
+
+Any child element of `<vertex>`/`<fragment>` may have an `if="..."` attribute. If the conditional expression is false, the whole child element will be ignored entirely.
+
+`<vertex>` can contain:
+ * `<stream name="..."/>` - requests that the engine provide a stream of per-vertex data. `name` can be `pos`, `normal`, `color`, `uv0`, `uv1`, `uv2`, `uv3`. The semantics of the streams (especially the UVs) is controlled by the rendering engine. For performance, shaders should only request streams that they actually use.
+
+=== ARB shaders ===
+
+Vertex streams (activated via `<stream>`) are automatically bound to the standard ARB-shader attribute symbols: `vertex.position`, `vertex.normal`, `vertex.color`, `vertex.texcoord[0]` etc.
+
+`<vertex>` and `<fragment>` can both contain:
+ * `<uniform name="..." loc="..." type="..."/>` - binds a name to a local parameter location. The ARB program can read these via "`PARAM sunColor = program.local[0];`" etc. `type` can be one of `float`, `vec2`, `vec3`, `vec4`, `mat2`, `mat3`, `mat4`, though it doesn't actually do anything since the only type supported by ARB programs is `vec4`.
+ * `<uniform name="..." loc="..." type="sampler..."/>` - binds a name to a texture unit. The ARB program can read these as `texture[0]` etc. `type` can be one of `sampler2D`, `sampler2DShadow`, `samplerCube`.
+
+Note that local parameters and texture units are totally separate, so the same `loc` may be used for one of each. Also note that `mat4` takes 4 consecutive locations, so if you define a `<uniform type="mat4" loc="1"/>` then the next free slot is `loc="5"`.
+
+=== GLSL shaders ===
+
+Unlike ARB shaders, the uniforms and texture units in GLSL shaders are determined automatically (via `glGetActiveUniform` etc), so you don't need to define them in the XML.
+
+We use a subset of GLSL that largely corresponds to GLSL ES 1.00 and non-deprecated GLSL 1.30 - in particular, there is no `gl_Vertex` or `gl_Normal` etc, only generic vertex attributes. Therefore, `<vertex>` must contain:
+ * `<attrib name="..." semantics="..."/>` - defines a binding between a named attribute in the vertex shader, and vertex data semantics. The `semantics` can be one of:
+  * `gl_Vertex`
+  * `gl_Normal`
+  * `gl_Color`
+  * `gl_SecondaryColor`
+  * `gl_FogCoord`
+  * `gl_MultiTexCoord0` to `gl_MultiTexCoord7`
+  * `CustomAttribute0` to `CustomAttribute2`
+ E.g. the XML file says `<attrib name="a_vertex" semantics="gl_Vertex"/>`, and the GLSL file says "`attribute vec3 a_vertex;`".