CreatePassWithPartition

Description

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#).

Scripting Syntax

CreatePassWithPartition( [PresetObj], [Name], [ParamName], [InputObjs], [Value] );

Parameters

Parameter Type Description
PresetObj String or a preset object (see SIGetPreset) Any of the Pass Presets

Default Value: "Pass" (default pass)

Name String Name of the new pass.

Default Value: If not specified, the name is automatically generated.

ParamName String Name of the new partition.

Default Value: If not specified, the name is automatically generated.

InputObjs String List of objects to go in the partition.

Default Value: Selected objects

Value Pass Returns the new pass.

Examples

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"

See Also

RenderPasses CreateLayer CreatePass SICreatePass SICreatePartition SICreateLayer