Public Member Functions
ShaderDef Class Reference

## Detailed Description

Represents a custom shader definition.

A shader definition is similar to a preset in that it stores a snapshot of a shader, often in a file on disk. However, a traditional Softimage `.preset` file is a binary file built from a SPDL, whereas a shader definition can be created and/or modified in several ways, including via a self-installing plug-in, a special XML file saved on disk (`.xsishaderdef`), or by coding on the fly.

To create a self-installing, plug-in based shader definition you need to implement the cb_Shader_Define Define and cb_Shader_DefineInfo DefineInfo callbacks. For more information, see cus_shaders Custom Shaders

To create a shader definition on the fly, you can use Factory::CreateShaderDef and then populate the definition using the returned ShaderDef object.

Saving shader definitions to a `.xsishaderdef` file is the most reliable way to manage shader versions. You can then use the ReplaceShadersDefinition command to upgrade a specific list of shaders to a new shader definition.

To get a list of all shader definitions in the current session of Softimage, use the Application::GetShaderDefinitions function. You can also access a specific shader definition by `ProgID` by using the Application::GetShaderDef function

See also:
  Application::GetShaderDef, Factory::CreateShaderDef, Shader::GetShaderDef, Factory::RemoveShaderDef, cb_shader Shader callbacks , cus_shaders Custom Shaders

Since:
  9.0 (2011)

`#include <xsi_shaderdef.h>`

Inheritance diagram for ShaderDef:
[legend]

List of all members.

## Public Member Functions
| ShaderDef ()
| ~ShaderDef ()
| ShaderDef (const CRef &in_ref)
| ShaderDef (const ShaderDef &in_obj)
bool | IsA (siClassID in_ClassID) const
siClassID | GetClassID () const
ShaderDef & | operator= (const ShaderDef &in_obj)
ShaderDef & | operator= (const CRef &in_ref)
MetaShaderRendererDef | AddRendererDef (const CString &in_renderer)
ValueMap | GetAttributes () const
CString | GetCategory () const
CStatus | PutCategory (const CString &in_category)
CString | GetDefinitionPath () const
CStatus | PutDefinitionPath (const CString &in_path)
CString | GetDisplayName () const
CStatus | PutDisplayName (const CString &in_name)
MetaShaderRendererDef | GetRendererDefByName (const CString &in_renderer) const
ShaderParamDefContainer | GetInputParamDefs () const
ShaderParamDefContainer | GetOutputParamDefs () const
bool | GetParsed () const
CStatus | PutParsed (bool in_parsed)
CString | GetParser () const
CStatus | PutParser (const CString &in_parser)
bool | GetParserBased () const
CString | GetPlugin () const
CStatus | PutPlugin (const CString &in_plugin)
bool | GetPluginBased () const
CString | GetPluginFilename () const
CString | GetProgID () const
CStatus | RemoveRendererDef (const MetaShaderRendererDef &in_rendererdef)
CRefArray | GetRendererDefs () const
ULONG | GetShaderInstanceCount () const
CRefArray | GetShaderInstances () const
ShaderballOptions | GetShaderballOptions () const
CStatus | AddShaderFamily (const CString &in_type, bool in_bPrimary=false)
bool | IsShaderFamily (const CString &in_type) const
CString | GetPrimaryShaderFamily ()
CStringArray | GetShaderFamilies () const
PPGLayout | GetPPGLayout () const
PPGLayout | GetRenderTreeLayout () const

## Constructor & Destructor Documentation

ShaderDef | ( |  | ) |

Default constructor.

Since:
  9.0 (2011)

~ShaderDef | ( |  | ) |

Default destructor.

Since:
  9.0 (2011)

ShaderDef | ( | const CRef & | in_ref | ) |

Constructor.

Parameters:

  in_ref | constant reference object.

Since:
  9.0 (2011)

ShaderDef | ( | const ShaderDef & | in_obj | ) |

