Material Scripts

From Axiom

Material scripts are used by Axiom (and OGRE) to define complex materials as reusable units. They can be used to specify fixed function rendering options, texture layers, fallback techniques, and even reference parameterized shaders. Material scripts are text files with a C-like bracket-based syntax very similiar to CSS (website style sheets) except that they are line-delimited instead of comma-delimited. The official documentation for OGRE Material scripts can be found in the online OGRE manual.

Naming Conventions and Requirements

The name of the .material file doesn't mater, however the general convention is to have the material script that includes the all material definitions for a mesh (such as is exported from a modeling utility) will have the base name as the model for which they are used (such as Houses.Cottage.3ds and Houses.Cottage.material). Material scripts can be included in any directory (for instance right next to the model which uses them or in a separate Materials directory) provided that the directory in which they are located is included in a Media Pack directory or archive.

Multiple material definitions can be included in a single material script or located in different ones allowing you to organize them however you like. However material definition names must be unique or else an exception will be thrown and Axiom setup will fail by default as it does not know which definition to use.

Graphical Design Tools

Though material scripts are hand-editable, generally they are exported by 3D modeling utilities such as 3ds Max and Milkshape and can even be used with and exported from RenderMonkey, ATI's free shader development environment for both programmers and artists which allows the graphical design of real-time shader effects.

The Chronos World Editor provides facilities for material editing, however it is in an early alpha stage and no binary releases have been made of it yet.

Fallback Techniques

One of the most important features of Material scripts is the ability to specify fallback techniques. Essentially, these are alternative material definitions that are automatically used when the preferred technique (the first one defined in the file) is not supported by the graphics card. This is very useful to provide alternatives for materials that use shaders so that for instance you could at least apply a scrolling water texture to simulate water if shaders are not supported by the user's graphics card. This ability to provide fallback techniques allows even the most demanding photorealistic games to run on much older hardware and allowing games to be developed and run satisfactorily for as many users as possible. Fallback techniques are also used with LODs (level of details) to prevent precious graphics card processing time from being wasted on objects that are far away from the camera and instead having them use less demanding techniques when the differences wouldn’t be noticeable. The Camera's RenderingDetail can be changes (eg. RF.Camera.RenderingDetail *= .5f) when the framerates are especially high or low to keep them within an optimum range ensure that balance between performance and graphics is always maintained. This modifies the LOD Bias so that lower LODs (and therefore less demanding fallback techniques) will be used if present in the models.

Multipass Rendering and Multitexturing

Multiple passes (up to 16) can be used to specify multiple rendering operations to achieve effects such as applying multiple shaders one after the other for instance. However, this mean that the rendering is performed that many times so it is much more demanding on the video card and could potentially reduce the framerate, especially if used often.

Multiple texture units can also be used for blending several layers of textures, lighting, and other effects (multitexturing) or applying several shaders. However if more texture units are used then are supported by the graphics card, then as many passes as needed to cover them all will be used. Since this could cause quite a bit of extra rendering time for entities using that material, it is suggested that this be avoided when possible by considering the average number of texture units supported by the graphics cards for the majority of the users that you are developing for.

Example Material Scripts

These are several example OGRE material scripts to give an idea of what material definitions look like. They do not make use of all of the supported attributes nor do they detail what they are for and what values are valid for them. For this information see the Material Script documentation in the OGRE manual.

Many different material scripts with numerous material definitions are included in the Media/Materials directory.

Simple Dual-Layered Animated Texture

A simple material script with a single pass and two texture units for multitexturing (blended texture layers).

// This is a comment
// The name of the material (/'s can be used in the name to group or categorize them)
material walls/funkywall1
{
	// first, preferred technique
	technique
	{
		// first rendering pass
		pass
		{
			// ambient lighting color
			ambient 0.5 0.5 0.5
			// diffuse lighting color
			diffuse 1.0 1.0 1.0
			
			// Texture unit 0
			texture_unit 
			{
				// texture image name
				texture wibbly.jpg
				// scroll the texture to the right
				scroll_anim 0.1 0.0
				// scale the texture over time
				wave_xform scale sine 0.0 0.7 0.0 1.0
			}
			// Texture unit 1 (this is a multitexture pass)
			texture_unit
			{
				// texture image name
				texture wobbly.png
				//rotate the texture at this speed
				rotate_anim 0.25
				//use additive texture blending
				colour_op add
			}
		}
	}

	// Second technique, can be used as a fallback or LOD level
	technique
	{
		// .. and so on
	}
		
}

Advanced Normal-Mapped Texture with Support for Multiple Lights

This is an excerpt from the material script file located in the file releases and repository at Media/Materials/Dot3Bump.material. It only shows the first (most advanced) technique of the last (most complex) material definition in the script for the sake of brevity. This shows how complex scripts can be (and even then the majority of the material scripts attributes are not used), however most material scripts are not this complicated. The majority of those exported modeling utilities or generated from models in formats other the OGRE .mesh are simply just a single technique, pass, and texture unit with just the ambient light and texture specified.

// Any number of lights, diffuse and specular
material Examples/BumpMapping/MultiLightSpecular
{

	// This is the preferred technique which uses both vertex and
	// fragment programs, supports coloured lights
	technique
	{
		// Base ambient pass
		pass
		{
			// Really basic vertex program
			// NB we don't use fixed function here because GL does not like
			// mixing fixed function and vertex programs, depth fighting can
			// be an issue
			vertex_program_ref Ogre/BasicVertexPrograms/AmbientOneTexture
			{
				param_named_auto worldViewProj worldviewproj_matrix
				param_named_auto ambient ambient_light_colour
			}
			
		}
		// Now do the lighting pass
		// NB we don't do decal texture here because this is repeated per light
		pass
		{
			// do this for each light
			iteration once_per_light

	
		scene_blend add

	// Vertex program reference
	vertex_program_ref Examples/BumpMapVPSpecular
	{
		param_named_auto lightPosition light_position_object_space 0
		param_named_auto worldViewProj worldviewproj_matrix
	}

	// Fragment program
	fragment_program_ref Examples/BumpMapFPSpecular
	{
		param_named_auto lightDiffuse light_diffuse_colour 0 
		param_named_auto lightSpecular light_specular_colour 0
	}
	
	// Base bump map
	texture_unit
	{
		texture NMBumpsOut.png
		colour_op replace
	}
	// Normalisation cube map
	texture_unit
	{
		cubic_texture nm.png combinedUVW
		tex_coord_set 1
		tex_address_mode clamp
	}
	// Normalisation cube map #2
	texture_unit
	{
		cubic_texture nm.png combinedUVW
		tex_coord_set 1
		tex_address_mode clamp
	}
	}
	
	// Decal pass
	pass
	{
		// Really basic vertex program
		// NB we don't use fixed function here because GL does not like
		// mixing fixed function and vertex programs, depth fighting can
		// be an issue
		vertex_program_ref Ogre/BasicVertexPrograms/AmbientOneTexture
		{
			param_named_auto worldViewProj worldviewproj_matrix
			param_named ambient float4 1 1 1 1
		}
		scene_blend dest_colour zero
		texture_unit
		{
			texture RustedMetal.jpg 
		}
		
	}
	}
}