OGRE (Object-Oriented Graphics Rendering Engine)
Material Scripts
Material Attributes
These attributes are valid within the outer braces of a material in a script. They must each be on their own line. Ordering is unimportant.
Sets the ambient colour reflectance properties of this material.
Format: ambient
<red> <green> <blue>
NB valid colour values are between 0.0
and 1.0.
Example: ambient 0.0 0.8 0.0
The base colour of a material is determined by how much red, green and blue light is reflects. This property determines how much ambient light (directionless global light) is reflected. 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
Sets the diffuse colour reflectance properties of this material.
Format: diffuse
<red> <green> <blue>
NB valid colour values are between 0.0
and 1.0.
Example: diffuse 1.0 0.5 0.5
The base colour of a material is determined by how much red, green and blue light is reflects. This property determines how much diffuse light (light from instances of the Light class in the scene) is reflected. 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
Sets the specular colour reflectance properties of this material.
Format: specular
<red> <green> <blue> <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 material is determined by how much red, green and blue light is reflects. This property determines how much specular light (highlights from instances of the Light class in the scene) is reflected. 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. 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
Sets the amount of self-illumination an object has.
Format: emissive <red>
<green> <blue>
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). 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
Sets the kind of blending this material has with the existing contents of the scene. Wheras the texture blending operations seen in the TextureLayer class are concerned with blending between texture layers, this blending is about combining the output of the material 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>
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 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)
Sets whether or not this material 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
Sets whether or not this material 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
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
Sets the bias applied to the depth value of this material. Can be used to make coplanar polygons appear on top of others e.g. for decals
Format: depth_bias <value>
Where <value> is between 0 and 16, the default being 0. The higher the value, the greater the offset (for if you want to do multiple overlapping decals).
Sets the hardware culling mode for this material.
Format: cull_hardware <clockwise|anitclockwise|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 materials).
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).
Sets the software culling mode for this material.
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
Sets whether or not dynamic lighting is turned on for this material or not. If lighting is turned off, all objects rendered using the material will be fully lit.
Format: lighting <on|off>
Turning dynamic lighting off makes any ambient, diffuse, specular, emissive and shading properties for this material 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
Sets the kind of shading which should be used for representing dynamic lighting for this material.
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
Sets the type of texture filtering used when magnifying or minifying a texture.
Format: filtering <none|bilinear|trilinear>
Default: filtering bilinear
Tells the material to 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
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 material 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 material 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' |
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
Texture Layer Attributes
Texture layers are added in order by including nested brace sections in the material. Any of the following attributes can be included in any order within these braces:
Sets the name of the static texture image this layer will use.
Format: texture <texturename>
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.
Default: none
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_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
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> <combinedUVW|separateUV>
In this case each face is specified explicitly, incase you don't want to conform to the image naming standards above.
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
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
Defines what happens when texture coordinates exceed 1.0 for this texture layer.
Format: tex_address_mode <wrap|clamp|mirror>
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 |
Default: tex_address_mode wrap
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 tetxure 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
Sets the way the layer 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
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>]
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> |
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. |
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)
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.
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.
Turns on/off texture coordinate effect that makes this layer an environment map.
Format: env_map <off|spherical|planar|cubic>
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 | Not yet supported but will be the same as spherical except that instead of a single fish-eye lens reflection map, it 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. Uses the camera-to-normal generation effect so good for curved geometry. |
Default: env_map off
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.
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>
Rotates a texture to a fixed angle. This attribute changes the rotational orientation of a texture to a fixed angle, useful for fixed adjustments. If you wish to animate the rotation, see rotate_anim.
Format: rotate <angle>
The parameter is a anticlockwise angle in degrees.
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.
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.
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> options
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> options
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).
Back to Index | << Previous section | Next section >> |