Providing Renderer Information

Each shader definition can have one or more renderer definitions associated with it, storing vital information, such as:

the location of the renderer's implementation
the name of the entry point (procedure to call)
special options (set of name-value pairs)

Specifying a Renderer Definition

Add a renderer definition to the shader definition using the ShaderDef.AddRendererDef or ShaderDef::AddRendererDef method, where you specify the name of your renderer, and which returns the new definition as a MetaShaderRendererDef or MetaShaderRendererDef object. The MetaShaderRendererDef object allows you to specify the following:

MetaShaderRendererDef Access	Matching SPDL declaration (Renderer section)	Description
MetaShaderRendererDef.SymbolName or MetaShaderRendererDef::PutSymbolName	Name	Indicates the symbol name of the shader code to use. For example with mental ray shaders this would indicate the prefix for the symbol (callback) name in the DLL/DSO where the code for the shader is.
MetaShaderRendererDef.CodePath or MetaShaderRendererDef::PutCodePath	FileName	The name of the DLL/DSO that contains the shader code. For example "{LIBS}/sibase.{EXT}".
MetaShaderRendererDef.CodeText or MetaShaderRendererDef::PutCodeText	BeginText...EndText	Provides a placeholder for any arbitrary text that can then be interpreted or compiled into a shader by the rendering engine, including the implementation of a shader. For example: { float4 retcolor; retcolor.x = factor.x * (input.x + input.y + input.z) / 3.0; retcolor.y = retcolor.x; retcolor.z = retcolor.x; retcolor.w = retcolor.x; return retcolor; }
MetaShaderRendererDef.RendererOptions or MetaShaderRendererDef::GetRendererOptions	Options	See Setting Renderer Options.

Python Example: Setting up a Single Renderer Definition

# You need to set up at least one renderer definition for each shader definition.
# Renderer definitions are available via the ShaderDef.RendererDefs property and
# allow you to tell Softimage which renderer to use, which procedure to call, how
# to set any renderer options, etc.
oRendererDef = oShaderDef.AddRendererDef("mental ray")
oRendererDef.SymbolName = "XSIModelMap"
oRendererDef.CodePath = "{LIBS}/xsibase.{EXT}"

# Set the version option
oRendererOpts = oRendererDef.RendererOptions
oRendererOpts.Set("version", 1)

Setting Renderer Options

Renderer options comprise a list of string/value pairs that are passed to the renderer. The option name can be any string. The value can be boolean, integer, float or string. Depending on the renderer, the Options list is used in different ways:

For mental ray, the Options list stores the rendering restrictions for this particular shader, such as whether shadows are on or off. See mental ray Options for details.
For realtime renderers, the Options section can be used to store parameter pairs.
For other renderers, the Options section could provide a path for the location of the source code of the shader. For example, this is useful for the RenderMan shader library where the all the code for a large shader library could be provided as one big SL file. For mental ray, you could also provide a source code which would then be compiled at render time.

Python Example: Setting up a Two Renderers (One with Cg Code to Run, Both with Options)

	# Add a mental ray renderer definition with the location of the library where it is defined
	oRendererDef = oShaderDef.AddRendererDef("mental ray")
	oRendererDef.SymbolName = "material-phong"
	oRendererDef.CodePath = "{LIBS}/sibase.{EXT}"
	oRendOpts = oRendererDef.RendererOptions
	oRendOpts.Set("version", 1)
	oRendOpts.Set("pass channel", "Ambient,Diffuse,Specular,Irradiance,Reflection,Refraction")
	
	# Add a Cg version with the code embedded in the definition
	oRendererDef = oShaderDef.AddRendererDef("Cg")
	oRendererDef.SymbolName = "mib_color_average_cg"
	oRendererDef.CodeText = "\tBeginText\n\t{\n\t\t float4 retcolor;\n\n\t\t retcolor.x = factor.x * (input.x + input.y + input.z) / 3.0;\n\t\t retcolor.y = retcolor.x;\n\t\t retcolor.z = retcolor.x;\n\t\t retcolor.w = retcolor.x;\n\n\t\t return retcolor;\n\t}\n\tEndText"
	oRendOpts = oRendererDef.RendererOptions
	oRendOpts.Set("param0", "ambient")
	oRendOpts.Set("param1", "diffuse")
	oRendOpts.Set("param2", "specular")
	oRendOpts.Set("param3", "ambience")
	oRendOpts.Set("param4", "shiny")
	oRendOpts.Set("const0", "diffuse_inuse")
	oRendOpts.Set("const1", "specular_inuse")
	oRendOpts.Set("param7", "radiance")

