C++ API Reference: MPxGeometryOverride Class Reference

MPxGeometryOverride Class Referenceabstract
+ Related help topics:

Base for user-defined classes to prepare geometry for drawing. More...

#include <MPxGeometryOverride.h>

Public Member Functions

 MPxGeometryOverride (const MObject &obj)
 Construct an MPxGeometryOverride. More...
 
virtual ~MPxGeometryOverride ()
 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 bool requiresGeometryUpdate () const
 This method is called one during each draw-preparation phase. More...
 
virtual bool requiresUpdateRenderItems (const MDagPath &path) const
 This method is called for each instance of the associated DAG object whenever the object changes. More...
 
virtual bool supportsEvaluationManagerParallelUpdate () const
 This method is called once each MPxGeometryOverride in the scene to determine if the MPxGeometryOverride is eligible for Evaluation Manager Parallel Update. More...
 
virtual bool supportsVP2CustomCaching () const
 This method is called at any time during evaluation to determine if VP2 Custom Caching is supported. More...
 
virtual void configCache (const MEvaluationNode &, MCacheSchema &) const
 Defines the node's behavior when participating in Cached Playback in VP2 Custom Caching. More...
 
virtual void updateDG ()=0
 Perform any work required to translate the geometry data that needs to get information from the dependency graph. More...
 
virtual bool isIndexingDirty (const MRenderItem &item)
 This method is called for each render item on the assocated DAG object whenever the object changes. More...
 
virtual bool isStreamDirty (const MVertexBufferDescriptor &desc)
 This method is called for each geometry stream on the assocated DAG object whenever the object changes. More...
 
virtual void updateRenderItems (const MDagPath &path, MRenderItemList &list)=0
 This method is called for each instance of the associated DAG object whenever the object changes. More...
 
virtual void addUIDrawables (const MDagPath &path, MUIDrawManager &drawManager, const MFrameContext &frameContext)
 For each instance of the object, besides the render items updated in updateRenderItems() there is also a render item list for rendering simple UI elements. More...
 
virtual void populateGeometry (const MGeometryRequirements &requirements, const MRenderItemList &renderItems, MGeometry &data)=0
 Implementations of this method should create and populate vertex and index buffers on the MGeometry instance 'data' in order to fulfill all of the geometry requirements defined by the 'requirements' parameter. More...
 
virtual void cleanUp ()=0
 Called after all other stages are completed. More...
 
virtual bool refineSelectionPath (const MSelectionInfo &selectInfo, const MRenderItem &hitItem, MDagPath &multipath, MObject &geomComponents, MSelectionMask &objectMask)
 Maya calls this function during the selection interpretation phase of Viewport 2.0 selection and can be 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 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 geometry override. More...
 
virtual void handleTraceMessage (const MString &message) const
 When debug tracing is enabled via MPxGeometryOverride::traceCallSequence(), this method will be called for each trace message. More...
 
const MFrameContextgetFrameContext () const
 Returns the frame context. More...
 

Static Public Member Functions

static bool pointSnappingActive ()
 Returns true if selection has been launched to find snap points. More...
 
static const char * className ()
 Returns the name of this class. More...
 

Detailed Description

Base for user-defined classes to prepare geometry for drawing.

MPxGeometryOverride allows the user to create an override to prepare vertex data that will be used to draw a specific Maya DAG object type with an arbitrary shader (standard Maya or custom) in Viewport 2.0.

This class is designed to be a high level data-translator independent of any specific hardware draw API. Once registered through MDrawRegistry, an instance will be created for each node with a matching classification string. That instance will be used to generate the vertex streams needed by the assigned shaders in order to draw the object. The intent of this class is that it be used to provide data for plugin shape types (MPxSurfaceShape) however it can also be used to override the geometry translation for any Maya geometry type.

If a more low-level interface to the Viewport 2.0 draw loop is needed, look at either MPxDrawOverride or MPxShaderOverride.

