Changes between Version 11 and Version 12 of MaterialSystem
- Timestamp:
- Mar 15, 2015, 12:54:55 PM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
MaterialSystem
v11 v12 4 4 5 5 == Definitions == 6 7 6 * '''Models''' are a single mesh with a single material and texture. ([wiki:Actors#ActorXMLformat Actor XML] files define how meshes and materials and textures are combined to make models. Actors can use props to combine multiple models for use by a single unit, but props are completely independent as far as the rendering is concerned, so we don't need to worry about them further.) 8 7 … … 17 16 * '''Defines''' are name/value strings that modify the behaviour of shader programs, e.g. `USE_SPECULAR=1` to activate the code that computes specular lighting, as with `#define`/`#ifdef` in the C preprocessor. They can also influence the selection of shader techniques. Some defines come from the rendering engine; others from materials. 18 17 18 * '''Texture Samplers''' are what define textures in shader programs. They are required by materials using a `<required_texture>` tag and are defined in the actors. 19 19 20 * '''Materials''' combine a shader effect with various defines and uniforms that specialize its behavior. 20 21 … … 24 25 25 26 == Conditionals == 26 27 27 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.: 28 28 29 {{{ 29 30 #!xml … … 32 33 <whatever if="(FOO || !(BAR && BAZ)) && QUX > 100"/> 33 34 }}} 34 35 35 == Materials == 36 37 36 Located in [source:ps/trunk/binaries/data/mods/public/art/materials art/materials/]. Example: 37 38 38 {{{ 39 39 #!xml … … 50 50 }}} 51 51 Materials can contain: 52 52 53 * (rarely used) `<alternative material="..." if="..."/>` - if the conditional expression is true, then this material will be replaced by the given alternative. This can be useful so e.g. alpha-blended materials can get replaced with alpha-tested materials depending on some configuration. 54 55 56 53 57 * (required) `<shader effect="..."/>` - refers to one of the [source:ps/trunk/binaries/data/mods/public/shaders/effects effect XML files]. 54 58 * (rarely used) `<alpha_blending/>` - required if using a shader effect that uses alpha-blending. (This causes the engine to render the model twice, in `ALPHABLEND_PASS_OPAQUE` and `ALPHABLEND_PASS_BLEND` passes, to get correct blending relative to transparent water.) 55 59 * (zero or more times) `<define name="..." value="..."/>` - specifies a name/value define that is used when loading the shader. The value is typically `"1"` to enable an effect. 56 60 * (zero or more times) `<uniform name="..." value="..."/>` - specifies a uniform value that is used when rendering models using this material. The value is between 1 and 4 space-separated decimal numbers, e.g. `value="16"` or `value="1.0 1.0 0.0 0.5"`. 61 * (zero or more times) `<required_texture name="..." (define="...")/>` - specifies that this material requires a texture sampler of the same name. The name itself is only a hint at what this texture will be used for. `define` is used as a shortcut if this texture requires a "define" to be used. See existing materials. 57 62 58 63 == Defines == 59 60 64 Defines can come from many places: first from the engine, and then from `<define>`s inside `<material>`, `<technique>`, `<pass>`, `<program>`, and from `#define` in the source files, in that order. At each stage, conditionals can refer to the defines from all earlier stages. If a name is defined that was already defined in an earlier stage, its value will be overridden. There's no way to undefine a name, but defining it to `0` should have the same effect. (Shader source files should use `#if` instead of `#ifdef` to correctly handle values of `0`.) 61 65 … … 84 88 85 89 Set per model by engine code: 90 86 91 * `IGNORE_LOS` - `1` when the `Vision` component has the `AlwaysVisible` flag, meaning the LOS texture should not be used. 87 92 88 93 Set by materials: 94 89 95 * `USE_OBJECTCOLOR` - `1` when the `objectColor` uniform should be used. 90 96 * `USE_PLAYERCOLOR` - `1` when the `playerColor` uniform should be used. (Mutually exclusive with `USE_OBJECTCOLOR`.) 91 97 * `USE_SPECULAR` - `1` when specular lighting should be rendered. Requires the following uniforms: 92 * `float specularPower` - sharpness of specular highlights.93 * `vec3 specularColor` - color and brightness (components can be larger than 1.0).98 * `float specularPower` - sharpness of specular highlights. 99 * `vec3 specularColor` - color and brightness (components can be larger than 1.0). 94 100 * `USE_TRANSPARENT` - `1` when the texture's alpha channel should be output by the fragment shader. 95 101 * `DISABLE_RECEIVE_SHADOWS` - `1` when shadows should not be cast onto this object. 96 102 97 103 == Shader effects and techniques == 98 99 104 Located in [source:ps/trunk/binaries/data/mods/public/shaders/effects shaders/effects/]. Example: 100 105 … … 140 145 </effect> 141 146 }}} 142 143 147 An `<effect>` contains one or more `<technique>`s. Each technique can have a set of requirements: 148 144 149 * `<require context="..."/>` - an arbitrary conditional expression. (This can refer to defines that come from the material, or the current rendering mode, or the global rendering context.) 145 150 * `<require shaders="glsl"/>` - requires that GLSL shaders are supported and enabled. 146 151 * `<require shaders="arb"/>` - requires that ARB shaders are supported and enabled. 147 152 * `<require shaders="fixed"/>` - requires that fixed-function (OpenGL 1.3ish) rendering is supported and enabled. 153 148 154 Whenever a material tries to use an effect, the most preferred technique whose requirements are satisfied will be used. There must always be at least one usable technique in each effect. Typically, techniques that are defined earliest in the XML file will be preferred over techniques defined later. The exception is if the `preferglsl` config option (or `renderer.preferGLSL` in the console) is true, techniques requiring GLSL will always be more preferred than others; if `preferglsl` is false (the default), then ones requiring GLSL will always be less preferred. 149 155 150 156 `<technique>` can also contain: 157 151 158 * (zero or more) `<define name="..." value="..."/>` - add a new define which may be used by the technique's shader programs. 152 159 * (rarely used) `<sort_by_distance/>` - required if the technique includes a pass that uses non-commutative alpha-blending. (This causes the engine to sort models from furthest to nearest before rendering, to get correct alpha-blending behaviour.) … … 156 163 157 164 Every pass is rendered with a shader program (via the `shader="..."` attribute). `<pass>` can also contain: 165 158 166 * (zero or more) `<define name="..." value="..."/>` - add a new define which may be used by the pass's shader program. 159 167 * `<alpha func="..." ref="..."/>` - equivalent to `glAlphaFunc(func, ref)`. `ref` is a float. `func` can be one of `never`, `always`, `less`, `lequal`, `equal`, `gequal`, `greater`, `notequal`. … … 163 171 164 172 == Shader programs == 165 166 GLSL shaders are in [source:ps/trunk/binaries/data/mods/public/shaders/glsl shaders/glsl/]. 167 ARB shaders are in [source:ps/trunk/binaries/data/mods/public/shaders/arb shaders/arb/]. 168 Fixed-function 'shaders' are in [source:ps/trunk/source/graphics/ShaderProgramFFP.cpp ShaderProgramFFP.cpp] and will be discussed later. 173 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. 169 174 170 175 ARB shaders are defined by an XML file like: 176 171 177 {{{ 172 178 #!xml … … 192 198 </program> 193 199 }}} 194 195 200 GLSL shaders are defined by an XML file like: 201 196 202 {{{ 197 203 #!xml … … 211 217 </program> 212 218 }}} 213 214 219 `<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. 215 220 … … 219 224 220 225 `<vertex>` can contain: 226 221 227 * `<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. 222 228 223 229 === ARB shaders === 224 225 230 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. 226 231 227 232 `<vertex>` and `<fragment>` can both contain: 233 228 234 * `<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`. 229 235 * `<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`. … … 232 238 233 239 === GLSL shaders === 234 235 240 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. 236 241 237 242 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: 243 238 244 * `<attrib name="..." semantics="..."/>` - defines a binding between a named attribute in the vertex shader, and vertex data semantics. The `semantics` can be one of: 239 * `gl_Vertex` 240 * `gl_Normal` 241 * `gl_Color` 242 * `gl_SecondaryColor` 243 * `gl_FogCoord` 244 * `gl_MultiTexCoord0` to `gl_MultiTexCoord7` 245 * `CustomAttribute0` to `CustomAttribute2` 246 E.g. the XML file says `<attrib name="a_vertex" semantics="gl_Vertex"/>`, and the GLSL file says "`attribute vec3 a_vertex;`". 245 * `gl_Vertex` 246 * `gl_Normal` 247 * `gl_Color` 248 * `gl_SecondaryColor` 249 * `gl_FogCoord` 250 * `gl_MultiTexCoord0` to `gl_MultiTexCoord7` 251 * `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;`". 247 252 248 253 === Fixed-function shaders === 249 250 254 'Fixed-function' refers to the OpenGL 1.3 era of `glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_COMBINE)` multi-texturing. These aren't really shaders but we use the same API as for the ARB/GLSL shaders, to simplify the rendering code. 251 255 … … 253 257 254 258 == Shader source files == 255 256 ARB vertex/fragment program source files have extensions `.vp` and `.fp` in [source:ps/trunk/binaries/data/mods/public/shaders/arb shaders/arb/]. 257 GLSL vertex/fragment shader source files have extensions `.vs` and `.fs` in [source:ps/trunk/binaries/data/mods/public/shaders/glsl shaders/glsl/]. 259 ARB vertex/fragment program source files have extensions `.vp` and `.fp` in [source:ps/trunk/binaries/data/mods/public/shaders/arb shaders/arb/]. GLSL vertex/fragment shader source files have extensions `.vs` and `.fs` in [source:ps/trunk/binaries/data/mods/public/shaders/glsl shaders/glsl/]. 258 260 259 261 All source files are passed through a custom preprocessor before being compiled. This recognises basic C preprocessor syntax (`#if`, `#ifdef`, `#define`, etc; unfortunately not `#elif`), and can refer to the defines from all the earlier XML files (passes, techniques, materials, rendering mode, global renderer context, etc).
