#
# Material Call Tips
#
[lod_distances]
By setting this attribute, you indicate that you want this material to alter the Technique that it uses based on distance from the camera. You must give it a list of distances, in ascending order, each one indicating the distance at which the material will switch to the next LOD. Implicitly, all materials activate LOD index 0 for distances less than the smallest of these. You must ensure that there is at least one Technique with a lod_index value for each distance in the list (so if you specify 3 distances, you must have techniques for indexes 1, 2 and 3). Note you must always have at least one Technique at lod_index 0.

Format: lod_distances <distance_1> [<distance_2> ... <distance_n>]
Example: lod_distances 300.0 600.5 1200

The above example would cause the material to use the best Technique at lod_index 0 up to a distance of 300 world units, the best from lod_index 1 from 300 up to 600, lod_index 2 from 600 to 1200, and lod_index 3 from 1200 upwards.

Techniques also contain one or more passes (and there must be at least one), See section 3.1.2 Passes. 
[receive_shadows]
This attribute controls whether objects using this material can have shadows cast upon them.

Format: receive_shadows <on|off>
Default: on

Whether or not an object receives a shadow is the combination of a number of factors, See section 7. Shadows for full details; however this allows you to make a material opt-out of receiving shadows if required. Note that transparent materials never receive shadows so this option only has an effect on solid materials.
[transparency_casts_shadows]
This attribute controls whether transparent materials can cast certain kinds of shadow.

Format: transparency_casts_shadows <on|off>
Default: off

Whether or not an object casts a shadow is the combination of a number of factors, See section 7. Shadows for full details; however this allows you to make a transparent material cast shadows, when it would otherwise not. For example, when using texture shadows, transparent materials are normally not rendered into the shadow texture because they should not block light. This flag overrides that.
[set_texture_alias]
This attribute associates a texture alias with a texture name.

Format: set_texture_alias <alias name> <texture name>

This attribute is used to set the textures used in texture unit states that were copied from another material.(See section 3.1.11 Copying Materials)
#
# Technique Call Tips
#
[scheme]
Sets the 'scheme' this Technique belongs to. Material schemes are used to control top-level switching from one set of techniques to another. For example, you might use this to define 'high', 'medium' and 'low' complexity levels on materials to allow a user to pick a performance / quality ratio. Another possibility is that you have a fully HDR-enabled pipeline for top machines, rendering all objects using unclamped shaders, and a simpler pipeline for others; this can be implemented using schemes. The active scheme is typically controlled at a viewport level, and the active one defaults to 'Default'.

Format: scheme <name>
Example: scheme hdr
Default: scheme Default
[lod_index]
Sets the level-of-detail (LOD) index this Technique belongs to. 

Format: lod_index <number>
NB Valid values are 0 (highest level of detail) to 65535, although this is unlikely. You should not leave gaps in the LOD indexes between Techniques.

Example: lod_index 1

All techniques must belong to a LOD index, by default they all belong to index 0, ie the highest LOD. Increasing indexes denote lower levels of detail. You can (and often will) assign more than one technique to the same LOD index, what this means is that OGRE will pick the best technique of the ones listed at the same LOD index. For readability, it is advised that you list your techniques in order of LOD, then in order of preference, although the latter is the only prerequisite (OGRE determines which one is 'best' by which one is listed first). You must always have at least one Technique at lod_index 0.

The distance at which a LOD level is applied is determined by the lod_distances attribute of the containing material, See section lod_distances for details.

Default: lod_index 0
#
# Pass Documentation
#
[ambient]
Sets the ambient colour reflectance properties of this pass. This attribute has no effect if a asm, CG, or HLSL shader program is used. With GLSL, the shader can read the OpenGL material state. 

Format: ambient (<red> <green> <blue> [<alpha>]| vertexcolour)
NB valid colour values are between 0.0 and 1.0.

Example: ambient 0.0 0.8 0.0

The base colour of a pass is determined by how much red, green and blue light is reflects at each vertex. This property determines how much ambient light (directionless global light) is reflected. It is also possible to make the ambient reflectance track the vertex colour as defined in the mesh by using the keyword vertexcolour instead of the colour values. The default is full white, meaning objects are completely globally illuminated. Reduce this if you want to see diffuse or specular light effects, or change the blend of colours to make the object have a base colour other than white. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.

Default: ambient 1.0 1.0 1.0 1.0
[diffuse]
Sets the diffuse colour reflectance properties of this pass. This attribute has no effect if a asm, CG, or HLSL shader program is used. With GLSL, the shader can read the OpenGL material state.

Format: diffuse (<red> <green> <blue> [<alpha>]| vertexcolour)
NB valid colour values are between 0.0 and 1.0.

Example: diffuse 1.0 0.5 0.5

The base colour of a pass is determined by how much red, green and blue light is reflects at each vertex. This property determines how much diffuse light (light from instances of the Light class in the scene) is reflected. It is also possible to make the diffuse reflectance track the vertex colour as defined in the mesh by using the keyword vertexcolour instead of the colour values. The default is full white, meaning objects reflect the maximum white light they can from Light objects. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.

Default: diffuse 1.0 1.0 1.0 1.0
[specular]
Sets the specular colour reflectance properties of this pass. This attribute has no effect if a asm, CG, or HLSL shader program is used. With GLSL, the shader can read the OpenGL material state.

Format: specular (<red> <green> <blue> [<alpha>]| vertexcolour) <shininess>
NB valid colour values are between 0.0 and 1.0. Shininess can be any value greater than 0.

Example: specular 1.0 1.0 1.0 12.5

The base colour of a pass is determined by how much red, green and blue light is reflects at each vertex. This property determines how much specular light (highlights from instances of the Light class in the scene) is reflected. It is also possible to make the diffuse reflectance track the vertex colour as defined in the mesh by using the keyword vertexcolour instead of the colour values. The default is to reflect no specular light. The colour of the specular highlights is determined by the colour parameters, and the size of the highlights by the separate shininess parameter.. The higher the value of the shininess parameter, the sharper the highlight ie the radius is smaller. Beware of using shininess values in the range of 0 to 1 since this causes the the specular colour to be applied to the whole surface that has the material applied to it. When the viewing angle to the surface changes, ugly flickering will also occur when shininess is in the range of 0 to 1. Shininess values between 1 and 128 work best in both DirectX and OpenGL renderers. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.

Default: specular 0.0 0.0 0.0 0.0 0.0
[emissive]
Sets the amount of self-illumination an object has. This attribute has no effect if a asm, CG, or HLSL shader program is used. With GLSL, the shader can read the OpenGL material state.

Format: emissive (<red> <green> <blue> [<alpha>]| vertexcolour)
NB valid colour values are between 0.0 and 1.0.

Example: emissive 1.0 0.0 0.0

If an object is self-illuminating, it does not need external sources to light it, ambient or otherwise. It's like the object has it's own personal ambient light. Unlike the name suggests, this object doesn't act as a light source for other objects in the scene (if you want it to, you have to create a light which is centered on the object). It is also possible to make the emissive colour track the vertex colour as defined in the mesh by using the keyword vertexcolour instead of the colour values. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.

Default: emissive 0.0 0.0 0.0 0.0
[scene_blend]
Sets the kind of blending this pass has with the existing contents of the scene. Wheras the texture blending operations seen in the texture_unit entries are concerned with blending between texture layers, this blending is about combining the output of this pass as a whole with the existing contents of the rendering target. This blending therefore allows object transparency and other special effects. There are 2 formats, one using predefined blend types, the other allowing a roll-your-own approach using source and destination factors.

Format1: scene_blend <add|modulate|alpha_blend|colour_blend>

Example: scene_blend add

