The material system contains many components. Artists should just care about telling actors to use appropriate materials, and occasionally creating new material XML files by copying old ones and tweaking the uniforms. Graphical programmers might care about all the various shader files.

== Definitions ==

 * '''Models''' are a single mesh with a single material and texture. (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.)

 * '''Shader programs''' contain the low-level GPU code that performs per-vertex and per-fragment computation. (These might be implemented with GLSL, or with ARB assembly programs, or with fixed-function multitexturing code - the choice of implementation language is hidden from the rest of the system.)

 * '''Attributes''' are the per-vertex data that shader programs use: vertex positions, normal vectors, colors, etc. The rendering engine computes all this data.

 * '''Uniforms''' are the global or per-model data that shader programs use: camera position, sun color, specular highlight power, player color, etc. Some uniforms are computed by the rendering engine; others are specified by material definitions.

 * '''Defines''' are name/value strings that control the behaviour of shader programs, e.g. `USE_SPECULAR=1` to activate the code that computes specular lighting. Some defines come from the rendering engine; others from materials.

 * '''Materials''' refer to a shader effect and specify various defines and uniforms.

 * '''Shader techniques''' define how to combine one or more shader programs and other OpenGL state (e.g. alpha-blending behaviour) to render a model. (Usually a technique only uses a single program, but sometimes it needs to perform multiple passes over each model with a different program each time.)

 * '''Rendering modes''' are the different ways the renderer processes each model. E.g. first it draws each model in the shadowmap generation mode to compute shadows, and later it draws each model in the standard textured lit mode.

 * '''Shader effects''' control which shader technique to use in each different context, depending on rendering mode, hardware capabilities, user-selected graphics options, etc.

== Materials ==

Located in [source:ps/trunk/binaries/data/mods/public/art/materials art/materials/]. Example:
{{{
<?xml version="1.0" encoding="utf-8"?>
<material>
    <shader effect="model_transparent"/>
    <alpha_blending/>
    <define name="USE_TRANSPARENT" value="1"/>
    <define name="USE_SPECULAR" value="1"/>
    <uniform name="specularPower" value="16.0"/>
    <uniform name="specularColor" value="1.0 1.0 1.0"/>
</material>
}}}
Materials can contain:
 * `<shader effect="..."/>` - refers to one of the [source:ps/trunk/binaries/data/mods/public/shaders/effects effect XML files].
 * `<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.)
 * `<define name="..." value="..."/>` - specifies a name/value define that is used when loading the shader. The value is typically `"1"` to enable an effect.
 * `<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"`.

== Defines ==

Set globally by engine code:

 * `USE_SHADOW` - `1` when shadows are supported by the hardware and enabled by the user.
 * `USE_FP_SHADOW` - `1` when `GL_ARB_fragment_program_shadow` is supported and enabled.
 * `USE_SHADOW_PCF` - `1` when shadow PCF filtering is enabled.
 * `USE_SHADOW_SAMPLER` - `1` when `sampler2DShadow` etc is supported in GLSL. (Unavailable on OpenGL ES.)
 * `SYS_HAS_ARB` - `1` when `GL_ARB_vertex_program`/`GL_ARB_fragment_program` are supported, and the renderer is in shader mode.
 * `SYS_HAS_GLSL` - `1` when `GL_ARB_vertex_shader`/`GL_ARB_fragment_shader` are supported, and the renderer is in shader mode.
 * `SYS_PREFER_GLSL` - `1` when the `preferGLSL` option is enabled. (On by default on OpenGL ES.)

Set by engine code in different renderer modes:

 * `MODE_SHADOWCAST` - `1` when rendering objects onto the shadow map. Only depth is needed, no color data.
 * `MODE_SILHOUETTEOCCLUDER` - `1` when rendering objects that silhouettes may be displayed behind. Only depth is needed, no color data.
 * `MODE_SILHOUETTEDISPLAY` - `1` when rendering objects that may be displayed as silhouettes. Should draw solid color `playerColor`.
 * `MODE_WIREFRAME` - `1` when rendering wireframe or edged-face versions of models, for debugging.
 * `ALPHABLEND_PASS_OPAQUE` - `1` when rendering the opaque alpha-tested pass of transparent models before water.
 * `ALPHABLEND_PASS_BLEND` - `1` when rendering the alpha-blended pass of transparent models after water.

Set per model by engine code:
 * `IGNORE_LOS` - `1` when the `Vision` component has the `AlwaysVisible` flag, meaning the LOS texture should not be used.

Set by materials:
 * `USE_OBJECTCOLOR` - `1` when the `objectColor` uniform should be used.
 * `USE_PLAYERCOLOR` - `1` when the `playerColor` uniform should be used. (Mutually exclusive with `USE_OBJECTCOLOR`.)
 * `USE_SPECULAR` - `1` when specular lighting should be rendered. Requires the following uniforms:
  * `float specularPower` - sharpness of specular highlights.
  * `vec3 specularColor` - color and brightness (components can be larger than 1.0).
 * `USE_TRANSPARENT` - `1` when the texture's alpha channel should be output by the fragment shader.
 * `DISABLE_RECEIVE_SHADOWS` - `1` when shadows should not be cast onto this object.