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
#include <xsi_shaderdef.h>
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 Softimage_mib_texture_checkerboard_1_0 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 Softimage_mib_texture_checkerboard_1_0 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 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 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 cus_shaders_CreatingShaderParsers 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 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.
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 cus_shaders_ProgID 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 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 |
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 cus_shaders_FamiliesNative 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 cus_shaders_Families Shader Families topic for more information about shader families.
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.
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.