pymel.core.rendering.prepareRender¶

prepareRender(*args, **kwargs)¶

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. preRenderTraversal run once per render, before any rendering is performed.postRenderTraversal run once per render, after all rendering has been performed.preRenderLayerTraversal run before rendering each render layer.postRenderLayerTraversal run after rendering each render layer.preRenderFrameTraversal run before rendering each frame.postRenderFrameTraversal 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 nulltraversal 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. 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. In query mode, return type is based on queried flag.

Flags:

Long Name / Short Name		Argument Types	Properties
defaultTraversalSet / dt		unicode
	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		unicode
	Deregister a registered traversal set. If the deregistered traversal set is the default traversal set, the new default traversal set will be the nulltraversal set.
invokePostRender / ior		bool
	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		bool
	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		bool
	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		bool
	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		bool
	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		bool
	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		bool
	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		unicode
	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		bool
	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		bool
	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		bool
	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		bool
	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		unicode
	Set or query properties for the specified registered traversal set.
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 have multiple arguments, passed either as a tuple or a list.

Derived from mel command maya.cmds.prepareRender

Example:

import pymel.core as pm

# Query what the default render traversal set is.
pm.prepareRender(query=True, defaultTraversalSet=True)
# Result: u'null' #
# Set the render traversal set to 'MyPrepareRender'.
cmd.prepareRender(edit=True, defaultTraversalSet='MyPrepareRender')
# Set the preRender traversal to the adskPrepareRender.preRender function,
# for the default render traversal set.
cmd.prepareRender(edit=True, preRender=adskPrepareRender.preRender)
# Set the default render traversal set to require saving the assembly node
# configuration before render, and restore it once rendering completes.
cmd.prepareRender(edit=True, saveAssemblyConfig=True)
# Set the label of traversal set 'MyPrepareRender' to be 'Custom Render'.
cmd.prepareRender(edit=True, label='Custom Render', traversalSet='MyPrepareRender')