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 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
.
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 miScalars 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.
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.)
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
Copyright 2000 by mental images