MDepthStencilState Class Reference

This reference page is linked to from the following overview topics: 2.6 State and State Manager.



Detailed Description

Container class for an acquired complete GPU depth stencil state.

MDepthStencilState wraps an acquired composite GPU depth stencil state. This depth stencil state can be used to set the current GPU depth stencil state using MStateManager::setDepthStencilState(myDepthState).

Instances of MDepthStencilState cannot be created or modified by users. You can read the descriptor for an MDepthStencilState using MDepthStencilState::desc(), but you cannot set or alter the descriptor directly.

MDepthStencilState can only be obtained via MStateManager::acquireDepthStencilState(). To use MStateManager::acquireDepthStencilState(), create and fill an MDepthStencilStateDesc instance with the requested state and pass it to MStateManager::acquireDepthStencilState() which will return the cached unique depth stencil state of that description. If the unique depth stencil state did not previously exist in the cache, it is created.

The information included in the depth stencil state includes depth buffer enable, depth buffer write enable, stencil enable, and separate stencil operations for front faces and back faces.

The advantages of using this class rather than setting depth stencil states explicitly are:

1. Since the states are cached internally, state setting is much faster than setting individual states. 2. Since state is set through the Maya viewport API, Maya can maintain accurate knowledge of the current GPU state, even in the presence of arbitrary plug-ins. This also speeds state setup by reducing redundant state setting and OGL queries. 3. The information is device aware, meaning that it will return the correct results based on the current active device. For example it will return the appropriate values for DirectX versus an OpenGL device.

Examples:

cgfxShaderNode.h, and squareScaleManip.cpp.

#include <MStateManager.h>

List of all members.

Public Types

enum  StencilOperation {
  kKeepStencil = 1, kZeroStencil = 2, kReplaceStencil = 3, kIncrementStencilSat = 4,
  kDecrementStencilSat = 5, kInvertStencil = 6, kIncrementStencil = 7, kDecrementStencil = 8
}
 

Describes the choices for stencil buffer operations.

More...

Public Member Functions

const MDepthStencilStateDescdesc (MStatus *ReturnStatus=NULL) const
 Get the depth stencil state descriptor that was used to create the state object.
void * resourceHandle () const
 This method allows access to the draw API dependent handle for a depth-stencil state.

Static Public Member Functions

static const char * className ()
 Returns the name of this class.

Member Enumeration Documentation

Describes the choices for stencil buffer operations.

Enumerator:
kKeepStencil 

Do not update the entry in the stencil buffer.

This is the default value

kZeroStencil 

Set the stencil-buffer entry to 0.

kReplaceStencil 

Replace the stencil-buffer entry with a reference value.

kIncrementStencilSat 

Increment the stencil buffer entry, clamping to the maximum value.

kDecrementStencilSat 

Decrement the stencil buffer entry, clamping to zero.

kInvertStencil 

Invert the bits in the stencil-buffer entry.

kIncrementStencil 

Increment the stencil buffer entry, wrapping to zero if the new value exceeds the maximum value.

kDecrementStencil 

Decrement the stencil buffer entry, wrapping to the maximum value if the new value is less than zero.


Member Function Documentation

const MDepthStencilStateDesc & desc ( MStatus ReturnStatus = NULL) const

Get the depth stencil state descriptor that was used to create the state object.

Parameters:
[out]ReturnStatusreturn status
Returns:
A reference to the depth stencil state descriptor
Status Codes:
const char * className ( ) [static]

Returns the name of this class.

Returns:
Name of this class.
void * resourceHandle ( ) const

This method allows access to the draw API dependent handle for a depth-stencil state.

This handle is owned by the MDepthStencilState and is provided to allow access to use as a read-only object.

Modifications should never be performed on this handle.

Any modifications may result in unpredictable stability as the MDepthStencilState no longer has knowledge of it's contents.

For OpenGL, such a handle does not exist and a NULL pointer will be returned.

For DirectX 10 and higher, a pointer to a Direct3D state will be returned.

Returns:
A pointer (handle) to the state if successful, otherwise NULL.

MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState
MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState MDepthStencilState