MDrawContext Class Reference


Detailed Description

Class to allow access to hardware draw context information.

MDrawContext provides access to current hardware draw context information when drawing is performed in either MPxShaderOverride or MPxDrawOverride.

MDrawContext is read-only and cannot be instantiated by the plugin writer.

The information provided includes various transformation matrices, camera information, and render target information such as output buffer size. It is also possible to access and alter GPU state through this calss.

There are a few main advantages for using this class:

1. The data is computed and cached as required. This can avoid work for the plugin writer to extract this information themselves. 2. The plugin writer should not need to directly access the device to extract this information. Any data extraction from the device has a performance penalty which can be avoided. 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.

Some information will vary from one draw to the next draw such as the object-to-world matrix which will change as different objects are being drawn.

Examples:

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

#include <MDrawContext.h>

List of all members.

Public Types

enum  MatrixType {
  kWorldMtx, kWorldTransposeMtx, kWorldInverseMtx, kWorldTranspInverseMtx,
  kViewMtx, kViewTransposeMtx, kViewInverseMtx, kViewTranspInverseMtx,
  kProjectionMtx, kProjectionTranposeMtx, kProjectionInverseMtx, kProjectionTranspInverseMtx,
  kViewProjMtx, kViewProjTranposeMtx, kViewProjInverseMtx, kViewProjTranspInverseMtx,
  kWorldViewMtx, kWorldViewTransposeMtx, kWorldViewInverseMtx, kWorldViewTranspInverseMtx,
  kWorldViewProjMtx, kWorldViewProjTransposeMtx, kWorldViewProjInverseMtx, kWorldViewProjTranspInverseMtx
}
 

Matrices that can be accessed.

More...
enum  TupleType {
  kViewPosition, kViewDirection, kViewUp, kViewRight,
  kViewportPixelSize
}
 

Vectors or positions that can be accessed.

More...
enum  DisplayStyle { kGouraudShaded = (0x1), kWireFrame = (0x1 << 1) }
 

Display styles.

More...
enum  LightingMode { kAmbientLight, kLightDefault, kSelectedLights, kSceneLights }
 

Lighting modes.

More...

Public Member Functions

MMatrix getMatrix (MDrawContext::MatrixType mtype, MStatus *ReturnStatus=NULL) const
 Get a matrix value of a certain type.
MDoubleArray getTuple (MDrawContext::TupleType ttype, MStatus *ReturnStatus=NULL) const
 Get a tuple (vector or position) value of a certain type.
MBoundingBox getSceneBox (MStatus *ReturnStatus=NULL) const
 Get a bounding box of the scene in world space.
MBoundingBox getFrustumBox (MStatus *ReturnStatus) const
 Get the bounding box of the current view frustum in world space.
MStatus getViewportDimensions (int &originX, int &originY, int &width, int &height) const
 Get the viewport dimensions.
MStatus getRenderTargetSize (int &width, int &height) const
 Get the size of the render target (output buffer) being rendered into.
MStatus getDepthRange (float &nearVal, float &farVal) const
 Get the depth range which specifies the mapping of depth values from normalized device coordinates to window coordinates.
bool viewDirectionAlongNegZ (MStatus *ReturnStatus) const
 Return whether the view direction is pointing down the -Z axis.
unsigned int numberOfActiveLights (MStatus *ReturnStatus=NULL) const
 Return the number of active lights being used to render the scene.
MStatus getLightInformation (unsigned int lightNumber, MFloatPointArray &positions, MFloatVector &direction, float &intensity, MColor &color, bool &hasDirection, bool &hasPosition) const
 Return common lighting information for a given active light.
MLightParameterInformationgetLightParameterInformation (unsigned int lightNumber) const
 Return parameter information for a given active light.
int getDisplayStyle () const
 Get the current display style as a bit field (see DisplayStyle enum).
LightingMode getLightingMode () const
 Get the current light mode.
MHWRender::MStateManagergetStateManager () const
 Access the GPU state manager for the current draw context.
const MHWRender::MPassContextgetPassContext () const
 Access the current pass context.
MUint64 getFrameStamp () const
 Returns the current frame stamp.
MStatus getLightInformation (unsigned int lightNumber, MFloatPoint &position, MFloatVector &direction, float &intensity, MColor &color, bool &hasDirection, bool &hasPosition) const
 This method is obsolete.

Static Public Member Functions

static MDrawContext::MatrixType semanticToMatrixType (const MString &value, MStatus *ReturnStatus=NULL)
 Given a semantic name return the corresponding matrix enumeration that can be used to retrieve a matrix value via the getMatrix() method.
static MDrawContext::TupleType semanticToTupleType (const MString &value, MStatus *ReturnStatus=NULL)
 Given a semantic name return the corresponding tuple enumeration that can be used to retrieve a value via the getTuple() method.
static const char * className ()
 Returns the name of this class.

Member Enumeration Documentation

enum MatrixType

Matrices that can be accessed.

Enumerator:
kWorldMtx 

Object to world matrix.

kWorldTransposeMtx 

Object to world matrix transpose.

