Render Passes for Maya

Written by Andrew Chapman

NOTE: Maya 7.0 Render Layers

One of the major new features of Maya 7.0 is a whole new Render Layers system. This new functionality is quite thorough and well implemented, and should cover most people's needs for render pass management.

However, whilst the new system is flexible enough to be able to override shaders, viibility or just about any other attribute in your scene, it doesn't support writing MEL code to be executed when changing passes. This means you can't do completely arbitrary things between passes. For example you couldn't reassign MTOR shaders between passes if you're using RenderMan, or execute scripts to make your changes for you, such as loading presets or shader assignments from external scene description files.

So there is definitely still a use for this plugin, particularly for more complex film pipelines, and I'll continue to support it and release new versions whenever a new Maya release is made, but I will probably not be making any major changes to it from now on.

Fortunately the functionality of this plugin and Maya 7.0's Render Layers don't clash, and they can quite happily cooperate within the one scene. For example, you could use Maya's Render Layers to more easily handle the shader assignments, and this plugin to handle other changes. You would then have an override to set the Maya Render Layer whenever you apply a render pass. You can do this with the MEL command: editRenderLayerGlobals -currentRenderLayer "LAYERNAME"

Introduction

Render Passes for Maya is a plugin that allows you to render any number of custom render passes from a single maya scene file.

Maya itself has only a rudimentary level of support for creating render passes. Maya provides you with render layers (where you can specify sets of objects to be rendered separately) and also some predefined render passes (beauty, colour, shadow, diffuse and specular).

This plugin goes much further, allowing you to override literally any aspect of your scene depending on which pass you are currently rendering. For example, you can assign specific shaders for each pass, enable/disable lights and shadows, modify object visibility (including primary/secondary rays) and customise render globals settings for each render (e.g. turning on and off raytracing).

Because Render Passes for Maya makes real changes to your scene (as opposed to relying on support for passes in the renderer), it should be fully compatible with any rendering or export system you have. For example you could have a single scene for rendering out some passes using the Maya renderer, some using RenderMan, and some for exporting to another tool in your production pipeline.

Installation

To install Render Passes for Maya, simply unzip the archive to a directory on your system, and add this directory to your MAYA_SCRIPT_PATH location, and add the appropriate subdirectory matching your platform to the MAYA_PLUG_IN_PATH setting. These settings are normally done by editing your maya.env file.

Alternatively, you can copy the RenderPass plugin into one of your existing MAYA_PLUG_IN_PATH locations, and copy the MEL files from the package to a directory somewhere within your MAYA_SCRIPT_PATH locations. You should also copy the HTML and PNG files to your MAYA_SCRIPT_PATH locations so you can access the online help from within Maya.

After updating your paths or copying the files, reload Maya and open the plugin manager. The RenderPass plugin should now be listed and you can load it (you can also set it to be automatically loaded whenever you start Maya).

For more help on installing custom plugins, please review the Maya documentation. If you're still stuck see the support section at the bottom of this page.

Usage

When you load the Render Passes plugin, you will find a new menu item added to Maya's main menu bar when you are in the Rendering interface mode:

The first entry in this menu brings up the Render Pass Editor, from which you can define your passes and overrides. The Set Render Pass item brings up a sub-menu listing all your current passes, allowing you to easily apply any one of them to the current scene (you can tear-off this menu to float over your workspace). The menu item labelled Create Render Pass Scenes brings up a window which allows you to optionally save out a render scene for each one of your passes.

