Shader Class Reference

Related Scripting Object: Shader

The Shader object represents a node in the render tree of an object. More...

#include <xsi_shader.h>

Inheritance diagram for Shader:

Detailed Description

The initial Shader of a render tree can be created with SceneItem::AddMaterial and additional shaders can be created and connected together with Parameter::ConnectFromPreset and Parameter::Connect.

A Shader is a type of DataSource.

See also:

OGLMaterial

Example:

        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        X3DObject myCube;
        root.AddGeometry( L"Cube",L"MeshSurface",L"" ,myCube );

        Material myMaterial;
        myCube.AddMaterial(L"Phong",false,L"",myMaterial);

        CRefArray refShaders = myMaterial.GetShaders();
        for(LONG i = 0;i < refShaders.GetCount(); ++i)
        {
            app.LogMessage( L"The shader: " +
                            Shader(refShaders[i]).GetFullName() );
        }

Example:

Phong Class Example The Shader object provides generalized access to the parameters of any shader object. Each shader has its own unique definition for which parameters it exposes. This example is a wrapper around the Shader object that works specifically for the Phong shader.

It is easy to find the entire list of parameters by calling ProjectItem::GetParameters. They are also documented in the SPDL parameter section of the reference.

        class CPhong
        {
        public:
            CPhong( const Shader & in_phong )
                : shader( in_phong )
            {
                // This object only works if we are constructed with a valid
                // reference to a phong shader
                assert( shader.IsValid() ) ;
                assert( shader.GetProgID() == L"Softimage.material-phong.1" ) ;
            }

            //
            // GetMethods
            //

            // Access to simple parameters
            float GetShiny()
            {
                return shader.GetParameterValue(L"Shiny") ;
            }

            LONG GetReflectSamples()
            {
                return shader.GetParameterValue(L"reflect_samples") ;
            }

            bool IsDiffuseInUse()
            {
                return shader.GetParameterValue(L"diffuse_inuse") ;
            }

            // Access to color parameters
            CStatus GetAmbient(float& r, float& g, float& b, float& a)
            {
                return shader.GetColorParameterValue(L"ambient",r,g,b,a ) ;
            }

            CStatus GetDiffuse(float& r, float& g, float& b, float& a)
            {
                return shader.GetColorParameterValue(L"diffuse",r,g,b,a ) ;
            }

            //
            // Put Methods
            //
            void PutShiny( float in_v )
            {
                shader.PutParameterValue( L"Shiny", in_v ) ;
            }

            void PutRelectSamples( LONG in_v )
            {
                shader.PutParameterValue( L"reflect_samples", in_v ) ;
            }

            void SetDiffuseInUse( bool in_enable )
            {
                shader.PutParameterValue( L"diffuse_inuse", in_enable ) ;
            }

            void PutAmbient(float r, float g, float b, float a)
            {
                shader.PutColorParameterValue( L"ambient", r, g, b, a ) ;
            }

            void PutDiffuse(float r, float g, float b, float a)
            {
                shader.PutColorParameterValue( L"diffuse", r, g, b, a ) ;
            }

        private:
            CPhong() ;
            Shader shader ; // We use this C++ API object to read the information
        } ;

Constructor & Destructor Documentation

Destructor.

Constructs a Shader object from a CRef object.

Parameters:

in_ref

A reference to a shader.

Constructs a new Shader object from an existing Shader object.

Parameters:

in_obj

An existing Shader object to copy into this Shader object.

Member Function Documentation

Returns the class ID for this object.

Returns:

The class ID.

Reimplemented from ProjectItem.

Reimplemented in Texture.

Assigns a Shader object to an existing Shader object.

Parameters:

in_obj

A Shader object to be copied into this object.

Returns:

The reinitialized Shader object.

Assigns a CRef to this Shader object. The Shader object is cleared if the CRef is not a reference to an object that supports the Shader class.

Parameters:

in_ref

A reference to an object that supports the Shader class.

Returns:

The reinitialized Shader object.

Reimplemented from ProjectItem.

Reimplemented in Texture.

Returns an array of references to the shaders connected to this Shader.

Returns:

CRefArray of references to the connected Shader objects.

Returns an array of references to the ImageClip objects in the shader tree whose root is this shader.

Returns:

Array of references to ImageClip objects.

Since:

4.0

Returns the programmatic identifier (ProgID) of this shader. You can use the ProgID with Parameter::ConnectFromProgID to recreate the shader.

Returns:

The string representing the ProgID.

Returns the output type of this shader. This is a convenient alternative to using Parameter::GetValueType for getting the parameter type of a color parameter.

Note:

This function replaces Shader::GetOutputType.

Returns:

The shader output type.

Since:

5.0

This function is obsolete and replaced by Shader::GetOutputType2

Deprecated:

5.0 (Shader::GetOutputType2 uses siShaderParameterType enum values instead of siShaderOutputType)

Returns the RGBA values of a color parameter. This is a convenient alternative to using ProjectItem::GetParameterValue for getting the RGBA values of a color parameter.

Note:

This function returns CStatus::InvalidArgument if the parameter is not a color or if it is driven by a connected Shader.

Parameters:

in_name

The scripting name of the Parameter, for example diffuse, specular, or ambient.