The override is only triggered when the associated DAG object has changed and that object is about to be drawn. So it is not invoked if the user is simply tumbling the scene, or if the object is not within the current view frustum.

Implementations of MPxGeometryOverride must be registered with Maya through MDrawRegistry.

Users of this interface must implement several virtual methods which will be called at specific times during the draw-preparation phase.

1) updateDG() : In the updateDG() call, all data needed to compute the indexing and geometry data must be pulled from Maya and cached. It is invalid to query attribute values from Maya nodes in any later stage and doing so may result in instability.

2) updateRenderItems() : For each shader assigned to the instance of the object Maya will assign a render item. A render item is a single atomic renderable entity containing a shader and some geometry. In updateRenderItems(), implementations of this class may enable or disable the automatic shader-based render items and they may add or remove custom user defined render items in order to cause additional things to be drawn. Look at the MRenderItem interface for more details.

3) addUIDrawables() : For each instance of the object, besides the render items updated in 'updateRenderItems()' for the geometry rendering, there is also a render item list there for render the simple UI elements. 'addUIDrawables()' happens just after normal geometry item updating, The original design for this stage is to allow user accessing 'MUIDrawManager' which helps drawing the simple geometry easily like line, circle, rectangle, text, etc. Overriding this methods is not always necessary, but if you want to override it, please also override 'hasUIDrawables()' to make it return true or the overrided method will not be called.

4) populateGeometry() : In this method the implementation is expected to fill the MGeometry data structure with the vertex and index buffers required to draw the object as indicated by the data in the geometry requirements instance passed to this method. Failure to fulfill the geometry requirements may result in incorrect drawing or possibly complete failure to draw the object.

5) cleanUp() : Delete any cached data generated in the earlier phases that is no longer needed.

Additionally, this interface includes some optional virtual methods which may be implemented to extend the functionality of MPxGeometryOverride.

1) requiresGeometryUpdate() : If this method returns true then all of the other methods will be called for this draw-preparation phase. This allows your MPxGeometryOverride to depend on data outside of associated DAG object. By default this method returns false.

2) requiresUpdateRenderItems() : If this method returns false for an MDagPath instance of the associated DAG object then updateRenderItems() will not be called for that MDagPath draw-preparation phase. If requiresUpdateRenderItems() returns false for all MDagPaths then updateRenderItems() will not be called at all for the draw-preparation phase.

3) supportsEvaluationManagerParallelUpdate() : If this method returns true then the MPxGeometryOverride will be considered for Evaluation Manager Parallel Update.

If the MPxGeometryOverride object returns false from hasUIDrawables and requiresUpdateRenderItems during the draw-preparation phase then the MPxGeometryOverride is eligible for Evaluation Manager Parallel Update during that draw-preparation phase.

Evaluation Manager Parallel Update is a performance optimization which allows the updateDG() and populateGeometry() step of the draw update to occur during Evaluation Graph Execution rather than during VP2 scene rendering. The improves performance by allowing updateDG() and populateGeometry() calls of several plug-ins to run in parallel with each other and with Evaluation Manager dependency graph evaluation.

Using Evaluation Manager Parallel Update incurs some additional overhead updating each object. For drawable objects where updateDG() and populateGeometry() calls are short (such as for UI objects) it may be faster to not support Evaluation Manager Parallel Update.

Enabling Evaluation Manager Parallel Update for MPxGeometryOverride does add some additional restrictions to the implementation of updateDG() and populateGeometry().

When Evaluation Manager Parallel Update is enabled, updateDG() and populateGeometry() may be called from a worker thread which may not safely access the graphics API. To populate geometry you must use the methods on MIndexBuffer and MVertexBuffer which explicitly state they are safe to use on a worker thread. Furthermore, updateDG() and populateGeometry() may only access values on the MObject associated with the MPxGeometryOverride. Accessing values on other objects will result in undefined behavior.

