Scripting: AddTextureLayer

AddTextureLayer

Introduced

v4.0

Description

Adds a texture layer to one or more containers (a container can be either a shader or a material). The command does some error checking, such as preventing layers from being added in a way that would introduce cycles between various containers, and preventing adding layers to containers contained in different render trees.

A texture layer is an object which simplifies layering of shader effects on top of shaders and materials. Each layer has a set of properties which describe its characteristics (such as color, mixing mode, scale factor) to specify how it will affect the shader ports it drives. The order that layers appear under a container indicates the order the layering is applied, similar to the way a "mix N colors" shader node works. Texture layer port objects (see AddTextureLayerPorts command) are owned by layers, and are used to specify which shader ports the layer should affect.

Scripting Syntax

oReturn = AddTextureLayer( [Object], [InputObjs], [Name], [After], [Reference] );

Return Value

Returns the new TextureLayer object, if one was created.

Parameters

Parameter	Type	Description
Object	String or object	Texture layer to add to the container(s). If not specified, then a new texture layer is created to add.
InputObjs	String	List of containers (shaders or materials) to which to add the texture layer. Note that all containers must currently be contained in a single render tree. Default Value: Current selection.
Name	String	Name to use for the new layer. If an existing layer is being passed in, then this argument is ignored.
After	Boolean	True to insert the new texture layer after the reference layer. False to insert it before. If no reference layer, then True will add at the end of the container's list, False will add it at the start. Default Value: True
Reference	String or object	Reference texture layer, to indicate where the newly-added layer should be located in the stack. The layer will be inserted adjacent to (before or after) the reference layer. If not specified, then the new layer will be added at the beginning or the end, depending on the value of the "After" argument.

Examples

VBScript Example

'
' This example creates two shaders in a simple render tree, and applies
' texture layers to them, illustrating inserting before/after, sharing layers
' between containers, and other fun things.
' In particular, it builds the following stacks of layers (in a slightly
' convoluted way, to show various features of the AddTextureLayer command)...
'
' Phong      Fractal
'   A           A
'   B           D
'   C           E
'   D
'
option explicit
dim oSph, oPhong, oFractal, oLyr(4)
' 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 )
set oFractal = BlendInPresetsInsp( "Fractal", , , True, siReplaceNoBlend, False, False, True )
' Now create and add all the layers, as indicated above.
' Add 'D' to (the end of) the first container.
set oLyr(3) = AddTextureLayer( , oPhong, "D", True )
' Add 'A' to both containers at the start.
set oLyr(0) = AddTextureLayer( , oPhong & "," & oFractal, "A", False )
' Insert 'B' after 'A'.
set oLyr(1) = AddTextureLayer( , oPhong, "B", True, oLyr(0) )
' Insert 'C' before 'D'.
set oLyr(2) = AddTextureLayer( , oPhong, "C", False, oLyr(3) )
' Add 'E' to the end of the second container.
set oLyr(4) = AddTextureLayer( , oFractal, "E", True )
' Add existing layer 'D' to the second container, before 'E'.
AddTextureLayer oLyr(3), oFractal, , False, oLyr(4)
PrintTextureLayersInContainer oPhong
PrintTextureLayersInContainer oFractal
sub PrintTextureLayersInContainer( in_cont )
        dim oStack, oItem, oStr
        oStr = "Texture Layers in Container: " & in_cont & vbCrLf
        set oStack = EnumElements( in_cont & ".TextureLayers" )
        for each oItem in oStack
                oStr = oStr & "    " & oItem.name & vbCrLf
        next
        logmessage oStr
end sub
'
' The output from the example should look something like this:
'
'INFO : "Texture Layers in Container: sphere.Material.Phong
'    A
'    B
'    C
'    D
'
'INFO : "Texture Layers in Container: sphere.Material.Phong.Fractal
'    A
'    D
'    E
'