MPxGeometryOverride Class Reference
Related help topics: #include <MPxGeometryOverride.h>
Class 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.
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.
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.
- Examples:
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 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 MHWRender::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 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 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... | |
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... | |
Constructor & Destructor Documentation
| MPxGeometryOverride | ( | const MObject & | obj | ) |
Construct an MPxGeometryOverride.
- Parameters
-
[in] obj The DAG object this override translates
Member Function Documentation
|
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
- Examples:
|
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:
|
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:
|
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.
- Parameters
-
[in] item The render item in question
- Returns
- True if the index buffer needs to be updated
- Examples:
|
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] desc The description of the vertex buffer
- Returns
- True if the vertex buffer needs to be updated
- Examples:
|
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] path The path to the instance to update render items for [in,out] list The current render item list, items may be modified, added or removed.
- Examples:
|
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] path The path to the instance to update auxiliary items for [in] drawManager The draw manager used to draw simple geometry [in] frameContext Frame level context information
- Examples:
|
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] requirements The requirements that need to be satisfied. [in,out] renderItems The list of render items that need to be updated. [out] data The container for the geometry data
- Examples:
|
pure virtual |
Called after all other stages are completed.
Clean up any cached data stored from the updateDG() phase.
- Examples:
|
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).
Implementation of this method here is empty and returns True (selection is accepted).
- Parameters
-
[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
- Returns
- True the selection candidate is acceptable
|
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 :
- MSelectionContext::kNone Nothing can be selected
- MSelectionContext::kObject Object can be selected as a whole
- MSelectionContext::kComponent Parts of the object - such as vertex, edge or face - are selectable 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] path The path to the instance to update the selection context for [out] selectionContext The selection context
- Examples:
|
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:
|
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] message A 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:
|
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().
- The granularity must be set to MSelectionContext::kComponent in updateSelectionGranularity()
- A component converter is not necessary in this scenario.
- refineSelectionPath() will not be called. All points present in the render item will be considered suitable locations for snapping.
- Returns
- true Snapping is active
- false Not currently snapping
|
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