Using Evaluation Manager Parallel Update with Evaluation Caching enabled adds additional limitations on Evaluation Manager Parallel Update. During Evaluation Manager Parallel Update it is only safe to read attributes which are not animated, or attributes which are animated and cached. For more information on how to ensure attributes are cached with Evaluation Caching please refer to the Evaluation Caching documentation.

MPxGeometryOverride automatically supports Evaluation Caching. No changes to MPxGeometryOverride are necessary to enable Evaluation Caching support. If MPxGeometryOverride is attached to an user-defined node then some changes to the user-defined node may be necessary for Evaluation Caching to work correct with the user-defined node and MPxGeometryOverride. Specifically, all values read by MPxGeometryOverride must be cached by the user-defined node.

MPxGeometryOverride includes optional support for VP2 Custom Caching. To support VP2 Custom Caching a node must also support Evaluation Manager Parallel Update. When VP2 Custom Caching is supported three new potential behaviors will occur.

1) During evaluation when the VP2 Custom Cache is not ready the MPxGeometryOverride will be invoked as normal. After populateGeometry() the VP2 Custom Cache will save references to the MVertexBuffers and MIndexBuffers used to draw the object for the current time. It is not safe to hold references to these buffers after returning from populateGometry().

2) During evaluation when the VP2 Custom Cache is ready a subset of the MPxGeomtryOverride methods will be invoked. The plug-in will have a chance to choose which render items draw and to add UI render items (hasUIDrawable(), updateRenderItems(), addUIDrawables() will all be called). However, no updateDG() or populateGeometry() call will be made. The pre-existing buffers from an earlier evaluation will be used to draw.

3) When Maya is idle Maya will fill the VP2 Custom Cache using background evaluation. updateDG(), populateGeometry() and cleanUp() will be invoked in a worker thread which does not have the normal context as the current context. During background evaluation there are additional restrictions on updateDG(), populateGeometry() and cleanUp(): it is not safe to access the graphics API and it is only safe to access values on the MObject associated with the MPxGeometryOverride. After the populateGeometry() call the MVertexBuffers and MIndexBuffers prepared will be stored. It is not safe to hold references to these buffers after returning from populateGeometry().

When MPxGeometryOverride is invoked from background evaluation for VP2 Custom Caching the current context will already be set correctly for the frame being background evaluated.

When VP2 Custom Caching is enabled and the desired content of the MVertexBuffers used to draw the MPxGeometryOverride is changing then requiresGeometryUpdate() must return true.

+ Examples:

Constructor & Destructor Documentation

MPxGeometryOverride ( const MObject obj)

Construct an MPxGeometryOverride.

Parameters
[in]objThe DAG object this override translates

Member Function Documentation

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.

Returns
The draw API supported by this override
+ Examples:
bool hasUIDrawables ( ) const
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.

Returns
Whether 'addUIDrawables()' will be called or not.
+ Examples:
bool requiresGeometryUpdate ( ) const
virtual

This method is called one during each draw-preparation phase.

If this method returns true then the associated DAG object will have a chance to update its render geometry this frame.

Depending on the other features enabled by Maya and the MPxGeometryOverride the update could be completed by calling some combination of methods on MPxGeometryOverride itself such as updateRenderItems and populateGeometry or by using VP2 custom caching and making no further calls to this object.

If the desired contents of the MVertexBuffers used to draw the render items for this object have changed then this method must return true. The source of the new buffer contents (evaluation or caching) doesn't change the behavior of this method.

This code has to be thread safe, non-blocking and work only on data owned by the associated DAG object.

Returns
true if further draw-preparation methods are required.
+ Examples:
bool requiresUpdateRenderItems ( const MDagPath path) const
virtual

This method is called for each instance of the associated DAG object whenever the object changes.

If, during a single draw-preparation phase this method returns false for all DAG instances of this MPxGeometryOverride then updateRenderItems() will not be called for the draw-preparation phase.

