MPxSubSceneOverride Class Reference
This reference page is linked to from the following overview topics: Autodesk Maya 2014, Scene Overrides, Devkit Samples, 3.1 Registration, 3.7 Sub-scene Overrides, 4.5 Handling custom renderables for object overrides.
Detailed Description
Base class for Viewport 2.0 drawing of DAG nodes which represent sub-scenes.
MPxSubSceneOverride allows the user to completely define the renderable units (render items) needed to draw a specific DAG object type in Maya when using Viewport 2.0.
This class is independent of any specific hardware draw API. Implementations operate using the MRenderItem interface and provide a list of the render items needed to draw all instances of the associated DAG object. One implementation of the override will be created for each object in the Maya scene whose classification string satisfies the classification string used when registering the override. If the associated DAG object is instanced, the override is responsible for drawing all instances.
The collection of render items is stored in an MSubSceneContainer object. This container is suitable for storing and accessing large numbers of render items (thousands or tens of thousands) in a high performance manner. Implementations are responsible for assigning a shader and an optional matrix to each render item and must also provide the geometry for each render item as required by its shader. Geometry may be shared between render items and management of the geometry is up to the implementation.
MPxSubSceneOverride falls in between MPxDrawOverride and MPxGeometryOverride with respect to the amount of control given to the implementation. MPxDrawOverride allows full control over the entire draw of the object, but as a result the implementation is entirely responsible for the draw. MPxGeometryOverride is relatively simple to work with but as a result only limited control of the draw is available. MPxSubSceneOverride is allowed to fully define all render items, geometry and shaders providing a high degree of control. However this definition is abstracted from the hardware draw API so only one implementation is needed to get support for both DirectX and OpenGL. Furthermore, Maya will handle actually drawing the render items and thus the items can participate fully in the Maya rendering pipeline (including screen-space effects like SSAO, transparency sorting, shadow casting/receiving, etc.). Finally, render items may specify which draw modes they should draw in (wireframe, shaded, textured, bounding box) so there is no need for the implementation to track these modes manually.
MPxSubSceneOverride can be used to provide Viewport 2.0 support for any type of DAG object, however it is optimized for use in cases where a single DAG object needs to produce a large number of renderables which are not necessarily located at the same point in space. For example, this interface would be a good choice for implementing support for a custom node that needs to read and draw a full scene based on a description from a cache file.
MPxSubSceneOverride has two stages. In each stage, an instance of MFrameContext is provided to give some information about the current state of the renderer. The implementation is also free to query any information it needs from Maya.
1) requiresUpdate() : In this call, the implementation is given constant access to the set of render items for the object. On the first call it will be empty. If the method returns true, Maya will call update() and the implementation will be given the opportunity to add/remove render items from the set as well as to modify those items. Render item state is maintained as long as the render item is stored in the MSubSceneContainer object. Thus, if nothing needs to be changed this method may return false to skip the update phase.
2) update() : In this call, the implementation may add/remove render items to/from the set, and it may modify existing render items. For each render item the implementation is required to call setGeometryForRenderItem() to provide the geometry for the render item. Render items without geometry will not draw.
Implementations of MPxSubSceneOverride must be registered with Maya through MDrawRegistry.
#include <MPxSubSceneOverride.h>
Public Member Functions | |
| MPxSubSceneOverride (const MObject &obj) | |
| Construct an MPxSubSceneOverride. | |
| virtual | ~MPxSubSceneOverride () |
| Destructor. | |
| virtual MHWRender::DrawAPI | supportedDrawAPIs () const |
| Returns the draw API supported by this override. | |
| virtual bool | requiresUpdate (const MSubSceneContainer &container, const MFrameContext &frameContext) const =0 |
| On each frame Maya will give each instantiated MPxSubSceneOverride object a chance to update its set of render items. | |
| virtual void | update (MSubSceneContainer &container, const MFrameContext &frameContext)=0 |
| This method is called by Maya on each frame as long as the implementation of MPxSubSceneOverride::requiresUpdate() returns true. | |
| MStatus | setGeometryForRenderItem (MRenderItem &renderItem, const MVertexBufferArray &vertexBuffers, const MIndexBuffer &indexBuffer, const MBoundingBox *objectBox) |
| Call this method to provide the geometry for a render item. | |
Static Public Member Functions | |
| static const char * | className () |
| Returns the name of this class. | |
Constructor & Destructor Documentation
| MPxSubSceneOverride | ( | const MObject & | obj | ) |
Construct an MPxSubSceneOverride.
- Parameters:
-
[in] obj The Maya object this override draws
Member Function Documentation
| MHWRender::DrawAPI supportedDrawAPIs | ( | ) | const [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
| bool requiresUpdate | ( | const MSubSceneContainer & | container, |
| const MFrameContext & | frameContext | ||
| ) | const [pure virtual] |
On each frame Maya will give each instantiated MPxSubSceneOverride object a chance to update its set of render items.
Before beginning the update process for a specific override, Maya will first call this method to give the override a chance to indicate whether or not an update is necessary. If this method returns false, MPxSubSceneOverride::update() will not be called.
The set of render items for this override must not be modified in this method.
- Parameters:
-
[in] container The container for this override [in] frameContext Context information for the current frame
- Returns:
- True if Maya should trigger the update process for this override
| void update | ( | MSubSceneContainer & | container, |
| const MFrameContext & | frameContext | ||
| ) | [pure virtual] |
This method is called by Maya on each frame as long as the implementation of MPxSubSceneOverride::requiresUpdate() returns true.
In this method, the MSubSceneContainer should be populated with the render items that are required to draw the associated DAG object. The render items will remain in the container until they are explicitly removed or the associated object is deleted. Render items in the container may also be modified at this time.
All render items in the container upon completion of this method will be processed for drawing. Any such items which pass all filtering tests for the active viewport will draw. At a minimum, render items must be enabled, have a valid shader and valid geometry in order to draw in Viewport 2.0.
It is the responsibility of this method to call MHWRender::MRenderer::setLightsAndShadowsDirty() to trigger recomputation of any shadow maps in the scene (if required).
- Parameters:
-
[in] container The container for this override [in] frameContext Context information for the current frame
| MStatus setGeometryForRenderItem | ( | MRenderItem & | renderItem, |
| const MVertexBufferArray & | vertexBuffers, | ||
| const MIndexBuffer & | indexBuffer, | ||
| const MBoundingBox * | objectBox | ||
| ) |
Call this method to provide the geometry for a render item.
Although the render item will add a reference to each buffer, ultimate ownership of the geometric data remains with the caller. This method may only be called on render items which have been generated by this override and it may only be called during update(). Buffers may be shared among multiple render items. This method will replace any geometry currently associated with the render item with the newly provided geometry.
The bounding box parameter to this method is optional. If NULL, Maya will attempt to calculate the box automatically. Note that this may require a read-back of vertex data from the graphics card which can be a very slow operation. It is better to supply a correct bounding box whenever possible.
It is the responsibility of the caller to ensure that the buffers provided fulfill the geometry requirements of the shader for the render item. If the requirements are not met, the render item will not draw. If there is no shader assigned to the render item, this method will fail.
- Parameters:
-
[in] renderItem The render item to provide geometry for [in] vertexBuffers The vertex buffers for the geometry [in] indexBuffer The index buffer for the geometry [in] objectBox Object-space bounding box, may be NULL
- Returns:
- Status code
- Status Codes:
- MStatus::kSuccess The method was successful
- MStatus::kNotFound The render item does not belong to this override
- MStatus::kInvalidParameter Incorrect parameter (no shader on render item, empty vertex buffer array, bad primitive type)
- MStatus::kFailure Object error
| const char * className | ( | ) | [static] |
