| 155 | |
| 156 | == Shader programs == |
| 157 | |
| 158 | GLSL shaders are in [source:ps/trunk/binaries/data/mods/public/shaders/glsl shaders/glsl/]. |
| 159 | ARB shaders are in [source:ps/trunk/binaries/data/mods/public/shaders/arb shaders/arb/]. |
| 160 | Fixed-function 'shaders' are in [source:ps/trunk/source/graphics/ShaderProgramFFP.cpp ShaderProgramFFP.cpp] and will be discussed later. |
| 161 | |
| 162 | ARB shaders are defined by an XML file like: |
| 163 | {{{ |
| 164 | #!xml |
| 165 | <?xml version="1.0" encoding="utf-8"?> |
| 166 | <program type="arb"> |
| 167 | <vertex file="arb/model_common.vp"> |
| 168 | <uniform name="sunColor" loc="0" type="vec3"/> |
| 169 | <uniform name="shadowTransform" loc="1" type="mat4"/> |
| 170 | <uniform if="USE_INSTANCING" name="instancingTransform" loc="5" type="mat4"/> |
| 171 | <stream name="pos"/> |
| 172 | <stream name="normal"/> |
| 173 | <stream name="uv0"/> |
| 174 | </vertex> |
| 175 | <fragment file="arb/model_common.fp"> |
| 176 | <uniform name="baseTex" loc="0" type="sampler2D"/> |
| 177 | <uniform name="shadowTex" loc="1" type="sampler2DShadow"/> |
| 178 | <uniform name="losTex" loc="2" type="sampler2D"/> |
| 179 | |
| 180 | <uniform if="USE_OBJECTCOLOR" name="objectColor" loc="0" type="vec3"/> |
| 181 | <uniform if="USE_PLAYERCOLOR" name="playerColor" loc="0" type="vec3"/> |
| 182 | <uniform name="sunColor" loc="1" type="vec3"/> |
| 183 | </fragment> |
| 184 | </program> |
| 185 | }}} |
| 186 | |
| 187 | GLSL shaders are defined by an XML file like: |
| 188 | {{{ |
| 189 | #!xml |
| 190 | <?xml version="1.0" encoding="utf-8"?> |
| 191 | <program type="glsl"> |
| 192 | <vertex file="glsl/model_common.vs"> |
| 193 | <stream name="pos"/> |
| 194 | <stream name="normal"/> |
| 195 | <stream name="uv0"/> |
| 196 | <attrib name="a_vertex" semantics="gl_Vertex"/> |
| 197 | <attrib name="a_normal" semantics="gl_Normal"/> |
| 198 | <attrib name="a_uv0" semantics="gl_MultiTexCoord0"/> |
| 199 | <attrib name="a_skinJoints" semantics="CustomAttribute0" if="USE_GPU_SKINNING"/> |
| 200 | <attrib name="a_skinWeights" semantics="CustomAttribute1" if="USE_GPU_SKINNING"/> |
| 201 | </vertex> |
| 202 | <fragment file="glsl/model_common.fs"/> |
| 203 | </program> |
| 204 | }}} |
| 205 | |
| 206 | `<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. |
| 207 | |
| 208 | `<program>` can contain zero or more `<define name="..." value="..."/>`, which will apply to its vertex/fragment shaders. |
| 209 | |
| 210 | 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. |
| 211 | |
| 212 | `<vertex>` can contain: |
| 213 | * `<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. |
| 214 | |
| 215 | === ARB shaders === |
| 216 | |
| 217 | 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. |
| 218 | |
| 219 | `<vertex>` and `<fragment>` can both contain: |
| 220 | * `<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`. |
| 221 | * `<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`. |
| 222 | |
| 223 | 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"`. |
| 224 | |
| 225 | === GLSL shaders === |
| 226 | |
| 227 | 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. |
| 228 | |
| 229 | 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: |
| 230 | * `<attrib name="..." semantics="..."/>` - defines a binding between a named attribute in the vertex shader, and vertex data semantics. The `semantics` can be one of: |
| 231 | * `gl_Vertex` |
| 232 | * `gl_Normal` |
| 233 | * `gl_Color` |
| 234 | * `gl_SecondaryColor` |
| 235 | * `gl_FogCoord` |
| 236 | * `gl_MultiTexCoord0` to `gl_MultiTexCoord7` |
| 237 | * `CustomAttribute0` to `CustomAttribute2` |
| 238 | E.g. the XML file says `<attrib name="a_vertex" semantics="gl_Vertex"/>`, and the GLSL file says "`attribute vec3 a_vertex;`". |