Scripting: AddTextureLayerPorts

AddTextureLayerPorts

Introduced

v4.0

Description

Adds texture layer ports (shader connections) to a texture layer. These indicate what shader ports are being driven by the layer. If the layer has ports added to it from containers it is currently not part of, it will be added to these containers (at the correct place in the stack, according to the order dependencies).

Scripting Syntax

oReturn = AddTextureLayerPorts( [InputObj], [InputObjs] );

Return Value

Returns the newly-created ports as an XSICollection.

Parameters

Parameter	Type	Description
InputObj	String or object	The layer to which to add new port connections.
InputObjs	String	List of targets (ports on shaders or materials) to which to add texture layer port connections (that is, to be driven by the given layer). Note that if a target is specified on a (valid) container which currently does not nest the layer, the layer will be added to that container (see AddTextureLayer command). Default Value: Current selection.

Examples

VBScript Example

'
' This example creates two shaders in a simple render tree, and applies
' texture layers to one of them.  Then it adds port connections to that
' layer, indicating what shader ports the layer should affect.
' In particular, it builds the following stack of layers.
'
' Phong
'   A
'   B
'
option explicit
dim oSph, oPhong, oMat, oLyr(1), oPorts, oPort
' Build our shaders (a Phong and a Fractal), which will be the "texture
' layer containers" that will each be able to hold a stack of layers.
NewScene , False
set oSph = CreatePrim( "Sphere", "MeshSurface" )
set oPhong = SIApplyShader( "Phong", oSph )
' Now create and add all the layers, as indicated above.
' Add 'A' and 'B' to the Phong at the end.
set oLyr(0) = AddTextureLayer( , oPhong, "A", True )
set oLyr(1) = AddTextureLayer( , oPhong, "B", True )
'
' Now start adding port connections, indicating what these layers will
' affect.
' Start by making layer 'A' affect ambient and diffuse on the Phong.
set oPorts = AddTextureLayerPorts( oLyr(0), oPhong & ".ambient," & oPhong & ".diffuse" )
for each oPort in oPorts
        logmessage "Created port: " & oPort
next
' Now let's add some ports on the 'B' layer, which affect the Phong's
' diffuse and specular, but also affect the material's environment.  We
' have not added the layer explicitly to the material texture layer
' container, so it will be done implicitly by this command.
set oMat = oPhong(0).parent
set oPorts = AddTextureLayerPorts( oLyr(1), _
                        oPhong & ".specular," & _
                        oPhong & ".diffuse," & _
                        oMat & ".environment" )
for each oPort in oPorts
        logmessage "Created port: " & oPort
next
PrintTextureLayersAndPortsInContainer oPhong
PrintTextureLayersAndPortsInContainer oMat
sub PrintTextureLayersAndPortsInContainer( in_cont )
        dim oLayerStack, oLayer, oPortList, oPort, oStr
        oStr = "Texture Layers in Container: " & in_cont & vbCrLf
        set oLayerStack = EnumElements( in_cont & ".TextureLayers" )
        for each oLayer in oLayerStack
                oStr = oStr & "    " & oLayer.name & " -- has ports:" & vbCrLf
                set oPortList = EnumElements( in_cont & ".TextureLayers." & oLayer.name & ".ports" )
                for each oPort in oPortList
                        oStr = oStr & "      " & oPort.name & vbCrLf
                next
        next
        logmessage oStr
end sub
'
' The output from the example should look something like this:
'
'INFO : "Created port: sphere.Material.Phong.A.ports.ambient"
'INFO : "Created port: sphere.Material.Phong.A.ports.diffuse"
'INFO : "Created port: sphere.Material.Phong.B.ports.specular"
'INFO : "Created port: sphere.Material.Phong.B.ports.diffuse"
'INFO : "Created port: sphere.Material.Phong.B.ports.environment"
'INFO : "Texture Layers in Container: sphere.Material.Phong
'    A -- has ports:
'      ambient
'      diffuse
'    B -- has ports:
'      specular
'      diffuse
'      Environment
'
'INFO : "Texture Layers in Container: sphere.Material
'    B -- has ports:
'      specular
'      diffuse
'      Environment
'