C++ API Reference
|
Virtual base class for user viewport compute. More...
#include <MPxViewportComputeItem.h>
Classes | |
struct | Actions |
A bitmask storing a set of actions. More... | |
Public Types | |
enum | Action { kAccessVirtualDevice = 0x1 << 0, kAccessConsolidation = 0x1 << 1, kModifyVertexBufferSize = 0x1 << 2, kModifyMatrix = 0x1 << 3, kModifyConsolidation = 0x1 << 4, kModifyBounds = 0x1 << 5, kAddVertexStream = 0x1 << 6, kModifyVertexBufferData = 0x1 << 7, kModifyPrimitive = 0x1 << 8, kActionFinal = 0x1 <<9 } |
Actions an MPxViewportComputeItem may perform during its operator() call. Some MRenderItem functions can never be called during execute(): setDrawMode, setShader, setShaderFromNode, setExcludedFromPostEffect, supportsAdvancedTransparency, setCustomData, enable, castsShadows, recievesShadows, depthPriority, setAllowIsolateSelectCopy, setWAntConsolidation, setCompatibleWithMayaInstancer, setTreatAsTransparent, setSelectionMask, setWantSubSceneConsolidation may never be called. More... | |
Public Member Functions | |
MPxViewportComputeItem (bool hasExternalOwner) | |
Construct an MPxViewportComputeItem. More... | |
virtual | ~MPxViewportComputeItem () |
Destructor. | |
bool | hasExternalOwner () const |
Return whether or not this MPxViewportComputeItem should be deleted when the Maya object it is attached to is deleted. | |
void | setHasExternalOwner (bool hasExternalOwner) |
Sets whether or not this MPxViewportComputeItem should be deleted when the Maya object it is attached to is deleted. | |
MStatus | setRequiredAction (Action action, bool required) |
Sets actions which must be available to this MPxViewportComputeItem when execute() is called. More... | |
bool | hasRequiredAction (Action action) const |
Returns if a action is required by the MPxViewportComputeItem. More... | |
Actions | requiredActions () const |
Returns the set of required actions for this MPxViewportComputeItem. More... | |
virtual bool | execute (const Actions &availableActions, MRenderItem &renderItem)=0 |
Perform the user defined compute operations. More... | |
Static Public Member Functions | |
static const char * | className () |
Returns the name of this class. More... | |
Virtual base class for user viewport compute.
MPxViewportComputeItem is a virtual base class meant to provide a means for users to attach compute to certain Maya object types such that the lifetime of the compute may be managed by Maya.
When hasExternalOwner is false then the MPxViewportComputeItem is owned by the Maya object it is attached to and the MPxViewportComputeItem will be deleted when that object is deleted. When hasExternalOwner is true the lifetime of the MPxViewportComputeItem object is the responsibility of the allocator.
A typical use case for MPxViewportComputeItem would be to compute stream data for an MRenderItem. For example, a shaded MRenderItem could be created with only a postion buffer & an MPxViewportComputeItem attached to compute & fill the normal buffer.
When MPxViewportComputeItem is attached to an MRenderItem it is visible to consolidated world. Use methods canConsolidate() and cloneForConsolidation() to control how MPxViewportComputeItem interacts with consolidation.
An MPxViewportComputeItem must declare the action(s) it will take during a call to execute. These actions reflect access to resources or modification of the associated MRenderItem, or access to global resources. See setRequiredAction() and execute() for more information.
enum Action |
Actions an MPxViewportComputeItem may perform during its operator() call. Some MRenderItem functions can never be called during execute(): setDrawMode, setShader, setShaderFromNode, setExcludedFromPostEffect, supportsAdvancedTransparency, setCustomData, enable, castsShadows, recievesShadows, depthPriority, setAllowIsolateSelectCopy, setWAntConsolidation, setCompatibleWithMayaInstancer, setTreatAsTransparent, setSelectionMask, setWantSubSceneConsolidation may never be called.
Enumerator | |
---|---|
kAccessVirtualDevice |
The VP2 Draw API context, such as when calling MVertexBuffer::resourceHandle(). |
kAccessConsolidation |
The MGeometryIndexMapping for the item (if any). |
kModifyVertexBufferSize |
The size of the MVertexBuffers can be modified. |
kModifyMatrix |
MRenderItem::setMatrix may be called. Not currently supported. |
kModifyConsolidation |
MRenderItem::setSourceIndexMapping() may be called. |
kModifyBounds |
Set new object space bounds. Not currently supported. |
kAddVertexStream |
New streams may be added to the MRenderItem's MGeometry. Not currently supported. |
kModifyVertexBufferData |
Data in MVertexBuffers stored in the MRenderItems MGeometry may be modified. |
kModifyPrimitive |
MRenderItem::setPrimitive() may be called. Not currently supported. |
kActionFinal |
The final call to execute() for this frame. |
MPxViewportComputeItem | ( | bool | hasExternalOwner | ) |
Construct an MPxViewportComputeItem.
An MPxViewportComputeItem must be attached to an MRenderItem with addViewportComputeItem() for it to be executed().
When hasExternalOwner is false then the MPxViewportComputeItem is owned by the Maya object it is attached to and the MPxViewportComputeItem will be deleted when that object is deleted. When hasExternalOwner is true the lifetime of the MPxViewportComputeItem object is the responsibility of the allocator.
MStatus setRequiredAction | ( | MPxViewportComputeItem::Action | action, |
bool | required | ||
) |
Sets actions which must be available to this MPxViewportComputeItem when execute() is called.
Some combinations of actions are not supported. If adding action would create an unsupported combination of capabilities then setRequiredAction fails.
[in] | action | The action to set |
[in] | required | True if the action is required. |
bool hasRequiredAction | ( | MPxViewportComputeItem::Action | action | ) | const |
Returns if a action is required by the MPxViewportComputeItem.
[in] | action | The action to check |
MPxViewportComputeItem::Actions requiredActions | ( | ) | const |
Returns the set of required actions for this MPxViewportComputeItem.
|
pure virtual |
Perform the user defined compute operations.
Modifying renderItem during execute is strictly limited by the current availableActions. Only actions allowed by availableActions may be performed. Performing an action not included in availableActions will result in undefined behavior. availableActions is a superset of requiredActions().
If the original MRenderItem the compute was attached to was consolidated and kAccessConsolidation is a required action then renderItem may be the consolidated render item rather than any of the original source items. The source items may be accessed through MRenderItem::sourceIndexMapping(). The consolidated render item will have a copy of an arbitrarily choosen source render item's MPxViewportComputeItem, created using the cloneForConsolidation() method.
execute(const Actions&, MRenderItem&) is called one or more times per viewport draw. The exact number of called depends on the required actions set on this MPxViewportComputeItem. In general setting more required actions will result in fewer calls to execute().
If execute() is blocked waiting for an asynchronous task to finish then you may return false. When execute() returns false Maya will call execute() again during this viewport draw, allowing execution to resume after the threading task is complete. When kActionFinal is in availableActions then when execute() returns the compute item is considered finished and the return value is ignored.
[in] | availableActions | availableActions are the actions it is safe for the current call to execute() to perform. availableActions may be different for each execute call, but they will always include all of the required actions set on this MPxViewportComputeItem. |
[in] | renderItem | renderItem is either the original render item this MPxViewportComputeItem was attached to, or the render item which is the consolidated parent of the original item. |
|
static |
Returns the name of this class.