### 3.1 Material Scripts

Material scripts offer you the ability to define complex materials in a script which can be reused easily. Whilst you could set up all materials for a scene in code using the methods of the Material and TextureLayer classes, in practice it’s a bit unwieldy. Instead you can store material definitions in text files which can then be loaded whenever required.

### Loading scripts

Material scripts are loaded when resource groups are initialised: OGRE looks in all resource locations associated with the group (see Root::addResourceLocation) for files with the ’.material’ extension and parses them. If you want to parse files manually, use MaterialSerializer::parseScript.

It’s important to realise that materials are not loaded completely by this parsing process: only the definition is loaded, no textures or other resources are loaded. This is because it is common to have a large library of materials, but only use a relatively small subset of them in any one scene. To load every material completely in every script would therefore cause unnecessary memory overhead. You can access a ’deferred load’ Material in the normal way (MaterialManager::getSingleton().getByName()), but you must call the ’load’ method before trying to use it. Ogre does this for you when using the normal material assignment methods of entities etc.

Another important factor is that material names must be unique throughout ALL scripts loaded by the system, since materials are always identified by name.

### Format

Several materials may be defined in a single script. The script format is pseudo-C++, with sections delimited by curly braces (’{’, ’}’), and comments indicated by starting a line with ’//’ (note, no nested form comments allowed). The general format is shown below in the example below (note that to start with, we only consider fixed-function materials which don’t use vertex, geometry or fragment programs, these are covered later):

    // This is a comment
    material walls/funkywall1
    {
        // first, preferred technique
        technique
        {
            // first pass
            pass
            {
                ambient 0.5 0.5 0.5
                diffuse 1.0 1.0 1.0

                // Texture unit 0
                texture_unit
                {
                    texture wibbly.jpg
                    scroll_anim 0.1 0.0
                    wave_xform scale sine 0.0 0.7 0.0 1.0
                }
                // Texture unit 1 (this is a multitexture pass)
                texture_unit
                {
                    texture wobbly.png
                    rotate_anim 0.25
                    colour_op add
                }
            }
        }

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

Every material in the script must be given a name, which is the line ’material <blah>’ before the first opening ’{’. This name must be globally unique. It can include path characters (as in the example) to logically divide up your materials, and also to avoid duplicate names, but the engine does not treat the name as hierarchical, just as a string. If you include spaces in the name, it must be enclosed in double quotes.

NOTE: ’:’ is the delimiter for specifying material copy in the script so it can’t be used as part of the material name.

A material can inherit from a previously defined material by using a colon : after the material name followed by the name of the reference material to inherit from. You can in fact even inherit just parts of a material from others; all this is covered in See Script Inheritance). You can also use variables in your script which can be replaced in inheriting versions, see See Script Variables.

A material can be made up of many techniques (See Techniques)- a technique is one way of achieving the effect you are looking for. You can supply more than one technique in order to provide fallback approaches where a card does not have the ability to render the preferred technique, or where you wish to define lower level of detail versions of the material in order to conserve rendering power when objects are more distant.

Each technique can be made up of many passes (See Passes), that is a complete render of the object can be performed multiple times with different settings in order to produce composite effects. Ogre may also split the passes you have defined into many passes at runtime, if you define a pass which uses too many texture units for the card you are currently running on (note that it can only do this if you are not using a fragment program). Each pass has a number of top-level attributes such as ’ambient’ to set the amount & colour of the ambient light reflected by the material. Some of these options do not apply if you are using vertex programs, See Passes for more details.

Within each pass, there can be zero or many texture units in use (See Texture Units). These define the texture to be used, and optionally some blending operations (which use multitexturing) and texture effects.

You can also reference vertex and fragment programs (or vertex and pixel shaders, if you want to use that terminology) in a pass with a given set of parameters. Programs themselves are declared in separate .program scripts (See Declaring Vertex/Geometry/Fragment Programs) and are used as described in Using Vertex/Geometry/Fragment Programs in a Pass.

#### Top-level material attributes

The outermost section of a material definition does not have a lot of attributes of its own (most of the configurable parameters are within the child sections. However, it does have some, and here they are:

#### lod_distances (deprecated)

This option is deprecated in favour of lod_values now.

#### lod_strategy

Sets the name of the LOD strategy to use. Defaults to ’Distance’ which means LOD changes based on distance from the camera. Also supported is ’PixelCount’ which changes LOD based on an estimate of the screen-space pixels affected.
Format: lod_strategy <name>
Default: lod_strategy Distance