Parameters
[in]pathThe path to the instance to update render items for
Returns
true if updateRenderItems() must be called. false if it is safe to not call updateRenderItems().
bool supportsEvaluationManagerParallelUpdate ( ) const
virtual

This method is called once each MPxGeometryOverride in the scene to determine if the MPxGeometryOverride is eligible for Evaluation Manager Parallel Update.

Returns
true if Evaluation Manager Parallel Update is supported by this plug-in.
+ Examples:
bool supportsVP2CustomCaching ( ) const
virtual

This method is called at any time during evaluation to determine if VP2 Custom Caching is supported.

It is not safe to perform any DG evaluation from this method.

This method must return the same value for the entire lifetime of the object.

Returns
true if VP2 Custom Caching is supported by this plug-in.
void configCache ( const MEvaluationNode ,
MCacheSchema  
) const
virtual

Defines the node's behavior when participating in Cached Playback in VP2 Custom Caching.

This method will be called at EM partition time, after cache configuration rules evaluation, when the object is configured as a VP2 Custom Caching point. It allows configuring the cache, for instance by adding extra attributes to cache, when VP2 Custom Caching is used.

Parameters
[in]evalNodeThis node's evaluation node, contains animated plug information
[in,out]schemaSpecification about what attributes to cache. The attribute list is pre-populated by the output attributes in EM's dirty plug list.
void updateDG ( )
pure virtual

Perform any work required to translate the geometry data that needs to get information from the dependency graph.

This should be the only place that dependency graph evaluation occurs. Any data retrieved should be cached for later stages.

+ Examples:
bool isIndexingDirty ( const MRenderItem item)
virtual

This method is called for each render item on the assocated DAG object whenever the object changes.

This method is passed a render item. This method should return true if the indexing for the render item has changed since the last frame. Note that returning false from isIndexingDirty may NOT prevent populate geometry from requiring that an index buffer is updated.

During evaluation with VP2 Custom Caching isIndexingDirty() must return false for all render items on the MPxGeometryOverride. If any render items require an indexing update then updateDG() and populateGeometry() will be called.

Parameters
[in]itemThe render item in question
Returns
True if the index buffer needs to be updated
+ Examples:
bool isStreamDirty ( const MVertexBufferDescriptor desc)
virtual

This method is called for each geometry stream on the assocated DAG object whenever the object changes.

This method is passed a vertex buffer descriptor representing one stream on the object to be updated. This method should return true if it is safe to reuse the existing buffer rather than filling a new buffer with data. Note that returning false from isStreamDirty may NOT prevent populateGeometry from requiring that a stream be updated.

Parameters
[in]descThe description of the vertex buffer
Returns
True if the vertex buffer needs to be updated
+ Examples:
void updateRenderItems ( const MDagPath path,
MRenderItemList list 
)
pure virtual

This method is called for each instance of the associated DAG object whenever the object changes.

The method is passed the path to the instance and the current list of render items associated with that instance. By default the list will contain one render item for each shader assigned to the instance. Implementations of this method method may add, remove or modify items in the list. Note that removal of items created by Maya for assigned shaders is not allowed and will fail. As an alternative this method can disable those items so that they do not draw.

Parameters
[in]pathThe path to the instance to update render items for
[in,out]listThe current render item list, items may be modified, added or removed.
+ Examples:
void addUIDrawables ( const MDagPath path,
MUIDrawManager drawManager,
const MFrameContext frameContext 
)
virtual

For each instance of the object, besides the render items updated in updateRenderItems() there is also a render item list for rendering simple UI elements.

updateAuxiliaryItems() is called just after updateRenderItems(). This stage gives the plugin access to MUIDrawManager which aids in drawing simple geometry like line, circle, rectangle, text, etc.

Overriding this methods is not always necessary, but if you want to override it, please also override 'hasUIDrawables()' to make it return true or the overridden method will not be called.

