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.
#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 } |
|
Vectors or positions that can be accessed. More... |
|
| enum | DisplayStyle { kGouraudShaded = 0x1, kWireFrame = 0x2 } |
|
Display style. More... |
|
Public Member Functions |
|
| MFloatMatrix | getMatrix (MDrawContext::MatrixType mtype, MStatus *ReturnStatus=NULL) const |
| Get a matrix value of a certain type.
|
|
| MFloatArray | 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. |
|
| 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, MFloatPoint &position, MFloatVector &direction, float &intensity, MColor &color, bool &hasDirection, bool &hasPosition) const |
| Return common lighting information for a
given active light. |
|
| int | getDisplayStyle () const |
| Get the current display style as a bit field
(see DisplayStyle enum). |
|
| MHWRender::MStateManager * | getStateManager () const |
| Access the GPU state manager for the current
draw context. |
|
Static Public Member Functions |
|
| 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 style.
Member Function Documentation
| MFloatMatrix 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
- Examples:
- cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
| MFloatArray 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.
| 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, |
| MFloatPoint & | position, | ||
| MFloatVector & | direction, | ||
| float & | intensity, | ||
| MColor & | color, | ||
| bool & | hasDirection, | ||
| bool & | hasPosition | ||
| ) | const |
Return common lighting information for a given active light.
- Parameters:
-
[in] lightNumber Light index number starting from 0 to the number of lights returned from numberOfActiveLights() one minus. Index 0 indicates the first light. There is no correspondance to fixed-function OpenGL light indices. [out] position The world space position of the light. If a light is purely directional then the position value has no meaning and will be set to a value of (0,0,0). [out] direction The world space direction of the light. If a light is purely positional 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.
| int getDisplayStyle | ( | ) | const |
Get the current display style as a bit field (see DisplayStyle enum).
- Returns:
- Current display style
- Examples:
- footPrintNode.cpp.
| 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, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
| const char * className | ( | ) | [static] |
