- Main Page
- Related Pages
- Modules
- Namespaces
- 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: Autodesk Maya 2014, Extension for Autodesk Maya 2013, Autodesk Maya 2013, Scene Overrides, Framework Classes, Devkit Samples, 3.2 The Renderer, 3.4 Effect Overrides, 3.6 Draw Overrides, 3.8 Render Loop Overrides, 4.2 Lighting Interfaces, 5.1 Single Device Model.

Search for all occurrences

## Detailed Description

Class to allow access to hardware draw context information.

MDrawContext provides access to current hardware draw context information. It 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 class.

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.

MDrawContext is derived from MFrameContext and provides its own implementation for all virtual methods. The values returned from these methods may differ slightly between MFrameContext and MDrawContext as MFrameContext retrieves the values from Maya and MDrawContext retrieves the values from the GPU device state.

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

Inheritance diagram for MDrawContext:
[legend]

List of all members.

## Public Types
enum | LightFilter { kFilteredToLightLimit, kFilteredIgnoreLightLimit }
| Options on which lights to return information for from light query methods. More...
## Public Member Functions
virtual MMatrix | getMatrix (MFrameContext::MatrixType mtype, MStatus *ReturnStatus=NULL) const
| Get a matrix value of a certain type.
virtual MDoubleArray | getTuple (MFrameContext::TupleType ttype, MStatus *ReturnStatus=NULL) const
| Get a tuple (vector or position) value of a certain type.
virtual MStatus | getViewportDimensions (int &originX, int &originY, int &width, int &height) const
| Get the viewport dimensions.
MUint64 | getFrameStamp () const
| Returns the current frame stamp.
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 | 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 (LightFilter lightFilter=kFilteredToLightLimit, MStatus *ReturnStatus=NULL) const
| Return the number of available lights to render the scene.
MStatus | getLightInformation (unsigned int lightNumber, MFloatPointArray &positions, MFloatVector &direction, float &intensity, MColor &color, bool &hasDirection, bool &hasPosition, LightFilter lightFilter=kFilteredToLightLimit) const
| Return common lighting information for a given active light.
MLightParameterInformation * | getLightParameterInformation (unsigned int lightNumber, LightFilter lightFilter=kFilteredToLightLimit) const
| Return parameter information for a given active light.
MHWRender::MStateManager * | getStateManager () const
| Access the GPU state manager for the current draw context.
const MHWRender::MPassContext & | getPassContext () const
| Access the current pass context.
unsigned int | numberOfActiveLights (MStatus *ReturnStatus) const
## Static Public Member Functions
static const char * | className ()
| Returns the name of this class.

## Member Enumeration Documentation

enum LightFilter

Search for all occurrences

Options on which lights to return information for from light query methods.

Enumerator:

  kFilteredToLightLimit | Return light information for lights which pass the VP2.0 filter options. The number of lights accessible is clamped to the VP2.0 light limit option. Search for all occurrences
  kFilteredIgnoreLightLimit | Return light information for lights which pass the VP2.0 filter options. The number of lights accessible ignores the VP2.0 light limit option. Search for all occurrences

## Member Function Documentation

MMatrix getMatrix | ( | MFrameContext::MatrixType | mtype,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const`[virtual]`

Search for all occurrences

Get a matrix value of a certain type.

Parameters:

  [in] | mtype | Type of matrix to return
  [out] | ReturnStatus | Return status

Returns:
  The requested matrix

Status Codes:
  - MS::kSuccess Method succeeded
  - MS::kUnknownParameter Unknown matrix type
  - MS::kFailure Object error

Reimplemented from MFrameContext.

Examples:
  cgfxShaderNode.cpp, footPrintNode.cpp, hwColorPerVertexShader.cpp, hwPhongShader.cpp, and swissArmyManip.cpp.

MDoubleArray getTuple | ( | MFrameContext::TupleType | ttype,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const`[virtual]`

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
  [out] | ReturnStatus | Return status

Returns:
  The requested tuple

Status Codes:
  - MS::kSuccess Method succeeded
  - MS::kUnknownParameter Unknown tuple type
  - MS::kFailure Object error

Reimplemented from MFrameContext.

Examples:
  hwPhongShader.cpp.

MStatus getViewportDimensions | ( | int & | originX,
|  | int & | originY,
|  | int & | width,
|  | int & | height
| ) |  | const`[virtual]`

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

Reimplemented from MFrameContext.

Examples:
  cgfxShaderNode.cpp, and hwPhongShader.cpp.

MUint64 getFrameStamp | ( |  | ) | const

Search for all occurrences

Returns the current frame stamp.

Returns:
  Unique render ID

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 Object error

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. 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 | ( | LightFilter | lightFilter = `kFilteredToLightLimit`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

Return the number of available lights to render the scene.

This method takes into consideration the VP2.0 lighting mode options, whether lights are visible, and whether the light is a member of the default light set (illuminates by default).

When the light mode is set to use all lights, if the lightFilter argument is set to be 'kFilteredIgnoreLightLimit', then the light limit value in the VP2.0 settings will be ignored. Otherwise the value returned is clamped to the light limit.

Parameters:

  [in] | lightFilter | Only consider lights which pass this filter option. The default value is kFilteredToLightLimit.
  [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,
|  | LightFilter | lightFilter = `kFilteredToLightLimit`
| ) |  | 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.
  [in] | lightFilter | Only consider lights which pass this filter option. The default value is kFilteredToLightLimit.

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,
|  | LightFilter | lightFilter = `kFilteredToLightLimit`
| ) |  | 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.
  [in] | lightFilter | Only consider lights which pass this filter option. The default value is kFilteredToLightLimit.

Returns:
  Light information instance

Examples:
  hwPhongShader.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, footPrintNode.cpp, hwColorPerVertexShader.cpp, hwPhongShader.cpp, squareScaleManip.cpp, and swissArmyManip.cpp.

const MHWRender::MPassContext & getPassContext | ( |  | ) | const

Search for all occurrences

Access the current pass context.

Returns:
  Reference to the current pass context

Examples:
  cgfxShaderNode.cpp, footPrintNode.cpp, and hwPhongShader.cpp.

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  Name of this class.

Reimplemented from MFrameContext.

unsigned int numberOfActiveLights | ( | MStatus * | ReturnStatus | ) | const

Search for all occurrences

Deprecated:

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

unsigned int numberOfActiveLights(LightFilter lightFilter, MStatus* ReturnStatus) const;

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

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