- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions

# MStateManager Class Reference
OpenMayaRender - API module for rendering

This reference page is linked to from the following overview topics: Autodesk Maya 2014, Extension for Autodesk Maya 2013, 2.6 State and State Manager, 3.4 Effect Overrides, 3.6 Draw Overrides.

Search for all occurrences

## Detailed Description

Class to allow efficient access to GPU state information.

MStateManager can be used to provide efficient access to GPU state information when drawing in MPxShaderOverride or MPxDrawOverride. It cannot be created by the user, only accessed through MDrawContext.

MStateManager works with GPU state in blocks for efficiency. These blocks are: blend state, rasterizer state, depth stencil state and sampler state. Each state block is represented by a different class.

Users may acquire immutable instances of such classes by calling the relevant acquire methods on the state manager using a descriptor object to indicate what parameters the state block should have. Once acquired a state block may be held throughout the session and used to set the state where needed. Acquiring state blocks is relatively slow and expensive so it is recommended to avoid acquiring them during draw. State blocks are not large and so holding the memory should not be overly burdensome.

For more details about the specific state block types, see MBlendState, MRasterizerState, MDepthStencilState and MSamplerState.

Examples:

  cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, hwPhongShader.cpp, squareScaleManip.cpp, and swissArmyManip.cpp.

`#include <MStateManager.h>`

List of all members.

## Public Types
enum | CompareMode { kCompareNever = 1, kCompareLess = 2, kCompareEqual = 3, kCompareLessEqual = 4, kCompareGreater = 5, kCompareNotEqual = 6, kCompareGreaterEqual = 7, kCompareAlways = 8 }
| Indicates how to perform comparisons for buffers. More...
enum | ShaderType { kNoShader, kVertexShader, kGeometryShader, kPixelShader, kHullShader, kDomainShader }
| Indicates which shader the sampler applies to. More...
## Public Member Functions
MStatus | setBlendState (const MBlendState *blendState)
| Sets the active blend state on the device.
const MBlendState * | getBlendState (MStatus *ReturnStatus=NULL) const
| Gets the current active blend state from the device.
MStatus | setRasterizerState (const MRasterizerState *rasterizerState)
| Sets the active rasterizer state on the device.
const MRasterizerState * | getRasterizerState (MStatus *ReturnStatus=NULL) const
| Gets the current active rasterizer state from the device.
MStatus | setDepthStencilState (const MDepthStencilState *depthStencilState)
| Sets the active depth stencil state on the device.
const MDepthStencilState * | getDepthStencilState (MStatus *ReturnStatus=NULL) const
| Gets the current active DepthStencil state from the device.
MStatus | setSamplerState (ShaderType shader, int samplerIndex, const MSamplerState *samplerState)
| Sets the active sampler state for any of the texture samplers on the device.
const MSamplerState * | getSamplerState (ShaderType shader, int samplerIndex, MStatus *ReturnStatus=NULL) const
| Gets the current active sampler state from the device.
## Static Public Member Functions
static const MBlendState * | acquireBlendState (const MBlendStateDesc &blendStateDesc, MStatus *ReturnStatus=NULL)
| Acquires an immutable unique blend state matching the blend state descriptor, and returns it in a disposable container.
static void | releaseBlendState (const MBlendState *state)
| Deletes the MBlendState and releases the reference to the underlying state object which is held by the MBlendState object.
static const MRasterizerState * | acquireRasterizerState (const MRasterizerStateDesc &rasterizerStateDesc, MStatus *ReturnStatus=NULL)
| Acquires an immutable unique rasterizer state matching the rasterizer state descriptor and returns it in a disposable container.
static void | releaseRasterizerState (const MRasterizerState *state)
| Deletes the MRasterizerState and releases the reference to the underlying state object which is held by the MRasterizerState object.
static const MDepthStencilState * | acquireDepthStencilState (const MDepthStencilStateDesc &desc, MStatus *ReturnStatus=NULL)
| Acquires an immutable unique DepthStencil state matching the DepthStencil state descriptor and returns it in a disposable container.
static void | releaseDepthStencilState (const MDepthStencilState *state)
| Deletes the MDepthStencilState and releases the reference to the underlying state object which is held by the MDepthStencilState object.
static int | getMaxSamplerCount ()
| Get the maximum number of simulataneous texture coordinate interpolation channels.
static const MSamplerState * | acquireSamplerState (const MSamplerStateDesc &samplerStateDesc, MStatus *ReturnStatus=NULL)
| Acquires an immutable unique Sampler state matching the Sampler state descriptor and returns it in a disposable container.
static void | releaseSamplerState (const MSamplerState *state)
| Deletes the MSamplerState and releases the reference to the underlying state object which is held by the MSamplerState object.
static const char * | className ()
| Returns the name of this class.

