ShaderDef Class Reference
#include <xsi_shaderdef.h>
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
| ShaderDef | ( | ) |
Default constructor.
| ~ShaderDef | ( | ) |
Default destructor.
Constructor.
| in_ref | constant reference object. |
Copy constructor.
| in_obj | constant class object. |
| bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
| in_ClassID | class type. |
Reimplemented from SIObject.
| siClassID GetClassID | ( | ) | const [virtual] |
Returns the type of the API class.
Reimplemented from SIObject.
Creates an object from another object. The newly created object is set to empty if the input object is not compatible.
| in_obj | constant class object. |
| 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.
| 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. |
| ValueMap GetAttributes | ( | ) | const |
Returns the list of attributes available on this shader definition as a ValueMap.
| 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.
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.
| in_category | The category name. |
| 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).
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).
| in_path | The definition path. You can modify it to include more information or make the path relative. |
| 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 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.
| in_name | The display name. |
| 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).
| 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. |
| 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.
| 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.
| 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.
| 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.
| in_parsed | true to force the shader definition to be parsed again |
| 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.
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).
| in_parser | the parser name |
| 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.
| 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.
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).
| in_plugin | the plugin name |
| 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.
| CString GetPluginFilename | ( | ) | const |
Returns the location of the plug-in file that defines this shader.
| 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:
Softimage as the PluginName.ProgID| CStatus RemoveRendererDef | ( | const MetaShaderRendererDef & | in_rendererdef | ) |
Removes the specified renderer definition from the shader definition.
| in_rendererdef | The MetaShaderRendererDef to remove. |
| 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.
| ULONG GetShaderInstanceCount | ( | ) | const |
Returns the number of shader instances in the scene are using this ShaderDef.
| CRefArray GetShaderInstances | ( | ) | const |
Returns a list containing all shader instances for this shader definition.
| ShaderballOptions GetShaderballOptions | ( | ) | const |
Returns the shaderball options.
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.
| 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 |
| 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.
| in_type | The shader family to check. See Native Softimage Shader Families for a list of supported families for Softimage native shaders. |
| 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.
| CStringArray GetShaderFamilies | ( | ) | const |
Returns the list of shader families for this shader definition. See the Shader Families topic for more information about shader families.
| 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.
| 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.