Base class for user defined drawing of nodes.
Note the third parameter of the constructor is optional and defaults to true:
MPxDrawOverride(obj, callback, isAlwaysDirty = True)
Inheritance diagram for OpenMayaRender.MPxDrawOverride:
x.__init__(...) initializes x; see help(type(x)) for signature
Member Function Documentation
OpenMayaRender.MPxDrawOverride.addUIDrawables
(
)
addUIDrawables(objPath, drawManager, frameContext, data) -> self
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 hasUIDrawables() is overridden to return True.
It is called after prepareForDraw() and carries the same restrictions on the sorts of operations it can perform.
* objPath (MDagPath) - The path to the object being drawn.
* drawManager (MUIDrawManager) - The UI draw manager, it can be used to draw some simple geometry including text.
* frameContext (MFrameContext) - Frame level context information.
* data (MUserData) - Data cached by prepareForDraw().
OpenMayaRender.MPxDrawOverride.boundingBox
(
)
boundingBox(objPath, cameraPath) -> MBoundingBox
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.
* objPath (MDagPath) - The path to the object being drawn
* cameraPath (MDagPath) - The path to the camera that is being used to draw
Returns The object space bounding box of object drawn in the draw callback
disableInternalBoundingBoxDraw() -> bool
Returns True to disable bounding box drawing. The default value is False.
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.
excludedFromPostEffects() -> bool
Returns False to indicate inclusion in post effects. The default value is true.
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.
OpenMayaRender.MPxDrawOverride.handleTraceMessage
(
)
handleTraceMessage(message) -> self
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.
* 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.
OpenMayaRender.MPxDrawOverride.hasUIDrawables
(
)
hasUIDrawables() -> bool
Query whether 'addUIDrawables()' will be called or not.
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.
OpenMayaRender.MPxDrawOverride.isBounded
(
)
isBounded(objPath, cameraPath) -> bool
Returns True if object is bounded.
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.
* objPath (MDagPath) - The path to the object whose transform is needed.
* cameraPath (MDagPath) - The path to the camera that is being used to draw.
OpenMayaRender.MPxDrawOverride.isTransparent
(
)
isTransparent() -> bool
Returns True to indicate inclusion in transparency passes. The default value is false.
Indicates whether or not the draw method should be called for each transparency pass(front-culling and back-culling).
OpenMayaRender.MPxDrawOverride.prepareForDraw
(
)
prepareForDraw(objPath, cameraPath, frameContext, oldData) -> MUserData
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.
* objPath (MDagPath) - The path to the object being drawn
* cameraPath (MDagPath) - The path to the camera that is being used to draw
* frameContext (MFrameContext) - Frame level context information
* oldData (MUserData) - Data cached by the previous draw of the instance
Returns the data to be passed to the draw callback method
refineSelectionPath(selectInfo, hitItem, path, components, objectMask) -> bool
This method is called 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.
Should return True if the selection candidate is acceptable.
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 makes no changes to 'path', 'components' or 'objectMask' and returns True (i.e. the selection is accepted).
* selectInfo (MSelectionInfo) - The selection info
* hitItem (MRenderItem) - The render item hit
* path [IN/OUT] (MDagPath) - The selected path
* components [IN/OUT] (MObject) - The selected components
* objectMask [IN/OUT] (MSelectionMask) - The object selection mask
OpenMayaRender.MPxDrawOverride.supportedDrawAPIs
(
)
supportedDrawAPIs() -> DrawAPI
Returns the draw API supported by this override.
OpenMayaRender.MPxDrawOverride.traceCallSequence
(
)
traceCallSequence() -> bool
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.
OpenMayaRender.MPxDrawOverride.transform
(
)
transform(objPath, cameraPath) -> MMatrix
Returns The world space transformation matrix.
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.
* objPath (MDagPath) - The path to the object whose transform is needed.
* cameraPath (MDagPath) - The path to the camera that is being used to draw.
updateSelectionGranularity(path, selectionContext) -> self
This is method is called 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()).
The default implementation leaves the selection level set at its default value, which is kObject.
path (MDagPath) - The path to the instance to update the selection context for
selectionContext [OUT] (MSelectionContext) - The selection context