OGRE (Object-Oriented Graphics Rendering Engine)
Material Scripts
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.
You can also use this facility to replace existing material definitions which get loaded in from resource files. For example, if you have a .3ds model which you converted using 3ds2oof, it contains a number of material definitions. You can replace any of the material definitions from the .3ds file with your own just by adding a material definition with the same name to a script (remember you can also rename materials in a .3ds file with the 3ds2oof utility with the -matnames option), which will override the one loaded from the .3ds file.
Loading scripts
Material scripts are loaded at initialisation time by the system: by default it looks in all common resource locations (see Root::addResourceLocation) for files with the '.material' extension and parses them. If you want to parse files with a different extension, use the MaterialManager::getSingleton().parseAllSources method with your own extension, or if you want to parse an individual file, use MaterialManager::getSingleton().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 (getMaterial() from SceneManager, or MaterialManager::getSingleton().getByName()), but you must call the 'load' method before trying to usde 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 a typical example:
// This is a comment
walls/funkywall1
{
ambient
0.5 0.5 0.5
diffuse 1.0 1.0 1.0
{
// Texture layer 1
texture
wibbly.jpg
scroll_anim 0.1
0.0
wave_xform scale sine
0.0 0.7 0.0 1.0
}
{
//
Texture Layer 2
texture wobbly.png
rotate_anim
0.25
colour_op add
}
}
Every material in the script must be given a name, which is the line 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 a hierarchical, just as a string.
A material can have top-level attributes set using the scripting commands available, such as 'ambient' to set the amount & colour of the ambient light reflected by the material. Texture layers are added by nesting braces within the material definition, and attributes defined within these braces apply to the texture layer only. The order of the texture layers is important; subsequent texture layers are applied on top of existing ones in the script.
For a detailed description of the material and layer attributes, see the list below:
Material Attributes
Texture Layer Attributes
Back to Index | << Previous section | Next section >> |