MDrawContext Class Reference
This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013, Autodesk Maya 2013, Scene Overrides, Framework Classes, Devkit Samples, 3.4 Effect Overrides, 3.5 Draw Overrides, 3.6 Render Loop Overrides, 4.2 Lighting Interfaces, 5.1 Single Device Model.
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.
#include <MDrawContext.h>
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. | |
| MLightParameterInformation * | getLightParameterInformation (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::MStateManager * | getStateManager () const |
| Access the GPU state manager for the current draw context. | |
| const MHWRender::MPassContext & | getPassContext () 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:
| enum TupleType |
Vectors or positions that can be accessed.
| enum DisplayStyle |
Display styles.
| enum LightingMode |
Lighting modes.
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] value Semantic name [out] ReturnStatus return status
- Returns:
- Matrix type enumeration
- Status Codes:
- MS::kSuccess A valid enumeration could be returned
- MS::kFailure The semantic is invalid so no valid enumeration could be returned. In this case MDrawContext::kWorldMtx is the return value.
| MMatrix getMatrix | ( | MDrawContext::MatrixType | mtype, |
| MStatus * | ReturnStatus = NULL |
||
| ) | const |
Get a matrix value of a certain type.
- Parameters:
-
[in] mtype Type of matrix to return. Refer to enumerations for allowable values. [out] ReturnStatus return status
- Returns:
- A matrix of the given type asked for.
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
| 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] value Semantic name [out] ReturnStatus return status
- Returns:
- Tuple type enumeration
- Status Codes:
- MS::kSuccess A valid enumeration could be returned
- MS::kFailure The semantic is invalid so no valid enumeration could be returned. In this case MDrawContext::kViewPosition is the return value.
| MDoubleArray getTuple | ( | MDrawContext::TupleType | ttype, |
| MStatus * | ReturnStatus = NULL |
||
| ) | const |
Get a tuple (vector or position) value of a certain type.
- Parameters:
-
[in] ttype Type of vector or position to return. Refer to enumerations for allowable values. [out] ReturnStatus return status
- Returns:
- A tuple of the given type asked for.
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
- Examples:
- hwPhongShader.cpp.
| MBoundingBox getSceneBox | ( | MStatus * | ReturnStatus = NULL | ) | const |
Get a bounding box of the scene in world space.
- Parameters:
-
[out] ReturnStatus return status
- Returns:
- The world space scene bounding box.
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
- Examples:
- hwPhongShader.cpp.
| MBoundingBox getFrustumBox | ( | MStatus * | ReturnStatus | ) | const |
Get the bounding box of the current view frustum in world space.
- Parameters:
-
[out] ReturnStatus return status
- Returns:
- The world space bounding box for the view frustum.
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
| 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] originX X coordinate of the viewport origin [out] originY Y coordinate of the viewport origin [out] width Width of the viewport [out] height Height of the viewport
- Returns:
- Status code
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
- 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] width Width of the render target [out] height Height of the render target
- Returns:
- Status code
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
- 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] nearVal Specifies the near clipping plane [out] farVal Specifies the far clipping plane
- Returns:
- Status code
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
- 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] ReturnStatus return status
- Returns:
- True if the view direction is pointing down the -Z axis.
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
- Examples:
- hwPhongShader.cpp.
| unsigned int numberOfActiveLights | ( | MStatus * | ReturnStatus = NULL | ) | const |
Return the number of active lights being used to render the scene.
- Parameters:
-
[out] ReturnStatus return status
- Returns:
- The number of active lights.
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
- 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] lightNumber Light 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] positions The 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] direction The 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] intensity The intensity of the light. [out] color The color value of the light. [out] hasDirection This will indicate if the light has any directional properties. [out] hasPosition This will indicate if the light has any positional properties.
- Returns:
- Status code
- Status Codes:
- MS::kSuccess method succeeded
- MS::kFailure method does not have a valid object
- MS::kInvalidParameter an invalid lightNumber was specified
- Examples:
- hwPhongShader.cpp.
| MLightParameterInformation * getLightParameterInformation | ( | unsigned int | lightNumber | ) | const |
Return parameter information for a given active light.
- Parameters:
-
[in] lightNumber Light 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
| 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 |
| const char * className | ( | ) | [static] |
| MStatus getLightInformation | ( | unsigned int | lightNumber, |
| MFloatPoint & | position, | ||
| MFloatVector & | direction, | ||
| float & | intensity, | ||
| MColor & | color, | ||
| bool & | hasDirection, | ||
| bool & | hasPosition | ||
| ) | const |
This method is obsolete.
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
