#include <MPxDrawOverride.h>
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.
The method excludedFromPostEffects() allows for the plug-in to indicate whether to contribute to passes which are required for post effects. If so, the plug-in's draw() may be called multiple times, once for each pass. Note that even without overriding this method that the plug-in's draw can be called more than once (e.g. for a shadow map pass).
The method isTransparent() allows for the plug-in to indicate whether the object should be drawn as transparency. If so, the plug-in's draw() will be called two times, one for front-culling pass and one for back-culling pass. It will never be called into weighted average or depth peeling. Note that without overriding this method or make the method return false means the object will only be drawn once in opaque pass.
addUIDrawables() provides access to the MUIDrawManager, which can be used to queue up operations for drawing simple UI elements such as lines, circles and text. It is called just after prepareForDraw() and carries the same restrictions on the sorts of operations it can perform. To enable addUIDrawables(), override hasUIDrawables() and make it return true. UI elements are not affected by post effects, and hence are not affected by the excludedFromPostEffects() return value.
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. If the registration contains "/includePostEffects" this will override the value returned from excludedFromPostEffects(). If the registration contains "/isTransparent" this will override the value returned from isTransparent(). For example, a classification starts with "/drawdb/geometry/testNode/includePostEffects/isTransparent" means testNode should contribute to passes required for post effect and it is a transparent object for draw.
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.
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, bool isAlwaysDirty=true) | |
Construct an MPxDrawOverride. More... | |
virtual | ~MPxDrawOverride () |
Destructor. | |
virtual ::MHWRender::DrawAPI | supportedDrawAPIs () const |
Returns the draw API supported by this override. More... | |
virtual bool | hasUIDrawables () const |
In order for any override for the addUIDrawables() method to be called this method must also be overridden to return true. More... | |
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. More... | |
virtual MBoundingBox | boundingBox (const MDagPath &objPath, const MDagPath &cameraPath) const |
Called by Maya whenever the bounding box of the drawable object is needed. More... | |
virtual bool | isBounded (const MDagPath &objPath, const MDagPath &cameraPath) const |
Called by Maya to determine if the drawable object is bounded or not. More... | |
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. More... | |
virtual bool | excludedFromPostEffects () const |
Indicates whether or not the draw code should be called for any additional passes required to perform post effects. More... | |
virtual bool | isTransparent () const |
Indicates whether or not the draw method should be called for each transparency pass(front-culling and back-culling). More... | |
virtual MUserData * | prepareForDraw (const MDagPath &objPath, const MDagPath &cameraPath, const MFrameContext &frameContext, MUserData *oldData)=0 |
Called by Maya whenever the object is dirty and needs to update for draw. More... | |
virtual void | addUIDrawables (const MDagPath &objPath, MUIDrawManager &drawManager, const MFrameContext &frameContext, const MUserData *data) |
Provides access to the MUIDrawManager, which can be used to queue up operations to draw simple UI shapes like lines, circles, text, etc. More... | |
virtual bool | refineSelectionPath (const MSelectionInfo &selectInfo, const MRenderItem &hitItem, MDagPath &path, MObject &geomComponents, MSelectionMask &objectMask) |
Maya calls this function during the hit test phase of the viewport 2.0 selection and is used to override the selected path, the selected components or simply reject the selection. More... | |
virtual void | updateSelectionGranularity (const MDagPath &path, MSelectionContext &selectionContext) |
Maya calls this function during the pre-filtering phase of the viewport 2.0 selection and is used to setup the selection context of the given DAG object. More... | |
virtual bool | traceCallSequence () const |
This method allows a way for a plug-in to examine the basic call sequence for a draw override. More... | |
virtual void | handleTraceMessage (const MString &message) const |
When debug tracing is enabled via MPxDrawOverride::traceCallSequence(), this method will be called for each trace message. More... | |
virtual bool | wantUserSelection () const |
Override this function and return true to indicate Maya system to invoke MPxDrawOverride::userSelect() for selection testing. More... | |
virtual bool | userSelect (MSelectionInfo &selectInfo, const MHWRender::MDrawContext &context, MPoint &hitPoint, const MUserData *data) |
This method is invoked when MPxDrawOverride::wantUserSelection() returns true. More... | |
Static Public Member Functions | |
static const char * | className () |
Returns the name of this class. More... | |
Protected Member Functions | |
MStatus | setGeometryForRenderItem (MRenderItem &renderItem, const MVertexBufferArray &vertexBuffers, const MIndexBuffer *indexBuffer, const MBoundingBox *objectBox) const |
Call this method to provide the geometry for a render item. More... | |
Static Protected Member Functions | |
static MStatus | drawRenderItem (const MHWRender::MDrawContext &context, MRenderItem &item) |
Call this method to draw a render item constructed for the MPxDrawOverride. More... | |
MPxDrawOverride | ( | const MObject & | obj, |
GeometryDrawOverrideCb | callback, | ||
bool | isAlwaysDirty = true |
||
) |
Construct an MPxDrawOverride.
[in] | obj | The Maya object this override draws |
[in] | callback | The callback function to be invoked at draw time |
[in] | isAlwaysDirty | If true, this override will always be updated (via prepareForDraw() or addUIDrawables()) without checking the dirty state of the Maya object. To avoid any unnecessary performance overhead due to the frequency of calling the update methods, the flag can be set to false. In this case the update methods will only be called when the Maya object is marked dirty via DG evaluation or dirty messages. To explicitly mark an object as being dirty the MRenderer::setGeometryDrawDirty() method can be used. Default is true. |
MHWRender::DrawAPI supportedDrawAPIs | ( | ) | const |
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.
|
virtual |
In order for any override for the addUIDrawables() method to be called this method must also be overridden to return true.
This method should not be overridden if addUIDrawables() has not also been overridden as there may be associated wasted overhead.
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.
[in] | objPath | The path to the object whose transform is needed |
[in] | cameraPath | The path to the camera that is being used to draw |
|
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.
Default implementation returns a huge bounding box which will never cull the object.
[in] | objPath | The path to the object being drawn |
[in] | cameraPath | The path to the camera that is being used to draw |
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.
[in] | objPath | The path to the object being drawn |
[in] | cameraPath | The path to the camera that is being used to draw |
|
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.
|
virtual |
Indicates whether or not the draw code should be called for any additional passes required to perform post effects.
Note that the appropriate pass identifier and pass semantic can be queried at draw time via the MPassContext data structure. Also note that if the pass requires a shader override that it can be obtained from the MDrawContext data structure provided at draw time.
|
virtual |
Indicates whether or not the draw method should be called for each transparency pass(front-culling and back-culling).
|
pure virtual |
Called by Maya whenever the object is dirty and needs to update for draw.
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 and Maya will delete it in a certain stage depending on whether the draw callback exists. If exists, the user data will be deleted after both addUIDrawables() and the draw callback are called; otherwise, the user data will be deleted immediately after addUIDrawables() is called. 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.
[in] | objPath | The path to the object being drawn |
[in] | cameraPath | The path to the camera that is being used to draw |
[in] | frameContext | Frame level context information |
[in] | oldData | Data cached by the previous draw of the instance |
|
virtual |
Provides access to the MUIDrawManager, which can be used to queue up operations to draw simple UI shapes like lines, circles, text, etc.
This method will only be called when this override is dirty and its hasUIDrawables() is overridden to return true. This method is called after prepareForDraw() and carries the same restrictions on the sorts of operations it can perform.
[in] | objPath | The path to the object being drawn |
[in] | drawManager | The UI draw manager, it can be used to draw some simple geometry including text |
[in] | frameContext | Frame level context information |
[in] | data | Data cached by prepareForDraw() |
|
virtual |
Maya calls this function during the hit test phase of the viewport 2.0 selection and is used to override the selected path, the selected components or simply reject the selection.
One can decide to change the selected path (ie: select the bottom-most transform instead of the proposed path). One can decide to remove or add component to the proposed selected list. One can decide to change the selection mask of the object (ie: override the selection mask returned by a component converter). One can decide that the proposed selection (path or component) is not acceptable and discard it (ie: return false).
The default implementation does nothing and returns True (selection is accepted).
[in] | selectInfo | The selection info |
[in] | hitItem | The render item hit |
[in,out] | path | The selected path |
[in,out] | components | The selected components |
[in,out] | objectMask | The object selection mask |
|
virtual |
Maya calls this function during the pre-filtering phase of the viewport 2.0 selection and is used to setup the selection context of the given DAG object.
This is useful to specify the selection level, which defines what can be selected on the object :
This is used to discard objects that are not selectable given the current selection mode (see MGlobal::selectionMode()).
The default implementation does nothing and the default selection level for a MPxDrawOverride is kObject.
[in] | path | The path to the instance to update the selection context for |
[out] | selectionContext | The selection context |
|
virtual |
This method allows a way for a plug-in to examine the basic call sequence for a draw override.
The default implementation returns false meaning no tracing will occur.
|
virtual |
When debug tracing is enabled via MPxDrawOverride::traceCallSequence(), this method will be called for each trace message.
The default implementation will print the message to stderr.
[in] | message | A string which will provide feedback on either an internal or plug-in call location. To help distinguish which draw override a message is associated with, the full path name for the DAG object (associated with the draw override) may be included as part of the string. |
|
virtual |
Override this function and return true to indicate Maya system to invoke MPxDrawOverride::userSelect() for selection testing.
Returning false means using default implementation that is based on rasterization result of the drawing method.
|
virtual |
This method is invoked when MPxDrawOverride::wantUserSelection() returns true.
Return true from this function to indicate Maya system the MPxDrawOverride with given MUserData instance is selected regarding current selection context.
[in] | selectInfo | A reference to MSelectionInfo from which the selection region and other information can be queried. |
[in] | context | The reference to MDrawContext that allows the derived class to implement drawing based selection method, or the plug-in can retrieve the world transform matrix for other purpose like performing hit testing on CPU. |
[in,out] | hitPoint | The hit position that Maya system will use for depth sorting of selected objects. Returning the correct hit position to result correct selection based on viewport visibility, especially in single pick mode. By default this parameter has been assigned to the local origin of current DAG path's transform. The plug-in may modify it to provide more accurate hit position. |
[in] | data | This is the same user data that MPxDrawOverride::prepareForDraw() returns. |
|
static |
Returns the name of this class.
|
protected |
Call this method to provide the geometry for a render item.
Although the render item will add a reference to each buffer, ultimate ownership of the geometric data remains with the caller. This method may only be called on render items which have been generated by this override. Buffers may be shared among multiple render items. This method will replace any geometry currently associated with the render item with the newly provided geometry.
The bounding box parameter to this method is optional. If NULL, Maya will attempt to calculate the box automatically. Note that this may require a read-back of vertex data from the graphics card which can be a very slow operation. It is better to supply a correct bounding box whenever possible.
It is the responsibility of the caller to ensure that the buffers provided fulfill the geometry requirements of the shader for the render item. If the requirements are not met, the render item will not draw. If there is no shader assigned to the render item, this method will fail.
[in] | renderItem | The render item to provide geometry for |
[in] | vertexBuffers | The vertex buffers for the geometry |
[in] | indexBuffer | The index buffer for the geometry. Can be NULL. |
[in] | objectBox | Object-space bounding box, may be NULL |
|
staticprotected |
Call this method to draw a render item constructed for the MPxDrawOverride.
This method is only valid to call from a derived class's draw callback function.
[in] | context | The draw context for the current draw pass. |
[in] | item | The render item to draw. |