Public Member Functions
Shader Class Reference

Detailed Description

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

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.

In order to keep the example short we don't cover every single parameter of a phong, for example "incandescence", "reflectivity", "trans_glossy". However handling those parameters would follow the exact same pattern. In fact it is conceivable that this code could be generated automatically using a script.

It is easy to find the entire list of parameters by calling ProjectItem::GetParameters. They are also documented in the intro XSI Parameter 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
        } ;

#include <xsi_shader.h>

Inheritance diagram for Shader:
Inheritance graph
[legend]

List of all members.

Public Member Functions
  Shader ()
  ~Shader ()
  Shader (const CRef &in_ref)
  Shader (const Shader &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
Shader &  operator= (const Shader &in_obj)
Shader &  operator= (const CRef &in_ref)
CRefArray  GetShaders () const
CRefArray  GetImageClips () const
CString  GetProgID () const
siShaderParameterType  GetOutputType2 () const
siShaderOutputType  GetOutputType () const
CStatus  GetColorParameterValue (const CString &in_name, float &out_red, float &out_green, float &out_blue, float &out_alpha, double in_time=DBL_MAX)
CStatus  PutColorParameterValue (const CString &in_name, float in_red, float in_green, float in_blue, float in_alpha=1.0f, double in_time=DBL_MAX)
TextureLayer  CreateTextureLayer (const CString &in_strName=CString(), bool in_bAfter=true, const TextureLayer &in_refLayer=TextureLayer())
CStatus  AddSharedTextureLayer (const TextureLayer &in_layer, bool in_bAfter=true, const TextureLayer &in_refLayer=TextureLayer())
CRefArray  GetTextureLayers () const
CStatus  RemoveTextureLayer (const TextureLayer &in_layer)
bool  HasRenderer (const CString &in_strRenderer) const
CValue  GetRendererOption (const CString &in_strRenderer, const CString &in_strOption) const
CString  GetSymbolName (const CString &in_strRenderer) const
CString  GetCodePath (const CString &in_strRenderer) const
CString  GetCodeText (const CString &in_strRenderer) const
Property  AddProperty (const CString &in_preset, bool in_bBranch=false, const CString &in_name=CString())
CRefArray  GetProperties () const
siShaderParameterType  GetShaderInputType (const CString &in_scriptname) const
CString  GetPortDisplayName (const CString &in_portScriptName) const
CStatus  PutPortDisplayName (const CString &in_portScriptName, const CString &in_displayName)
CRef  GetRoot (void) const
siShaderType  GetShaderType () const
siShaderParameterType  GetShaderParameterType (const CString &in_paramscriptname, bool &out_input) const
CRefArray  GetAllShaders () const
CRef  GetShaderContainer () const
CRefArray  GetShaderParameterTargets (const CString &in_paramscriptname) const
CRefArray  GetAllImageClips () const
CRef  GetShaderDef () const

Constructor & Destructor Documentation

Shader ( )

Constructs a Shader object.

~Shader ( )

Destructor.

Shader ( const CRef &  in_ref )

Constructs a Shader object from a CRef object.

Parameters:
in_ref A reference to a shader.
Shader ( const Shader &  in_obj )

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

bool IsA ( siClassID  in_ClassID ) const [virtual]

Returns true if this object supports the functionality of a specified class. For example, a Shader is a type of ProjectItem, so a Shader object supports ProjectItem functionality.

Parameters:
in_ClassID Test if this object supports this class.
Returns:
True if this object supports the specified class, and false otherwise.

Reimplemented from ProjectItem.

Reimplemented in Texture.

siClassID GetClassID ( ) const [virtual]

Returns the class ID for this object.

Returns:
The class ID.

Reimplemented from ProjectItem.

Reimplemented in Texture.

Shader& operator= ( const Shader &  in_obj )

Assigns a Shader object to an existing Shader object.

Parameters:
in_obj The shader object to be copied into this object.
Returns:
The reinitialized shader object.
Shader& operator= ( const CRef &  in_ref )

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.

CRefArray GetShaders ( ) const

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

Returns:
CRefArray of references to the connected Shader objects.
CRefArray GetImageClips ( ) const

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
CString GetProgID ( ) const

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

Note:
Since v7.0, this function also returns the ProgID of shader compounds with the following syntax:

XSIRTCompound...

If the shader compound has not been exported and cannot be created it returns only XSIRTCOMPOUND.
Returns:
The string representing the ProgID.
See also:
Parameter::ConnectFromProgID,
siShaderParameterType GetOutputType2 ( ) const

This function is obsolete and replaced by Shader::GetShaderParameterType.

Deprecated:
7.0 Use Shader::GetShaderParameterType instead.
siShaderOutputType GetOutputType ( ) const

This function is obsolete and replaced by Shader::GetShaderParameterType.

Deprecated:
5.0 Use Shader::GetShaderParameterType instead.
CStatus GetColorParameterValue ( const CString &  in_name,
float &  out_red,
float &  out_green,
float &  out_blue,
float &  out_alpha,
double  in_time = DBL_MAX 
)

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).
CStatus PutColorParameterValue ( const CString &  in_name,
float  in_red,
float  in_green,
float  in_blue,
float  in_alpha = 1.0f,
double  in_time = 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).
TextureLayer CreateTextureLayer ( const CString &  in_strName = CString(),
bool  in_bAfter = true,
const TextureLayer &  in_refLayer = TextureLayer() 
)

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
CStatus AddSharedTextureLayer ( const TextureLayer &  in_layer,
bool  in_bAfter = true,
const TextureLayer &  in_refLayer = TextureLayer() 
)

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
CRefArray GetTextureLayers ( ) const

