prepareRender command

Go to: Synopsis. Return value. Keywords. Related. Flags. MEL examples.

Synopsis

prepareRender [-defaultTraversalSet string] [-deregister string] [-invokePostRender] [-invokePostRenderFrame] [-invokePostRenderLayer] [-invokePreRender] [-invokePreRenderFrame] [-invokePreRenderLayer] [-invokeSettingsUI] [-label string] [-listTraversalSets] [-postRender script] [-postRenderFrame script] [-postRenderLayer script] [-preRender script] [-preRenderFrame script] [-preRenderLayer script] [-restore] [-saveAssemblyConfig boolean] [-settingsUI script] [-setup] [-traversalSet string] [-traversalSetInit script]

prepareRender is undoable, queryable, and editable.

This command is used to register, manage and invoke render traversals. Render traversals are used to configure a scene to prepare it for rendering.

This command has special support for scene assembly nodes. To render scene assembly nodes, a rendering traversal can activate an appropriate representation, for each assembly node in the scene. When rendering is done, this command can correspondingly restore the representation that was active before rendering on each assembly. Render traversals are grouped into traversal sets. A render traversal set includes callbacks, or render traversals, for one or more of the following steps of rendering, ordered by decreasing level of granularity. A render traversal callback is an arbitrary script, either MEL or Python, that can transform the Maya scene for rendering purposes.

preRender: Traversal run once per render, before any rendering is performed.
postRender: Traversal run once per render, after all rendering has been performed.
preRenderLayer: Traversal run before rendering each render layer.
postRenderLayer: Traversal run after rendering each render layer.
preRenderFrame: Traversal run before rendering each frame.
postRenderFrame: Traversal run after rendering each frame.

During a render view or batch render, Maya will run the render traversals from the same traversal set, the default traversal set. Traversal sets are named, so multiple traversal sets can be registered with this command, and the default render traversal set can be switched to any one of these registered traversal sets. When changing the default traversal set, the different render traversal callbacks (preRender, preRenderLayer, preRenderFrame, postRender, postRenderLayer, postRenderFrame) are switched as a unit.

At render time, the software rendering code invokes the callbacks of the default traversal set. The prepareRender scripting capability allows for the development of multiple rendering preparation scripts, including from plugins, to provide extensibility rather than being constrained to a single implementation.

A special traversal set is the "null" traversal set. It is the initial default traversal set, and cannot be deregistered. It performs no work, and does not save and restore the assembly node active representation configuration. It will provide WYSIWYG (What You See Is What You Get) rendering of assembly nodes, without switching to a different representation to render.

Render traversals are invoked by Maya using this command's create mode. This is done by Maya's rendering infrastructure, and should not be required unless developing new render views or batch render code. Most uses of this command will simply use the edit mode to register render traversals into a render traversal set, or the query mode to query the names of the render traversals in a render traversal set.

Render Traversals versus Render MEL Scripts

Render traversals are similar in intent to the user-specified pre- and post-render, pre- and post-render layer, pre- and post-render frame MEL script capability. The difference with the user MEL scripts is that prepareRender is in addition to, and does not replace, the user MEL scripts, can register multiple render traversal sets and switch them, and supports both MEL and Python. The MEL render scripts are run inside the scope of the render traversals, that is, the preRender traversal is run before the pre-render MEL script and the postRender traversal is run after the post-render MEL script, the preRenderLayer traversal is run before the pre-render layer MEL script and the postRenderLayer traversal is run after the post-render layer MEL script, and finally the preRenderFrame traversal is run before the pre-render frame MEL script and the postRenderFrame traversal is run after the post-render frame MEL script.

Saving and Restoring State

The prepareRender command has support for saving and restoring the active representation of assembly nodes in the scene. Use the saveAssemblyConfig flag to indicate that the render traversal set requires saving the assembly node active representation before rendering begins, and should restore the assembly node active representation after rendering ends.

It is the responsibility of render traversals that modify the scene in ways other than changing the active representation on assembly nodes to restore the scene to its previous state, most likely using the postRender, postRenderLayer, and postRenderFrame traversals.

Note that Maya does not call the prepareRender -restore command on batch render completion, since batch rendering is done on a copy of the scene which is discarded once rendering terminates. Implementors of render traversals may wish to check whether they are running in batch mode, to implement the same optimization.

Return value

None

In query mode, return type is based on queried flag.

Keywords

render, assembly

assembly

Flags

defaultTraversalSet, deregister, invokePostRender, invokePostRenderFrame, invokePostRenderLayer, invokePreRender, invokePreRenderFrame, invokePreRenderLayer, invokeSettingsUI, label, listTraversalSets, postRender, postRenderFrame, postRenderLayer, preRender, preRenderFrame, preRenderLayer, restore, saveAssemblyConfig, settingsUI, setup, traversalSet, traversalSetInit

Long name (short name) Argument types Properties

-defaultTraversalSet(-dt) string

Set or query the default traversal set. The prepareRender command performs operations on the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-deregister(-d) string

Deregister a registered traversal set. If the deregistered traversal set is the default traversal set, the new default traversal set will be the "null" traversal set.

-invokePostRender(-ior)

Invoke the postRender render traversal for a given traversal set. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-invokePostRenderFrame(-iof)

Invoke the postRenderFrame render traversal for a given traversal set. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-invokePostRenderLayer(-iol)

Invoke the postRenderLayer render traversal for a given traversal set. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-invokePreRender(-irr)

Invoke the preRender render traversal for a given traversal set. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-invokePreRenderFrame(-irf)

Invoke the preRenderFrame render traversal for a given traversal set. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-invokePreRenderLayer(-irl)

Invoke the preRenderLayer render traversal for a given traversal set. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-invokeSettingsUI(-isu)

Invoke the settings UI callback to populate a layout with UI controls, for a given traversal set. The current UI parent will be a form layout, which the callback can query using the setParent command. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-label(-lbl) string

Set or query the label for a given traversal set. The label is used for UI display purposes, and can be localized. The traversal set will be the default, unless the -traversalSet flag is used to specify an explicit traversal set.

-listTraversalSets(-lt)

Query the supported render traversal sets.

-postRender(-por) script

Set or query the postRender render traversal for a given traversal set. This traversal is run after a render. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-postRenderFrame(-pof) script

Set or query the postRenderFrame render traversal for a given traversal set. This traversal is run after the render of a single frame, with a render layer. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-postRenderLayer(-pol) script

Set or query the postRenderLayer render traversal for a given traversal set. This traversal is run after a render layer is rendered, within a render. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-preRender(-prr) script

Set or query the preRender render traversal for a given traversal set. This traversal is run before a render. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-preRenderFrame(-prf) script

Set or query the preRenderFrame render traversal for a given traversal set. This traversal is run before the render of a single frame, with a render layer. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-preRenderLayer(-prl) script

Set or query the preRenderLayer render traversal for a given traversal set. This traversal is run before a render layer is rendered, within a render. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-restore(-rtr)

Clean up after rendering, including restoring the assembly active representation configuration for the whole scene, if the saveAssemblyConfig flag for the traversal set is true. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-saveAssemblyConfig(-sac) boolean

Set or query whether or not the assembly active representation configuration for the whole scene should be saved for a given traversal set. The traversal set will be the default, unless the -traversalSet flag is used to specify an explicit traversal set.

-settingsUI(-sui) script

Set or query the settings UI callback for a given traversal set. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-setup(-stp)

Setup render preparation, including saving the assembly active representation configuration for the whole scene, if the saveAssemblyConfig flag for the traversal set is true. Any previously-saved configuration will be overwritten. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set.

-traversalSet(-ts) string

Set or query properties for the specified registered traversal set.

In query mode, this flag needs a value.

-traversalSetInit(-tsi) script

Set or query the traversal set initialisation callback for a given traversal set. The traversal set will be the default traversal set, unless the -traversalSet flag is used to specify an explicit traversal set. This callback is invoked whenever the specified traversal set becomes the default. traversal set.

Flag can appear in Create mode of command	Flag can appear in Edit mode of command
Flag can appear in Query mode of command	Flag can be used more than once in a command.

MEL examples

// Query what the default render traversal set is.
prepareRender -q -defaultTraversalSet
// Set the render traversal set to MyPrepareRender.
prepareRender -e -defaultTraversalSet MyPrepareRender
// Set the default render traversal set to require saving the assembly node
// configuration before render, and restore it once rendering completes.
prepareRender -e -saveAssemblyConfig
// Set the label of traversal set "MyPrepareRender" to be "Custom Render".
prepareRender -e -label "Custom Render" -traversalSet "MyPrepareRender"

command (MEL)	Python version
prepareRender	In categories: Rendering