Next: 2.2 Shader Definitions
Up: 2. Scene Description Language
Previous: 2. Scene Description Language
Subsections
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.
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:
- boolean A boolean is either true or false. Possible values are true and
false, or their synonyms on and off,
- integer Integers are numbers without decimal point 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 sequence of 16 scalars describing a 4 x 4matrix, with the translation in the last row. The data structure
consists of an array of 16 miScalars in row-major order. Many
shaders check the last scalar and ignore the matrix if it is 0. In
most cases the last scalar of a valid matrix is 1, and always nonzero.
- 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.
- data Data parameters reference a user data block, holding arbitrary
structured or unstructured data of any kind. User data is useful for
large amounts of shared scene data. Shaders access it much like strings.
See section
for details.
- lightprofile3.1
Light profiles such as IES and Eulumdat are physical lamp description
files supplied by lamp vendors. They can be used by shaders to
determine the accurate amount of light emitted in a given direction.
See section
for details.
- geometry Geometry references objects, groups, 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 (non-empty) 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.
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.
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.
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.
- scanline on|off
The scanline rendering algorithm must be turned on or off,
respectively.
- trace on|off
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 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 front-facing, back-facing,
or both front-facing and back-facing geometry, respectively.
For example, a surface is visible if the incoming ray direction
is opposite to the normal vector of the surface, and the face
mode is either front or both but not back.
- 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
mental ray 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.
- volume level levelint
The volume level3.x defines the ``density'' behavior
of volume shaders. If autovolume mode is enabled in the
options block, mental ray keeps track of which volumes a ray is
in. If the current point is in multiple volumes, equal volume
levels mix, and higher levels displace lower volumes. For
example, if the point is in four volumes A, B, C, and D, with
volume shaders defining levels 3, 2, 3, and 1, respectively,
both the volume shaders A and C will be called because they
displace B and D. See page
for more
information about autovolume-enabled volume shaders.
Next: 2.2 Shader Definitions
Up: 2. Scene Description Language
Previous: 2. Scene Description Language
Copyright 2002 by mental images