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.

ambient

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

diffuse

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

specular

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

emissive

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

scene_blend

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)

depth_check

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

depth_write

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

depth_func

Sets the function used to compare depth values when depth checking is on.

Format: depth_func <func>

If depth checking is enabled (see depth_check) a comparison occurs between the depth value of the pixel to be written and the current contents of the buffer. This comparison is normally less_equal, i.e. the pixel is written if it is closer (or at the same distance) than the current contents. The possible functions are:

always_fail
Never writes a pixel to the render target
always_pass
Always writes a pixel to the render target
less
Write if (new_Z < existing_Z)
less_equal
Write if (new_Z <= existing_Z)
equal
Write if (new_Z == existing_Z)
not_equal
Write if (new_Z != existing_Z)
greater_equal
Write if (new_Z >= existing_Z)
greater
Write if (new_Z >existing_Z)

Default: depth_func less_equal

depth_bias

Sets the bias applied to the depth value of this 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).


cull_hardware

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).

cull_software

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

lighting

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

shading

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

filtering

Sets the type of texture filtering used when magnifying or minifying a texture.

Format: filtering <none|bilinear|trilinear>

Default: filtering bilinear

fog_override

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'
linear: Linear fog from the <start> and <end> distances
exp: Fog increases exponentially from the camera (fog = 1/e^(distance * density)), use <density> param to control it
exp2: Fog increases at the square of FOG_EXP, i.e. even quicker (fog = 1/e^(distance * density)^2), use <density> param to control it

colour
Sequence of 3 floating point values from 0 to 1 indicating the red, green and blue intensities
density
The density parameter used in the 'exp' or 'exp2' fog types. Not used in linear mode but param must still be there as a placeholder
start
The start distance from the camera of linear fog. Must still be present in other modes, even though it is not used.
end
The end distance from the camera of linear fog. Must still be present in other modes, even though it is not used.

Example: fog_override true exp 1 1 1 0.002 100 10000

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:

texture

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

anim_texture

Sets the images to be used in an animated texture layer. In this case an animated texture layer means one which has multiple frames, each of which is a separate image file. There are 2 formats, one for implicitly determined image names, one for explicitly named images.

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

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

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

Example: anim_texture flamestart.jpg flamemore.png flameagain.jpg moreflame.jpg lastflame.tga 2.5
This sets up the same duration animation but from 5 separately named image files.

The first format is more concise, but the second is provided if you cannot make your images conform to the naming standard required for it.

Default: none

cubic_texture

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

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

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

Format2 (long): cubic_texture <front> <back> <left> <right> <up> <down> <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

tex_coord_set

Sets which texture coordinate set is to be used for this texture layer. A mesh can define multiple sets of texture coordinates, this sets which one this material uses.

Format: tex_coord_set <set_num>

Example: tex_coord_set 2

Default: tex_coord_set 0

tex_address_mode

Defines what happens when texture coordinates exceed 1.0 for this texture layer.

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

colour_op

Determines how the colour of this texture layer is combined with the one below it (or the lighting effect on the geometry if this is the first layer).

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

This method is the simplest way to blend 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

alpha_rejection

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

colour_op_ex

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

Format: colour_op_ex <operation> <source1> <source2> [<manual>]

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)

colour_op_multipass_fallback

Sets the multipass fallback operation for this layer, if you used colour_op_ex and not enough multitexturing hardware is available.

Format: colour_op_multipass_fallback <src_factor> <dest_factor>

Example: colour_op_mulitpass_fallback one one_minus_dest_alpha

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

The parameters are the same as in the scene_blend attribute; this is because multipass rendering IS effectively scene blending, since each layer is rendered on top of the last using the same mechanism as making an object transparent, it's just being rendered in the same place repeatedly to get the multitexture effect. If you use the simpler (and less flexible) colour_op attribute you don't need to call this as the system sets up the fallback for you.

alpha_op_ex

Behaves in exactly the same away as colour_op_ex except that it determines how alpha values are combined between texture layers rather than colour values.

env_map

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

scroll

Sets a fixed scroll offset for the texture.

Format: scroll <x> <y>

This method offsets the texture in this layer by a fixed amount. Useful for small adjustments without altering texture coordinates in models. However if you wish to have an animated scroll effect, see the scroll_anim attribute.

scroll_anim

Sets up an animated scroll for the texture layer. Useful for creating fixed-speed scrolling effects on a texture layer (for varying scroll speeds, see wave_xform).

Format: scroll_anim <xspeed> <yspeed>

rotate

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.

rotate_anim

Sets up an animated rotation effect of this layer. Useful for creating fixed-speed rotation animations (for varying speeds, see wave_xform).

Format: rotate_anim <revs_per_second>

The parameter is a number of anticlockwise revolutions per second.

scale

Adjusts the scaling factor applied to this texture layer. Useful for adjusting the size of textures without making changes to geometry. This is a fixed scaling factor, if you wish to animate this see wave_xform.

Format: scale <x_scale> <y_scale>

Valid scale values are greater than 0, with a scale factor of 2 making the texture twice as big in that dimension etc.

wave_xform

Sets up a transformation animation based on a wave function. Useful for more advanced texture layer transform effects. You can add multiple instances of this attribute to a single texture layer if you wish.

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

Example: wave_xform scale_x sine 1.0 0.2 0.0 5.0

<xform_type> 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 sectionNext section >>