- Main Page
- Related Pages
- Modules
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions

# MDrawContext Class Reference

# OpenMayaRender - API module for rendering

This reference page is linked to from the following overview topics: Scene Overrides, Framework Classes, Devkit Samples.

Search for all occurrences

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

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, and hwPhongShader.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 = 0x2 }
| Display style. 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).
MHWRender::MStateManager * | getStateManager () const
| Access the GPU state manager for the current draw context.
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

Search for all occurrences

Matrices that can be accessed.

Enumerator:

  kWorldMtx | Object to world matrix. Search for all occurrences
  kWorldTransposeMtx | Object to world matrix transpose. Search for all occurrences
  kWorldInverseMtx | Object to world matrix inverse. Search for all occurrences
  kWorldTranspInverseMtx | Object to world matrix transpose inverse (adjoint) Search for all occurrences
  kViewMtx | World to view matrix. Search for all occurrences
  kViewTransposeMtx | World to view matrix tranpose. Search for all occurrences
  kViewInverseMtx | World to view matrix inverse. Search for all occurrences
  kViewTranspInverseMtx | World to view matrix transpose inverse (adjoint) Search for all occurrences
  kProjectionMtx | Projection matrix. Search for all occurrences
  kProjectionTranposeMtx | Projection matrix tranpose. Search for all occurrences
  kProjectionInverseMtx | Projection matrix inverse. Search for all occurrences
  kProjectionTranspInverseMtx | Projection matrix tranpose inverse (adjoint) Search for all occurrences
  kViewProjMtx | View * projection matrix. Search for all occurrences
  kViewProjTranposeMtx | View * projection matrix tranpose. Search for all occurrences
  kViewProjInverseMtx | View * projection matrix inverse. Search for all occurrences
  kViewProjTranspInverseMtx | View * projection matrix tranpose inverse (adjoint) Search for all occurrences
  kWorldViewMtx | World * view matrix. Search for all occurrences
  kWorldViewTransposeMtx | World * view matrix transpose. Search for all occurrences
  kWorldViewInverseMtx | World * view matrix inverse. Search for all occurrences
  kWorldViewTranspInverseMtx | World * view matrix transpose inverse (adjoint) Search for all occurrences
  kWorldViewProjMtx | World * view * projection matrix. Search for all occurrences
  kWorldViewProjTransposeMtx | World * view * projection matrix transpose. Search for all occurrences
  kWorldViewProjInverseMtx | World * view * projection matrix inverse. Search for all occurrences
  kWorldViewProjTranspInverseMtx | World * view * projection matrix tranpose inverse (adjoint) Search for all occurrences

enum TupleType

Search for all occurrences

Vectors or positions that can be accessed.

Enumerator:

  kViewPosition | View position. Search for all occurrences
  kViewDirection | View direction. Search for all occurrences
  kViewUp | View up vector. Search for all occurrences
  kViewRight | View right vector. Search for all occurrences
  kViewportPixelSize | Viewport size in pixels. Search for all occurrences

enum DisplayStyle

Search for all occurrences

Display style.

Enumerator:

  kGouraudShaded | Gouraud shaded display. Search for all occurrences
  kWireFrame | Wire frame display. Search for all occurrences

## Member Function Documentation

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

Search for all occurrences

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

Search for all occurrences

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.

MDrawContext::TupleType semanticToTupleType | ( | const MString & | value,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Different devices will have difference conventions. For OpenGL the conventions 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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

int getDisplayStyle | ( |  | ) | const

Search for all occurrences

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

Returns:
  Current display style

Examples:
  footPrintNode.cpp.

MHWRender::MStateManager * getStateManager | ( |  | ) | const

Search for all occurrences

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]`

Search for all occurrences

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

Search for all occurrences

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