MStateManager Class Reference

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



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

const MBlendStateacquireBlendState (const MBlendStateDesc &blendStateDesc, MStatus *ReturnStatus=NULL)
 Acquires an immutable unique blend state matching the blend state descriptor, and returns it in a disposable container.
MStatus setBlendState (const MBlendState *blendState)
 Sets the active blend state on the device.
const MBlendStategetBlendState (MStatus *ReturnStatus=NULL) const
 Gets the current active blend state from the device.
const MRasterizerStateacquireRasterizerState (const MRasterizerStateDesc &rasterizerStateDesc, MStatus *ReturnStatus=NULL)
 Acquires an immutable unique rasterizer state matching the rasterizer state descriptor and returns it in a disposable container.
MStatus setRasterizerState (const MRasterizerState *rasterizerState)
 Sets the active rasterizer state on the device.
const MRasterizerStategetRasterizerState (MStatus *ReturnStatus=NULL) const
 Gets the current active rasterizer state from the device.
const MDepthStencilStateacquireDepthStencilState (const MDepthStencilStateDesc &desc, MStatus *ReturnStatus=NULL)
 Acquires an immutable unique DepthStencil state matching the DepthStencil state descriptor and returns it in a disposable container.
MStatus setDepthStencilState (const MDepthStencilState *depthStencilState)
 Sets the active depth stencil state on the device.
const MDepthStencilStategetDepthStencilState (MStatus *ReturnStatus=NULL) const
 Gets the current active DepthStencil state from the device.
int getMaxSamplerCount () const
 Get the maximum number of simulataneous texture coordinate interpolation channels.
const MSamplerStateacquireSamplerState (const MSamplerStateDesc &samplerStateDesc, MStatus *ReturnStatus=NULL)
 Acquires an immutable unique Sampler state matching the Sampler state descriptor and returns it in a disposable container.
MStatus setSamplerState (ShaderType shader, int samplerIndex, const MSamplerState *samplerState)
 Sets the active sampler state for any of the texture samplers on the device.
const MSamplerStategetSamplerState (ShaderType shader, int samplerIndex, MStatus *ReturnStatus=NULL) const
 Gets the current active sampler state from the device.

Static Public Member Functions

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 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 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 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

Indicates how to perform comparisons for buffers.

Enumerator:
kCompareNever 

never True.

kCompareLess 

True if less.

kCompareEqual 

True if equal.

kCompareLessEqual 

True if less or equal.

kCompareGreater 

True if greater.

kCompareNotEqual 

True if not equal.

kCompareGreaterEqual 

True if greater or equal.

kCompareAlways 

Always true.

enum ShaderType

Indicates which shader the sampler applies to.

Enumerator:
kNoShader 

Shader type is unknown at this point.

kVertexShader 

The vertex shader.

kGeometryShader 

The geometry shader.

kPixelShader 

The pixel or fragment shader.

kHullShader 

The hull or pre-tesselation shader.

kDomainShader 

The domain or post-tesselation shader.


Member Function Documentation

const MBlendState * acquireBlendState ( const MBlendStateDesc desc,
MStatus ReturnStatus = NULL 
)

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]descThe blend state descriptor structure.
[out]ReturnStatusThe return status.
Returns:
The blend state container object.
Status Codes:
Examples:
footPrintNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
void releaseBlendState ( const MBlendState state) [static]

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]stateThe state to release
Examples:
cgfxShaderNode.cpp.
MStatus setBlendState ( const MBlendState blendState)

Sets the active blend state on the device.

Parameters:
[in]blendStateThe blend state container object that was previously acquired.
Returns:
The return status.
Status Codes:
Examples:
cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
const MBlendState * getBlendState ( MStatus ReturnStatus = NULL) const

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]ReturnStatusThe return status.
Returns:
The blend state container object.
Status Codes:
Examples:
cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
const MRasterizerState * acquireRasterizerState ( const MRasterizerStateDesc desc,
MStatus ReturnStatus = NULL 
)

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]descThe rasterizer state descriptor structure.
[out]ReturnStatusThe return status.
Returns:
The rasterizer state container object.
Status Codes:
Examples:
footPrintNode.cpp.
void releaseRasterizerState ( const MRasterizerState state) [static]

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]stateThe state to release
Examples:
cgfxShaderNode.cpp.
MStatus setRasterizerState ( const MRasterizerState rasterizerState)

Sets the active rasterizer state on the device.

Parameters:
[in]rasterizerStateThe rasterizer state container object that was previously acquired.
Returns:
The return status.
Status Codes:
Examples:
cgfxShaderNode.cpp, and footPrintNode.cpp.
const MRasterizerState * getRasterizerState ( MStatus ReturnStatus = NULL) const

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]ReturnStatusThe return status.
Returns:
The rasterizer state container object.
Status Codes:
Examples:
cgfxShaderNode.cpp, and footPrintNode.cpp.
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.

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]descThe depth stencil state descriptor structure.
[out]ReturnStatusThe return status.
Returns:
The depth stencil state container object.
Status Codes:
Examples:
squareScaleManip.cpp.
void releaseDepthStencilState ( const MDepthStencilState state) [static]

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]stateThe state to release
Examples:
cgfxShaderNode.cpp.
MStatus setDepthStencilState ( const MDepthStencilState depthState)

Sets the active depth stencil state on the device.

Parameters:
[in]depthStateThe depth stencil state container object that was previously acquired.
Returns:
The return status.
Status Codes:
Examples:
cgfxShaderNode.cpp, and squareScaleManip.cpp.
const MDepthStencilState * getDepthStencilState ( MStatus ReturnStatus = NULL) const

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]ReturnStatusThe return status.
Returns:
The Depth Stencil state container object.
Status Codes:
Examples:
cgfxShaderNode.cpp, and squareScaleManip.cpp.
int getMaxSamplerCount ( ) const

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 
)

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]descThe sampler state descriptor structure.
[out]ReturnStatusThe return status.
Returns:
The sampler state container object.
Status Codes:
void releaseSamplerState ( const MSamplerState state) [static]

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]stateThe state to release
MStatus setSamplerState ( ShaderType  shader,
int  samplerIndex,
const MSamplerState samplerState 
)

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

Parameters:
[in]shaderThe shader this sampler will apply to, e.g. kPixelShader.
[in]samplerIndexThe index of the sampler to set with the given shader state.
[in]samplerStateThe sampler state container object that was previously acquired.
Returns:
The return status.
Status Codes:
const MSamplerState * getSamplerState ( ShaderType  shader,
int  samplerIndex,
MStatus ReturnStatus = NULL 
) const

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]shaderThe shader this sampler will apply to.
[in]samplerIndexThe index of the sampler to set with the given shader state.
[out]ReturnStatusThe return status.
Returns:
The sampler state container object.
Status Codes:
const char * className ( ) [static]

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