next up previous contents
Next: 2.2 Shader Definitions Up: 2. Scene Description Language Previous: 2. Scene Description Language

Subsections

2.1 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",
            type "parameter_name",
            ...
            type "parameter_name"
        )
        [ version versionint ]
        [ 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 [*]. If the shader has no parameters, the parameter list between the parentheses is left empty.

2.1.1 Parameter Types

The declaration gives the type and name of the shader to declare, which is the name of the C function and the name used when the shader is called, followed by a list of parameters with types. Names are normally quoted to disambiguate them from keywords reserved by mental ray. Commas separate parameter declarations. The following types are supported:

 

When choosing names, avoid periods and double colons, which have a special meaning when accessing  interface parameters in  phenomenon subshaders.

The return type of the shader must either be a simple type (any type except struct or array), or an unnamed struct containing only simple types. Unnamed means that there is no name between the struct keyword and the opening brace. This allows a shader to return multiple result values.

Note that mental ray 3.0 requires that  contour store shaders are correctly defined with all return parameters, typically an unnamed struct. mental ray will use the size of the declared return parameters to reserve enough space for the contour store shader to store into. mental ray 2.1 basically ignored the declared return parameters, and got the return size from the shader itself. mental ray 3.0 will print an error messages if the return parameters are undeclared, but an incorrect declaration will cause memory trouble.

2.1.2 Shader Apply Flags

The apply  statement allows specification of possible uses for the  shader. The shader_type_list consists of a comma-separated list of one or more of the following keywords:

keyword shader application
lens lens shader in a camera
material material shader in a material
light light shader
shadow shadow shader in a material
environment environment shader in a material or camera
volume volume shader in a material or camera
texture texture shader
photon photon shader in a material
geometry geometry shader
displace displacement shader in a material
emitter photon emitter shader in a light
output output shader in a camera

If the apply statement is missing, the applicability of a shader is unknown. This will commonly be the case for base shaders, for example, which can be used for any purpose. Apply lists help user interfaces to categorize shaders. mental ray performs no checks to make sure that shaders are used only in legal contexts, and in fact ignores the apply list completely.

2.1.3 Declaration Options

Declarations of shaders (and phenomena, see page [*]) allow a number of options to be specified in the  declaration block. These options specify requirements of the shader or  phenomenon, specifying conditions that must be met before the  shader or phenomenon can run correctly, or information about the shader that tells mental ray how to call it. They should be used only if it is impossible for the shader to do its job without this option, but not to second-guess the user, assuming that if this shader is used, then the user ``probably'' wants this option. Shader requirements take away control from the user and should be used with care. Before rendering, mental ray collects the requirements of all shaders defined in the scene, checks for conflicts, and adjusts global options and camera parameters to suit the shaders. Shaders should not assume that an option specified in the declaration has an effect because mental ray may choose to ignore it if there is a conflict with another declaration.

For example, if a shader specifies that it can operate only if ray tracing is enabled (a common case for lens shaders), it should specify the trace on option to tell mental ray to enable ray tracing even if no ray tracing was specified in the global options statement.

Here is the complete list of available options. If an option is not present, the default is ``don't care'' unless otherwise noted. If specified, these options are equivalent to the corresponding options given in the options top-level statement; refer to the description of option blocks for more details on the operation of these options.


next up previous contents
Next: 2.2 Shader Definitions Up: 2. Scene Description Language Previous: 2. Scene Description Language
Copyright 2002 by mental images