SICreateEmptyPartition

Categories

render

Description

Creates a new empty partition of the specified type (either object or light) and inspects it. This is the scripting equivalent of deselecting everything in the scene and then selecting Pass - Partition > New from the Render menu.

Note: After creating an empty partition, you can add items to it, but CreatePartition and SICreatePartition command already performs both tasks simultaneously.

A partition is a division of a pass and behaves like a group. Partitions are used to organize scene elements within a pass. There are only two types of partitions, object and light. A render pass creates a picture layer of a scene that can be composited with any other passes to create a complete image.

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

SICreateEmptyPartition( [Target], [Name], [Type], [Value] );

Parameters

Parameter Type Description
Target String Pass to add the partition to.

Default Value: Selected pass, or current pass

Name String Name of the new partition.

Default Value: "Partition"

Type siPartitionType Type of the partition to create.

Default Value: siObjectPartition

Value XSICollection containing a Group object Returns the new partition.

Examples

VBScript Example

'
'       This example demonstrates how to create an empty partition
'       and then add an object to it. 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 standard (default) pass 
CreatePass , "PassMeBy", oPass
' Print partition info for default pass
getPartInfo oPass
' Now add an empty light partition to the pass and add the light to it
SICreateEmptyPartition oPass, "Sweet_Sorrow", siLightPartition, oLightPart
AddToPartition oLightPart(0), "Light"
' Print new partition info 
getPartInfo oPass
function getPartInfo( in_pass )
        Application.LogMessage "Partitions for " & in_pass & ":"
        Application.LogMessage "--------------------------------"
        ' Create an XSICollection with the partition info
        set oParts = CreateObject( "XSI.Collection" )
        oParts.SetAsText in_pass & ".Partitions.*" 
        For Each p In oParts
                Application.LogMessage p
        Next
end function
' Output of the above script:
'INFO : "Partitions for Passes.PassMeBy:"
'INFO : "--------------------------------"
'INFO : "Passes.PassMeBy.Background_Objects_Partition"
'INFO : "Passes.PassMeBy.Background_Lights_Partition"
'
'INFO : "Partitions for Passes.PassMeBy:"
'INFO : "--------------------------------"
'INFO : "Passes.PassMeBy.Background_Objects_Partition"
'INFO : "Passes.PassMeBy.Background_Lights_Partition"
'INFO : "Passes.PassMeBy.Sweet_Sorrow"

See Also

RenderPasses CreateLayer CreatePartition CreatePass GetCurrentPass SetCurrentPass DeleteCurrentPass SICreateLayer CreateEmptyPartition AddToPartition