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