kWorldInverseMtx 

Object to world matrix inverse.

kWorldTranspInverseMtx 

Object to world matrix transpose inverse (adjoint)

kViewMtx 

World to view matrix.

kViewTransposeMtx 

World to view matrix tranpose.

kViewInverseMtx 

World to view matrix inverse.

kViewTranspInverseMtx 

World to view matrix transpose inverse (adjoint)

kProjectionMtx 

Projection matrix.

kProjectionTranposeMtx 

Projection matrix tranpose.

kProjectionInverseMtx 

Projection matrix inverse.

kProjectionTranspInverseMtx 

Projection matrix tranpose inverse (adjoint)

kViewProjMtx 

View * projection matrix.

kViewProjTranposeMtx 

View * projection matrix tranpose.

kViewProjInverseMtx 

View * projection matrix inverse.

kViewProjTranspInverseMtx 

View * projection matrix tranpose inverse (adjoint)

kWorldViewMtx 

World * view matrix.

kWorldViewTransposeMtx 

World * view matrix transpose.

kWorldViewInverseMtx 

World * view matrix inverse.

kWorldViewTranspInverseMtx 

World * view matrix transpose inverse (adjoint)

kWorldViewProjMtx 

World * view * projection matrix.

kWorldViewProjTransposeMtx 

World * view * projection matrix transpose.

kWorldViewProjInverseMtx 

World * view * projection matrix inverse.

kWorldViewProjTranspInverseMtx 

World * view * projection matrix tranpose inverse (adjoint)

enum TupleType

Vectors or positions that can be accessed.

Enumerator:
kViewPosition 

View position.

kViewDirection 

View direction.

kViewUp 

View up vector.

kViewRight 

View right vector.

kViewportPixelSize 

Viewport size in pixels.

Display styles.

Enumerator:
kGouraudShaded 

Shaded display.

kWireFrame 

Wire frame display.

Lighting modes.

Enumerator:
kAmbientLight 

Use global ambient light.

kLightDefault 

Use default light.

kSelectedLights 

Use lights which are selected.

kSceneLights 

Use all lights in the scene.


Member Function Documentation

MDrawContext::MatrixType semanticToMatrixType ( const MString value,
MStatus ReturnStatus = NULL 
) [static]

Given a semantic name return the corresponding matrix enumeration that can be used to retrieve a matrix value via the getMatrix() method.

Valid semantic names include:

  • world
  • worldtranspose
  • worldinverse
  • worldinversetranspose
  • worldview
  • worldviewtranspose
  • worldviewinverse
  • worldviewinversetranspose
  • worldviewprojection
  • worldviewprojectiontranspose
  • worldviewprojectioninverse
  • worldviewprojectioninversetranspose
  • view
  • viewtranspose
  • viewinverse
  • viewinversetranspose
  • projection
  • projectiontranspose
  • projectioninverse
  • projectioninversetranspose
  • viewprojection
  • viewprojectiontranspose
  • viewprojectioninverse
  • viewprojectioninversetranspose
Parameters:
[in]valueSemantic name
[out]ReturnStatusreturn status
Returns:
Matrix type enumeration
Status Codes:
MMatrix getMatrix ( MDrawContext::MatrixType  mtype,
MStatus ReturnStatus = NULL 
) const

Get a matrix value of a certain type.

Parameters:
[in]mtypeType of matrix to return. Refer to enumerations for allowable values.
[out]ReturnStatusreturn status
Returns:
A matrix of the given type asked for.
Status Codes:
Examples:
cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, hwPhongShader.cpp, and swissArmyManip.cpp.
MDrawContext::TupleType semanticToTupleType ( const MString value,
MStatus ReturnStatus = NULL 
) [static]

Given a semantic name return the corresponding tuple enumeration that can be used to retrieve a value via the getTuple() method.

Valid semantic names include:

  • viewdirection
  • worldcameraposition
  • viewportpixelsize
Parameters:
[in]valueSemantic name
[out]ReturnStatusreturn status
Returns:
Tuple type enumeration
Status Codes:
MDoubleArray getTuple ( MDrawContext::TupleType  ttype,
MStatus ReturnStatus = NULL 
) const

Get a tuple (vector or position) value of a certain type.

Parameters:
[in]ttypeType of vector or position to return. Refer to enumerations for allowable values.
[out]ReturnStatusreturn status
Returns:
A tuple of the given type asked for.
Status Codes:
Examples:
hwPhongShader.cpp.
MBoundingBox getSceneBox ( MStatus ReturnStatus = NULL) const

Get a bounding box of the scene in world space.

Parameters:
[out]ReturnStatusreturn status
Returns:
The world space scene bounding box.
Status Codes:
Examples:
hwPhongShader.cpp.
MBoundingBox getFrustumBox ( MStatus ReturnStatus) const

Get the bounding box of the current view frustum in world space.

Parameters:
[out]ReturnStatusreturn status
Returns:
The world space bounding box for the view frustum.
Status Codes:
MStatus getViewportDimensions ( int &  originX,
int &  originY,
int &  width,
int &  height 
) const

