ShaderDef

Object Hierarchy | Related C++ Class: ShaderDef

Inheritance

SIObject

ShaderDef

Introduced

v9.0 (2011)

Description

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 XSIFactory.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 XSIApplication.ShaderDefinitions property. You can also access a specific shader definition by ProgID by using the XSIApplication.GetShaderDef method.

Methods

AddRendererDef operator AddShaderFamily operator GetRendererDefByName operator IsClassOf operator
IsEqualTo operator IsShaderFamily operator RemoveRendererDef operator  
       

Properties

Application Attributes operator Categories Category operator
DefinitionPath operator DisplayName operator FullName operator Help
InputParamDefs operator Name operator NestedObjects Origin
OriginPath OutputParamDefs operator PPGLayout operator Parent
Parsed operator Parser operator ParserBased operator Plugin operator
PluginBased operator PluginFilename operator PrimaryShaderFamily operator ProgID operator
RenderTreeLayout operator RendererDefs operator ShaderFamilies operator ShaderInstanceCount operator
ShaderInstances operator ShaderballOpts operator Type operator  
       

Examples

1. Python Example

from win32com.client import constants as si
app = Application
app.NewScene("", 0)
#
#	SETUP
#
# Create a ShaderDef from the factory
oShaderDef = XSIFactory.CreateShaderDef("NoParser", "Nunce", 1, 0)
# On-the-fly shader definitions won't show up in the preset manager 
# but just in case this definition eventually gets saved to file
oShaderDef.Category = "Test Shaders"
# Add the basic Texture family
oShaderDef.AddShaderFamily(si.siShaderFamilyTexture)
#
#	PARAMETERS
#
# Create one set of parameter definition options for all 
oPDefOptions = XSIFactory.CreateShaderParamDefOptions()
oPDefOptions.SetTexturable(True) # make it a port on the shader node
# Get the ShaderParamDefContainers for both inputs and outputs. The
# new parameter definitions will be added to these objects
oInputPDefs = oShaderDef.InputParamDefs
oOutputPDefs = oShaderDef.OutputParamDefs
# Add color, scalar, and boolean ShaderParamDefs as inputs
oInputPDefs.AddParamDef("in_color", si.siShaderDataTypeColor4 , oPDefOptions)
oInputPDefs.AddParamDef("in_scalar", si.siShaderDataTypeScalar , oPDefOptions)
oInputPDefs.AddParamDef("in_boolean", si.siShaderDataTypeBoolean , oPDefOptions)
# Output a color
oOutputPDefs.AddParamDef("out", si.siShaderDataTypeColor4, oPDefOptions)
# Set up a Renderer
oRendererDef = oShaderDef.AddRendererDef("mental ray")
oRendererDef.SymbolName = "sib_attribute_boolean"
oRendererDef.CodePath = "{LIBS}/sibase.{EXT}"
oRendererOpts = oRendererDef.RendererOptions
oRendererOpts.Set("version", 1)
#
#	INSTANTIATION
#
# Generate a preset and connect it to a cone
app.CreatePrim("Cone", "MeshSurface")
app.CreateShaderFromProgID("NoParser.Nunce.1.0", 
	"Sources.Materials.DefaultLib.Scene_Material")
app.SIConnectShaderToCnxPoint("Sources.Materials.DefaultLib.Scene_Material.Nunce.out", 
	"Sources.Materials.DefaultLib.Scene_Material.volume", False)
# Open the Render Tree with the cone selected to see it
# Open the Synoptic viewer
app.OpenView("Render Tree")

2. JScript Example

//
//	This example demonstrates how to instantiate and connect a shader
//	definition, then how to get the shader definition from the system
//	and use it to find its instance (shader)
//
app = Application;
app.NewScene("", false);
var sProgID = "Softimage.material-moviescreen.1.0";
LogInstances(sProgID);
CreateShaderFromProgID(sProgID, "Sources.Materials.DefaultLib.Scene_Material");
LogInstances(sProgID);
// INFO : # of instances on Flat Light: 1
// INFO : Found shader instance: Shader
// INFO : Shader container: null
// Set up a torus and a disc and connect the shader to both
var obj1 = CreatePrim("Torus", "MeshSurface");
SIConnectShaderToCnxPoint("Sources.Materials.DefaultLib.Scene_Material.Flat_Light.out", 
	"Sources.Materials.DefaultLib.Scene_Material.Phong.reflectivity", false);
SIConnectShaderToCnxPoint("Sources.Materials.DefaultLib.Scene_Material.Flat_Light.out", 
	"Sources.Materials.DefaultLib.Scene_Material.Phong.radiance", false);
var obj2 = CreatePrim("Disc", "MeshSurface");
RemoveShaderFromCnxPoint("Sources.Materials.DefaultLib.Scene_Material.Flat_Light.out", 
	"Sources.Materials.DefaultLib.Scene_Material.Phong.reflectivity", false);
SIConnectShaderToCnxPoint("Sources.Materials.DefaultLib.Scene_Material.Flat_Light.out", 
	"Sources.Materials.DefaultLib.Scene_Material.Phong.reflectivity", false);
LogInstances(sProgID);
// INFO : # of instances on Flat Light: 2
// INFO : Found shader instance: Shader
// INFO : Shader container: null
// INFO : Found shader instance: Flat_Light
// INFO : Shader container: Sources.Materials.DefaultLib.Scene_Material
// Convenience function that will be called before and after 
// instantiating and after connecting the shader
function LogInstances( in_name )
{
	var oShaderDef = app.ShaderDefinitions(in_name);
	app.LogMessage("# of instances on "+oShaderDef.DisplayName+": "+oShaderDef.ShaderInstanceCount);
	if (oShaderDef.ShaderInstanceCount) {
		for (var i=0; i<oShaderDef.ShaderInstanceCount; i++) {
			var oShader = oShaderDef.ShaderInstances(i);
			app.LogMessage("Found shader instance: "+oShader.Name);
			app.LogMessage("Shader container: "+oShader.GetShaderContainer());
		}
	}
}

See Also

XSIApplication.GetShaderDef XSIFactory.CreateShaderDef Shader.ShaderDef XSIFactory.RemoveShaderDef Shader callbacks Custom Shaders Shader Definition examples installed with Softimage Shader Parser examples installed with Softimage