Returns a collection of TextureLayer objects owned by the shader.

Returns:
An array of references to the texture layers.
Since:
4.0
CStatus RemoveTextureLayer ( const TextureLayer &  in_layer )

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 TextureLayer to remove from this container.
Returns:
CStatus::OK if successful
CStatus::Fail if the layer could not be removed.
Since:
4.0
bool HasRenderer ( const CString &  in_strRenderer ) const

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
CValue GetRendererOption ( const CString &  in_strRenderer,
const CString &  in_strOption 
) const

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
CString GetSymbolName ( const CString &  in_strRenderer ) const

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
CString GetCodePath ( const CString &  in_strRenderer ) const

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
CString GetCodeText ( const CString &  in_strRenderer ) const

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
Property AddProperty ( const CString &  in_preset,
bool  in_bBranch = false,
const CString &  in_name = CString() 
)

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 cus_prop 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
CRefArray GetProperties ( ) const

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
siShaderParameterType GetShaderInputType ( const CString &  in_scriptname ) const

Returns the input type of a parameter. Before you connect a Shader to the parameter, use Parameter::GetCapabilities to make sure that the parameter supports the siTexturable capability.

Deprecated:
7.0 This function is obsolete and replaced by Shader::GetShaderParameterType that works with multi-output shaders.
Parameters:
in_scriptname The script name of a parameter.
Returns:
The shader input type (one of the siShaderParameterType values). If the parameter cannot be connected to a shader, siUnknownParameterType is returned.
Since:
5.0
CString GetPortDisplayName ( const CString &  in_portScriptName ) const

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
CStatus PutPortDisplayName ( const CString &  in_portScriptName,
const CString &  in_displayName 
)

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
CRef GetRoot ( void  ) const

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

Note:
As of v7.0, shaders can live without being connected to a root, so this function now can return an empty CRef.
Since:
5.0
siShaderType GetShaderType ( ) const

Returns the shader type that identifies if the shader is a normal shader or a shader compound.

Returns:
The shader type or siShaderUnknown if the call fails.
Since:
7.0
siShaderParameterType GetShaderParameterType ( const CString &  in_paramscriptname,
bool &  out_input 
) const

Returns a siShaderParameterType value describing whether the parameter is an input or output and whether or not the shader is a compound.

Tip:
On single output shaders, you can use an empty scriptname Parameter::GetScriptName to get the parameter type of the output.
Note:
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 an input or output parameter or the empty string to query for the output of a single output shader.
out_input Returns true for an input parameter and false for an output parameter.
Returns:
The shader parameter type. If the parameter cannot be connected to a shader, siUnknownParameterType is returned.
Since:
7.0
CRefArray GetAllShaders ( ) const

Returns the shaders nested under a compound shader. You can test to see whether a shader is a compound by calling the Shader::GetShaderParameterType function (compounds return siShaderCompound).

Returns:
Array of references to the nested shader objects.
See also:
Shader::GetShaderParameterType, siShaderParameterType
Since:
7.0
CRef GetShaderContainer ( ) const

Returns a reference to the shader container under which this shader is nested. Shader containers can be shader compounds, materials, cameras, or lights.

Returns:
Reference to the shader container.
See also:
Material, Camera, Light
Since:
7.0
CRefArray GetShaderParameterTargets ( const CString &  in_paramscriptname ) const

Returns the shader input parameters connected to a shader source.

Tip:
On single output shaders, you can use an empty scriptname Parameter::GetScriptName to get the parameter type of the output.
Parameters:
in_paramscriptname The script name of an output parameter or the empty string to query for the output of a single output shader.
Returns:
Array of references to the target shader input Parameter objects.
Since:
7.0
CRefArray GetAllImageClips ( ) const

Returns the image clips nested under a compound shader. You can test to see whether a shader is a compound by calling the Shader::GetShaderParameterType function (compounds return siShaderCompound).

Returns:
Array of references to the nested ImageClip2 objects.
See also:
Shader::GetShaderParameterType, siShaderParameterType, Light::GetAllImageClips, Camera::GetAllImageClips, Material:GetAllImageClips, Shader::GetAllImageClips, Override::GetAllImageClips
Since:
7.0
CRef GetShaderDef ( ) const

Returns the shader definition associated with the shader.

Returns:
A reference to the ShaderDef object
Since:
9.0 (2011)
The documentation for this class was generated from the following file:
Generated on Mon Sep 12 2011 16:31:43 by doxygen 1.7.4
Please send us your comment about this page