Shader Definitions

After a shader has been declared, it can be used in a shader definition. While a shader is made known to mental ray using a declaration only once, it may be used any number of times. Each use is called a definition, sometimes also referred to as a shader "instance". A definition supplies numerical or other values for shader parameters, and is attached to some other scene element.

In this manual, shader definitions will be used in many places, denoted by the shader meta symbol. A shader is defined as a shading function name followed by parameters:

"shader_name" ( parameters )

This sequence can be inserted for every instance of shader in the rest of this manual. (There are other forms, lists and named references, that can also be used in place of shader. They are described later.)

The shader name must have been previously declared with a declare command; see above. Normally shader libraries containing compiled C/C++ shaders come with a $include file that contains all declarations for the shaders in the library. The library itself is typically linked into mental ray with a link command. There are usually many shader references for every declaration, each with a unique set of parameters. The syntax of shader calls is described in the chapter on shaders; they are basically a comma-separated sequence of quoted parameter names, each followed by a parameter value.

The parenthesized parameters list is a comma-separated list of shader parameter assignments that have one of the following three forms:

"parameter_name" value  
"parameter_name" = "shader_name"  
"parameter_name" = interface "ifname"

The first form assigns a constant value to the parameter. The format of constant values depends on the parameter type:

type	value
`boolean`	`true`
	`false`
`integer`	value_int
`scalar`	value
`vector`	x y z
`transform`	t₀₀ t₀₁ t₀₂ t₀₃ t₁₀ t₁₁ t₁₂ t₁₃ t₂₀ t₂₁ t₂₂ t₂₃ t₃₀ t₃₁ t₃₂ t₃₃
`color`	red green blue
	red green blue alpha
	`colorprofile` "profile_name" red green blue
	`colorprofile` "profile_name" red green blue alpha
`spectrum`	"spectrum_name"
`string`	"string"
`data`	"data_name"
`shader`	"shader_name"
`color texture`	"texture_name"
`scalar texture`	"texture_name"
`vector texture`	"texture_name"
`light`	"light_instance_name"
`material`	"material_name"
`geometry`	"object_group_or_instance_name"
`struct`	{ parameters }
`array`	[ comma-separated value list ]

Integer values must be signed 32-bit values. All other numerical values are floating-point numbers that may contain a decimal point and/or a decimal exponent introduced by the letter e, as in 1.6e-27. The shader_name must be the name of a named shader from a preceding shader statement; the texture_name must be the name of a previously defined color texture, scalar texture, or vector texture statement, respectively. A spectrum_name referes to a previously declared spectrum block

Colors may only be given a colorprofile parameter, if color profiles have been enabled in the options block. The colors are then presumed to be given in the color space associated with the color profile. The color components will be transformed to the render color space before they are passed to the shader.

The special value keyword null can be used to replace any number, symbol, string, data, true, or false. It stores the numerical value 0 in the parameter. Its main purpose is to create "holes" in arrays by listing nulls between the square brackets.

The two non-constant forms of parameter assignment are explained later.

The above shader definition form is also called an anonymous shader because the shader name/parameter pair is formed on the fly and used in place. Sometimes it is useful to give a name to a shader/parameters pair using a shader statement and use it more than once:

shader "named_shader"  
    "shader_name" ( parameters )

Such pairs are called named shaders. After the pair was set up with a shader statement, it can be used in any place where a shader can be used, as an alternative to the anonymous shader statement listed above:

= "named_shader"

This is especially useful if the same shader/parameters pair is used in many different places in the scene, and it changes for every frame. Since shader statements allow incremental changes, an incremental change to a named shader affects all places that reference it (with the exception of displacement shaders - once an object is tessellated it remains unchanged until explicitly modified). Without named shaders it would be necessary to incrementally change every scene element containing the shader.