Show frames
Go to: Synopsis. Return value. Keywords. Related. Flags. MEL examples.
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.
None
In query mode, return type is based on queried flag.
render, assembly
assembly
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.
|
// 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"