This is the simpler form, where the most commonly used blending modes are enumerated using a single parameter. Valid <blend_type> parameters are: 
add 
The colour of the rendering output is added to the scene. Good for exposions, flares, lights, ghosts etc. Equivalent to 'scene_blend one one'. 
modulate 
The colour of the rendering output is multiplied with the scene contents. Generally colours and darkens the scene, good for smoked glass, semi-transparent objects etc. Equivalent to 'scene_blend dest_colour zero'. 
colour_blend 
Colour the scene based on the brightness of the input colours, but don't darken. Equivalent to 'scene_blend src_colour one_minus_src_colour' 
alpha_blend 
The alpha value of the rendering output is used as a mask. Equivalent to 'scene_blend src_alpha one_minus_src_alpha' 

Format2: scene_blend <src_factor> <dest_factor>

Example: scene_blend one one_minus_dest_alpha

This version of the method allows complete control over the blending operation, by specifying the source and destination blending factors. The resulting colour which is written to the rendering target is (texture * sourceFactor) + (scene_pixel * destFactor). Valid values for both parameters are: 
one 
Constant value of 1.0 
zero 
Constant value of 0.0 
dest_colour 
The existing pixel colour 
src_colour 
The texture pixel (texel) colour 
one_minus_dest_colour 
1 - (dest_colour) 
one_minus_src_colour 
1 - (src_colour) 
dest_alpha 
The existing pixel alpha value 
src_alpha 
The texel alpha value 
one_minus_dest_alpha 
1 - (dest_alpha) 
one_minus_src_alpha 
1 - (src_alpha) 

Default: scene_blend one zero (opaque) 
[depth_check]
Sets whether or not this pass renders with depth-buffer checking on or not.

Format: depth_check <on|off>

If depth-buffer checking is on, whenever a pixel is about to be written to the frame buffer the depth buffer is checked to see if the pixel is in front of all other pixels written at that point. If not, the pixel is not written. If depth checking is off, pixels are written no matter what has been rendered before. Also see depth_func for more advanced depth check configuration.

Default: depth_check on
[depth_write]
Sets whether or not this pass renders with depth-buffer writing on or not.
Format: depth_write <on|off>

If depth-buffer writing is on, whenever a pixel is written to the frame buffer the depth buffer is updated with the depth value of that new pixel, thus affecting future rendering operations if future pixels are behind this one. If depth writing is off, pixels are written without updating the depth buffer. Depth writing should normally be on but can be turned off when rendering static backgrounds or when rendering a collection of transparent objects at the end of a scene so that they overlap each other correctly.

Default: depth_write on
[depth_func]
Sets the function used to compare depth values when depth checking is on.

Format: depth_func <func>

If depth checking is enabled (see depth_check) a comparison occurs between the depth value of the pixel to be written and the current contents of the buffer. This comparison is normally less_equal, i.e. the pixel is written if it is closer (or at the same distance) than the current contents. The possible functions are: 
always_fail 
Never writes a pixel to the render target 
always_pass 
Always writes a pixel to the render target 
less 
Write if (new_Z < existing_Z) 
less_equal 
Write if (new_Z <= existing_Z) 
equal 
Write if (new_Z == existing_Z) 
not_equal 
Write if (new_Z != existing_Z) 
greater_equal 
Write if (new_Z >= existing_Z) 
greater 
Write if (new_Z >existing_Z) 

Default: depth_func less_equal
[depth_bias]
Sets the bias applied to the depth value of this pass. Can be used to make coplanar polygons appear on top of others e.g. for decals. 

Format: depth_bias <constant_bias> [<slopescale_bias>]

The final depth bias value is constant_bias * minObservableDepth + maxSlope * slopescale_bias. Slope scale biasing is relative to the angle of the polygon to the camera, which makes for a more appropriate bias value, but this is ignored on some older hardware. Constant biasing is expressed as a factor of the minimum depth value, so a value of 1 will nudge the depth by one 'notch' if you will.
[alpha_rejection]
Sets the way the pass will have use alpha to totally reject pixels from the pipeline.

Format: alpha_rejection <function> <value>

Example: alpha_rejection greater_equal 128

The function parameter can be any of the options listed in the material depth_function attribute. The value parameter can theoretically be any value between 0 and 255, but is best limited to 0 or 128 for hardware compatibility.

Default: alpha_rejection always_pass
[cull_hardware]
Sets the hardware culling mode for this pass.

Format: cull_hardware <clockwise|anticlockwise|none>

