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>
Constructor & Destructor Documentation
| ShaderDef | ( | ) |
Default constructor.
- Since:
- 9.0 (2011)
| ~ShaderDef | ( | ) |
Default destructor.
- Since:
- 9.0 (2011)
Constructor.
- Parameters:
-
in_ref constant reference object.
- Since:
- 9.0 (2011)
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.
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)
| 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 Renderersection under theMetaShadersection in a SPDL file.
- Returns:
- The new MetaShaderRendererDef object.
- 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)
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)
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)
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 Renderersection under theMetaShadersection in a SPDL file.
- Returns:
- The matching MetaShaderRendererDef object
- An invalid object if not found
- 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)
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)
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
Softimageas 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
- 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)
- 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)
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:
