ShaderDef Class Reference
 
 
 
ShaderDef Class Reference

#include <xsi_shaderdef.h>


Class 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 Define and DefineInfo callbacks. For more information, see 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, Shader callbacks, Custom Shaders
Since:
9.0 (2011)
Inheritance diagram for ShaderDef:
SIObject CBase

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 Checkerboard shader appears under the Texture category.

Returns:
The category name.
See also:
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 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 Populating the Preset Manager
Parameters:
in_category The category name.
Returns:
Success/failure
See also:
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, 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, 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 DefineInfo callback. When creating a definition via a shader language parser plug-in, set this using the DisplayName attribute in the ParseInfo callback.

Returns:
The display name.
See also:
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:
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, Shader Parameter Definitions, 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, Shader Parameter Definitions, 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, 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, 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, Creating Shader Language Parser Definitions, 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, Creating Shader Language Parser Definitions, 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 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, 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, Creating Shader Definition Plug-ins, 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, Creating Shader Definition Plug-ins, 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 DefineInfo and Define callbacks give you access to the ShaderDef object so you can populate it with the list of parameters, categories, attributes, etc. See the 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, 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, 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 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, 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 Native Softimage Shader Families. You can also register custom shader families in Softimage and add them using this method. For more information, see 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, 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 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, Shader Families
Since:
9.0 (2011)
CString GetPrimaryShaderFamily ( )

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

Returns:
primary shader family name
See also:
ShaderDef::AddShaderFamily, ShaderDef::IsShaderFamily, ShaderDef::GetShaderFamilies, Application::RegisterShaderFamily, Shader Families
Since:
9.0 (2011)
CStringArray GetShaderFamilies ( ) const

Returns the list of shader families for this shader definition. See the 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, 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, 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, Refining UI Controls for Parameter Definitions
Since:
9.0 (2011)

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