Keywords: main

Next: 2.2 Shader Definitions Up: 2. Scene Description Language Previous: 2. Scene Description Language
Subsections

- 2.1.1 Parameter Types
- 2.1.2 Shader Apply Flags
- 2.1.3 Declaration Options

# 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 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 , must be declared. When called, shaders accept a pointer to an arbitrary parameter structure as their third argument, and 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 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 .

## 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 . Commas separate parameter declarations. The following types are supported:

- `boolean` A boolean is either true or false. Possible values are `on`, `off`, `true`, and `false`.

- `integer` Integers are in the range -231...231 - 1.

- `scalar` Scalars are floating-point numbers, defined as an optional minus sign, a sequence of digits containing an optional decimal point at any place, followed by an optional decimal exponent. A decimal exponent is the letter `e` or `E` followed by a positive or negative integer. Examples are `1.0`, `.5`, `2.`, `1.e4`, or `-2.3e-6` .

- `vector` A vector is a sequence of three scalars as defined above, describing the x, y, and z components of the vector.

- `transform` A transformation is a 4 `x` 4 matrix of scalars, with the translation in the last row. The data structure consists of an array of 16 `miScalar`s in row-major order.

- `color` A color is a sequence of three or four scalars as defined above, describing the red, blue, green, and alpha components of the color, in this order. If alpha is omitted, it defaults to 0.0.

- `shader` Shader names defined with the `shader` statement (not to be confused with the shader declaration statement) can be passed to other shaders that have parameters of this type. The shader receives a tag that it can call using mi_call_shader and similar shader interface functions.

- `color texture` Color textures name a texture as defined by a `color texture` statement in the .mi file. The `color texture` statement names either a texture file, or a texture shader followed by a user parameter list. Note that a color texture does not name the texture shader directly. When a color texture is evaluated, it returns an RGBA color.

- `scalar texture` Scalar textures are equivalent to color textures, except that they name a `scalar texture` statement in the .mi file. When a scalar texture is evaluated, it returns a scalar (a single floating-point number). This is most often used to apply a texture map to a scalar material parameter such as transparency.

- `vector texture` Vector textures are another variation. They name a `vector texture` statement in the .mi file, which returns a vector when evaluated. Bump map bases on materials are typical applications for vector textures. Vector textures are rarely used.

- `light` Lights specify a light instance as defined by an `instance` statement in the .mi file, which in turn names a light. Despite the name, shader parameters of type `light` do not name the light directly because only the light's instance provides the necessary position and orientation information. Like textures, light parameters do not name light shaders directly.

- `string` Strings are quoted character strings of arbitrary length. The data type is a tag, which can be converted by the shader to a character pointer using the mi_db_access and mi_db_unpin shader interface functions.

- `geometry` Geometry references objects or instances. They are allowed for all types of shaders but are primarily useful for geometry shaders, which can introduce geometric scene entities. Geometry shaders have a different shader API than other shaders. They are described in chapter . Shaders and phenomena whose return type is `geometry` can be used in instance definition statements (see page ).

- `material` Material references. Their purpose is to operate on materials in phenomenon definitions, which may contain materials in addition to shaders. Shaders and phenomena whose return type is `material` can be used in material definition statements (see page ).

- `struct` {`...` } Structures define sub-lists of parameters. This is normally used to build arrays of structures, for example to declare an array of textures, each of which comes with a blending factor and other sub-parameters. The ellipsis ... stands for another comma-separated sequence of type/parameter_name pairs.

- `array type` Arrays are different from all other types in that they are not named. The `array` keyword is a prefix to any of the above types that turns a single value into a one-dimensional array of values. For example, `array scalar "terms"` declares a parameter named `terms` that is an array of scalars. The number of elements in the array size is dynamic and unlimited. Arrays of arrays are not supported but arrays of structs containing arrays can be used.

When choosing names, avoid double colons and periods, 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.

## 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. performs no checks to make sure that shaders are used only in legal contexts. (Future versions may use a material shader as shadow or photon shader if its applicability list allows it and there is no other shadow or photon shader listed in the material.)

## 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 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, 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 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, it should specify the `trace on` option to tell 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.

- `scanline on|off`
  The scanline rendering algorithm must be turned on or off, respectively.

- `trace on|off`
  Ray tracing ray tracing must be turned on or off. For example, lens shaders that modify the ray direction should set this to `on`.

- `shadow off`
  Shadows shadow must be turned off for this shader to function.

- `shadow on`
  Shadowing must be enabled, either regular, sorted, or segmented.

- `shadow sort`
  Shadowing must be enabled, either sorted or segmented. Regular is not sufficient.

- `shadow segments`
  Segmented shadows must be enabled. Regular or sorted shadows are not sufficient.

- `face front|back|both`
  Intersection testing should consider at least front-facing, back-facing, or both front-facing and back-facing geometry, respectively. ``At least'' means that a request for either front-facing or back-facing geometry is met of ``both'' is enabled.

- `derivative` [`1`] [`2`] The object that this shader or phenomenon is attached to (by being named in its material, for example) must have first or second derivatives, respectively, or both. This option has an effect only on free-form surface geometry because cannot compute derivatives for polygons.

- `object space`
  The shader functions only if all geometry is defined in object coordinates.

- `camera space`
  The shader functions only if all geometry is defined in camera coordinates.

- `mixed space`
  The shader functions only if all geometry is defined in camera coordinates, but it is ok if the camera is defined in object coordinates. This is done for certain kinds of walkthrough scenes and is not recommended for general shaders.

Next: 2.2 Shader Definitions Up: 2. Scene Description Language Previous: 2. Scene Description Language