Shader Declarations

Shaders are procedural elements that are implemented in C or C++. They are typically, but not necessarily, precompiled and stored in shared libraries. They are linked by mental ray at runtime and perform a variety of functions, such as determining the surface characteristics of an object. The term "shader" originally referred to "surface shading" (color and illumination computation) but has expanded and now refers to any custom function, regardless of its use.

All shading functions linked with a code or link statement, and all shading functions built into mental ray, must be declared. When called, shaders accept a pointer to an arbitrary parameter structure as their third argument, and mental ray must know the structure declaration in order to put together the parameter block according to C/C++ structure layout conventions. Usually, declarations are included from a separate file using the $include statement. For a detailed description of shader declarations, see the chapter on writing shaders.

A declaration is a top-level statement that informs mental ray about the shader name (which is identical to the C/C++ function name), the return type, and the types and names of all the parameters. Certain options can also be specified.

      declare shader
          [type] "shader_name" (
              type "parameter_name" [default],
              type "parameter_name" [default],
              ...
              type "parameter_name" [default]
          )
          [version version_int]
          [apply shader_type_list]
          [options]
      end declare

It is recommended that shader_name and parameter_name are enclosed in double quotes to disambiguate them from reserved keywords and to allow special characters such as punctuation marks. Note that old-style declarations of the form

    declare [type] "shader_name" (...)

are also still supported for backwards compatibility, but they should not be used because they do not support versioning, apply masks, and options. The optional (but highly recommended) version is an arbitrary integer that identifies the shader version. The default is 0. See the discussion of shader versioning in section versioning. If the shader has no parameters, the parameter list between the parentheses is left empty.

mental ray allows to specify default values for numerical parameters. They are given with the keyword default followed by one (boolean, integer, scalar), three (vector, color), four (color), or sixteen (transform) values. This example:

    color "ambience" default 1 0 0,

declares a color parameter named "ambience" with a red default RGB color. Whenever a shader is derived from this declaration, the ambience parameter will be red unless changed in the definition. The example specifies only RGB, so the alpha component defaults to 0. To make it default to 1.0, a value of 1 needs to be inserted before the comma. Parameters that have no explicit default clause are initialized with null values. It is not possible to specify defaults for non-numerical parameters and array members.