# # 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 [ ... ] 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 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 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 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 Example: scheme hdr Default: scheme Default [lod_index] Sets the level-of-detail (LOD) index this Technique belongs to. Format: lod_index 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 ( []| 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 ( []| 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 ( []| vertexcolour) 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 ( []| 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 Example: scene_blend add This is the simpler form, where the most commonly used blending modes are enumerated using a single parameter. Valid 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 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 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 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 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 [] 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 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 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 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 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 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 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 [ ] 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 and distances exp = Fog increases exponentially from the camera (fog = 1/e^(distance * density)), use param to control it exp2 = Fog increases at the square of FOG_EXP, i.e. even quicker (fog = 1/e^(distance * density)^2), use 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 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 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 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 [lightType] Format 2: iteration [ [lightType]] Format 3: iteration [ [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 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 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 [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 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 Default: point_size_max 0 # # Texture Unit Docs # [texture_alias] Sets the alias name for this texture unit. Format: texture_alias 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 [] [unlimited | numMipMaps] [alpha] [] 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 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 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 ... 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 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 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 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 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 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 Extended Format: tex_address_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 [] 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 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 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 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 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 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 [] [] [] 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 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 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 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 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 [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 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 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 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. # # Shader Pass Docs # [param_indexed] This command sets the value of an indexed parameter. format: param_indexed 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, int4, int. 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 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 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 Example: param_named_auto worldViewProj WORLDVIEWPROJ_MATRIX The allowed value codes and the meaning of extra_params are detailed in param_indexed_auto.