# Materials

Core
Collaboration diagram for Materials:

## Classes

class | Ogre::AutoParamDataSource
| This utility class is used to hold the information used to generate the matrices and other information required to automatically populate GpuProgramParameters. More...
class | Ogre::LayerBlendModeEx
| Class which manages blending of both colour and alpha components. More...
class | Ogre::ExternalTextureSource
| IMPORTANT: **Plugins must override default dictionary name!** Base class that texture plugins derive from. More...
class | Ogre::ExternalTextureSourceManager
| Singleton Class which handles the registering and control of texture plugins. More...
struct | Ogre::GpuConstantDefinition
| Information about predefined program constants. More...
struct | Ogre::GpuNamedConstants
| Struct collecting together the information for named constants. More...
class | Ogre::GpuNamedConstantsSerializer
| Simple class for loading / saving GpuNamedConstants. More...
struct | Ogre::GpuLogicalIndexUse
| Structure recording the use of a physical buffer by a logical parameter index. More...
struct | Ogre::GpuLogicalBufferStruct
| Container struct to allow params to safely & update shared list of logical buffer assignments. More...
class | Ogre::GpuSharedParameters
| A group of manually updated parameters that are shared between many parameter sets. More...
class | Ogre::GpuSharedParametersUsage
| This class records the usage of a set of shared parameters in a concrete set of GpuProgramParameters. More...
class | Ogre::GpuProgramParameters
| Collects together the program parameters used for a GpuProgram. More...
class | Ogre::GpuProgramUsage
| This class makes the usage of a vertex and fragment programs (low-level or high-level), with a given set of parameters, explicit. More...
class | Ogre::Material
| Class encapsulates rendering properties of an object. More...
class | Ogre::MaterialPtr
| Specialisation of SharedPtr to allow SharedPtr to be assigned to MaterialPtr. More...
class | Ogre::MaterialManager
| Class for managing Material settings for Ogre. More...
struct | Ogre::MaterialScriptProgramDefinition
| Struct for holding a program definition which is in progress. More...
struct | Ogre::MaterialScriptContext
| Struct for holding the script context while parsing. More...
class | Ogre::MaterialSerializer
| Class for serializing Materials to / from a .material script. More...
class | Ogre::Pass
| Class defining a single pass of a Technique (of a Material), i.e. More...
struct | Ogre::IlluminationPass
| Struct recording a pass which can be used for a specific illumination stage. More...
class | Ogre::Technique
| Class representing an approach to rendering this particular Material. More...
class | Ogre::TextureUnitState
| Class representing the state of a single texture unit during a Pass of a Technique, of a Material. More...

## Typedefs