Copy constructor.

Parameters:

  in_obj | constant class object.

Since:
  9.0 (2011)

## 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.

Since:
  9.0 (2011)

Reimplemented from SIObject.

siClassID GetClassID | ( |  | ) | const `[virtual]`

Returns the type of the API class.

Returns:
  The class type.

Since:
  9.0 (2011)

Reimplemented from SIObject.

ShaderDef& operator= | ( | const ShaderDef & | 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 ShaderDef object.

Since:
  9.0 (2011)

ShaderDef& 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 ShaderDef object.

Since:
  9.0 (2011)

Reimplemented from SIObject.

MetaShaderRendererDef AddRendererDef | ( | const CString & | in_renderer | ) |

Adds a MetaShaderRendererDef definition and returns it. Every ShaderDef must have at least one renderer defined in order to know how to render. This is equivalent to having a `MetaShader` section in a SPDL file.

The newly created object is set to empty if the renderer definition is already present.

Parameters:

  in_renderer | The name of the renderer. This is the equivalent of the string identifying each `Renderer` section under the `MetaShader` section in a SPDL file.

Returns:
  The new MetaShaderRendererDef object.

See also:
  ShaderDef::RemoveRendererDef, ShaderDef::GetRendererDefByName, ShaderDef::GetRendererDefs

Since:
  9.0 (2011)

ValueMap GetAttributes | ( |  | ) | const

Returns the list of attributes available on this shader definition as a ValueMap.

Returns:
  A new ValueMap object.

See also:
  ShaderParamDef::GetAttributes

Since:
  9.0 (2011)

CString GetCategory | ( |  | ) | const

Returns the category for this shader definition. The category is used to determine where the shader preset will appear in the preset manager in the render tree. For example, the native Softimage Softimage_mib_texture_checkerboard_1_0 Checkerboard shader appears under the `Texture` category.

Returns:
  The category name.

See also:
  cus_shaders_PresetMgr Populating the Preset Manager

Since:
  9.0 (2011)

CStatus PutCategory | ( | const CString & | in_category | ) |

Sets the category for this shader definition. The category is used to determine where the shader preset will appear in the preset manager in the render tree. For example, the native Softimage Softimage_mib_texture_checkerboard_1_0 Checkerboard shader appears under the `Texture` category.

Note:
  If you do not specify a category, your shader definition will not appear in the preset manager. For more information, see cus_shaders_PresetMgr Populating the Preset Manager

Parameters:

  in_category | The category name.

Returns:
  Success/failure

See also:
  cus_shaders_PresetMgr Populating the Preset Manager

Since:
  9.0 (2011)

CString GetDefinitionPath | ( |  | ) | const

Returns the definition path for this shader definition. The definition path is where the shader was defined, so for parser-based definitions, this means that the file that was parsed (for example, `<factory_path>.cgfx`), whereas the plug-in based definition paths refer to the plug-in file where the definition was implemented (for example, `<workgroup_path>.dll`), and the spdl-based definition paths point to the SPDL files (for example, `<factory_path>.spdl`).

Returns:
  The definition path.

See also:
  ShaderDef::GetPlugin, ShaderDef::GetPluginFilename, cus_shaders_GettingStarted Understanding Softimage Custom Shaders

Since:
  9.0 (2011)

CStatus PutDefinitionPath | ( | const CString & | in_path | ) |

Sets the definition path for this shader definition. The definition path is where the shader was defined, so for parser-based definitions, this means that the file that was parsed (for example, `<factory_path>.cgfx`), whereas the plug-in based definition paths refer to the plug-in file where the definition was implemented (for example, `<workgroup_path>.dll`), and the spdl-based definition paths point to the SPDL files (for example, `<factory_path>.spdl`).

Parameters:

  in_path | The definition path. You can modify it to include more information or make the path relative.

Returns:
  Success/failure

See also:
  ShaderDef::GetPlugin, ShaderDef::GetPluginFilename, cus_shaders_GettingStarted Understanding Softimage Custom Shaders

Since:
  9.0 (2011)

CString GetDisplayName | ( |  | ) | const

Sets the name that appears in the preset manager. When creating a plug-in based shader definition, set this using the `DisplayName` attribute in the cb_Shader_DefineInfo DefineInfo callback. When creating a definition via a shader language parser plug-in, set this using the `DisplayName` attribute in the cb_ShaderParser_ParseInfo ParseInfo callback.

Returns:
  The display name.

See also:
  cus_shaders_PresetMgr Populating the Preset Manager

Since:
  9.0 (2011)

CStatus PutDisplayName | ( | const CString & | in_name | ) |

Returns the name that appears in the preset manager. The display name tells the Preset Manager which name to display for the shader. It is also used when as the default name for new shaders.

Parameters:

  in_name | The display name.

Returns:
  Success/failure

See also:
  cus_shaders_PresetMgr Populating the Preset Manager

Since:
  9.0 (2011)

MetaShaderRendererDef GetRendererDefByName | ( | const CString & | in_renderer | ) | const

Returns the MetaShaderRendererDef that matches the specified name. This is the equivalent to calling ShaderDef::GetRendererDefs(`in_str`).

Parameters:

  in_renderer | The name of the renderer to return. This is the equivalent of the string identifying each `Renderer` section under the `MetaShader` section in a SPDL file.

Returns:
  The matching MetaShaderRendererDef object
  An invalid object if not found

See also:
  ShaderDef::AddRendererDef, ShaderDef::RemoveRendererDef, ShaderDef::GetRendererDefs

Since:
  9.0 (2011)

ShaderParamDefContainer GetInputParamDefs | ( |  | ) | const

Returns a ShaderParamDefContainer containing the input parameter definitions for this shader definition. You can use this container to iterate over input parameter definitions or add new input parameter definitions to the shader definition while creating it.

Returns:
  A ShaderParamDefContainer object representing the input parameters.

See also:
  ShaderDef::GetOutputParamDefs, cus_shaders_Params Shader Parameter Definitions , cus_shaders_ParamsAdding Adding Parameter Definitions

Since:
  9.0 (2011)

ShaderParamDefContainer GetOutputParamDefs | ( |  | ) | const

Returns a ShaderParamDefContainer containing the output parameter definitions for this shader definition. You can use this container to iterate over output parameter definitions or add new output parameter definitions to the shader definition while creating it.

Returns:
  A ShaderParamDefContainer object representing the output parameters.

See also:
  ShaderDef::GetInputParamDefs, cus_shaders_Params Shader Parameter Definitions , cus_shaders_ParamsAdding Adding Parameter Definitions

Since:
  9.0 (2011)

bool GetParsed | ( |  | ) | const

Indicates whether or not the shader was parsed. See ShaderDef::GetParserBased for a description of how shader definitions can be created by parsing files and ShaderDef::GetPluginBased for a description of how shader definitions can be created from self-installing plug-ins.

Returns:
  true if the shader definition was parsed
  false otherwise

See also:
  ShaderDef::GetParserBased, ShaderDef::GetParser, cus_shaders_CreatingShaderParsers Creating Shader Language Parser Definitions

Since:
  9.0 (2011)

CStatus PutParsed | ( | bool | in_parsed | ) |

Indicates whether or not the shader was parsed. See ShaderDef::GetParserBased for a description of how shader definitions can be created by parsing files and ShaderDef::GetPluginBased for a description of how shader definitions can be created from self-installing plug-ins.

Note:
  This only affects shader definitions that are parser based.

Parameters:

  in_parsed | true to force the shader definition to be parsed again

Returns:
  Success/failure

See also:
  ShaderDef::GetParserBased, ShaderDef::GetParser, cus_shaders_CreatingShaderParsers Creating Shader Language Parser Definitions

Since:
  9.0 (2011)

CString GetParser | ( |  | ) | const

Returns the the name of the parser. This is the name you specified for the parser you created with the PluginRegistrar::RegisterShaderLanguageParser function. It is used, along with the class name and version number, to create the shader definition's `ProgID`.

Note:
  See ShaderDef::GetParserBased for a description of how shader definitions can be created by parsing files with a specific shader language parser.

Returns:
  the parser name

See also:
  ShaderDef::GetParserBased, ShaderDef::GetParsed, ShaderDef::GetPlugin, cus_shaders_CreatingShaderParsers Creating Shader Language Parser Definitions , cus_shaders_ProgID Instantiating Shader Definitions and the ProgID

Since:
  9.0 (2011)

CStatus PutParser | ( | const CString & | in_parser | ) |

Changes the parser name. The parser name is normally set by calling PluginRegistrar::RegisterShaderLanguageParser; however, changing the parser name can be useful if you have 2 parsers for the same file extension. A ShaderDef must have a non-empty ParserName or a PluginName in order to build a valid ProgID.

For plugin-based shader definitions, this method is meaningless (use ShaderDef::PutPlugin instead).

Note:
  See ShaderDef::GetParserBased for a description of how shader definitions can be created by parsing files with a specific shader language parser.

Parameters:

  in_parser | the parser name

Returns:
  Success/failure

See also:
  ShaderDef::GetParserBased, ShaderDef::GetParsed, ShaderDef::GetPlugin, cus_shaders_CreatingShaderParsers Creating Shader Language Parser Definitions , cus_shaders_ProgID Instantiating Shader Definitions and the ProgID

Since:
  9.0 (2011)

bool GetParserBased | ( |  | ) | const

Returns whether or not the definition was generated from a parsed file by checking if ShaderDef::GetParser returns an empty string. Softimage can create shader definitions by extracting the list of parameters, categories, attributes, etc. from one of the standard text file shader formats, such as `.mi` or `.cgfx`, or a custom text file format. Softimage ships with several built-in parsers to create shader definitions from several file formats (including `.fx`, `.cgfx`, etc.) but you can also create your own shader language parser plug-in using the PluginRegistrar::RegisterShaderLanguageParser function. See the cus_shaders_CreatingShaderParsers Creating Shader Language Parser Definitions topic for more details.

Returns:
  true if the shader definition was defined from a parsed file
  false otherwise

See also:
  ShaderDef::GetPluginBased, ShaderDef::GetParsed, ShaderDef::GetParser, cus_shaders_CreatingShaderParsers Creating Shader Language Parser Definitions

Since:
  9.0 (2011)

CString GetPlugin | ( |  | ) | const

Returns the name of the plug-in. This is the name specified in the PluginRegistrar::RegisterShader method for the plug-in containing this shader definition. The plug-in name is used, along with the class name and version number, to create the shader definition's `ProgID`.

Returns:
  the plugin name

See also:
  ShaderDef::GetProgID, ShaderDef::GetPluginBased, ShaderDef::GetPluginFilename, ShaderDef::GetParser, cus_shaders_CreatingDefPlugins Creating Shader Definition Plug-ins , cus_shaders_ProgID Instantiating Shader Definitions and the ProgID

Since:
  9.0 (2011)

CStatus PutPlugin | ( | const CString & | in_plugin | ) |

Changes the plug-in name. The plug-in name is normally set by by calling PluginRegistrar::RegisterShader. It is used, along with the class name and version number, to create the shader definition's `ProgID`.

For parser-based shader definitions, this method is meaningless (use ShaderDef::PutParser instead).

Parameters:

  in_plugin | the plugin name

Returns:
  Success/failure

See also:
  ShaderDef::GetProgID, ShaderDef::GetPluginBased, ShaderDef::GetPluginFilename, ShaderDef::GetParser, cus_shaders_CreatingDefPlugins Creating Shader Definition Plug-ins , cus_shaders_ProgID Instantiating Shader Definitions and the ProgID

Since:
  9.0 (2011)

bool GetPluginBased | ( |  | ) | const

Returns whether or not the definition is plug-in-based by checking if ShaderDef::GetPlugin returns an empty string. Shader definitions can be created in a self-installing plug-in using the PluginRegistrar::RegisterShader function. The cb_Shader_DefineInfo DefineInfo and cb_Shader_Define Define callbacks give you access to the ShaderDef object so you can populate it with the list of parameters, categories, attributes, etc. See the cus_shaders_CreatingDefPlugins Creating Shader Definition Plug-ins topic for more details.

Returns:
  true if the definition is plug-in based
  false otherwise

See also:
  ShaderDef::GetParserBased, ShaderDef::GetPlugin, cus_shaders_CreatingDefPlugins Creating Shader Definition Plug-ins

Since:
  9.0 (2011)

CString GetPluginFilename | ( |  | ) | const

Returns the location of the plug-in file that defines this shader.

Returns:
  Returns the full path to the plug-in or an empty string.

See also:
  ShaderDef::GetPlugin, ShaderDef::GetDefinitionPath, cus_shaders_CreatingDefPlugins Creating Shader Definition Plug-ins

Since:
  9.0 (2011)

CString GetProgID | ( |  | ) | const

Returns the unique shader `ProgID`, which can be used to instantiate shaders to be used in the render tree. For more information, see cus_shaders_ProgID Instantiating Shader Definitions and the ProgID . The ProgID is a formatted string built from these components separated by periods:

- PluginName or ParserName
- ClassName
- MajorVersion
- MinorVersion

Tip:
  Shader definitions built by the legacy SPDL parser use `Softimage` as the PluginName.

Note:
  This property returns exactly the same string as calling both the SIObject::GetName and SIObject::GetFullName functions.

Returns:
  the `ProgID`

See also:
  Shader::GetProgID, Parameter::ConnectFromProgID, cus_shaders_ProgID Instantiating Shader Definitions and the ProgID

Since:
  9.0 (2011)

CStatus RemoveRendererDef | ( | const MetaShaderRendererDef & | in_rendererdef | ) |

Removes the specified renderer definition from the shader definition.

Parameters:

  in_rendererdef | The MetaShaderRendererDef to remove.

Returns:
  Success/failure

See also:
  ShaderDef::AddRendererDef, ShaderDef::GetRendererDefByName, ShaderDef::GetRendererDefs

Since:
  9.0 (2011)

CRefArray GetRendererDefs | ( |  | ) | const

Returns a list of MetaShaderRendererDef object(s) associated with this shader definition. MetaShaderRendererDef objects can be added with ShaderDef::AddRendererDef and accessed with ShaderDef::GetRendererDefByName.

Returns:
  list of references to MetaShaderRendererDef object(s)

See also:
  ShaderDef::AddRendererDef, ShaderDef::RemoveRendererDef, ShaderDef::GetRendererDefByName

Since:
  9.0 (2011)

ULONG GetShaderInstanceCount | ( |  | ) | const

Returns the number of shader instances in the scene are using this ShaderDef.

Returns:
  shader instance count

See also:
  ShaderDef::GetShaderInstances

Since:
  9.0 (2011)

CRefArray GetShaderInstances | ( |  | ) | const

Returns a list containing all shader instances for this shader definition.

Returns:
  list of references to Shader object(s)

See also:
  ShaderDef::GetShaderInstanceCount

Since:
  9.0 (2011)

ShaderballOptions GetShaderballOptions | ( |  | ) | const

Returns the shaderball options.

Returns:
  the shaderball options

Since:
  9.0 (2011)

CStatus AddShaderFamily | ( | const CString & | in_type,
|  | bool | in_bPrimary = `false`
| ) |  |

Adds a new shader family. Shader families specify the context in which the shader can be used (for example, you cannot connect a light shader to a material node for a scene item). In the UI, the context is identified by color: for example, Surface Material (`mrSurfaceMat`) appears as green, Volume (`mrVolume`) appears as violet, Realtime shaders (`xgsRealTimeShader`) appear as light blue, etc.

A shader definition must have at least one shader family defined but may also have one or more secondary families. One of these families is designated as the primary family, and it is that family that determines what color the node displays in the UI. Softimage uses pre-defined families for mental ray and realtime shaders, but you can also define your own shader family with the Application::RegisterShaderFamily function.

Note:
  You cannot remove a shader family once it has been added.

Parameters:

  in_type | The new shader family. The native shader families that ship with Softimage are described in cus_shaders_FamiliesNative Native Softimage Shader Families . You can also register custom shader families in Softimage and add them using this method. For more information, see cus_shaders_FamiliesCustom Creating Custom Shader Families .
  in_bPrimary | true if this family is the primary shader family for the shader definition

Returns:
  CStatus::OK if the type was a valid type
  CStatus::Fail otherwise

See also:
  ShaderDef::IsShaderFamily, ShaderDef::GetPrimaryShaderFamily, ShaderDef::GetShaderFamilies, Application::RegisterShaderFamily, cus_shaders_Families Shader Families

Since:
  9.0 (2011)

bool IsShaderFamily | ( | const CString & | in_type | ) | const

Checks whether this shader definition belongs to the specified shader family or not. See ShaderDef::AddShaderFamily for more information about shader families.

Parameters:

  in_type | The shader family to check. See cus_shaders_FamiliesNative Native Softimage Shader Families for a list of supported families for Softimage native shaders.

Returns:
  true if the specified shader family is supported.

See also:
  ShaderDef::AddShaderFamily, ShaderDef::GetPrimaryShaderFamily, ShaderDef::GetShaderFamilies, cus_shaders_Families Shader Families

Since:
  9.0 (2011)

CString GetPrimaryShaderFamily | ( |  | ) |

Returns the name of the primary shader family this shader definition belongs to. See the cus_shaders_Families Shader Families topic for more information about shader families.

Returns:
  primary shader family name

See also:
  ShaderDef::AddShaderFamily, ShaderDef::IsShaderFamily, ShaderDef::GetShaderFamilies, Application::RegisterShaderFamily, cus_shaders_Families Shader Families

Since:
  9.0 (2011)

CStringArray GetShaderFamilies | ( |  | ) | const

Returns the list of shader families for this shader definition. See the cus_shaders_Families Shader Families topic for more information about shader families.

Returns:
  array of names representing each shader family supported by this shader definition

See also:
  ShaderDef::AddShaderFamily, ShaderDef::IsShaderFamily, ShaderDef::GetPrimaryShaderFamily, Application::RegisterShaderFamily, cus_shaders_Families Shader Families

Since:
  9.0 (2011)

PPGLayout GetPPGLayout | ( |  | ) | const

Returns a PPGLayout object representing the parameters associated to this shader definition. Getting the PPGLayout object using this function allows you customize the property page that is displayed when the user double-clicks the shader node in the render tree.

Returns:
  PPGLayout representing the property page layout

See also:
  ShaderDef::GetRenderTreeLayout, cus_shaders_ParamsControls Refining UI Controls for Parameter Definitions

Since:
  9.0 (2011)

PPGLayout GetRenderTreeLayout | ( |  | ) | const

Returns the PPGLayout for the shader node associated with this shader definition. Getting the PPGLayout object using this function allows you customize how the ports appear on the shader node in the render tree. For example, this allows you to group some ports together.

Returns:
  PPGLayout representing the render tree layout

See also:
  ShaderDef::GetPPGLayout, cus_shaders_ParamsControls Refining UI Controls for Parameter Definitions

Since:
  9.0 (2011)

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

- xsi_shaderdef.h