Keywords: main

Next: 2.3 Shader Lists Up: 2. Scene Description Language Previous: 2.1 Shader Declarations

# 2.2 Shader Definitions

After a shader has been declared, it can be used in a 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. A definition supplies numerical or other values for shader parameters, and is attached to some other scene element.

In this book, 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 book. (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` | valueint
`scalar` | value
`vector` | x y z
`transform` | a00 a01 a02 a03 a10 a11 a12 a13 a20 a21 a22 a23 a30 a31 a32 a33
`color` | red green blue
| red green blue alpha
`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.

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 `null`s 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.

Next: 2.3 Shader Lists Up: 2. Scene Description Language Previous: 2.1 Shader Declarations