typedef map< String, GpuConstantDefinition >::type | Ogre::GpuConstantDefinitionMap
typedef ConstMapIterator < GpuConstantDefinitionMap > | Ogre::GpuConstantDefinitionIterator
typedef SharedPtr < GpuNamedConstants > | Ogre::GpuNamedConstantsPtr
typedef map< size_t, GpuLogicalIndexUse >::type | Ogre::GpuLogicalIndexUseMap
typedef SharedPtr < GpuLogicalBufferStruct > | Ogre::GpuLogicalBufferStructPtr
typedef vector< float >::type | Ogre::FloatConstantList
| Definition of container that holds the current float constants.
typedef vector< int >::type | Ogre::IntConstantList
| Definition of container that holds the current float constants.
typedef SharedPtr < GpuSharedParameters > | Ogre::GpuSharedParametersPtr
| Shared pointer used to hold references to GpuProgramParameters instances.
typedef SharedPtr < GpuProgramParameters > | Ogre::GpuProgramParametersSharedPtr
| Shared pointer used to hold references to GpuProgramParameters instances.
typedef bool(* | Ogre::ATTRIBUTE_PARSER )(String &params, MaterialScriptContext &context)
| Function def for material attribute parser; return value determines if the next line should be {.
typedef vector < IlluminationPass * >::type | Ogre::IlluminationPassList

## Enumerations

enum | Ogre::LayerBlendType { Ogre::LBT_COLOUR, Ogre::LBT_ALPHA }
| Type of texture blend mode. More...
enum | Ogre::LayerBlendOperation { Ogre::LBO_REPLACE, Ogre::LBO_ADD, Ogre::LBO_MODULATE, Ogre::LBO_ALPHA_BLEND }
| List of valid texture blending operations, for use with TextureUnitState::setColourOperation. More...
enum | Ogre::LayerBlendOperationEx { Ogre::LBX_SOURCE1, Ogre::LBX_SOURCE2, Ogre::LBX_MODULATE, Ogre::LBX_MODULATE_X2, Ogre::LBX_MODULATE_X4, Ogre::LBX_ADD, Ogre::LBX_ADD_SIGNED, Ogre::LBX_ADD_SMOOTH, Ogre::LBX_SUBTRACT, Ogre::LBX_BLEND_DIFFUSE_ALPHA, Ogre::LBX_BLEND_TEXTURE_ALPHA, Ogre::LBX_BLEND_CURRENT_ALPHA, Ogre::LBX_BLEND_MANUAL, Ogre::LBX_DOTPRODUCT, Ogre::LBX_BLEND_DIFFUSE_COLOUR }
| Expert list of valid texture blending operations, for use with TextureUnitState::setColourOperationEx and TextureUnitState::setAlphaOperation, and internally in the LayerBlendModeEx class. More...
enum | Ogre::LayerBlendSource { Ogre::LBS_CURRENT, Ogre::LBS_TEXTURE, Ogre::LBS_DIFFUSE, Ogre::LBS_SPECULAR, Ogre::LBS_MANUAL }
| List of valid sources of values for blending operations used in TextureUnitState::setColourOperation and TextureUnitState::setAlphaOperation, and internally in the LayerBlendModeEx class. More...
enum | Ogre::SceneBlendType { Ogre::SBT_TRANSPARENT_ALPHA, Ogre::SBT_TRANSPARENT_COLOUR, Ogre::SBT_ADD, Ogre::SBT_MODULATE, Ogre::SBT_REPLACE }
| Types of blending that you can specify between an object and the existing contents of the scene. More...
enum | Ogre::SceneBlendFactor { Ogre::SBF_ONE, Ogre::SBF_ZERO, Ogre::SBF_DEST_COLOUR, Ogre::SBF_SOURCE_COLOUR, Ogre::SBF_ONE_MINUS_DEST_COLOUR, Ogre::SBF_ONE_MINUS_SOURCE_COLOUR, Ogre::SBF_DEST_ALPHA, Ogre::SBF_SOURCE_ALPHA, Ogre::SBF_ONE_MINUS_DEST_ALPHA, Ogre::SBF_ONE_MINUS_SOURCE_ALPHA }
| Blending factors for manually blending objects with the scene. More...
enum | Ogre::SceneBlendOperation { Ogre::SBO_ADD, Ogre::SBO_SUBTRACT, Ogre::SBO_REVERSE_SUBTRACT, Ogre::SBO_MIN, Ogre::SBO_MAX }
| Blending operations controls how objects are blended into the scene. More...
enum | Ogre::eTexturePlayMode { Ogre::TextureEffectPause = 0, Ogre::TextureEffectPlay_ASAP = 1, Ogre::TextureEffectPlay_Looping = 2 }
| Enum for type of texture play mode. More...

enum

Ogre::GpuConstantType {
Ogre::GCT_FLOAT1 = 1, Ogre::GCT_FLOAT2 = 2, Ogre::GCT_FLOAT3 = 3, Ogre::GCT_FLOAT4 = 4,
Ogre::GCT_SAMPLER1D = 5, Ogre::GCT_SAMPLER2D = 6, Ogre::GCT_SAMPLER3D = 7, Ogre::GCT_SAMPLERCUBE = 8,
Ogre::GCT_SAMPLER1DSHADOW = 9, Ogre::GCT_SAMPLER2DSHADOW = 10, Ogre::GCT_MATRIX_2X2 = 11, Ogre::GCT_MATRIX_2X3 = 12,
Ogre::GCT_MATRIX_2X4 = 13, Ogre::GCT_MATRIX_3X2 = 14, Ogre::GCT_MATRIX_3X3 = 15, Ogre::GCT_MATRIX_3X4 = 16,
Ogre::GCT_MATRIX_4X2 = 17, Ogre::GCT_MATRIX_4X3 = 18, Ogre::GCT_MATRIX_4X4 = 19, Ogre::GCT_INT1 = 20,
Ogre::GCT_INT2 = 21, Ogre::GCT_INT3 = 22, Ogre::GCT_INT4 = 23, Ogre::GCT_UNKNOWN = 99
}

| Enumeration of the types of constant we may encounter in programs. More...
enum | Ogre::GpuParamVariability { Ogre::GPV_GLOBAL = 1, Ogre::GPV_PER_OBJECT = 2, Ogre::GPV_LIGHTS = 4, Ogre::GPV_PASS_ITERATION_NUMBER = 8, Ogre::GPV_ALL = 0xFFFF }
| The variability of a GPU parameter, as derived from auto-params targetting it. More...
enum | Ogre::MaterialScriptSection { Ogre::MSS_NONE, Ogre::MSS_MATERIAL, Ogre::MSS_TECHNIQUE, Ogre::MSS_PASS, Ogre::MSS_TEXTUREUNIT, Ogre::MSS_PROGRAM_REF, Ogre::MSS_PROGRAM, Ogre::MSS_DEFAULT_PARAMETERS, Ogre::MSS_TEXTURESOURCE }
| Enum to identify material sections. More...
enum | Ogre::IlluminationStage { Ogre::IS_AMBIENT, Ogre::IS_PER_LIGHT, Ogre::IS_DECAL, Ogre::IS_UNKNOWN }
| Categorisation of passes for the purpose of additive lighting. More...

## Typedef Documentation

typedef bool(* Ogre::ATTRIBUTE_PARSER)(String &params, MaterialScriptContext &context)

Function def for material attribute parser; return value determines if the next line should be {.

Definition at line 101 of file OgreMaterialSerializer.h.

typedef vector<float>::type Ogre::FloatConstantList

Definition of container that holds the current float constants.

Note:
  Not necessarily in direct index order to constant indexes, logical to physical index map is derived from GpuProgram

Definition at line 365 of file OgreGpuProgramParams.h.

typedef ConstMapIterator<GpuConstantDefinitionMap> Ogre::GpuConstantDefinitionIterator

Definition at line 261 of file OgreGpuProgramParams.h.

typedef map<String, GpuConstantDefinition>::type Ogre::GpuConstantDefinitionMap

Definition at line 260 of file OgreGpuProgramParams.h.

typedef SharedPtr<GpuLogicalBufferStruct> Ogre::GpuLogicalBufferStructPtr

Definition at line 359 of file OgreGpuProgramParams.h.

typedef map<size_t, GpuLogicalIndexUse>::type Ogre::GpuLogicalIndexUseMap

Definition at line 348 of file OgreGpuProgramParams.h.

typedef SharedPtr<GpuNamedConstants> Ogre::GpuNamedConstantsPtr

Definition at line 318 of file OgreGpuProgramParams.h.

typedef SharedPtr<GpuProgramParameters> Ogre::GpuProgramParametersSharedPtr

Shared pointer used to hold references to GpuProgramParameters instances.

Definition at line 1823 of file OgreGpuProgramParams.h.

typedef SharedPtr<GpuSharedParameters> Ogre::GpuSharedParametersPtr

Shared pointer used to hold references to GpuProgramParameters instances.

Definition at line 494 of file OgreGpuProgramParams.h.

typedef vector<IlluminationPass*>::type Ogre::IlluminationPassList

Definition at line 1685 of file OgrePass.h.

typedef vector<int>::type Ogre::IntConstantList

Definition of container that holds the current float constants.

Note:
  Not necessarily in direct index order to constant indexes, logical to physical index map is derived from GpuProgram

Definition at line 370 of file OgreGpuProgramParams.h.

## Enumeration Type Documentation

enum Ogre::eTexturePlayMode

Enum for type of texture play mode.

Enumerator:

  TextureEffectPause |
  TextureEffectPlay_ASAP | Video starts out paused.
  TextureEffectPlay_Looping | Video starts playing as soon as possible.

Definition at line 59 of file OgreExternalTextureSource.h.

enum Ogre::GpuConstantType

Enumeration of the types of constant we may encounter in programs.

Note:
  Low-level programs, by definition, will always use either float4 or int4 constant types since that is the fundamental underlying type in assembler.

Enumerator:

  GCT_FLOAT1 |
  GCT_FLOAT2 |
  GCT_FLOAT3 |
  GCT_FLOAT4 |
  GCT_SAMPLER1D |
  GCT_SAMPLER2D |
  GCT_SAMPLER3D |
  GCT_SAMPLERCUBE |
  GCT_SAMPLER1DSHADOW |
  GCT_SAMPLER2DSHADOW |
  GCT_MATRIX_2X2 |
  GCT_MATRIX_2X3 |
  GCT_MATRIX_2X4 |
  GCT_MATRIX_3X2 |
  GCT_MATRIX_3X3 |
  GCT_MATRIX_3X4 |
  GCT_MATRIX_4X2 |
  GCT_MATRIX_4X3 |
  GCT_MATRIX_4X4 |
  GCT_INT1 |
  GCT_INT2 |
  GCT_INT3 |
  GCT_INT4 |
  GCT_UNKNOWN |

Definition at line 52 of file OgreGpuProgramParams.h.

enum Ogre::GpuParamVariability

The variability of a GPU parameter, as derived from auto-params targetting it.

These values must be powers of two since they are used in masks.

Enumerator:

  GPV_GLOBAL | No variation except by manual setting - the default.
  GPV_PER_OBJECT | Varies per object (based on an auto param usually), but not per light setup.
  GPV_LIGHTS | Varies with light setup.
  GPV_PASS_ITERATION_NUMBER | Varies with pass iteration number.
  GPV_ALL | Full mask (16-bit)

Definition at line 83 of file OgreGpuProgramParams.h.

enum Ogre::IlluminationStage

Categorisation of passes for the purpose of additive lighting.

Enumerator:

  IS_AMBIENT | Part of the rendering which occurs without any kind of direct lighting.
  IS_PER_LIGHT | Part of the rendering which occurs per light.
  IS_DECAL | Post-lighting rendering.
  IS_UNKNOWN | Not determined.

Definition at line 49 of file OgrePass.h.

enum Ogre::LayerBlendOperation

List of valid texture blending operations, for use with TextureUnitState::setColourOperation.

Remarks:
  This list is a more limited list than LayerBlendOperationEx because it only includes operations that are supportable in both multipass and multitexture rendering and thus provides automatic fallback if multitexture hardware is lacking or insufficient.

Enumerator:

  LBO_REPLACE | Replace all colour with texture with no adjustment.
  LBO_ADD | Add colour components together.
  LBO_MODULATE | Multiply colour components together.
  LBO_ALPHA_BLEND | Blend based on texture alpha.

Definition at line 57 of file OgreBlendMode.h.

enum Ogre::LayerBlendOperationEx

Expert list of valid texture blending operations, for use with TextureUnitState::setColourOperationEx and TextureUnitState::setAlphaOperation, and internally in the LayerBlendModeEx class.

It's worth noting that these operations are for blending between texture layers and not between rendered objects and the existing scene. Because all of these modes are only supported in multitexture hardware it may be required to set up a fallback operation where this hardware is not available.

Enumerator:

  LBX_SOURCE1 | use source1 without modification
  LBX_SOURCE2 | use source2 without modification
  LBX_MODULATE | multiply source1 and source2 together
  LBX_MODULATE_X2 | as LBX_MODULATE but brighten afterwards (x2)
  LBX_MODULATE_X4 | as LBX_MODULATE but brighten more afterwards (x4)
  LBX_ADD | add source1 and source2 together
  LBX_ADD_SIGNED | as LBX_ADD, but subtract 0.5 from the result
  LBX_ADD_SMOOTH | as LBX_ADD, but subtract product from the sum
  LBX_SUBTRACT | subtract source2 from source1
  LBX_BLEND_DIFFUSE_ALPHA | use interpolated alpha value from vertices to scale source1, then add source2 scaled by (1-alpha)
  LBX_BLEND_TEXTURE_ALPHA | as LBX_BLEND_DIFFUSE_ALPHA, but use alpha from texture
  LBX_BLEND_CURRENT_ALPHA | as LBX_BLEND_DIFFUSE_ALPHA, but use current alpha from previous stages
  LBX_BLEND_MANUAL | as LBX_BLEND_DIFFUSE_ALPHA but use a constant manual blend value (0.0-1.0)
  LBX_DOTPRODUCT | dot product of color1 and color2
  LBX_BLEND_DIFFUSE_COLOUR | use interpolated color values from vertices to scale source1, then add source2 scaled by (1-color)

Definition at line 75 of file OgreBlendMode.h.

enum Ogre::LayerBlendSource

List of valid sources of values for blending operations used in TextureUnitState::setColourOperation and TextureUnitState::setAlphaOperation, and internally in the LayerBlendModeEx class.

Enumerator:

  LBS_CURRENT | the colour as built up from previous stages
  LBS_TEXTURE | the colour derived from the texture assigned to this layer
  LBS_DIFFUSE | the interpolated diffuse colour from the vertices
  LBS_SPECULAR | the interpolated specular colour from the vertices
  LBS_MANUAL | a colour supplied manually as a separate argument

Definition at line 112 of file OgreBlendMode.h.

enum Ogre::LayerBlendType

Type of texture blend mode.

Enumerator:

  LBT_COLOUR |
  LBT_ALPHA |

Definition at line 44 of file OgreBlendMode.h.

enum Ogre::MaterialScriptSection

Enum to identify material sections.

Enumerator:

  MSS_NONE |
  MSS_MATERIAL |
  MSS_TECHNIQUE |
  MSS_PASS |
  MSS_TEXTUREUNIT |
  MSS_PROGRAM_REF |
  MSS_PROGRAM |
  MSS_DEFAULT_PARAMETERS |
  MSS_TEXTURESOURCE |

Definition at line 47 of file OgreMaterialSerializer.h.

enum Ogre::SceneBlendFactor

Blending factors for manually blending objects with the scene.

If there isn't a predefined SceneBlendType that you like, then you can specify the blending factors directly to affect the combination of object and the existing scene. See Material::setSceneBlending for more details.

Enumerator:

  SBF_ONE |
  SBF_ZERO |
  SBF_DEST_COLOUR |
  SBF_SOURCE_COLOUR |
  SBF_ONE_MINUS_DEST_COLOUR |
  SBF_ONE_MINUS_SOURCE_COLOUR |
  SBF_DEST_ALPHA |
  SBF_SOURCE_ALPHA |
  SBF_ONE_MINUS_DEST_ALPHA |
  SBF_ONE_MINUS_SOURCE_ALPHA |

Definition at line 234 of file OgreBlendMode.h.

enum Ogre::SceneBlendOperation

Blending operations controls how objects are blended into the scene.

The default operation is add (+) but by changing this you can change how drawn objects are blended into the existing scene.

Enumerator:

  SBO_ADD |
  SBO_SUBTRACT |
  SBO_REVERSE_SUBTRACT |
  SBO_MIN |
  SBO_MAX |

Definition at line 253 of file OgreBlendMode.h.

enum Ogre::SceneBlendType

Types of blending that you can specify between an object and the existing contents of the scene.

Remarks:
  As opposed to the LayerBlendType, which classifies blends between texture layers, these blending types blend between the output of the texture units and the pixels already in the viewport, allowing for object transparency, glows, etc.

  These types are provided to give quick and easy access to common effects. You can also use the more manual method of supplying source and destination blending factors. See Material::setSceneBlending for more details.

See also:
  Material::setSceneBlending

Enumerator:

  SBT_TRANSPARENT_ALPHA | Make the object transparent based on the final alpha values in the texture.
  SBT_TRANSPARENT_COLOUR | Make the object transparent based on the colour values in the texture (brighter = more opaque)
  SBT_ADD | Add the texture values to the existing scene content.
  SBT_MODULATE | Multiply the 2 colours together.
  SBT_REPLACE | The default blend mode where source replaces destination.

Definition at line 215 of file OgreBlendMode.h.

Copyright © 2008 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Last modified Sun May 8 2011 20:28:09