MStateManager Class Reference

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, hwColorPerVertexShader.cpp, and hwPhongShader.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 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.
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.
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.
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.
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.
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.
int	getMaxSamplerCount () const
	Get the maximum number of simulataneous texture coordinate interpolation channels.
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.
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 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
	)

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

hwColorPerVertexShader.cpp, and hwPhongShader.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, 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.

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, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.

const MRasterizerState * acquireRasterizerState	(	const MRasterizerStateDesc &	desc,
		MStatus *	ReturnStatus = NULL
	)

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

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.

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.

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.

const MDepthStencilState * acquireDepthStencilState	(	const MDepthStencilStateDesc &	desc,
		MStatus *	ReturnStatus = NULL
	)

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

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.

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.

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.

int getMaxSamplerCount

(

)

const

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
	)

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

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.

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.