MDrawContext Class Reference

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:

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