## Member Enumeration Documentation

enum CompareMode

Search for all occurrences

Indicates how to perform comparisons for buffers.

Enumerator:

  kCompareNever | never True. Search for all occurrences
  kCompareLess | True if less. Search for all occurrences
  kCompareEqual | True if equal. Search for all occurrences
  kCompareLessEqual | True if less or equal. Search for all occurrences
  kCompareGreater | True if greater. Search for all occurrences
  kCompareNotEqual | True if not equal. Search for all occurrences
  kCompareGreaterEqual | True if greater or equal. Search for all occurrences
  kCompareAlways | Always true. Search for all occurrences

enum ShaderType

Search for all occurrences

Indicates which shader the sampler applies to.

Enumerator:

  kNoShader | Shader type is unknown at this point. Search for all occurrences
  kVertexShader | The vertex shader. Search for all occurrences
  kGeometryShader | The geometry shader. Search for all occurrences
  kPixelShader | The pixel or fragment shader. Search for all occurrences
  kHullShader | The hull or pre-tesselation shader. Search for all occurrences
  kDomainShader | The domain or post-tesselation shader. Search for all occurrences

## Member Function Documentation

const MBlendState * acquireBlendState | ( | const MBlendStateDesc & | desc,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Acquires an immutable unique blend state matching the blend state descriptor, and returns it in a disposable container.

The returned state container may be held throughout the session or may be deleted when unneeded and not active. To delete the container, call releaseBlendState(). State objects are small (16 bytes on 64 bit platforms) and acquiring a state is comparatively slow, so it's important to reuse states as much as possible. Acquiring new states inside the draw loop will have a performance impact.

The returned MBlendState can be passed to setBlendState() to set the device's active blend state.

Parameters:

  [in] | desc | The blend state descriptor structure.
  [out] | ReturnStatus | The return status.

Returns:
  The blend state container object.

Status Codes:
  - MS::kSuccess method succeeded.
  - MS::kFailure desc does not describe a valid blend state.

Examples:
  footPrintNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.

void releaseBlendState | ( | const MBlendState * | state | ) | `[static]`

Search for all occurrences

Deletes the MBlendState and releases the reference to the underlying state object which is held by the MBlendState object.

After calling this method it is an error to try to use the MBlendState and attempting to do so will result in instability. The underlying state object might not be deleted immediately if it is in use by the renderer.

Parameters:

  [in] | state | The state to release

Examples:
  cgfxShaderNode.cpp.

MStatus setBlendState | ( | const MBlendState * | blendState | ) |

Search for all occurrences

Sets the active blend state on the device.

Parameters:

  [in] | blendState | The blend state container object that was previously acquired.

Returns:
  The return status.

Status Codes:
  - MS::kSuccess method succeeded
  - MS::kFailure not a valid blend state object

Examples:
  cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.

const MBlendState * getBlendState | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Gets the current active blend state from the device.

Can be used for query or to reset the device to this blend state at a later time. The returned state may be held throughout the session or may be deleted when unneeded and not active by calling releaseBlendState().

The returned MBlendState can be passed to setBlendState() to set the device's active blend state.

Parameters:

  [out] | ReturnStatus | The return status.

Returns:
  The blend state container object.

Status Codes:
  - MS::kSuccess method succeeded
  - MS::kFailure there is no blend state active on the device

Examples:
  cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.

const MRasterizerState * acquireRasterizerState | ( | const MRasterizerStateDesc & | desc,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Acquires an immutable unique rasterizer state matching the rasterizer state descriptor and returns it in a disposable container.

The returned state container may be held throughout the session or may be deleted when unneeded and not active. To delete the container, call releaseRasterizerState(). State objects are small (8 bytes on 64 bit platforms) and acquiring a state is comparatively slow, so it's important to reuse states as much as possible. Acquiring new states inside the draw loop will have a performance impact.

The returned MRasterizerState can be passed to setRasterizerState() to set the device's active rasterizer state.

Parameters:

  [in] | desc | The rasterizer state descriptor structure.
  [out] | ReturnStatus | The return status.

Returns:
  The rasterizer state container object.

Status Codes:
  - MS::kSuccess method succeeded
  - MS::kFailure desc does not describe a valid rasterizer state

Examples:
  footPrintNode.cpp.

void releaseRasterizerState | ( | const MRasterizerState * | state | ) | `[static]`

Search for all occurrences

Deletes the MRasterizerState and releases the reference to the underlying state object which is held by the MRasterizerState object.

After calling this method it is an error to try to use the MRasterizerState and attempting to do so will result in instability. The underlying state object might not be deleted immediately if it is in use by the renderer.

Parameters:

  [in] | state | The state to release

Examples:
  cgfxShaderNode.cpp.

MStatus setRasterizerState | ( | const MRasterizerState * | rasterizerState | ) |

Search for all occurrences

Sets the active rasterizer state on the device.

Parameters:

  [in] | rasterizerState | The rasterizer state container object that was previously acquired.

Returns:
  The return status.

Status Codes:
  - MS::kSuccess method succeeded
  - MS::kFailure rasterizerState is not a valid object

Examples:
  cgfxShaderNode.cpp, and footPrintNode.cpp.

const MRasterizerState * getRasterizerState | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Gets the current active rasterizer state from the device.

Can be used for query or to reset the device to this rasterizer state at a later time. The returned state may be held throughout the session or may be deleted when unneeded by calling releaseRasterizerState().

The returned MRasterizerState can be passed to setRasterizerState()to set the device's active rasterizer state.

Parameters:

  [out] | ReturnStatus | The return status.

Returns:
  The rasterizer state container object.

Status Codes:
  - MS::kSuccess method succeeded
  - MS::kFailure device does not have a valid rasterizer state

Examples:
  cgfxShaderNode.cpp, and footPrintNode.cpp.

const MDepthStencilState * acquireDepthStencilState | ( | const MDepthStencilStateDesc & | desc,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Acquires an immutable unique DepthStencil state matching the DepthStencil state descriptor and returns it in a disposable container.

The returned state container may be held throughout the session or may be deleted when unneeded and not active. To delete the container, call releaseDepthStencilState(). State objects are small (8 bytes on 64 bit platforms) and acquiring a state is comparatively slow, so it's important to reuse states as much as possible. Acquiring new states inside the draw loop will have a performance impact.

The returned MDepthStencilState can be passed to setDepthStencilState() to set the device's active depth stencil state.

Parameters:

  [in] | desc | The depth stencil state descriptor structure.
  [out] | ReturnStatus | The return status.

Returns:
  The depth stencil state container object.

Status Codes:
  - MS::kSuccess method succeeded
  - MS::kFailure desc does not describe a valid depth stencil state

Examples:
  squareScaleManip.cpp.

void releaseDepthStencilState | ( | const MDepthStencilState * | state | ) | `[static]`

Search for all occurrences

Deletes the MDepthStencilState and releases the reference to the underlying state object which is held by the MDepthStencilState object.

After calling this method it is an error to try to use the MDepthStencilState and attempting to do so will result in instability. The underlying state object might not be deleted immediately if it is in use by the renderer.

Parameters:

  [in] | state | The state to release

Examples:
  cgfxShaderNode.cpp.

MStatus setDepthStencilState | ( | const MDepthStencilState * | depthState | ) |

Search for all occurrences

Sets the active depth stencil state on the device.

Parameters:

  [in] | depthState | The depth stencil state container object that was previously acquired.

Returns:
  The return status.

Status Codes:
  - MS::kSuccess method succeeded
  - MS::kFailure depthState is not a valid object

Examples:
  cgfxShaderNode.cpp, and squareScaleManip.cpp.

const MDepthStencilState * getDepthStencilState | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Gets the current active DepthStencil state from the device.

Can be used for query or to reset the device to this DepthStencil state at a later time. The returned state may be held throughout the session or may be deleted when unneeded by calling releaseDepthStencilState().

The returned MDepthStencilState can be passed to setDepthStencilState() to set the device's active depth stencil state.

Parameters:

  [out] | ReturnStatus | The return status.

Returns:
  The Depth Stencil state container object.

Status Codes:
  - MS::kSuccess method succeeded
  - MS::kFailure device does not have a valid depth stencil state object

Examples:
  cgfxShaderNode.cpp, and squareScaleManip.cpp.

int getMaxSamplerCount | ( |  | ) | `[static]`

Search for all occurrences

Get the maximum number of simulataneous texture coordinate interpolation channels.

Returns:
  The maximum number of simulataneous texture coordinate interpolation channels

const MSamplerState * acquireSamplerState | ( | const MSamplerStateDesc & | desc,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Acquires an immutable unique Sampler state matching the Sampler state descriptor and returns it in a disposable container.

The returned state container may be held throughout the session or may be deleted when unneeded and not active. To delete the container, call releaseSamplerState(). State objects are small (8 bytes on 64 bit platforms) and acquiring a state is comparatively slow, so it's important to reuse states as much as possible. Acquiring new states inside the draw loop will have a performance impact.

The returned MSamplerState can be passed to setSamplerState()to set the device's active sampler state.

Parameters:

  [in] | desc | The sampler state descriptor structure.
  [out] | ReturnStatus | The return status.

Returns:
  The sampler state container object.

Status Codes:
  - MS::kSuccess method succeeded.
  - MS::kFailure desc does not describe a valid sampler state.

void releaseSamplerState | ( | const MSamplerState * | state | ) | `[static]`

Search for all occurrences

Deletes the MSamplerState and releases the reference to the underlying state object which is held by the MSamplerState object.

After calling this method it is an error to try to use the MSamplerState and attempting to do so will result in instability. The underlying state object might not be deleted immediately if it is in use by the renderer.

Parameters:

  [in] | state | The state to release

MStatus setSamplerState | ( | ShaderType | shader,
|  | int | samplerIndex,
|  | const MSamplerState * | samplerState
| ) |  |

Search for all occurrences

Sets the active sampler state for any of the texture samplers on the device.

Parameters:

  [in] | shader | The shader this sampler will apply to, e.g. kPixelShader.
  [in] | samplerIndex | The index of the sampler to set with the given shader state.
  [in] | samplerState | The sampler state container object that was previously acquired.

Returns:
  The return status.

Status Codes:
  - MS::kSuccess method succeeded.
  - MS::kFailure method does not have a valid samplerState object, index, or shader type.

const MSamplerState * getSamplerState | ( | ShaderType | shader,
|  | int | samplerIndex,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

Gets the current active sampler state from the device.

Can be used for query or to reset the device to this sampler state at a later time. The returned state may be held throughout the session or may be deleted when unneeded by calling releaseSamplerState().

The returned MSamplerState can be passed to setSamplerState() to set the device's active sampler state.

Parameters:

  [in] | shader | The shader this sampler will apply to.
  [in] | samplerIndex | The index of the sampler to set with the given shader state.
  [out] | ReturnStatus | The return status.

Returns:
  The sampler state container object.

Status Codes:
  - MS::kSuccess method succeeded.
  - MS::kFailure device does not have a valid sampler at given shader and index.

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  Name of this class.

MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager
MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager MStateManager