## 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
    '

### See Also

RemoveTextureLayers MoveTextureLayers AddTextureLayerPorts AddImageTextureLayer AddClipTextureLayer AddPresetTextureLayer Shader.CreateTextureLayer Shader.AddSharedTextureLayer Material.CreateTextureLayer Material.AddSharedTextureLayer