MPxDrawOverride Class Reference


Detailed Description

Base class for user defined drawing of nodes.

MPxDrawOverride allows the user to define custom draw code to be used to draw all instances of a specific DAG object type in Maya when using Viewport 2.0.

transform() should always return the world space transformation matrix for the object to be drawn in the custom draw code. The default implementation simply returns the transformation defined by the parent transform nodes.

isBounded() can return true or false to indicate whether the object is bounded or not respectively. If a false value is returned then camera frustum culling will not be performed against the bounding box. In this situation the boundingBox() method will not be called since the bounding box is not required.

boundingBox() should always return the object space bounding box for whatever is to be drawn in the custom draw code. If the bounding box is incorrect the node may be culled at the wrong time and the custom draw method might not be called.

When the object associated with the draw override changes, prepareForDraw() is called which allows the user to pull data from Maya to be used in the draw phase. It is invalid to query attribute values from Maya nodes during the draw callback and doing so may result in instability.

At draw time, the user defined callback will be invoked at which point any custom OpenGL drawing may occur. Data needed from the Maya dependency graph must have been cached in the prepareForDraw() stage as it is invalid to query such data during the draw callback.

Implementations of MPxDrawOverride must be registered with Maya through MDrawRegistry.

When using the MHWRender::MRenderer::setGeometryDrawDirty() interface to mark a DAG object associated with an MPxDrawOverride object dirty, the optional topologyChanged parameter must be set to true.

Examples:

footPrintNode.cpp, squareScaleManip.h, and swissArmyManip.cpp.

#include <MPxDrawOverride.h>

List of all members.

Public Types

typedef void(* GeometryDrawOverrideCb )(const MDrawContext &, const MUserData *)
 User draw callback definition, draw context and blind user data are parameters.

Public Member Functions

 MPxDrawOverride (const MObject &obj, GeometryDrawOverrideCb callback)
 Construct an MPxDrawOverride.
virtual ~MPxDrawOverride ()
 Destructor.
virtual MHWRender::DrawAPI supportedDrawAPIs () const
 Returns the draw API supported by this override.
virtual MMatrix transform (const MDagPath &objPath, const MDagPath &cameraPath) const
 Called by Maya whenever the world space transform is needed for the object to be drawn by the draw callback.
virtual MBoundingBox boundingBox (const MDagPath &objPath, const MDagPath &cameraPath) const =0
 Called by Maya whenever the bounding box of the drawable object is needed.
virtual bool isBounded (const MDagPath &objPath, const MDagPath &cameraPath) const
 Called by Maya to determine if the drawable object is bounded or not.
virtual bool disableInternalBoundingBoxDraw () const
 Indicates whether to disable the automatic drawing of bounding boxes when the display mode has been set to 'bounding box' display.
virtual MUserDataprepareForDraw (const MDagPath &objPath, const MDagPath &cameraPath, MUserData *oldData)=0
 Called by Maya each time the object needs to be drawn.

Static Public Member Functions

static const char * className ()
 Returns the name of this class.

Constructor & Destructor Documentation

MPxDrawOverride ( const MObject obj,
GeometryDrawOverrideCb  callback 
)

Construct an MPxDrawOverride.

Parameters:
[in]objThe Maya object this override draws
[in]callbackThe callback function to be invoked at draw time

Member Function Documentation

MHWRender::DrawAPI supportedDrawAPIs ( ) const [virtual]

Returns the draw API supported by this override.

The returned value may be formed as the bitwise 'or' of MHWRender::DrawAPI elements to indicate that the override supports multiple draw APIs. This method returns 'MHWRender::kOpenGL' by default.

Returns:
The draw API supported by this override
MMatrix transform ( const MDagPath objPath,
const MDagPath cameraPath 
) const [virtual]

Called by Maya whenever the world space transform is needed for the object to be drawn by the draw callback.

The default implementation simply returns the transformation defined by the parent transform nodes in Maya. Override to get custom behaviour.

Parameters:
[in]objPathThe path to the object whose transform is needed
[in]cameraPathThe path to the camera that is being used to draw
Returns:
The world space transformation matrix
MBoundingBox boundingBox ( const MDagPath objPath,
const MDagPath cameraPath 
) const [pure virtual]

Called by Maya whenever the bounding box of the drawable object is needed.

This method should return the object space bounding box for the object to be drawn.

Note that this method will not be called if the isBounded() method returns a value of false.

Parameters:
[in]objPathThe path to the object being drawn
[in]cameraPathThe path to the camera that is being used to draw
Returns:
The object space bounding box of object drawn in the draw callback
bool isBounded ( const MDagPath objPath,
const MDagPath cameraPath 
) const [virtual]

Called by Maya to determine if the drawable object is bounded or not.

If the object is not bounded then it will never be culled by the current camera frustum used for drawing.

The default implementation will always return true. This method can be overridden in derived classes to customize the behaviour.

Note that if this method returns false then the boundingBox() method will not be called as no bounds are required in this case.

Parameters:
[in]objPathThe path to the object being drawn
[in]cameraPathThe path to the camera that is being used to draw
Returns:
True if object is bounded
bool disableInternalBoundingBoxDraw ( ) const [virtual]

Indicates whether to disable the automatic drawing of bounding boxes when the display mode has been set to 'bounding box' display.

Note that bounding box drawing is also disabled if the isBounded() method has been set to false. As noted the boundingBox() method is never called under this condition. As such with no bounding box information provided it is not possible to automatically draw due to insufficient information provided.

Returns:
True to disable bounding box drawing. The default value is false.
MUserData * prepareForDraw ( const MDagPath objPath,
const MDagPath cameraPath,
MUserData oldData 
) [pure virtual]

Called by Maya each time the object needs to be drawn.

Any data needed from the Maya dependency graph must be retrieved and cached in this stage. It is invalid to pull data from the Maya dependency graph in the draw callback method and Maya may become unstable if that is attempted.

Implementors may allow Maya to handle the data caching by returning a pointer to the data from this method. The pointer must be to a class derived from MUserData. This same pointer will be passed to the draw callback. On subsequent draws, the pointer will also be passed back into this method so that the data may be modified and reused instead of reallocated. If a different pointer is returned Maya will delete the old data. If the cache should not be maintained between draws, set the delete after use flag on the user data. In all cases, the lifetime and ownership of the user data is handled by Maya and the user should not try to delete the data themselves. Data caching occurs per-instance of the associated DAG object. The lifetime of the user data can be longer than the associated node, instance or draw override. Due to internal caching, the user data can be deleted after an arbitrary long time. One should therefore be careful to not access stale objects from the user data destructor. If it is not desirable to allow Maya to handle data caching, simply return NULL in this method and ignore the user data parameter in the draw callback method.

Parameters:
[in]objPathThe path to the object being drawn
[in]cameraPathThe path to the camera that is being used to draw
[in]oldDataData cached by the previous draw of the instance
Returns:
Pointer to data to be passed to the draw callback method
const char * className ( ) [static]

Returns the name of this class.

Returns:
Name of this class.

MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride
MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride MPxDrawOverride