Return values:

	out_red	The Red component value, typically a number in the range 0.0 to 1.0.
	out_green	The Green component value, typically a number in the range 0.0 to 1.0.
	out_blue	The Blue component value, typically a number in the range 0.0 to 1.0.
	out_alpha	The Alpha component value.

Parameters:

in_time

Time (in frames) at which to get the value. By default, GetColorParameterValue gets the value at the current frame (represented by the value DBL_MAX).

Sets the RGBA values for a color parameter. This is a convenient alternative to ProjectItem::PutParameterValue for setting the RGBA values of a color parameter.

Note:

All shader colors are represented with floating-point precision.

Parameters:

	in_name	The scripting name of the color parameter, for example "ambient".
	in_red	The Red component value, typically a number in the range 0 to 1.0.
	in_green	The Green component value, typically a number in the range 0 to 1.0.
	in_blue	The Blue component value, typically a number in the range 0 to 1.0.
	in_alpha	The Alpha component value. If the Alpha channel is hidden in the user interface and is not used by the shader, setting the Alpha value has no effect.
	in_time	Time (in frames) at which to set the color values. By default, PutColorParameterValue sets the value at the current frame (which is represented by the value DBL_MAX).

Creates a new texture layer belonging to the container (the shader).

Parameters:

	in_strName	The name of new texture layer.
	in_bAfter	True to insert the layer after the reference layer (in_refLayer), and False to insert the layer before the reference layer. If there is no reference layer, then True adds the layer to the end of the list, and False adds the layer to the start of the list.
	in_refLayer	The reference texture layer. Used to indicate where the new layer is inserted in the list.

Returns:

The new texture layer.

Since:

4.0

Adds an existing texture layer to the container. The layer already belongs to at least one other texture layer container (either a Shader or a Material).

Parameters:

	in_layer	The texture layer to add to this container.
	in_bAfter	True to insert the layer after the reference layer (in_refLayer), and False to insert the layer before the reference layer. If there is no reference layer, then True adds the layer to the end of the list, and False adds the layer to the start of the list.
	in_refLayer	The reference texture layer. Used to indicate where the new layer is inserted in the list.

Returns:

CStatus::OK if successful

CStatus::Fail if the texture layer could not be created.

Since:

4.0

Returns a collection of TextureLayer objects owned by the shader.

Returns:

An array of references to the texture layers.

Since:

4.0

Removes a texture layer from the container. If this container is the only owner of the layer, then the layer is deleted from the scene, otherwise the layer is removed from this container (but is still owned by other containers).

Parameters:

in_layer

Texture layer to remove from this container.

Returns:

CStatus::OK if successful

CStatus::Fail if the layer could not be removed.

Since:

4.0

Returns true if the shader supports the specified renderer.

Parameters:

in_strRenderer

Name of a renderer.

Returns:

True if the renderer is supported, and False otherwise.

Since:

4.0

Returns the value of a renderer option. If the renderer or the option do not exist for this shader, an empty CValue is returned.

Parameters:

	in_strRenderer	Name of a renderer.
	in_strOption	Name of a render option.

Returns:

The value of the option.

Since:

4.0

Returns the symbol name of the shader code executed by the renderer for this shader. If the symbol name is not set, an empty string is returned.

Parameters:

in_strRenderer

Name of a renderer.

Returns:

Symbol name of the shader code.

Since:

4.0

Returns the file path of the shader code executed during rendering. If the file path is not set, an empty string is returned.

Parameters:

in_strRenderer

Name of a renderer.

Returns:

The file path of the shader code.

Since:

4.0

Returns the text of the shader code executed during rendering. If the text is not set, an empty string is returned.

Parameters:

in_strRenderer

Name of a renderer.

Returns:

The text of the shader code.

Since:

4.0

Adds a property to the shader. For example, you can add a UserDataBlob or CustomProperty to store custom user data inside a render tree.

Parameters:

	in_preset	A preset name or the name of a self-installed CustomProperty.
	in_bBranch	Should always be false.
	in_name	Optional name for the new property. If no name is specified, the name is based on in_preset.

Returns:

The new Property.

See also:

Shader::GetProperties, SceneItem::AddProperty

Since:

4.0

Returns an array of all Property objects applied to the shader. A Shader may have nested CustomProperty or UserDataBlob properties.

See also:

Shader::AddProperty, SceneItem::GetProperties

Since:

4.0

Returns the input type of a shader parameter. Before you connect a shader to the parameter, use Parameter::GetCapabilities to make sure that the parameter supports the siTexturable capability (see the siCapabilities enum).

Parameters:

in_paramscriptname

The script name of a parameter.

Returns:

The shader input type. If the parameter cannot be connected to a shader, siUnknownParameterType is returned.

Since:

5.0

Returns the port's display name, as it appears in the rendertree.

Parameters:

in_portScriptName

The script name of the port parameter.

Returns:

CString containing the shader port's display name, or "" if no name was set.

Since:

6.01

Sets the port's display name, as it appears in the rendertree.

Parameters:

	in_portScriptName	The script name of the port parameter.
	in_displayName	The shader port's new display name. If the string is empty, it will be reset to its original value.

Returns:

CStatus::OK if the display name was successfully set; CStatus::Fail otherwise.

Since:

6.01

Returns the root of the shader tree. The root may be a Camera, Light, Material, or a geometry shader.

Since:

5.0

• xsi_shader.h