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:
[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:

- xsi_shader.h