A typical way for the hardware rendering engine to cull triangles is based on the 'vertex winding' of triangles. Vertex winding refers to the direction in which the vertices are passed or indexed to in the rendering operation as viewed from the camera, and will wither be clockwise or anticlockwise (that's 'counterclockwise' for you Americans out there ;). If the option 'cull_hardware clockwise' is set, all triangles whose vertices are viewed in clockwise order from the camera will be culled by the hardware. 'anticlockwise' is the reverse (obviously), and 'none' turns off hardware culling so all triagles are rendered (useful for creating 2-sided passes).

Default: cull_hardware clockwise
NB this is the same as OpenGL's default but the opposite of Direct3D's default (because Ogre uses a right-handed coordinate system like OpenGL). 
[cull_software]
Sets the software culling mode for this pass.

Format: cull_software <back|front|none>

In some situations the engine will also cull geometry in software before sending it to the hardware renderer. This setting only takes effect on SceneManager's that use it (since it is best used on large groups of planar world geometry rather than on movable geometry since this would be expensive), but if used can cull geometry before it is sent to the hardware. In this case the culling is based on whether the 'back' or 'front' of the traingle is facing the camera - this definition is based on the face normal (a vector which sticks out of the front side of the polygon perpendicular to the face). Since Ogre expects face normals to be on anticlockwise side of the face, 'cull_software back' is the software equivalent of 'cull_hardware clockwise' setting, which is why they are both the default. The naming is different to reflect the way the culling is done though, since most of the time face normals are precalculated and they don't have to be the way Ogre expects - you could set 'cull_hardware none' and completely cull in software based on your own face normals, if you have the right SceneManager which uses them.

Default: cull_software back
[lighting]
Sets whether or not dynamic lighting is turned on for this pass or not. If lighting is turned off, all objects rendered using the pass will be fully lit. This attribute has no effect if a vertex program is used.

Format: lighting <on|off>

Turning dynamic lighting off makes any ambient, diffuse, specular, emissive and shading properties for this pass redundant. When lighting is turned on, objects are lit according to their vertex normals for diffuse and specular light, and globally for ambient and emissive.

Default: lighting on
[shading]
Sets the kind of shading which should be used for representing dynamic lighting for this pass.

Format: shading <flat|gouraud|phong>

When dynamic lighting is turned on, the effect is to generate colour values at each vertex. Whether these values are interpolated across the face (and how) depends on this setting.


flat 
No interpolation takes place. Each face is shaded with a single colour determined from the first vertex in the face. 
gouraud 
Colour at each vertex is linearly interpolated across the face. 
phong 
Vertex normals are interpolated across the face, and these are used to determine colour at each pixel. Gives a more natural lighting effect but is more expensive and works better at high levels of tesselation. Not supported on all hardware. 
Default: shading gouraud
[polygon_mode]
Sets how polygons should be rasterised, ie whether they should be filled in, or just drawn as lines or points.

Format: polygon_mode <solid|wireframe|points>


solid 
The normal situation - polygons are filled in. 
wireframe 
Polygons are drawn in outline only. 
points 
Only the points of each polygon are rendered. 
Default: polygon_mode solid
[fog_override]
Tells the pass whether it should override the scene fog settings, and enforce it's own. Very useful for things that you don't want to be affected by fog when the rest of the scene is fogged, or vice versa. Note that this only affects fixed-function fog - the original scene fog parameters are still sent to shaders which use the fog_params parameter binding (this allows you to turn off fixed function fog and calculate it in the shader instead; if you want to disable shader fog you can do that through shader parameters anyway). 

Format: fog_override <override?> [<type> <colour> <density> <start> <end>]

Default: fog_override false

If you specify 'true' for the first parameter and you supply the rest of the parameters, you are telling the pass to use these fog settings in preference to the scene settings, whatever they might be. If you specify 'true' but provide no further parameters, you are telling this pass to never use fogging no matter what the scene says. Here is an explanation of the parameters:

type 
none = No fog, equivalent of just using 'fog_override true'
linear = Linear fog from the <start> and <end> distances
exp = Fog increases exponentially from the camera (fog = 1/e^(distance * density)), use <density> param to control it
exp2 = Fog increases at the square of FOG_EXP, i.e. even quicker (fog = 1/e^(distance * density)^2), use <density> param to control it 
colour 
Sequence of 3 floating point values from 0 to 1 indicating the red, green and blue intensities 
density 
The density parameter used in the 'exp' or 'exp2' fog types. Not used in linear mode but param must still be there as a placeholder 
start 
The start distance from the camera of linear fog. Must still be present in other modes, even though it is not used. 
end 
The end distance from the camera of linear fog. Must still be present in other modes, even though it is not used. 

Example: fog_override true exp 1 1 1 0.002 100 10000 
[colour_write]
Sets whether or not this pass renders with colour writing on or not.
Format: colour_write <on|off>

If colour writing is off no visible pixels are written to the screen during this pass. You might think this is useless, but if you render with colour writing off, and with very minimal other settings, you can use this pass to initialise the depth buffer before subsequently rendering other passes which fill in the colour data. This can give you significant performance boosts on some newer cards, especially when using complex fragment programs, because if the depth check fails then the fragment program is never run. 

Default: colour_write on
[start_light]
Sets the first light which will be considered for use with this pass.

Format: start_light <number>

You can use this attribute to offset the starting point of the lights for this pass. In other words, if you set start_light to 2 then the first light to be processed in that pass will be the third actual light in the applicable list. You could use this option to use different passes to process the first couple of lights versus the second couple of lights for example, or use it in conjunction with the iteration option to start the iteration from a given point in the list (e.g. doing the first 2 lights in the first pass, and then iterating every 2 lights from then on perhaps). 

Default: start_light 0
[max_lights]
Sets the maximum number of lights which will be considered for use with this pass.

Format: max_lights <number>

The maximum number of lights which can be used when rendering fixed-function materials is set by the rendering system, and is typically set at 8. When you are using the programmable pipeline (See section 3.1.9 Using Vertex and Fragment Programs in a Pass) this limit is dependent on the program you are running, or, if you use 'iteration once_per_light' or a variant (See section iteration), it effectively only bounded by the number of passes you are willing to use. If you are not using pass iteration, the light limit applies once for this pass. If you are using pass iteration, the light limit applies across all iterations of this pass - for example if you have 12 lights in range with an 'iteration once_per_light' setup but your max_lights is set to 4 for that pass, the pass will only iterate 4 times. 

Default: max_lights 8
[iteration]
Sets whether or not this pass is iterated, ie issued more than once.

Format 1: iteration <once | once_per_light> [lightType]

Format 2: iteration <number> [<per_light> [lightType]]

Format 3: iteration <number> [<per_n_lights> <num_lights> [lightType]]

Examples: 
iteration once 
The pass is only executed once which is the default behaviour. 
iteration once_per_light point 
The pass is executed once for each point light. 
iteration 5 
The render state for the pass will be setup and then the draw call will execute 5 times. 
iteration 5 per_light point 
The render state for the pass will be setup and then the draw call will execute 5 times. This will be done for each point light. 
iteration 1 per_n_lights 2 point 
The render state for the pass will be setup and the draw call executed once for every 2 lights. 

By default, passes are only issued once. However, if you use the programmable pipeline, or you wish to exceed the normal limits on the number of lights which are supported, you might want to use the once_per_light option. In this case, only light index 0 is ever used, and the pass is issued multiple times, each time with a different light in light index 0. Clearly this will make the pass more expensive, but it may be the only way to achieve certain effects such as per-pixel lighting effects which take into account 1..n lights.

Using a number instead of "once" instructs the pass to iterate more than once after the render state is setup. The render state is not changed after the initial setup so repeated draw calls are very fast and ideal for passes using programmable shaders that must iterate more than once with the same render state ie. shaders that do fur, motion blur, special filtering.

If you use once_per_light, you should also add an ambient pass to the technique before this pass, otherwise when no lights are in range of this object it will not get rendered at all; this is important even when you have no ambient light in the scene, because you would still want the objects sihouette to appear.

The lightType parameter to the attribute only applies if you use once_per_light, per_light, or per_n_lights and restricts the pass to being run for lights of a single type (either 'point', 'directional' or 'spot'). In the example, the pass will be run once per point light. This can be useful because when you're writing a vertex / fragment program it is a lot easier if you can assume the kind of lights you'll be dealing with. However at least point and directional lights can be dealt with in one way. 

Default: iteration once
[point_size]
This setting allows you to change the size of points when rendering a point list, or a list of point sprites. The interpretation of this command depends on the point_size_attenuation option - if it is off (the default), the point size is in screen pixels, if it is on, it expressed as normalised screen coordinates (1.0 is the height of the screen) when the point is at the origin. 

NOTE: Some drivers have an upper limit on the size of points they support - this can even vary between APIs on the same card! Don't rely on point sizes that cause the points to get very large on screen, since they may get clamped on some cards. Upper sizes can range from 64 to 256 pixels.

Format: point_size <size>

Default: point_size 1.0
[point_sprites]
This setting specifies whether or not hardware point sprite rendering is enabled for this pass. Enabling it means that a point list is rendered as a list of quads rather than a list of dots. It is very useful to use this option if you're using a billboardset and only need to use point oriented billboards which are all of the same size. You can also use it for any other point list render. 

Format: point_sprites <on|off>

Default: point_sprites off
[point_size_attenuation]
Defines whether point size is attenuated with view space distance, and in what fashion. This option is especially useful when you're using point sprites (See section point_sprites) since it defines how they reduce in size as they get further away from the camera. You can also disable this option to make point sprites a constant screen size (like points), or enable it for points so they change size with distance.

You only have to provide the final 3 parameters if you turn attenuation on. The formula for attenuation is that the size of the point is multiplied by 1 / (constant + linear * dist + quadratic * d^2); therefore turning it off is equivalent to (constant = 1, linear = 0, quadratic = 0) and standard perspective attenuation is (constant = 0, linear = 1, quadratic = 0). The latter is assumed if you leave out the final 3 parameters when you specify 'on'.

Note that the resulting attenuated size is clamped to the minimum and maximum point size, see the next section.

Format: point_size_attenuation <on|off> [constant linear quadratic] Default: point_size_attenuation off 
[point_size_min]
Sets the minimum point size after attenuation (point_size_attenuation). For details on the size metrics, See section point_size.

Format: point_size_min <size> Default: point_size_min 0
[point_size_max]
Sets the maximum point size after attenuation (point_size_attenuation). For details on the size metrics, See section point_size. A value of 0 means the maximum is set to the same as the max size reported by the current card. 

Format: point_size_max <size> Default: point_size_max 0 
#
# Texture Unit Docs
#
[texture_alias]
Sets the alias name for this texture unit.

Format: texture_alias <name>

Example: texture_alias NormalMap

Setting the texture alias name is usefull if this material is to be copied by other other materials and only the textures will be changed in the new material.(See section 3.1.11 Copying Materials)

Default: If a texture_unit has a name then the texture_alias defaults to the texture_unit name.
[texture]
Sets the name of the static texture image this layer will use.

Format: texture <texturename> [<type>] [unlimited | numMipMaps] [alpha] [<PixelFormat>]

Example: texture funkywall.jpg

This setting is mutually exclusive with the anim_texture attribute. Note that the texture file cannot include spaces. Those of you Windows users who like spaces in filenames, please get over it and use underscores instead.

The 'type' parameter allows you to specify a the type of texture to create - the default is '2d', but you can override this; here's the full list: 
1d 
A 1-dimensional texture; that is, a texture which is only 1 pixel high. These kinds of textures can be useful when you need to encode a function in a texture and use it as a simple lookup, perhaps in a fragment program. It is important that you use this setting when you use a fragment program which uses 1-dimensional texture coordinates, since GL requires you to use a texture type that matches (D3D will let you get away with it, but you ought to plan for cross-compatibility). Your texture widths should still be a power of 2 for best compatibility and performance. 
2d 
The default type which is assumed if you omit it, your texture has a width and a height, both of which should preferably be powers of 2, and if you can, make them square because this will look best on the most hardware. These can be addressed with 2D texture coordinates. 
3d 
A 3 dimensional texture ie volume texture. Your texture has a width, a height, both of which should be powers of 2, and has depth. These can be addressed with 3d texture coordinates ie through a pixel shader. 
cubic 
This texture is made up of 6 2D textures which are pasted around the inside of a cube. Can be addressed with 3D texture coordinates and are useful for cubic reflection maps and normal maps. 
The 'numMipMaps' option allows you to specify the number of mipmaps to generate for this texture. The default is 'unlimited' which means mips down to 1x1 size are generated. You can specify a fixed number (even 0) if you like instead. Note that if you use the same texture in many material scripts, the number of mipmaps generated will conform to the number specified in the first texture_unit used to load the texture - so be consistent with your usage.

The 'alpha' option allows you to specify that a single channel (luminence) texture should be loaded as alpha, rather than the default which is to load it into the red channel. This can be helpful if you want to use alpha-only textures in the fixed function pipeline. Default: none

The <PixelFormat> option allows you to specify the desired pixel format of the texture to create, which may be different to the pixel format of the texture file being loaded. Bear in mind that the final pixel format will be constrained by hardware capabilities so you may not get exactly what you ask for. The available options are: 
PF_L8 
8-bit pixel format, all bits luminace. 
PF_L16 
16-bit pixel format, all bits luminace. 
PF_A8 
8-bit pixel format, all bits alpha. 
PF_A4L4 
8-bit pixel format, 4 bits alpha, 4 bits luminace. 
PF_BYTE_LA 
2 byte pixel format, 1 byte luminance, 1 byte alpha 
PF_R5G6B5 
16-bit pixel format, 5 bits red, 6 bits green, 5 bits blue. 
PF_B5G6R5 
16-bit pixel format, 5 bits blue, 6 bits green, 5 bits red. 
PF_R3G3B2 
8-bit pixel format, 3 bits red, 3 bits green, 2 bits blue. 
PF_A4R4G4B4 
16-bit pixel format, 4 bits for alpha, red, green and blue. 
PF_A1R5G5B5 
16-bit pixel format, 1 bit for alpha, 5 bits for red, green and blue. 
PF_R8G8B8 
24-bit pixel format, 8 bits for red, green and blue. 
PF_B8G8R8 
24-bit pixel format, 8 bits for blue, green and red. 
PF_A8R8G8B8 
32-bit pixel format, 8 bits for alpha, red, green and blue. 
PF_A8B8G8R8 
32-bit pixel format, 8 bits for alpha, blue, green and red. 
PF_B8G8R8A8 
32-bit pixel format, 8 bits for blue, green, red and alpha. 
PF_R8G8B8A8 
32-bit pixel format, 8 bits for red, green, blue and alpha. 
PF_X8R8G8B8 
32-bit pixel format, 8 bits for red, 8 bits for green, 8 bits for blue like PF_A8R8G8B8, but alpha will get discarded 
PF_X8B8G8R8 
32-bit pixel format, 8 bits for blue, 8 bits for green, 8 bits for red like PF_A8B8G8R8, but alpha will get discarded 
PF_A2R10G10B10 
32-bit pixel format, 2 bits for alpha, 10 bits for red, green and blue. 
PF_A2B10G10R10 
32-bit pixel format, 2 bits for alpha, 10 bits for blue, green and red. 
PF_FLOAT16_R 
16-bit pixel format, 16 bits (float) for red 
PF_FLOAT16_RGB 
48-bit pixel format, 16 bits (float) for red, 16 bits (float) for green, 16 bits (float) for blue 
PF_FLOAT16_RGBA 
64-bit pixel format, 16 bits (float) for red, 16 bits (float) for green, 16 bits (float) for blue, 16 bits (float) for alpha 
PF_FLOAT32_R 
16-bit pixel format, 16 bits (float) for red 
PF_FLOAT32_RGB 
96-bit pixel format, 32 bits (float) for red, 32 bits (float) for green, 32 bits (float) for blue 
PF_FLOAT32_RGBA 
128-bit pixel format, 32 bits (float) for red, 32 bits (float) for green, 32 bits (float) for blue, 32 bits (float) for alpha 
PF_SHORT_RGBA 
64-bit pixel format, 16 bits for red, green, blue and alpha 
[anim_texture]
Sets the images to be used in an animated texture layer. In this case an animated texture layer means one which has multiple frames, each of which is a separate image file. There are 2 formats, one for implicitly determined image names, one for explicitly named images.

Format1 (short): anim_texture <base_name> <num_frames> <duration>

Example: anim_texture flame.jpg 5 2.5

This sets up an animated texture layer made up of 5 frames named flame_0.jpg, flame_1.jpg, flame_2.jpg etc, with an animation length of 2.5 seconds (2fps). If duration is set to 0, then no automatic transition takes place and frames must be changed manually in code.

Format2 (long): anim_texture <frame1> <frame2> ... <duration>

Example: anim_texture flamestart.jpg flamemore.png flameagain.jpg moreflame.jpg lastflame.tga 2.5

This sets up the same duration animation but from 5 separately named image files. The first format is more concise, but the second is provided if you cannot make your images conform to the naming standard required for it. 

Default: none
[cubic_texture]
Sets the images used in a cubic texture, i.e. one made up of 6 individual images making up the faces of a cube. These kinds of textures are used for reflection maps (if hardware supports cubic reflection maps) or skyboxes. There are 2 formats, a brief format expecting image names of a particular format and a more flexible but longer format for arbitrarily named textures.

Format1 (short): cubic_texture <base_name> <combinedUVW|separateUV>

The base_name in this format is something like 'skybox.jpg', and the system will expect you to provide skybox_fr.jpg, skybox_bk.jpg, skybox_up.jpg, skybox_dn.jpg, skybox_lf.jpg, and skybox_rt.jpg for the individual faces.

Format2 (long): cubic_texture <front> <back> <left> <right> <up> <down> separateUV

In this case each face is specified explicitly, incase you don't want to conform to the image naming standards above. You can only use this for the separateUV version since the combinedUVW version requires a single texture name to be assigned to the combined 3D texture (see below).

In both cases the final parameter means the following: 
combinedUVW 
The 6 textures are combined into a single 'cubic' texture map which is then addressed using 3D texture coordinates with U, V and W components. Necessary for reflection maps since you never know which face of the box you are going to need. Note that not all cards support cubic environment mapping. 
separateUV 
The 6 textures are kept separate but are all referenced by this single texture layer. One texture at a time is active (they are actually stored as 6 frames), and they are addressed using standard 2D UV coordinates. This type is good for skyboxes since only one face is rendered at one time and this has more guaranteed hardware support on older cards. 

Default: none 
[binding_type]
Tells this texture unit to bind to either the fragment processing unit or the vertex processing unit (for 3.1.10 Vertex Texture Fetch). 

Format: binding_type <vertex|fragment> Default: binding_type fragment 
[content_type]
Tells this texture unit where it should get its content from. The default is to get texture content from a named texture, as defined with the texture, cubic_texture, anim_texture attributes. However you can also pull texture information from other automated sources. The options are: 
named 
The default option, this derives texture content from a texture name, loaded by ordinary means from a file or having been manually created with a given name. 
shadow 
This option allows you to pull in a shadow texture, and is only valid when you use texture shadows and one of the 'custom sequence' shadowing types (See section 7. Shadows). The shadow texture in question will be from the 'n'th closest light that casts shadows, unless you use light-based pass iteration or the light_start option which may start the light index higher. When you use this option in multiple texture units within the same pass, each one references the next shadow texture. The shadow texture index is reset in the next pass, in case you want to take into account the same shadow textures again in another pass (e.g. a separate specular / gloss pass). By using this option, the correct light frustum projection is set up for you for use in fixed-function, if you use shaders just reference the texture_viewproj_matrix auto parameter in your shader. 
Format: content_type <named|shadow> Default: content_type named 
[tex_coord_set]
Sets which texture coordinate set is to be used for this texture layer. A mesh can define multiple sets of texture coordinates, this sets which one this material uses.

Format: tex_coord_set <set_num>

Example: tex_coord_set 2

Default: tex_coord_set 0
[tex_address_mode]
Defines what happens when texture coordinates exceed 1.0 for this texture layer.You can use the simple format to specify the addressing mode for all 3 potential texture coordinates at once, or you can use the 2/3 parameter extended format to specify a different mode per texture coordinate. 

Simple Format: tex_address_mode <uvw_mode> 
Extended Format: tex_address_mode <u_mode> <v_mode> [<w_mode>] 
wrap 
Any value beyond 1.0 wraps back to 0.0. Texture is repeated. 
clamp 
Values beyond 1.0 are clamped to 1.0. Texture 'streaks' beyond 1.0 since last line of pixels is used across the rest of the address space. Useful for textures which need exact coverage from 0.0 to 1.0 without the 'fuzzy edge' wrap gives when combined with filtering. 
mirror 
Texture flips every boundary, meaning texture is mirrored every 1.0 u or v 
border 
Values outside the range [0.0, 1.0] are set to the border colour, you might also set the tex_border_colour attribute too. 

Default: tex_address_mode wrap
[tex_border_colour]
Sets the border colour of border texture address mode (see tex_address_mode). 

Format: tex_border_colour <red> <green> <blue> [<alpha>]
NB valid colour values are between 0.0 and 1.0.

Example: tex_border_colour 0.0 1.0 0.3

Default: tex_border_colour 0.0 0.0 0.0 1.0
[filtering]
Sets the type of texture filtering used when magnifying or minifying a texture. There are 2 formats to this attribute, the simple format where you simply specify the name of a predefined set of filtering options, and the complex format, where you individually set the minification, magnification, and mip filters yourself.

Simple Format
Format: filtering <none|bilinear|trilinear|anisotropic>
Default: filtering bilinear

With this format, you only need to provide a single parameter which is one of the following: 
none 
No filtering or mipmapping is used. This is equivalent to the complex format 'filtering point point none'. 
bilinear 
2x2 box filtering is performed when magnifying or reducing a texture, and a mipmap is picked from the list but no filtering is done between the levels of the mipmaps. This is equivalent to the complex format 'filtering linear linear point'. 
trilinear 
2x2 box filtering is performed when magnifying and reducing a texture, and the closest 2 mipmaps are filtered together. This is equivalent to the complex format 'filtering linear linear linear'. 
anisotropic 
This is the same as 'trilinear', except the filtering algorithm takes account of the slope of the triangle in relation to the camera rather than simply doing a 2x2 pixel filter in all cases. This makes triangles at acute angles look less fuzzy. Equivalent to the complex format 'filtering anisotropic anisotropic linear'. Note that in order for this to make any difference, you must also set the max_anisotropy attribute too. 


Complex Format
Format: filtering <minification> <magnification> <mip>
Default: filtering linear linear point

This format gives you complete control over the minification, magnification, and mip filters. Each parameter can be one of the following: 
none 
Nothing - only a valid option for the 'mip' filter , since this turns mipmapping off completely. The lowest setting for min and mag is 'point'. 
point 
Pick the closet pixel in min or mag modes. In mip mode, this picks the closet matching mipmap. 
linear 
Filter a 2x2 box of pixels around the closest one. In the 'mip' filter this enables filtering between mipmap levels. 
anisotropic 
Only valid for min and mag modes, makes the filter compensate for camera-space slope of the triangles. Note that in order for this to make any difference, you must also set the max_anisotropy attribute too.
[max_anisotropy]
Sets the maximum degree of anisotropy that the renderer will try to compensate for when filtering textures. The degree of anisotropy is the ratio between the height of the texture segment visible in a screen space region versus the width - so for example a floor plane, which stretches on into the distance and thus the vertical texture coordinates change much faster than the horizontal ones, has a higher anisotropy than a wall which is facing you head on (which has an anisotropy of 1 if your line of sight is perfectly perpendicular to it). You should set the max_anisotropy value to something greater than 1 to begin compensating; higher values can compensate for more acute angles. The maximum value is determined by the hardware, but it is usually 8 or 16. 

In order for this to be used, you have to set the minification and/or the magnification filtering option on this texture to anisotropic. Format: max_anisotropy <value>
Default: max_anisotropy 1 
[mipmap_bias]
Sets the bias value applied to the mipmapping calculation, thus allowing you to alter the decision of which level of detail of the texture to use at any distance. The bias value is applied after the regular distance calculation, and adjusts the mipmap level by 1 level for each unit of bias. Negative bias values force larger mip levels to be used, positive bias values force smaller mip levels to be used. The bias is a floating point value so you can use values in between whole numbers for fine tuning.

In order for this option to be used, your hardware has to support mipmap biasing (exposed through the render system capabilities), and your minification filtering has to be set to point or linear. Format: mipmap_bias <value>
Default: mipmap_bias 0
[colour_op]
Determines how the colour of this texture layer is combined with the one below it (or the lighting effect on the geometry if this is the first layer).

Format: colour_op <replace|add|modulate|alpha_blend>

This method is the simplest way to blend texture layers, because it requires only one parameter, gives you the most common blending types, and automatically sets up 2 blending methods: one for if single-pass multitexturing hardware is available, and another for if it is not and the blending must be achieved through multiple rendering passes. It is, however, quite limited and does not expose the more flexible multitexturing operations, simply because these can't be automatically supported in multipass fallback mode. If want to use the fancier options, use colour_op_ex, but you'll either have to be sure that enough multitexturing units will be available, or you should explicitly set a fallback using colour_op_multipass_fallback.

replace 
Replace all colour with texture with no adjustment. 
add 
Add colour components together. 
modulate 
Multiply colour components together. 
alpha_blend 
Blend based on texture alpha. 

Default: colour_op modulate 
[colour_op_ex]
This is an extended version of the colour_op attribute which allows extremely detailed control over the blending applied between this and earlier layers. Multitexturing hardware can apply more complex blending operations that multipass blendind, but you are limited to the number of texture units which are available in hardware.

Format: colour_op_ex <operation> <source1> <source2> [<manual_factor>] [<manual_colour1>] [<manual_colour2>]

Example colour_op_ex add_signed src_manual src_current 0.5

See the IMPORTANT note below about the issues between mulitpass and multitexturing that using this method can create. Texture colour operations determine how the final colour of the surface appears when rendered. Texture units are used to combine colour values from various sources (e.g. the diffuse colour of the surface from lighting calculations, combined with the colour of the texture). This method allows you to specify the 'operation' to be used, i.e. the calculation such as adds or multiplies, and which values to use as arguments, such as a fixed value or a value from a previous calculation.


Operation options 
source1 
Use source1 without modification 
source2 
Use source2 without modification 
modulate 
Multiply source1 and source2 together. 
modulate_x2 
Multiply source1 and source2 together, then by 2 (brightening). 
modulate_x4 
Multiply source1 and source2 together, then by 4 (brightening). 
add 
Add source1 and source2 together. 
add_signed 
Add source1 and source2 then subtract 0.5. 
add_smooth 
Add source1 and source2, subtract the product 
subtract 
Subtract source2 from source1 
blend_diffuse_alpha 
Use interpolated alpha value from vertices to scale source1, then add source2 scaled by (1-alpha). 
blend_texture_alpha 
As blend_diffuse_alpha but use alpha from texture 
blend_current_alpha 
As blend_diffuse_alpha but use current alpha from previous stages (same as blend_diffuse_alpha for first layer) 
blend_manual 
As blend_diffuse_alpha but use a constant manual alpha value specified in <manual> 
dotproduct 
The dot product of source1 and source2 
blend_diffuse_colour 
Use interpolated colour value from vertices to scale source1, then add source2 scaled by (1-colour). 
Source1 and source2 options 
src_current 
The colour as built up from previous stages. 
src_texture 
The colour derived from the texture assigned to this layer. 
src_diffuse 
The interpolated diffuse colour from the vertices (same as 'src_current' for first layer). 
src_specular 
The interpolated specular colour from the vertices. 
src_manual 
The manual colour specified at the end of the command. 

For example 'modulate' takes the colour results of the previous layer, and multiplies them with the new texture being applied. Bear in mind that colours are RGB values from 0.0-1.0 so multiplying them together will result in values in the same range, 'tinted' by the multiply. Note however that a straight multiply normally has the effect of darkening the textures - for this reason there are brightening operations like modulate_x2. Note that because of the limitations on some underlying APIs (Direct3D included) the 'texture' argument can only be used as the first argument, not the second. 

Note that the last parameter is only required if you decide to pass a value manually into the operation. Hence you only need to fill these in if you use the 'blend_manual' operation.

IMPORTANT: Ogre tries to use multitexturing hardware to blend texture layers together. However, if it runs out of texturing units (e.g. 2 of a GeForce2, 4 on a GeForce3) it has to fall back on multipass rendering, i.e. rendering the same object multiple times with different textures. This is both less efficient and there is a smaller range of blending operations which can be performed. For this reason, if you use this method you really should set the colour_op_multipass_fallback attribute to specify which effect you want to fall back on if sufficient hardware is not available (the default is just 'modulate' which is unlikely to be what you want if you're doing swanky blending here). If you wish to avoid having to do this, use the simpler colour_op attribute which allows less flexible blending options but sets up the multipass fallback automatically, since it only allows operations which have direct multipass equivalents.

Default: none (colour_op modulate)
[colour_op_multipass_fallback]
Sets the multipass fallback operation for this layer, if you used colour_op_ex and not enough multitexturing hardware is available.

Format: colour_op_multipass_fallback <src_factor> <dest_factor>

Example: colour_op_mulitpass_fallback one one_minus_dest_alpha

Because some of the effects you can create using colour_op_ex are only supported under multitexturing hardware, if the hardware is lacking the system must fallback on multipass rendering, which unfortunately doesn't support as many effects. This attribute is for you to specify the fallback operation which most suits you.

The parameters are the same as in the scene_blend attribute; this is because multipass rendering IS effectively scene blending, since each layer is rendered on top of the last using the same mechanism as making an object transparent, it's just being rendered in the same place repeatedly to get the multitexture effect. If you use the simpler (and less flexible) colour_op attribute you don't need to call this as the system sets up the fallback for you.
[alpha_op_ex]
Behaves in exactly the same away as colour_op_ex except that it determines how alpha values are combined between texture layers rather than colour values.The only difference is that the 2 manual colours at the end of colour_op_ex are just single floating-point values in alpha_op_ex. 
[env_map]
Turns on/off texture coordinate effect that makes this layer an environment map.

Format: env_map <off|spherical|planar|cubic_reflection|cubic_normal>

Environment maps make an object look reflective by using automatic texture coordinate generation depending on the relationship between the objects vertices or normals and the eye.


spherical 
A spherical environment map. Requires a single texture which is either a fish-eye lens view of the reflected scene, or some other texture which looks good as a spherical map (a texture of glossy highlights is popular especially in car sims). This effect is based on the relationship between the eye direction and the vertex normals of the object, so works best when there are a lot of gradually changing normals, i.e. curved objects. 
planar 
Similar to the spherical environment map, but the effect is based on the position of the vertices in the viewport rather than vertex normals. This effect is therefore useful for planar geometry (where a spherical env_map would not look good because the normals are all the same) or objects without normals. 
cubic_reflection 
A more advanced form of reflection mapping which uses a group of 6 textures making up the inside of a cube, each of which is a view if the scene down each axis. Works extremely well in all cases but has a higher technical requirement from the card than spherical mapping. Requires that you bind a cubic_texture to this texture unit and use the 'combinedUVW' option. 
cubic_normal 
Generates 3D texture coordinates containing the camera space normal vector from the normal information held in the vertex data. Again, full use of this feature requires a cubic_texture with the 'combinedUVW' option. 

Default: env_map off
[scroll]
Sets a fixed scroll offset for the texture.

Format: scroll <x> <y>

This method offsets the texture in this layer by a fixed amount. Useful for small adjustments without altering texture coordinates in models. However if you wish to have an animated scroll effect, see the scroll_anim attribute.
[scroll_anim]
Sets up an animated scroll for the texture layer. Useful for creating fixed-speed scrolling effects on a texture layer (for varying scroll speeds, see wave_xform).

Format: scroll_anim <xspeed> <yspeed>
[rotate_anim]
Sets up an animated rotation effect of this layer. Useful for creating fixed-speed rotation animations (for varying speeds, see wave_xform).

Format: rotate_anim <revs_per_second>

The parameter is a number of anticlockwise revolutions per second.
[scale]
Adjusts the scaling factor applied to this texture layer. Useful for adjusting the size of textures without making changes to geometry. This is a fixed scaling factor, if you wish to animate this see wave_xform.

Format: scale <x_scale> <y_scale>

Valid scale values are greater than 0, with a scale factor of 2 making the texture twice as big in that dimension etc.
[wave_xform]
Sets up a transformation animation based on a wave function. Useful for more advanced texture layer transform effects. You can add multiple instances of this attribute to a single texture layer if you wish.

Format: wave_xform <xform_type> <wave_type> <base> <frequency> <phase> <amplitude>

Example: wave_xform scale_x sine 1.0 0.2 0.0 5.0


xform_type 
scroll_x 
Animate the x scroll value 
scroll_y 
Animate the y scroll value 
rotate 
Animate the rotate value 
scale_x 
Animate the x scale value 
scale_y 
Animate the y scale value 
wave_type 
sine 
A typical sine wave which smoothly loops between min and max values 
triangle 
An angled wave which increases & decreases at constant speed, changing instantly at the extremes 
square 
Max for half the wavelength, min for the rest with instant transition between 
sawtooth 
Gradual steady increase from min to max over the period with an instant return to min at the end. 
inverse_sawtooth 
Gradual steady decrease from max to min over the period, with an instant return to max at the end. 
base 
The base value, the minimum if amplitude > 0, the maximum if amplitdue < 0 
frequency 
The number of wave iterations per second, i.e. speed 
phase 
Offset of the wave start 
amplitude 
The size of the wave 

The range of the output of the wave will be {base, base+amplitude}. So the example above scales the texture in the x direction between 1 (normal size) and 5 along a sine wave at one cycle every 5 second (0.2 waves per second).
[trasform]
This attribute allows you to specify a static 4x4 transformation matrix for the texture unit, thus replacing the individual scroll, rotate and scale attributes mentioned above. 

Format: transform m00 m01 m02 m03 m10 m11 m12 m13 m20 m21 m22 m23 m30 m31 m32 m33

The indexes of the 4x4 matrix value above are expressed as m<row><col>. 
#
# Shader Pass Docs
#
[param_indexed]
This command sets the value of an indexed parameter. 

format: param_indexed <index> <type> <value>

example: param_indexed 0 float4 10.0 0 0 0

The 'index' is simply a number representing the position in the parameter list which the value should be written, and you should derive this from your program definition. The index is relative to the way constants are stored on the card, which is in 4-element blocks. For example if you defined a float4 parameter at index 0, the next index would be 1. If you defined a matrix4x4 at index 0, the next usable index would be 4, since a 4x4 matrix takes up 4 indexes.

The value of 'type' can be float4, matrix4x4, float<n>, int4, int<n>. Note that 'int' parameters are only available on some more advanced program syntaxes, check the D3D or GL vertex / fragment program documentation for full details. Typically the most useful ones will be float4 and matrix4x4. Note that if you use a type which is not a multiple of 4, then the remaining values up to the multiple of 4 will be filled with zeroes for you (since GPUs always use banks of 4 floats per constant even if only one is used).

'value' is simply a space or tab-delimited list of values which can be converted into the type you have specified. 
[param_indexed_auto]
This command tells Ogre to automatically update a given parameter with a derived value. This frees you from writing code to update program parameters every frame when they are always changing.

format: param_indexed_auto <index> <value_code> <extra_params>

example: param_indexed_auto 0 worldviewproj_matrix

'index' has the same meaning as param_indexed; note this time you do not have to specify the size of the parameter because the engine knows this already. In the example, the world/view/projection matrix is being used so this is implicitly a matrix4x4.

'value_code' is one of a list of recognised values:

world_matrix 
The current world matrix. 
inverse_world_matrix 
The inverse of the current world matrix. 
transpose_world_matrix 
The transpose of the world matrix 
inverse_transpose_world_matrix 
The inverse transpose of the world matrix 
world_matrix_array_3x4 
An array of world matrices, each represented as only a 3x4 matrix (3 rows of 4columns) usually for doing hardware skinning. You should make enough entries available in your vertex program for the number of bones in use, ie an array of numBones*3 float4's. 
view_matrix 
The current view matrix. 
inverse_view_matrix 
The inverse of the current view matrix. 
transpose_view_matrix 
The transpose of the view matrix 
inverse_transpose_view_matrix 
The inverse transpose of the view matrix 
projection_matrix 
The current projection matrix. 
inverse_projection_matrix 
The inverse of the projection matrix 
transpose_projection_matrix 
The transpose of the projection matrix 
inverse_transpose_projection_matrix 
The inverse transpose of the projection matrix 
worldview_matrix 
The current world and view matrices concatenated. 
inverse_worldview_matrix 
The inverse of the current concatenated world and view matrices. 
transpose_worldview_matrix 
The transpose of the world and view matrices 
inverse_transpose_worldview_matrix 
The inverse transpose of the current concatenated world and view matrices. 
viewproj_matrix 
The current view and projection matrices concatenated. 
inverse_viewproj_matrix 
The inverse of the view & projection matrices 
transpose_viewproj_matrix 
The transpose of the view & projection matrices 
inverse_transpose_viewproj_matrix 
The inverse transpose of the view & projection matrices 
worldviewproj_matrix 
The current world, view and projection matrices concatenated. 
inverse_worldviewproj_matrix 
The inverse of the world, view and projection matrices 
transpose_worldviewproj_matrix 
The transpose of the world, view and projection matrices 
inverse_transpose_worldviewproj_matrix 
The inverse transpose of the world, view and projection matrices 
render_target_flipping 
The value use to adjust transformed y position if bypassed projection matrix transform. It's -1 if the render target requires texture flipping, +1 otherwise. 
light_diffuse_colour 
The diffuse colour of a given light; this requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light - note that directional lights are always first in the list and always present). NB if there are no lights this close, then the parameter will be set to black. 
light_specular_colour 
The specular colour of a given light; this requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to black. 
light_attenuation 
A float4 containing the 4 light attenuation variables for a given light. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. The order of the parameters is range, constant attenuation, linear attenuation, quadric attenuation. 
spotlight_params 
A float4 containing the 3 spotlight parameters and a control value. The order of the parameters is cos(inner angle /2 ), cos(outer angle / 2), falloff, and the final w value is 1.0f. For non-spotlights the value is float4(1,0,0,1). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). If there are less lights than this, the details are like a non-spotlight. 
light_position 
The position of a given light in world space. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. Note that this property will work with all kinds of lights, even directional lights, since the parameter is set as a 4D vector. Point lights will be (pos.x, pos.y, pos.z, 1.0f) whilst directional lights will be (-dir.x, -dir.y, -dir.z, 0.0f). Operations like dot products will work consistently on both. 
light_direction 
The direction of a given light in world space. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. DEPRECATED - this property only works on directional lights, and we recommend that you use light_position instead since that returns a generic 4D vector. 
light_position_object_space 
The position of a given light in object space (ie when the object is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. Note that this property will work with all kinds of lights, even directional lights, since the parameter is set as a 4D vector. Point lights will be (pos.x, pos.y, pos.z, 1.0f) whilst directional lights will be (-dir.x, -dir.y, -dir.z, 0.0f). Operations like dot products will work consistently on both. 
light_direction_object_space 
The direction of a given light in object space (ie when the object is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. DEPRECATED, except for spotlights - for directional lights we recommend that you use light_position_object_space instead since that returns a generic 4D vector. 
light_distance_object_space 
The distance of a given light from the centre of the object - this is a useful approximation to per-vertex distance calculations for relatively small objects. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. 
light_position_view_space 
The position of a given light in view space (ie when the camera is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. Note that this property will work with all kinds of lights, even directional lights, since the parameter is set as a 4D vector. Point lights will be (pos.x, pos.y, pos.z, 1.0f) whilst directional lights will be (-dir.x, -dir.y, -dir.z, 0.0f). Operations like dot products will work consistently on both. 
light_direction_view_space 
The direction of a given light in view space (ie when the camera is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. DEPRECATED, except for spotlights - for directional lights we recommend that you use light_position_view_space instead since that returns a generic 4D vector. 
light_power 
The 'power' scaling for a given light, useful in HDR rendering. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). 
light_diffuse_colour_array 
As light_diffuse_colour, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_specular_colour_array 
As light_specular_colour, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_attenuation_array 
As light_attenuation, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
spotlight_params_array 
As spotlight_params, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_position_array 
As light_position, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_direction_array 
As light_direction, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_position_object_space_array 
As light_position_object_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_direction_object_space_array 
As light_direction_object_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_distance_object_space_array 
As light_distance_object_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_position_view_space_array 
As light_position_view_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_direction_view_space_array 
As light_direction_view_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
light_power_array 
As light_power, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
ambient_light_colour 
The colour of the ambient light currently set in the scene. 
surface_ambient_colour 
The ambient colour reflectance properties of the pass (See section ambient). This allows you access to fixed-function pipeline property handily. 
surface_diffuse_colour 
The diffuse colour reflectance properties of the pass (See section diffuse). This allows you access to fixed-function pipeline property handily. 
surface_specular_colour 
The specular colour reflectance properties of the pass (See section specular). This allows you access to fixed-function pipeline property handily. 
surface_emissive_colour 
The amount of self-illumination of the pass (See section emissive). This allows you access to fixed-function pipeline property handily. 
surface_shininess 
The shininess of the pass, affecting the size of specular highlights (See section specular). This allows you bind to fixed-function pipeline property handily. 
derived_ambient_light_colour 
The derived ambient light colour, with 'r', 'g', 'b' components filled with product of surface_ambient_colour and ambient_light_colour, respectively, and 'a' component filled with surface ambient alpha component. 
derived_scene_colour 
The derived scene colour, with 'r', 'g' and 'b' components filled with sum of derived_ambient_light_colour and surface_emissive_colour, respectively, and 'a' component filled with surface diffuse alpha component. 
derived_light_diffuse_colour 
The derived light diffuse colour, with 'r', 'g' and 'b' components filled with product of surface_diffuse_colour and light_diffuse_colour, respectively, and 'a' component filled with surface diffuse alpha component. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). 
derived_light_specular_colour 
The derived light specular colour, with 'r', 'g' and 'b' components filled with product of surface_specular_colour and light_specular_colour, respectively, and 'a' component filled with surface specular alpha component. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). 
derived_light_diffuse_colour_array 
As derived_light_diffuse_colour, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
derived_light_specular_colour_array 
As derived_light_specular_colour, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting. 
fog_colour 
The colour of the fog currently set in the scene. 
fog_params 
The parameters of the fog currently set in the scene. Packed as (exp_density, linear_start, linear_end, 1.0 / (linear_end - linear_start)). 
camera_position 
The current cameras position in world space. 
camera_position_object_space 
The current cameras position in object space (ie when the object is at (0,0,0)). 
time 
The current time, factored by the optional parameter (or 1.0f if not supplied). 
time_0_x 
Single float time value, which repeats itself based on "cycle time" given as an 'extra_params' field 
costime_0_x 
Cosine of time_0_x 
sintime_0_x 
Sine of time_0_x 
tantime_0_x 
Tangent of time_0_x 
time_0_x_packed 
4-element vector of time0_x, sintime0_x, costime0_x, tantime0_x 
time_0_1 
As time0_x but scaled to [0..1] 
costime_0_1 
As costime0_x but scaled to [0..1] 
sintime_0_1 
As sintime0_x but scaled to [0..1] 
tantime_0_1 
As tantime0_x but scaled to [0..1] 
time_0_1_packed 
As time0_x_packed but all values scaled to [0..1] 
time_0_2pi 
As time0_x but scaled to [0..2*Pi] 
costime_0_2pi 
As costime0_x but scaled to [0..2*Pi] 
sintime_0_2pi 
As sintime0_x but scaled to [0..2*Pi] 
tantime_0_2pi 
As tantime0_x but scaled to [0..2*Pi] 
time_0_2pi_packed 
As time0_x_packed but scaled to [0..2*Pi] 
frame_time 
The current frame time, factored by the optional parameter (or 1.0f if not supplied). 
fps 
The current frames per second 
viewport_width 
The current viewport width in pixels 
viewport_height 
The current viewport height in pixels 
inverse_viewport_width 
1.0/the current viewport width in pixels 
inverse_viewport_height 
1.0/the current viewport height in pixels 
viewport_size 
4-element vector of viewport_width, viewport_height, inverse_viewport_width, inverse_viewport_height 
texel_offsets 
Provides details of the rendersystem-specific texture coordinate offsets required to map texels onto pixels. float4(horizontalOffset, verticalOffset, horizontalOffset / viewport_width, verticalOffset / viewport_height). 
view_direction 
View direction vector in object space 
view_side_vector 
View local X axis 
view_up_vector 
View local Y axis 
fov 
Vertical field of view, in radians 
near_clip_distance 
Near clip distance, in world units 
far_clip_distance 
Far clip distance, in world units (may be 0 for infinite view projection) 
texture_viewproj_matrix 
Applicable to vertex programs which have been specified as the 'shadow receiver' vertex program alternative, or where a texture unit is marked as content_type shadow; this provides details of the view/projection matrix for the current shadow projector. The optional 'extra_params' entry specifies which light the projector refers to (for the case of content_type shadow where more than one shadow texture may be present in a single pass), where 0 is the default and refers to the first light referenced in this pass. 
scene_depth_range 
Provides information about the depth range as viewed from the current camera being used to render. Provided as float4(minDepth, maxDepth, depthRange, 1 / depthRange). 
shadow_scene_depth_range 
Provides information about the depth range as viewed from the shadow camera relating to a selected light. Requires a light index parameter. Provided as float4(minDepth, maxDepth, depthRange, 1 / depthRange). 
texture_size 
Provides texture size of the selected texture unit. Requires a texture unit index parameter. Provided as float4(width, height, depth, 1). For 2D-texture, depth sets to 1, for 1D-texture, height and depth sets to 1. 
inverse_texture_size 
Provides inverse texture size of the selected texture unit. Requires a texture unit index parameter. Provided as float4(1 / width, 1 / height, 1 / depth, 1). For 2D-texture, depth sets to 1, for 1D-texture, height and depth sets to 1. 
packed_texture_size 
Provides packed texture size of the selected texture unit. Requires a texture unit index parameter. Provided as float4(width, height, 1 / width, 1 / height). For 3D-texture, depth is ignored, for 1D-texture, height sets to 1. 
pass_number 
Sets the active pass index number in a gpu parameter. The first pass in a technique has an index of 0, the second an index of 1 and so on. This is usefull for multipass shaders (ie fur or blur shader) that need to know what pass it is. By setting up the auto parameter in a Default Program Parameters list in a program definition, there is no requirement to set the pass number parameter in each pass and lose track. (See fur_example) 
pass_iteration_number 
Usefull for GPU programs that need to know what the current pass iteration number is. The first iteration of a pass is numbered 0. The last iteration number is one less than what is set for the pass iteration number. If a pass has its iteration attribute set to 5 then the last iteration number (5th execution of the pass) is 4.(See section iteration) 
animation_parametric 
Useful for hardware vertex animation. For morph animation, sets the parametric value (0..1) representing the distance between the first position keyframe (bound to positions) and the second position keyframe (bound to the first free texture coordinate) so that the vertex program can interpolate between them. For pose animation, indicates a group of up to 4 parametric weight values applying to a sequence of up to 4 poses (each one bound to x, y, z and w of the constant), one for each pose. The original positions are held in the usual position buffer, and the offsets to take those positions to the pose where weight == 1.0 are in the first 'n' free texture coordinates; 'n' being determined by the value passed to includes_pose_animation. If more than 4 simultaneous poses are required, then you'll need more than 1 shader constant to hold the parametric values, in which case you should use this binding more than once, referencing a different constant entry; the second one will contain the parametrics for poses 5-8, the third for poses 9-12, and so on. 
custom 
This allows you to map a custom parameter on an individual Renderable (see Renderable::setCustomParameter) to a parameter on a GPU program. It requires that you complete the 'extra_params' field with the index that was used in the Renderable::setCustomParameter call, and this will ensure that whenever this Renderable is used, it will have it's custom parameter mapped in. It's very important that this parameter has been defined on all Renderables that are assigned the material that contains this automatic mapping, otherwise the process will fail. 
[param_named]
This is the same as param_indexed, but uses a named parameter instead of an index. This can only be used with high-level programs which include parameter names; if you're using an assembler program then you have no choice but to use indexes. Note that you can use indexed parameters for high-level programs too, but it is less portable since if you reorder your parameters in the high-level program the indexes will change.

format: param_named <name> <type> <value>

example: param_named shininess float4 10.0 0 0 0

The type is required because the program is not compiled and loaded when the material script is parsed, so at this stage we have no idea what types the parameters are. Programs are only loaded and compiled when they are used, to save memory. 
[param_named_auto]
This is the named equivalent of param_indexed_auto, for use with high-level programs.

Format: param_named_auto <name> <value_code> <extra_params>

Example: param_named_auto worldViewProj WORLDVIEWPROJ_MATRIX

The allowed value codes and the meaning of extra_params are detailed in param_indexed_auto.