Finally, the Render Pass Help menu item brings up this online help from within Maya if the help files are found within your MAYA_SCRIPT_PATH locations. (NOTE: this will only work if you can normally launch Maya's own online help from within the program - sometimes under Linux this requires a browser window to be open on your desktop beforehand).

For a quick run through using the plugin, you can read this simple tutorial.

Render Pass Editor

Using the Render Pass Editor you can create render passes, and specify the changes to be made to your scene when you apply those render passes.

After creating some passes and giving them recognizable names, you then add your overrides and assign these overrides to the passes they should be applied to. An override consists of a name (so you can easily recognize it later) and two chunks of MEL code. The first section of MEL code is executed when the override is applied, and the second section of MEL code is executed when the override's effects are to be removed (when switching to another pass). The second block of code is known as the override revert code.

In the simplest case you can just have one override for each of your passes - for example a render pass named ShadowPass and an override named ShadowOverride to apply shadow catching materials to all your objects.

However, with a complex scene you might find yourself duplicating a lot of code amongst your overrides to do common things, such as turning on and off raytracing calculations. Instead, you could have an override named 'turnOnRaytracing' which activates raytracing in your render globals, and you have this override active in your 'beauty' and 'reflection' passes, and off in your 'mattes', 'depth' and 'diffuse' passes (for example).

As a general rule, it is best to keep each override to performing a single simple task, and have them on or off for different passes.

After creating your passes and overrides, you can change the order that they are displayed by right-clicking on the lists for a context menu. When you have a lot of passes it helps to keep similar ones together.

Writing Override MEL Code

The only way for render passes to be able to modify all aspects of your scene is to specify the required changes using MEL code (though as of version 1.5 of the Render Passes plugin, you also have the option of taking shader assignment snapshots - see the section on 'Snapshots' below).

Writing MEL code for the overrides can seem daunting to anyone who isn't familiar with MEL scripting - but it really is quite simple for our purposes. The best way to know what code you need is to look in the script editor whilst you make changes to your scene. For example, if you wish to change the colour of a material for a certain pass, then select the material, set the new colour, and you will see in the script editor something like this:

  setAttr "lambert1.color" -type double3 1 0 0;

You can see that it is setting three values for the color attibute of the material lambert1 which would make it pure red in this case. Set the colour back how you want it and you will see the code that reverts that change again, e.g:

  setAttr "lambert1.color" -type double3 0.5 0.5 0.5;

Many changes aren't shown in the script editor by default, and if you are trying to work out how a certain change is made you can turn on the Echo All Commands option in the script menu of the script editor. This will cause many more commands to be shown as they are executed in Maya. This will cause a lot more output, and you will have to do a bit of searching through to find just the minimal bit of code that will affect the change you're after.

I've also find that a great way to determine how to do something is to look in Maya's own MEL scripts to see how it does things. This can be a little tricky, but using a search program to look for little bits of text (such as the label of a menu that performs the function) in Maya's scripts directories you can usually find what you're after.

If you are still stuck, you should find someone who does know MEL coding to help you out. The Maya forums on the excellent HighEnd3D site are also a great source of help, as is Bryan Ewert's excellent Maya API+MEL site. You shouldn't really be asking any questions specific to using this plugin on the Maya lists though - see the Support section at the end of this page for that.

Snapshots (new to v1.5+)

Specifying what needs to change between passes by MEL code is certainly the most powerful and flexible way of doing things, but it can be quite tedious for common tasks, such as shader assigments, particularly when you have many objects in your scene, or your shader setups are changing frequently.

As an alternative to writing override MEL code, you can take 'snapshots' of your scene at a certain point, and the Render Passes plugin will store the state of things in order to automatically restore that setup when a pass is applied. Currently, only Maya shader assignments are able to be captured, but the mechanism will be expanded soon to include at least MTOR shader assignment and object visibility.

To create a snapshot, select a pass in the Render Pass Editor (you don't need to have the pass applied, just selected in the list), and on the right hand side of the editor, under the 'Snapshots' heading, you can see the different types of snapshots you can create. Next to each one there are three buttons:

    Snapshot - create a snapshot for this pass
    Clear - clear the snapshot for this pass
    Clear All - clear the snapshot for all passes

The snapshots are created when you click the 'Snapshot' button - you don't need to also click the 'Save Changes' button at the bottom of pass edit panel.

As there is no snapshot for the '<none>' pass (or any concept of a 'revert snapshot'), you probably want to make sure you've got some sort of a 'default' or 'beauty' pass for your normal shader assignments before making snapshots for your more specialized passes, or your original shader assignments may be lost.

There is no harm in mixing snapshots and MEL code overrides. When changing passes the snapshots are first applied, then the override code is run. So any shader assignments made by overrides will have precedence over the snapshots. This is something to look out for when adding snapshots to older scenes - they may appear to not be working if your existing overrides are still in effect.

One thing to be wary of when adding new passes with snapshots: when you click 'save changes' for a pass, all the relevant overrides, snapshots and override revert code are run to ensure that the current state of the scene matches the currently applied pass. Because of this, if you are adding a new pass and have already applied the shaders to your scene for the new pass, be sure to snapshot the shader assignments with the newly added pass selected in the editor before ever clicking 'save changes', or your new shader assignments may be lost. To be on the safe side, it is better to add the new pass, save it with any selected overrides, then apply and snapshot your shaders.

Quick Tutorial & Demo Scene

The concepts of using overrides and passes can be somewhat confusing for new users. There is a small tutorial available to take you through the steps of creating a very simple render pass setup. Click here to jump to the tutorial.

You should also find a demo scene included in the package you downloaded. This scene contains a number of pre-configured render passes. Just open the render view, and select each pass in turn and render it to see the results. You can then inspect the override code in the Render Passes Editor to see how it works.

MEL Code for Common Override Tasks

When writing overrides, there are certain things that you are going to want to do quite regularly, so I will list the code required here. All you will need to do is change the object/material names in these examples to suit your scenes.

TaskOverride CodeCode to Revert
Assign a Shading Group* assignSG specialMaterial_SG myObject; assignSG normalMaterial_SG myObject;
Hide an Object setAttr myObject.visibility 0; setAttr myObject.visibility 1;
Turn on Raytracing setAttr defaultRenderQuality.enableRaytracing true; setAttr defaultRenderQuality.enableRaytracing false;
Set Reflection Trace Limit setAttr defaultRenderQuality.reflections 4; setAttr defaultRenderQuality.reflections 0;
Set Refraction Trace Limit setAttr defaultRenderQuality.refractions 2; setAttr defaultRenderQuality.refractions 0;
Set Shadow Trace Limit setAttr defaultRenderQuality.shadows 6; setAttr defaultRenderQuality.shadows 0;
Turn off an object's
primary visibility		 setAttr myObject.primaryVisibility 0; setAttr myObject.primaryVisibility 1;

*Notes on the 'assignSG' command

This command is part of Maya, but for some reason they chose not to make it accessible until after the buildShaderMenus.mel script has been sourced. This normally happens when you right-click on an object in the 3D viewports, but this script is also sourced automatically when the Render Passes plugin is loaded. This command prints out a line like // Result: big_ball_matSG // to the script editor - if you get tired of lots of these appearing when you switch between passes containing assignSG commands, you can comment out the line that prints this message in the buildShaderMenus.mel MEL script within your Maya installation.

RenderPass Tips:

Here's some quick tips and things to look out for when using the Render Passes plugin:

Create Render Pass Scenes Window

Render Passes for Maya also provides you with an easy way for saving out one scene per pass. Selecting Create Render Pass Scenes from the Render menu brings up a new window:

Using the settings shown in the image above, the following files will be written out:

  CURRENT_MAYA_PROJECT/renderScenes/myScene_mattePass.mb
  CURRENT_MAYA_PROJECT/renderScenes/myScene_gradientPass.mb
  CURRENT_MAYA_PROJECT/renderScenes/myScene_reflectionPass.mb

Where CURRENT_MAYA_PROJECT is your currently active maya project. The output directory should be an existing directory within your current project - usually 'scenes' or 'renderScenes' unless you have created another one yourself.

The only reason why you would need to use the Create Render Pass Scenes function is if you wish to render all your passes together on a render farm that does not allow you to run the applyRenderPass MEL command between passes (see the section on scripting below for more info on this command).

Also, if you only need to render one pass at a time, you can stick with your original scene file - just apply a render pass, render, set another pass, render, etc. If you apply a pass to your scene and save it, then it will remain setup for that pass if you perform a batch render using that scene file too.

Importing and Exporting Render Passes

All the Render Pass data in your scene is held on a single custom node named renderPassManager. If you wish to save off a copy of your passes, either as a template or to import into another scene then you can select the Export Render Passes Node option from the menu to save this node out to a new Maya scene file.

If you are importing this node into another scene then you need to first ensure that there is not already a node named renderPassManager. If there is, then the node you import will be renamed by Maya as renderPassManager1 and it will not be found by the plugin. So before importing a Render Passes node it is best to select the Delete Render Passes Node option from the menu first. This can also be done to completely remove Render Passes from any scene.

Snapshots are an exception to the import/export process. Snapshots are implemented as connections between nodes in your scene. Therefore, if you export your Render Passes node (called 'renderPassManager') from one scene to import into another, the snapshots cannot be maintained. However, if the geometry nodes and their shaders are exported from one scene to another, then the snapshots will still work, provided there are matching pass names in the second scene, or if the Render Pass node is exported with them (see notes under 'Importing and Exporting Render Passes' below). If there is any demand for it, I can add a function to import/export snapshots between scenes.

Render Pass Scripting

The Render Passes plugin is fully integrated into Maya and provides commands for you to be able to query and modify the passes using custom MEL commands. Here is a quick rundown of the commands that the plugin provides:

addRenderPass [-edit INDEX] -name PASSNAME
This allows you to add new render passes. Any new passes will have no effect until you assign overrides to be associated with that pass. Passing the -edit flag with a pass index (zero based) allows you to edit the name of an existing pass.

addRenderPassOverride [-edit INDEX] -name [-pass PASSNAME | -nopasses] -override CODESTRING -default CODESTRING
Allows you to add new overrides, and also to edit them (including assigning them to one or more passes). The -pass flag can be used any number of times to assign an override to multiple passes. The -nopasses flag is used to remove all pass assignments for this override when in editing mode.

deleteRenderPass -pass PASSINDEX | -override OVERRIDEINDEX
Use this command with either the -pass or -override flags to delete an existing pass or override. Deleting a pass will automatically remove all references to it in any overrides assigned to it (but will not delete the overrides themselves).

duplicateRenderPass -pass PASSINDEX | -override OVERRIDEINDEX
Use this command with either the -pass or -override flags to duplicate an existing pass or override. The new override/pass will have the same name as the one being copied, but with "_Copy1", "_Copy2", etc appended.

renderPassInfo -numPasses | -numOverrides | -currentPass | -passName PASSINDEX | -overrideName OVERRIDEINDEX | -overridePasses OVERRIDEINDEX | -overrideCode OVERRIDEINDEX | -defaultCode OVERRIDEINDEX
Use this command to query any information about the render passes you have defined. Use the zero based index when asking about a particular pass or override. The command returns data in different formats depending on what is being asked: int for -numPasses/-numOverrides, string for -currentPass/-passName/-overrideName/-overrideCode/-defaultCode, and a string array for -overridePasses.

applyRenderPass PASSNAME
This applies an existing render pass to the current scene. The revert code for all existing passes will be executed, followed by the override MEL code for the specified pass.

saveRenderPassScene PASSNAME BASENAME OUTPUTDIR ASCIIMODE
This MEL script is provided for saving out a single render pass scene. Normally this is done through the 'Create Render Pass Scenes' window, but you can use this command if you need to save out scenes from a MEL script. BASENAME is the name to save your scene as (the name of the pass will be appended to it), OUTPUTDIR is a subdirectory relative to your Maya project to save the scene to, and ASCIIMODE will save the scenes as ascii files if set to 1, or binary if set to 0. Returns the full path name of the scene file it saves.

renderPassOrder -pass|-override INDEX1 INDEX2
This command is used to change the order of passes or overrides. It will swap the order of the two given indices.

validateRenderPasses
This applies each render pass in turn and checks that no errors are present in the MEL code for any of the overrides. Returns '1' if all passes have tested correctly, and is interrupted in the case of errors.

renderPassSnapshot PASSNAME SNAPSHOT_TYPE MAKE_OR_CLEAR
This command takes a snapshot of the current scene and associates it with the specified pass. SNAPSHOT_TYPE is currently either "all" or "MayaShaders". More snapshot types will soon be supported, with "MTORShaders" and "Visibility" coming soon. The MAKE_OR_CLEAR parameter is an integer flag which controls whether the snapshot is being created (value of 0), cleared for this pass (value of 1) or cleared for all passes (value of 2).

renderPassSnapshotApply SNAPSHOT_TYPE PASSNAME
This command applies a previously captured snapshot to the scene. SNAPSHOT_TYPE is currently either "all" or "MayaShaders". More snapshot types will soon be supported, with "MTORShaders" and "Visibility" coming soon.

NOTE: If you have any pass names that begin with non-alphabetic characters (e.g "01_foreground") then you should always use double quotes around the name when running the MEL commands above. Without these Maya can get a little confused and ends up trying to interpret the argument as a number instead of a string. For this reason I'd avoid using passes named in this way.

New Feature Ideas and Known Issues

History

Support and Feedback

If you're having trouble, or you'd like to make feature suggestions, please email via my contact form here.

You can download the latest release of the plugin at http://www.technolumiere.com/