TextureLayer Class Reference
 
 
 
TextureLayer Class Reference

#include <xsi_texturelayer.h>


Class Description

The TextureLayer 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.

TextureLayerPort objects are owned by TextureLayers, and are used to specify which shader ports the layer should affect. If there are no ports, then the layer is just a stub or placeholder, and as such does not affect the material's rendering.

TextureLayers can be created using Shader::CreateTextureLayer and Material::CreateTextureLayer. TextureLayers can have "sub" render trees connected to them as driving inputs, in the same way one would connect Shader objects together (using Parameter::ConnectFromPreset or Parameter::Connect).

See also:
Shader::GetTextureLayers, Shader::CreateTextureLayer, Material::GetTextureLayers, Material::CreateTextureLayer, TextureLayerPort
Since:
4.0
Example:
Shows how to create, enumerate and remove texture layers.
                using namespace XSI;
                Application app;
                Model root = app.GetActiveSceneRoot();
                X3DObject mySphere;
                root.AddGeometry( L"Sphere",L"MeshSurface",L"" ,mySphere );
                Material myMaterial;
                mySphere.AddMaterial(L"Phong",false,L"",myMaterial);
                CRefArray       myShaders;
                Shader myPhong;
                myShaders = myMaterial.GetShaders();
                myPhong = myShaders[0];

                CRefArray       myLayers(3);
                // Add a layer at the end (since there are no others the "After"
                // flag is irrelevant).
                myLayers[0] = myPhong.CreateTextureLayer( L"B", true );

                // Add another layer before the other one.
                myLayers[1] = myPhong.CreateTextureLayer( L"A", false, myLayers[0] );

                // Create a third layer at the very start.
                myLayers[2] = myPhong.CreateTextureLayer( L"base", false );

                myLayers = myPhong.GetTextureLayers();

                CString         l_str = L"Created " + CValue(myLayers.GetCount()).GetAsText() + L" layers.";
                app.LogMessage( l_str );

                for ( LONG i = 0; i < myLayers.GetCount(); i++ )
                {
                        app.LogMessage( CValue(i + 1L).GetAsText() + L": " + TextureLayer(myLayers[i]).GetName() );
                }

                myPhong.RemoveTextureLayer( myLayers[1] );
                myPhong.RemoveTextureLayer(     myLayers[2] );

                myLayers = myPhong.GetTextureLayers();
                l_str = L"Only " + CValue(myLayers.GetCount()).GetAsText() + L" remain(s) after removal.";
                app.LogMessage( l_str );
                for ( i = 0; i < myLayers.GetCount(); i++ )
                {
                        app.LogMessage( CValue(i + 1L).GetAsText() + L": " + TextureLayer(myLayers[i]).GetFullName() );
                }

                // This example should output something like this:
                // 'INFO : "Created 3 layers."
                // 'INFO : "1: base"
                // 'INFO : "2: A"
                // 'INFO : "3: B"
                // 'INFO : "Only 1 remain(s) after removal."
                // 'INFO : "1: sphere.Material.Phong.base"
Inheritance diagram for TextureLayer:
ProjectItem SIObject CBase

List of all members.

Public Member Functions

  TextureLayer ()
  ~TextureLayer ()
  TextureLayer (const CRef &in_ref)
  TextureLayer (const TextureLayer &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
TextureLayer operator= (const TextureLayer &in_obj)
TextureLayer operator= (const CRef &in_ref)
CStatus  Move (LONG in_lOffset)
TextureLayerPort  AddTextureLayerPort (const Parameter &in_param)
CStatus  RemoveTextureLayerPort (const TextureLayerPort &in_port)
CStatus  RemoveTextureLayerPort (const CString &in_portFullName)
CRefArray  GetTextureLayerPorts () const

Constructor & Destructor Documentation

Default constructor.

Default destructor.

TextureLayer ( const CRef in_ref )

Constructor.

Parameters:
in_ref constant reference object.
TextureLayer ( const TextureLayer in_obj )

Copy constructor.

Parameters:
in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassID class type.
Returns:
true if the class is compatible, false otherwise.

Reimplemented from ProjectItem.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Reimplemented from ProjectItem.

TextureLayer& operator= ( const TextureLayer in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:
in_obj constant class object.
Returns:
The new TextureLayer object.
TextureLayer& operator= ( const CRef in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_ref constant class object.
Returns:
The new TextureLayer object.

Reimplemented from ProjectItem.

CStatus Move ( LONG  in_lOffset )

Moves texture layers up or down in the ordered stacks of layers. This considers the overall order of layers in other containers that share the given texture layers, so that the ordering is always consistent.

Parameters:
in_lOffset Amount to move the layer. A negative value moves it up in the list, positive moves it down. The absolute value is the number of steps to move in that direction. Any value is valid, if more offset steps are requested than are actually available, the layer will simply move to the end (for positive offsets) or beginning (for negative offsets) of all the containers where it exists. So specifying a very large value of offset is a good way to set a layer to be the final layer in all containers where it appears.
Returns:
CStatus::OK success
CStatus::Fail failure.
TextureLayerPort AddTextureLayerPort ( const Parameter in_param )

Adds a TextureLayerPort object (shader connection) 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).

Parameters:
in_param Parameter on the target (must be a port on a shader or material) to which to add a texture layer port connection (that is, to be driven by this 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.
Returns:
The new TextureLayerPort, or an empty one if it failed to be created.
CStatus RemoveTextureLayerPort ( const TextureLayerPort in_port )

Removes a TextureLayerPort from the texture layer. This actually disconnects it and causes the layer to no longer affect that shader property. It is valid to have texture layers which have no port connections, these empty layers act like placeholders, and do not affect the rendered result in any way. They will maintain their ordering in the containers in which they appear. Of course, new port connections can be added to them at any time.

Parameters:
in_port TextureLayerPort to remove from this texture layer.
Returns:
CStatus::OK success
CStatus::Fail failure.
CStatus RemoveTextureLayerPort ( const CString in_portFullName )

Removes a TextureLayerPort from the texture layer. This actually disconnects it and causes the layer to no longer affect that shader property. It is valid to have texture layers which have no port connections, these empty layers act like placeholders, and do not affect the rendered result in any way. They will maintain their ordering in the containers in which they appear. Of course, new port connections can be added to them at any time.

Parameters:
in_portFullName Name of the TextureLayerPort to remove from this texture layer.
Returns:
CStatus::OK success
CStatus::Fail failure.
CRefArray GetTextureLayerPorts ( ) const

Returns an array of references to the TextureLayerPorts owned by the texture layer.

Returns:
Array of references to TextureLayerPort objects.

The documentation for this class was generated from the following file: