Creates a new pass and allows the user to set visibility on background partition. This is the scripting equivalent of selecting Render > Pass - Partition > New with the object(s) you want to add to the partition already selected.

A PARTITION is a division of a pass, which behaves like a group. Partitions are used to organize scene elements within a pass. There are only two types of partitions, object and light. Light partitions can only contain lights, and object partitions can only contain geometric objects.

Each PASS that you create has at least two partitions, a background objects partition, which contains most or all of the scene's objects, and a background lights partition, which contains most or all of the scene's lights. The objects and lights that appear in the background partitions depend on how you create the pass. For example, if you create an empty pass, all of the scene's objects and lights are placed in the background partitions. Some pass presets, on the other hand, automatically create partitions (besides the background partitions) containing the objects that were selected when you created the pass.

Note: This command uses output arguments. C# and some scripting languages (such as JScript, PerlScript and Python) don't support arguments passed by reference so you need to use the best workaround for your situation:

For scripting languages this command returns an ISIVTCollection which you can use to get the output arguments.

For C# you can use the XSIApplication.ExecuteCommand method to call this command. ExecuteCommand packs the output arguments into a C# System.Object containing an Array of the output arguments (see Calling Commands from C#).

VBScript Example

'
'       This example demonstrates how to create a depth pass with 
'       a partition containing a cone. It also shows how you can 
'       access partition information from a particular pass.
'
' Create a new scene 
NewScene , false
' Create a cone to add to one of the partitions
Set oCone = GetPrim( "Cone", "MeshSurface" )
' Create a depth pass with a partition for the cone
CreatePassWithPartition InstallationPath( siFactoryPath ) _
        & "\Data\DSPresets\Groups\Depth_Pass.Preset", _
        "Deep_Pass", "Coney_Island", oCone, oPass
' Print partition info
Application.LogMessage "Partitions for " & oPass & ":"
Application.LogMessage "--------------------------------"
' Create an XSICollection with the partition info
set oParts = CreateObject( "XSI.Collection" )
oParts.SetAsText( "Passes.Deep_Pass.Partitions.*" )
For Each p In oParts
        Application.LogMessage p
Next
' Output of the above script:
'INFO : "Partitions for Passes.Deep_Pass:"
'INFO : "--------------------------------"
'INFO : "Passes.Deep_Pass.Background_Objects_Partition"
'INFO : "Passes.Deep_Pass.Background_Lights_Partition"
'INFO : "Passes.Deep_Pass.Coney_Island"

RenderPasses CreateLayer CreatePass SICreatePass SICreatePartition SICreateLayer