mental ray Options

Option values	Description	Examples
scanline option	Scanline rendering speeds up rendering of objects visible from the camera. If disabled mental ray will use raytracing for all rendering. Lens shaders which modify the ray direction from the camera should disable scanline rendering.
on	Scanline should always be on (be it default, opengl or rapid)	"scanline", "on"
off	Scanline should always be off.	"scanline", "off"
"opengl"	Scanline should use OpenGL acceleration.	"scanline", "opengl"
"rapid"	Always render using rapid motion blur.	"scanline", "rapid"
environment trace option	Controls whether raytracing is enabled for secondary rays (or, if scanline is disabled, for all rays). If ray tracing is off, shadows will not be rendered except for lights casting shadows using shadow maps.
on	Raytracing should be enabled.	"environment trace", "on"
off	Raytracing should be disabled. No secondary rays are allowed. mi_trace_reflection and mi_trace_refraction will always return miFALSE.	"environment trace", "off"
shadow option
on	Shadows can be on for the scene. Any type of shadow mode is allowed.	"shadow", "on"
off	Shadows disabled for the scene.	"shadow", "off"
"sort"	Shadow calculations have to be either in sorted or segmented mode.	"shadow", "sort"
"segment"	Shadows can only be segmented.	"shadow", "segment"
face option	A triangle is considered frontfacing if its normal points to the direction of the ray.
"both"	Both backfacing and frontfacing triangles will be rendered. This is recommended if the shader performs volumetric effects on objects, since the volume needs both in and out points to work properly.	"face", "both"
"front"	Only frontfacing triangles will be rendered.	"face", "front"
"back"	Only backfacing triangles will be rendered.	"face", "back"
autovolume option	Autovolumes are an extension to volume rendering, where mental ray will assist where multiple volume objects overlap. They're slightly more expensive to compute but will allow, if the shader supports autovolume cooperation, overlapping volume effects.
on	mental ray will return a list of volumes the shader is to be called for, if necessary. Use the functions mi_volume_num_shaders, mi_volume_cur_shader, mi_volume_tags and mi_volume_instances to work with the autovolume algorithm.	"autovolume", "on"
off	mental ray will use the old method of dealing with volumes, where each volume effect is called in turn. This may lead to rendering artifacts if volume objects overlap.	"autovolume", "off"
"framebuffers" option	A framebuffer requirement specification. This option is used for output shaders to determine what types of framebuffers it will need to compute its effects. See section 1.28 of the mental ray user guide for further information.	"framebuffers", "rgba_fp,-tag"
"pass channel" option	A comma-separated list of pass channels. Each pass channel can optionally specify an image type in brackets. For example, "Normal Buffer(normal)" adds a pass channel named "Normal Buffer" with a normal image type, which maps to the mental ray miIMG_TYPE_N image type.	"pass channel", "Ambient,Diffuse,Specular,Irradiance,Reflection,Refraction"
"version" option	This option indicates the version of the shader as an integer. The value should correspond to the return value of the _version shader callback. Note If this option is omitted, Softimage assumes the shader version is 1 by default.	"version", "1"
"derivative1" option	Whether or not mental ray should compute the first derivative of a surface for each intersection point (gradient). The miState::deriv array will hold the derivative values at offset 0 and 1.
on	On to compute first derivative	"derivative1", "on"
off	Do not compute first derivative	"derivative1", "off"
"derivative2" option	Whether or not mental ray should compute the second derivative of a surface for each intersection point (curvature). The miState::deriv array will hold the derivative values at offset 2 to 3.
on	On to compute second derivative	"derivative2", "on"
off	Do not compute second derivative	"derivative2", "off"

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License