OpenMayaRender.MPxDrawOverride Class Reference

Inheritance diagram for OpenMayaRender.MPxDrawOverride:

Public Member Functions
def	__init__ ()
def	addUIDrawables ()
def	boundingBox ()
def	disableInternalBoundingBoxDraw ()
def	excludedFromPostEffects ()
def	handleTraceMessage ()
def	hasUIDrawables ()
def	isBounded ()
def	isTransparent ()
def	prepareForDraw ()
def	refineSelectionPath ()
def	supportedDrawAPIs ()
def	traceCallSequence ()
def	transform ()
def	updateSelectionGranularity ()
def	userSelect ()
def	wantUserSelection ()

Static Public Member Functions
def	__new__ ()
def	pointSnappingActive ()

Detailed Description

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)

Constructor & Destructor Documentation

def OpenMayaRender.MPxDrawOverride.__init__

(

)

Initialize self.  See help(type(self)) for accurate signature.

Member Function Documentation

def OpenMayaRender.MPxDrawOverride.__new__ ( )

static

Create and return a new object.  See help(type) for accurate signature.

def 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().

def 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

def OpenMayaRender.MPxDrawOverride.disableInternalBoundingBoxDraw

(

)

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.

def OpenMayaRender.MPxDrawOverride.excludedFromPostEffects

(

)

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.

def 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.

def 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.

def 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.

def 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).

def OpenMayaRender.MPxDrawOverride.pointSnappingActive ( )

static

pointSnappingActive() -> bool

This utility function can be called by a draw override to query whether Viewport 2.0 selection has been launched to find points for snapping. If so, in order for the associated DAG object to participate,

- The MPxSurfaceShape::getComponentSelectionMask() method must be overridden to include MSelectionMask::kSelectPointsForGravity.

- During the pre-filtering phase, updateSelectionGranularity() must be overridden to set the selection level to MSelectionContext::kComponent.

- During the hit test phase, wantUserSelection() must be overridden to return true, userSelect() must be overridden to return points for snapping.

The method returns true if snapping to points is active.

def 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

def OpenMayaRender.MPxDrawOverride.refineSelectionPath

(

)

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

def OpenMayaRender.MPxDrawOverride.supportedDrawAPIs

(

)

supportedDrawAPIs() -> DrawAPI

Returns the draw API supported by this override.

def 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.

def 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.

def OpenMayaRender.MPxDrawOverride.updateSelectionGranularity

(

)

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

def OpenMayaRender.MPxDrawOverride.userSelect

(

)

userSelect(selectInfo, drawContext, objPath, data, selectionList, worldSpaceHitPts) -> bool

This method is called during the hit test phase of Viewport 2.0 selection if wantUserSelection() returns true, in order to override the default hit test implementation for the associated DAG object. 

The selection info encapsulates the selection states such as the selection region. The draw context along with the user data cached by prepareForDraw() provides information the same as that being passed to the draw callback, thus makes it possible for a draw override to match its custom hit test with its custom drawing (a.k.a. WYSIWYG selection). 

If the object is hit, the implementation should add the DAG path and if appropriate its component to selectionList. It is the responsibility of the implementation to add world-space coordinate of the intersection between the selected item and selection ray to worldSpaceHitPts. 

A custom hit test implementation can choose GPU-based approaches such as OpenGL selection mode, occlusion query etc., or CPU-based approaches which perform hit test for custom geometries. Note that a custom hit test implementation is an object-level override, thus the default hit test implementation can still work for other objects in the scene. 

After a scene traversal in the hit test phase, Maya records a list of selected items and hit points. During the selection interpretation phase, the hit points will be sorted for certain cases such as single selection; only the winning hit point(s) will have the corresponding selected item(s) to call the refineSelectionPath() method for final selection result that is used to adjust the global active selection list. Thus, for these cases, Maya can only guarantee correct behavior if the implementation returns a valid hit point. 

For cases such as marquee selection over multiple components, where hit points don't matter, instead of creating one component object for each selected component element, the implementation should create one component object for all selected component elements, to avoid any unnecessary performance overhead due to the frequency of calling refineSelectionPath(). 

For cases such as point snapping, where multiple hit points are required, each hit point should be stored with the same array index as its selected item (typically a vertex component object), in order for Maya to associate each pair of selected item and hit point. 

This method should return true if at least one object was hit. The default value is false. 

* selectInfo [IN] (MSelectionInfo) - The selection info
* context [IN] (MDrawContext) - The draw context
* objPath [IN] (MDagPath) - The path to the associated DAG object
* data [IN] (MUserData) - The data cached by prepareForDraw()
* selectionList [OUT] (MSelectionList) - List of items selected by this method
* worldSpaceHitPts [OUT] (MPointArray) - List of hit points

def OpenMayaRender.MPxDrawOverride.wantUserSelection

(

)

wantUserSelection() -> bool

This method is called during the hit test phase of Viewport 2.0 selection and is used to indicate whether or not the userSelect() method should be called to override the default hit test implementation for the associated DAG object. 

This method returns false by default. In this case the draw callback method is invoked for the selection pass, with a special shader that encodes each entity with a different plain color, then the draw buffer is scanned and each color found inside the selection region is transformed into hit info that will be used by the later selection interpretation phase, including selected item and world-space hit point. 

If a custom hit test implementation is required, this method must be overridden to return true in order for userSelect() to be called.