Get the viewport dimensions.

The origin is the upper left corner of the viewport.

Parameters:
[out]originXX coordinate of the viewport origin
[out]originYY coordinate of the viewport origin
[out]widthWidth of the viewport
[out]heightHeight of the viewport
Returns:
Status code
Status Codes:
Examples:
cgfxShaderNode.cpp, and hwPhongShader.cpp.
MStatus getRenderTargetSize ( int &  width,
int &  height 
) const

Get the size of the render target (output buffer) being rendered into.

The dimensions of the target are in pixels.

Parameters:
[out]widthWidth of the render target
[out]heightHeight of the render target
Returns:
Status code
Status Codes:
Examples:
hwPhongShader.cpp.
MStatus getDepthRange ( float &  nearVal,
float &  farVal 
) const

Get the depth range which specifies the mapping of depth values from normalized device coordinates to window coordinates.

The depth range values are normally 0.0 and 1.0.

Parameters:
[out]nearValSpecifies the near clipping plane
[out]farValSpecifies the far clipping plane
Returns:
Status code
Status Codes:
Examples:
cgfxShaderNode.cpp.
bool viewDirectionAlongNegZ ( MStatus ReturnStatus) const

Return whether the view direction is pointing down the -Z axis.

Different devices will have difference conventions. For OpenGL the conventions is -Z. For DirectX the convention is +Z.

Parameters:
[out]ReturnStatusreturn status
Returns:
True if the view direction is pointing down the -Z axis.
Status Codes:
Examples:
hwPhongShader.cpp.
unsigned int numberOfActiveLights ( MStatus ReturnStatus = NULL) const

Return the number of active lights being used to render the scene.

Parameters:
[out]ReturnStatusreturn status
Returns:
The number of active lights.
Status Codes:
Examples:
hwPhongShader.cpp.
MStatus getLightInformation ( unsigned int  lightNumber,
MFloatPointArray positions,
MFloatVector direction,
float &  intensity,
MColor color,
bool &  hasDirection,
bool &  hasPosition 
) const

Return common lighting information for a given active light.

Note that any ambient lighting information is returned as the last light.

Parameters:
[in]lightNumberLight index number starting from 0 to the number of lights returned from numberOfActiveLights() minus one. Index 0 indicates the first light. There is no correspondance to fixed-function OpenGL light indices.
[out]positionsThe world space positions on a light. If a light is purely directional or represents ambient lighting then the position value has no meaning and the return value will be an empty array. In all other cases except for area lights a single position entry will be returned. Multiple positions are returned to represent different sample points on area lights.
[out]directionThe world space direction of the light. If a light is purely positional or represents ambient lighting then the direction value has no meaning and will be set to a value of (0,0,0,1).
[out]intensityThe intensity of the light.
[out]colorThe color value of the light.
[out]hasDirectionThis will indicate if the light has any directional properties.
[out]hasPositionThis will indicate if the light has any positional properties.
Returns:
Status code
Status Codes:
Examples:
hwPhongShader.cpp.
MLightParameterInformation * getLightParameterInformation ( unsigned int  lightNumber) const

Return parameter information for a given active light.

Parameters:
[in]lightNumberLight index number starting from 0 to the number of lights returned from numberOfActiveLights() minus one. Index 0 indicates the first light. There is no correspondance to fixed-function OpenGL light indices.
Returns:
Light information instance
Examples:
hwPhongShader.cpp.
int getDisplayStyle ( ) const

Get the current display style as a bit field (see DisplayStyle enum).

Returns:
Current display style
Examples:
footPrintNode.cpp.
MDrawContext::LightingMode getLightingMode ( ) const

Get the current light mode.

See the LightingMode enum for possible return values.

Returns:
Lighting mode
MHWRender::MStateManager * getStateManager ( ) const

Access the GPU state manager for the current draw context.

Returns:
The GPU state manager for the current draw context
Examples:
cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, hwPhongShader.cpp, squareScaleManip.cpp, and swissArmyManip.cpp.
const MHWRender::MPassContext & getPassContext ( ) const

Access the current pass context.

Returns:
Reference to the current pass context
Examples:
cgfxShaderNode.cpp, footPrintNode.cpp, and hwPhongShader.cpp.
MUint64 getFrameStamp ( ) const

Returns the current frame stamp.

Returns:
Unique render ID
const char * className ( ) [static]

Returns the name of this class.

Returns:
Name of this class.
MStatus getLightInformation ( unsigned int  lightNumber,
MFloatPoint position,
MFloatVector direction,
float &  intensity,
MColor color,
bool &  hasDirection,
bool &  hasPosition 
) const

This method is obsolete.

Deprecated:

In place of this method the following interface should be used instead:

MStatus getLightInformation( unsigned int lightNumber, MFloatPointArray &positions, MFloatVector &direction, float &intensity, MColor &color, bool &hasDirection, bool &hasPosition ) const

Parameters:
[in]lightNumber
[out]position
[out]direction
[out]intensity
[out]color
[out]hasDirection
[out]hasPosition

MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext
MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext MDrawContext