If you are not going to override this function, please don't make 'hasUIDrawables()' return true or there may be some wasted performance overhead.

Implementation of this method here is empty.

Parameters
[in]pathThe path to the instance to update auxiliary items for
[in]drawManagerThe draw manager used to draw simple geometry
[in]frameContextFrame level context information
+ Examples:
void populateGeometry ( const MGeometryRequirements requirements,
const MRenderItemList renderItems,
MGeometry data 
)
pure virtual

Implementations of this method should create and populate vertex and index buffers on the MGeometry instance 'data' in order to fulfill all of the geometry requirements defined by the 'requirements' parameter.

Failure to do so will result in the object either drawing incorrectly or not drawing at all. See the documentation of MGeometryRequirements and MGeometry for more details on the usage of these classes. The geometry requirements will ask for index buffers on demand. Implementations can force the geometry requirements to update index buffers by calling MHWRender::MRenderer::setGeometryDrawDirty() with topologyChanged setting to true.

Parameters
[in]requirementsThe requirements that need to be satisfied.
[in,out]renderItemsThe list of render items that need to be updated.
[out]dataThe container for the geometry data
+ Examples:
void cleanUp ( )
pure virtual

Called after all other stages are completed.

Clean up any cached data stored from the updateDG() phase.

When using Evaluation Manager Parallel Update it is safe to access the GPU representation of an MIndexBuffer or MVertexBuffer during cleanUp().

When using VP2 Custom Caching it is not safe to access the GPU representation of an MIndexBuffer or MVertexBuffer during cleanUp().

+ Examples:
bool refineSelectionPath ( const MSelectionInfo selectInfo,
const MRenderItem hitItem,
MDagPath path,
MObject components,
MSelectionMask objectMask 
)
virtual

Maya calls this function during the selection interpretation phase of Viewport 2.0 selection and can be 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).

Implementation of this method here is empty and returns True (selection is accepted).

Parameters
[in]selectInfoThe selection info
[in]hitItemThe render item hit
[in,out]pathThe selected path
[in,out]componentsThe selected components
[in,out]objectMaskThe object selection mask
Returns
True the selection candidate is acceptable
void updateSelectionGranularity ( const MDagPath path,
MSelectionContext selectionContext 
)
virtual

Maya calls this function during the pre-filtering phase of 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()).

Implementation of this method here is empty, and default selection level is set to kObject.

Parameters
[in]pathThe path to the instance to update the selection context for
[out]selectionContextThe selection context
+ Examples:
bool traceCallSequence ( ) const
virtual

This method allows a way for a plug-in to examine the basic call sequence for a geometry override.

The default implementation returns false meaning no tracing will occur.

Returns
Whether to turn on call sequence tracing
+ Examples:
void handleTraceMessage ( const MString message) const
virtual

When debug tracing is enabled via MPxGeometryOverride::traceCallSequence(), this method will be called for each trace message.

The default implementation will print the message to stderr.

Parameters
[in]messageA string which will provide feedback on either an internal or plug-in call location. To help distinguish which geometry override a message is associated with, the full path name for the DAG object (associated with the geometry override) may be included as part of the string.
+ Examples:
const MFrameContext * getFrameContext ( ) const

Returns the frame context.

Note that this context is only valid between setup and cleanup.

Returns
Pointer to frame context. The context should never be deleted by the plug-in as it is owned by the geometry override. Null if obtained before setup or after cleanup.
bool pointSnappingActive ( )
static

Returns true if selection has been launched to find snap points.

To participate, you need to have at least one render item with point geometry and MSelectionMask::kSelectPointsForGravity set in MRenderItem::selectableMask().

Returns
  • true Snapping is active
  • false Not currently snapping
const char * className ( )
static

Returns the name of this class.

Returns
Name of this class.

The documentation for this class was generated from the following files:
  • MPxGeometryOverride.h
  • MPxGeometryOverride.cpp