MPxRenderer Class Reference
Related help topics: #include <MPxRenderer.h>
Class Description
Base class for plugin renderers.
A base class providing an interface through which a plugin can implement a renderer to provide rendered images of a scene.
LIMITATION: Currently this class is only used for rendering into the Material Viewer in the Hypershade editor. For renderer integration into the Render View, please refer to the API class MRenderView and the MEL command "renderer". For rendering of shader swatches, please refer to the API class MSwatchRenderBase.
The derived class needs to be registered and deregistered with Maya using calls to MFnPlugin::registerRenderer() and MFnPlugin::deregisterRenderer().
Translation of the scene data to render is done by Maya calling the corresponding translate and set methods. The translate methods (translateMesh(), translateLightSource(), translateCamera(), translateTransform(), translateShader(), translateEnvironment) should implement translation of a Maya object to a corresponding renderer specific object. When Maya calls translate or set methods it is always done in a thread-safe context. This means that the Maya handle sent in (and associated data) is valid and thread-safe for the duration of the call, but not guaranteed to be valid or thread-safe after the call, so the renderer should not save the Maya handle. If it needs to save the handle, it should do so using an MObjectHandle and never save the MObject directly. If the handle is saved it is up to the renderer to make sure the data is accessed in a thread-safe way.
When Maya translates a shape object (mesh, light, camera), the call to the translate method is always followed by one or more calls to translateTransform(), which instantiates the shape and assigns it as a child to one or more transform nodes.
Calls to all translate and set methods are always preceded by a call to beginSceneUpdate(). This is to let the renderer know that scene updates are about to happen, to let it cancel the current rendering or otherwise prepare for scene updates. The update is then followed by a call to endSceneUpdate(), to let the renderer know that no more updates are comming (until next beginSceneUpdate()). The renderer can then do any scene data post-processing and restart the rendering.
Calls to translate and set methods can occur before a render job is started, for initial scene translation. But it can also occur during rendering for scene changes. So the renderer must support these methods being called at any time. However they are always encapsulated by calls to beginSceneUpdate() and endSceneUpdate().
The translate methods are also used to update already existing objects. So if a translate method is called with an uuid pointing to an already translated object, that means the object should be updated.
A render session is started by Maya calling startAsync(). This call should start a render control thread running asynchronously from Maya's main thread. The control thread is in turn allowed to spawn as many render worker threads as given by the JobParams sent in.
During rendering the refresh() method should be called to send new image data back to Maya. The progress() method could be called to report the progress of the current image.
While the job is running it is up to the renderer to decide when the rendered image is finished. When finished the render worker threads should terminate or sleep, and not cause unnecessary CPU usage. If scene updates occur the control thread should restart the rendering to produce a new image with the new scene data. The job should be running in this manner until a call to stopAsync() is received. At that point both worker threads and the control thread should terminate.
A call to destroyScene() should clear out the scene and destroy all allocated scene data.
The steps below outlines the events for a render job session and which calls Maya sends to the renderer. A scene update consists of a block of calls, named a Scene Update Block below:
beginSceneUpdate() translateMesh() translateTransform() setProperty() setShader() ... endSceneUpdate()
1. Maya will start the render session with 0 or more Scene Update Blocks. The renderer should use them to build its internal representation for the scene graph. 2. Maya will call startAsync(). The renderer should start a separate thread. 3. The renderer should start rendering the internal scene graph that it now has, in the separate thread or by starting other worker threads. 4. The renderer should call progress() to indicate to Maya how far along it is. A value between 0.0 and 1.0 indicates the rendering is in progress. A value of 1.0 or higher indicates the rendering is completed. A negative value indicates the task is done and scene graph destroyed (see point 12). 5. The renderer should call refresh() during rendering to present successive image results that Maya can display. 6. When the rendering is completed the renderer should drop into a waiting state. Notification of this is done by calling progress() with a value of 1.0 or higher. 7. Maya may modify the scene graph through additional Scene Update Blocks. If these occur while the renderer is in its waiting state then it must start up a new render. If these occur while the renderer is already rendering, it must incorporate the changes into the current render, typically by restarting it. 8. Steps 3 through 7 may be repeated multiple times. 9. Maya calls stopAsync(). The renderer should terminate its separate threads but retains its internal scene graph. 10. Steps 1 through 9 may be repeated to produce renderings of variations of the same scene. 11. Maya calls destroyScene(). The renderer should destroy its internal scene graph. 12. The renderer should then finish by calling progress() with a negative value, to let Maya know the scene graph is destroyed and the renderer is shut down.
Classes | |
| class | JobParams |
| Parameters for starting a new job. More... | |
| class | ProgressParams |
| Parameters for reporting progress of a task. More... | |
| class | RefreshParams |
| Parameters for doing refresh of the view when new image data is available. More... | |
Public Types | |
| enum | EnvironmentType { IBL_ENVIRONMENT } |
| Identifier for environment types. More... | |
| enum | JobType { SWATCH_RENDER_JOB } |
| Identifier for job types. More... | |
Public Member Functions | |
| virtual | ~MPxRenderer () |
| Class destructor. | |
| virtual MStatus | startAsync (const JobParams ¶ms) |
| Start an asynchronous render job session. More... | |
| virtual MStatus | stopAsync () |
| Stop an asynchronous render job session. More... | |
| virtual bool | isRunningAsync () |
| Returns true if an asynchronous job is running. More... | |
| virtual MStatus | beginSceneUpdate () |
| Notify the renderer that scene updates are about to happen. More... | |
| virtual MStatus | translateMesh (const MUuid &id, const MObject &node) |
| Translate a Maya mesh node to a corresponding renderer specific object. More... | |
| virtual MStatus | translateLightSource (const MUuid &id, const MObject &node) |
| Translate a Maya light source node to a corresponding renderer specific object. More... | |
| virtual MStatus | translateCamera (const MUuid &id, const MObject &node) |
| Translate a Maya camera node to a corresponding renderer specific object. More... | |
| virtual MStatus | translateEnvironment (const MUuid &id, EnvironmentType type) |
| Translate an environment of given type to a corresponding renderer specific object. More... | |
| virtual MStatus | translateTransform (const MUuid &id, const MUuid &childId, const MMatrix &matrix) |
| Translate a Maya transform to a corresponding renderer specific object. More... | |
| virtual MStatus | translateShader (const MUuid &id, const MObject &node) |
| Translate a Maya shader node to a corresponding renderer specific object. More... | |
| virtual MStatus | setProperty (const MUuid &id, const MString &name, bool value) |
| Set a boolean property value on a node. More... | |
| virtual MStatus | setProperty (const MUuid &id, const MString &name, int value) |
| Set an integer property value on a node. More... | |
| virtual MStatus | setProperty (const MUuid &id, const MString &name, float value) |
| Set a float property value on a node. More... | |
| virtual MStatus | setProperty (const MUuid &id, const MString &name, const MString &value) |
| Set a string property value on a node. More... | |
| virtual MStatus | setShader (const MUuid &id, const MUuid &shaderId) |
| Assign a shader to a node. More... | |
| virtual MStatus | setResolution (unsigned int width, unsigned int height) |
| Sets rendering resolution. More... | |
| virtual MStatus | endSceneUpdate () |
| Notify the renderer that scene update is completed. More... | |
| virtual MStatus | destroyScene () |
| A call to this method should clear out the scene and destroy all allocated scene data. More... | |
| virtual bool | isSafeToUnload ()=0 |
| Returns true if it is safe to unload the plugin for this renderer. More... | |
Protected Member Functions | |
| MPxRenderer () | |
| Class constructor. | |
| void | refresh (const RefreshParams ¶ms) |
| Send new image data to Maya. More... | |
| void | progress (const ProgressParams ¶ms) |
| This should be called during rendering to notify Maya about the progress of a task. More... | |
Member Enumeration Documentation
| enum EnvironmentType |
| enum JobType |
Member Function Documentation
Start an asynchronous render job session.
This call should start a render control thread running asynchronously from Maya's main thread. The control thread is in turn allowed to spawn as many render worker threads as given by JobParams.maxThreads.
During rendering the refresh() method should be called to send new image data back to Maya and the progress() method should be called to report progress of the current task.
While the job is running it is up to the renderer to decide when the rendered image is finished. When finished the render worker threads should terminate or sleep, and not cause unnecessary CPU usage. If scene updates occur the control thread should restart the rendering to produce a new image with the new scene data. The job should be running in this manner until a call to stopAsync() is received. At that point both worker threads and the control thread should terminate.
There will only be a single job running a any one time. Maya will never start multiple jobs.
- Parameters
-
[in] params The job parameters
- Returns
- Status code
|
virtual |
Stop an asynchronous render job session.
All threads started should be terminated at this point, and resurces allocated by the threads should be freed.
The scene objects should not be destroyed by this call, as a new call to startAsync() could be done to re-render the same scene. Scene objects should stay loaded until a call to destroyScene() is received.
- Returns
- Status code
|
virtual |
Returns true if an asynchronous job is running.
- Returns
- async job state
|
virtual |
Notify the renderer that scene updates are about to happen.
Any preparations for receiving new scene data should be made here. For instance if rendering is in progress it could be interrupted here, to make the renderer ready to receive the new data.
- Returns
- Status code
Translate a Maya mesh node to a corresponding renderer specific object.
This call will always be followed by one or more calls to translateTransform(), to instantiate the mesh and assign it as a child to one or more transform nodes.
- Parameters
-
[in] id Identifier for the mesh node [in] node Object handle to the Maya mesh node
- Returns
- Status code
Translate a Maya light source node to a corresponding renderer specific object.
This call will always be followed by one or more calls to translateTransform(), to instantiate the light source and assign it as a child to one or more transform nodes.
- Parameters
-
[in] id Identifier for the light source node [in] node Object handle to the Maya light source node
- Returns
- Status code
Translate a Maya camera node to a corresponding renderer specific object.
This call will always be followed by one or more calls to translateTransform(), to instantiate the camera and assign it as a child to one or more transform nodes.
- Parameters
-
[in] id Identifier for the camera node [in] node Object handle to the Maya camera node
- Returns
- Status code
|
virtual |
Translate an environment of given type to a corresponding renderer specific object.
- Parameters
-
[in] id Identifier for the environment [in] type Type of environment to create
- Returns
- Status code
|
virtual |
Translate a Maya transform to a corresponding renderer specific object.
A transform node is used to create instances of other nodes. The node to instantiate becomes a child to the transform node, and the transformation matrix will affect the appearance of the child node.
A transform node should support having multiple children. Such a setup is translated by Maya calling this method multiple times, with the same transform node id, but different child ids.
A call to translate a shape node (mesh, light, camera) is always followed by one or more calls to this method, in order to instantiate the shape node. See translateMesh(), translateLightSource() and translateCamera().
- Parameters
-
[in] id Identifier for the transform node [in] childId Identifier for the node to become child to this transform [in] matrix The transformation matrix for the transform node
- Returns
- Status code
Translate a Maya shader node to a corresponding renderer specific object.
This should translate the shader node as well as the upstream network if the shader node has connections.
- Parameters
-
[in] id Identifier for the shader node [in] node Object handle to the Maya shader node
- Returns
- Status code
Set a boolean property value on a node.
- Parameters
-
[in] id Identifier for the node to set the property on [in] name Name of the property [in] value The new value
- Returns
- Status code
Set an integer property value on a node.
- Parameters
-
[in] id Identifier for the node to set the property on [in] name Name of the property [in] value The new value
- Returns
- Status code
Set a float property value on a node.
- Parameters
-
[in] id Identifier for the node to set the property on [in] name Name of the property [in] value The new value
- Returns
- Status code
Set a string property value on a node.
- Parameters
-
[in] id Identifier for the node to set the property on [in] name Name of the property [in] value The new value
- Returns
- Status code
Assign a shader to a node.
- Parameters
-
[in] id Identifier for the node [in] shaderId Identifier for the shader
- Returns
- Status code
|
virtual |
Sets rendering resolution.
- Parameters
-
[in] width Rendering width [in] height Rendering height
- Returns
- Status code
|
virtual |
Notify the renderer that scene update is completed.
Any postprocessing of the new scene data could be done here. A call to this method is always preceded by a call to beginSceneUpdate(). If rendering was in progress when the call to beginSceneUpdate() came, the rendering should be resumed and continue here.
- Returns
- Status code
|
virtual |
A call to this method should clear out the scene and destroy all allocated scene data.
When the scene has been destroyed a notification of this should be sent to Maya. This is done by calling the progress() method with the progress value set to a negative value.
- Returns
- Status code
|
pure virtual |
Returns true if it is safe to unload the plugin for this renderer.
Should only return true if the renderer is stopped and all of its scene data is destroyed. This is a pure virtual method, and must be overridden in derived classes.
- Returns
- True if safe to unload, false otherwise
|
protected |
Send new image data to Maya.
This should be called multiple times during rendering to show results progressively. It is up to the renderer to decide the granularity of these results. It can be done on smaller tiles of the image or as iterations on the full frame.
- Parameters
-
[in] params The refresh data
|
protected |
This should be called during rendering to notify Maya about the progress of a task.
The �progress� field in the params structure should be set according to the state of the task. A value between 0.0 and 1.0 indicates the task is currently in progress, where 1.0 means the task is completed. A negative value indicates the task is done (cancelled or completed) and all resources for it has been destroyed. A call to progress with a negative value should therefore be done when destroyScene() has been executed.
- Parameters
-
[in] params The progress data
The documentation for this class was generated from the following files:
- MPxRenderer.h
- MPxRenderer.cpp