Next: 3.5 Shader Parameter Declarations
Up: 3. Using and Writing
Previous: 3.3 Shader Type Overview
Subsections
Every shader needs to access information about the current state of
mental ray, and information about the intersection that led to the
shader call. This information is stored in a single structure known as
the state. Not all information in the state is of interest or
defined for all shaders; for example, lens shaders are called before an
intersection is done and hence have no information such as the
intersection point or the normal there. See page
for a table of which variable is available in which type of shader.
It is recommended to call the state parameter that shaders receive as a
formal parameter state because some macros provided in the shader.h include file that require access to the state rely on this
name (namely, the typed mi_eval_* variants). The
state, and everything else needed to write shaders, is defined in shader.h, which must be included by all shader source files.
Before a shader is called, mental ray prepares a new state structure
that provides global information to the shader. This state may be
the same data structure that was used in the previous call (this is
the case for shaders that modify another shader's result, like lens,
shadow, and volume shaders); or it may be a new state structure that
is a copy of the calling shader's state with some state variables
changed (this is done if a secondary ray is cast with one of the
tracing functions provided by mental ray). For example, if a material
shader that is using state A casts a reflected ray, which hits another
object and causes that object's material shader to be called with
state B, state B will be a copy of state A except for the ray and
intersection information, which will be different in states A and B.
State A is said to be the parent of state B. The state contains
a parent pointer that allows sub-shader to access the state of parent
shaders. If a volume shader is called after the material shader, the
volume shader modifies the color calculated by the material shader,
and gets the same state as the material shader, instead of a fresh
copy.
The state also contains a child pointer that, together with
the parent pointer, forms a double-linked list of states. After a
shader casts a ray, the state used by the ray remains available after
the trace call returns. This means that the shader has full access to
the intersection information, label value, and all other state variables
used by the child shader. For example, the shader for a completely
transparent object may decide to copy state - > child - > label to state - > label after mi_trace_transparency
returns. Only the most recent discarded child state is retained;
state - > child - > child is undefined.
This means that it is possible to pass information from one shader
to another in the call tree for a primary ray, by one of two methods:
either the parent (the caller) changes its own state that will be
inherited by the child, or the child follows the parent pointer. The
state contains a user pointer that a parent can store the address
of a local data structure in, for passing it to sub-shaders. Since
every sub-shader inherits this pointer, it may access information
provided by its parent. A typical application of this are inside/outside
calculations performed by material shaders to find out whether the
ray is inside a closed object to base the interpretation of parameters
such as the index of refraction on.
Note that the state can be used to pass information from one shader to
sub-shaders that are lower in the call tree. Care must be taken not to
destroy information in the state because some shaders (shadow, volume,
and the first eye shader) re-use the state from the previous call.
In particular, the state cannot be used to pass information from one
primary (camera) ray to the next. Static variables can be used in the
shader for this purpose, but care must be taken to avoid multiple
access on multiprocessor shared-memory machines. On such a machine,
all processors share the same set of static variables, and every
change by one processor becomes immediately visible to all other
processors, which may be executing the same shader at the same time.
Locking facilities are available in mental ray to protect critical
sections that may execute only once at any time.
Here is a complete list of state variables usable by shaders. Variables
not listed here are for internal use only and should not be accessed or
modified by shaders. Some variables are available only in some types of
shaders; see the ``State Variables by Shader Type'' section on
page
. The first table lists all state variables
that remain unchanged for the duration of the frame:
type |
name |
content |
int |
version |
shader interface version |
miTag |
camera_inst |
tag of camera instance |
miCamera * |
camera |
camera information |
miOptions * |
options |
general rendering options |
- version
The version number of the interface and the state structure.
Useful to check if the version is compatible with the shader.
Version 1 stands for mental ray 1.8, version 2 stands for 1.9
and 2.0.
- camera_inst
The camera instance is a data structure in the mental ray database
that contains transformation information about the camera. Like
all other tags in the state, a pointer to that data structure
can be obtained by calling mi_db_access with the tag
as the only argument. This function returns a void pointer to
the accessed data structure. After the pointer is no longer
used, the pointer must be ``returned'' by calling mi_db_unpin with it. Failure to do so will abort rendering.
The camera data structure pointed to by camera has the following
fields. None of these may be written to by a shader.
type |
name |
content |
miBoolean |
orthographic |
orthographic rendering |
float |
focal |
focal length of the camera |
float |
aperture |
aperture of the camera |
float |
aspect |
aspect ratio y x |
miRange |
clip |
Z clipping distances |
int |
x_resolution |
image width in pixels |
int |
y_resolution |
image height in pixels |
int |
window.xl |
left image margin |
int |
window.yl |
bottom image margin |
int |
window.xh |
right image margin |
int |
window.yh |
top image margin |
miTag |
volume |
camera volume (atmosphere) |
miTag |
environment |
camera environment shader |
miTag |
lens |
lens shader or lens shader list |
miTag |
output |
output shader or output shader list |
int |
frame |
frame number |
float |
frame_time |
frame time in seconds |
float |
frame_field |
0: frame, 1: even field, 2: odd field |
float |
x_offset |
x offset of image in pixels |
float |
y_offset |
y offset of image in pixels |
miTag |
userdata3.x |
user data scene element, or 0 |
- orthographic
This flag is miTRUE if the
renderer is in orthographic mode, and miFALSE if it is in
perspective mode.
- focal
The focal length of the camera (the distance from the origin in
camera space to the viewing plane that the image pixels are
mapped on).
- aperture
The aperture of the camera (the width of the viewing plane in
camera space).
- aspect
The aspect ratio (the ratio of the width and height of the
viewing plane in camera space).
- clip
This data structure has two members, min and max,
that specify the hither and yon clipping planes in camera space.
Objects will be clipped if their Z coordinate in camera space
is less than -max or greater than -min.
- x_resolution
The x resolution of the image in pixels.
- y_resolution
The y resolution of the image in pixels.
- window
The window specifies the lower left and the upper right pixel of
the sub-region of the image to be rendered. If xl and yl are 0 and xh and yh match or exceed the resolution
minus one, the entire image is rendered. The window is clipped to
the resolution. Pixels outside the window are set to black.
- volume
The global volume (atmosphere) shader from the
camera that is used for attenuating rays outside of objects,
such as the primary ray from the camera to the first object
intersection. Material shaders inherit this volume shader
because the volume state variable defaults to the camera
volume, but shaders may override the volume. See below.
- environment
The environment (reflection map) shader
of the camera. It is used to assign a color to primary eye rays
that leave the scene without ever intersecting an object.
Material shaders that do not define their own environment
shaders for evaluation of local reflection maps inherit the
camera environment shader. Reflection maps give the illusion of
true raytraced reflections by looking up a texture based on the
reflection direction.
- lens
The list of lenses applied to the standard
pinhole camera. Each lens shader in this list is called when
a primary ray leaves the camera.
- output
The list of output shaders and file outputs
attached to the camera. File outputs are encoded in special miFunction data structures that contain a file name and various
miscellaneous data instead of a shader reference.
- pass3.1
The list of multipass rendering statements.
- frame
The current frame number. In field mode, this is the field
number, two successive frames rendered by mental ray are combined
into a single output frame by an output shader. In field mode,
the odd frame is the first frame and the even frame is the second.
- frame_time
The current frame number, expressed as a time in seconds. The
relation between frame and frame_time depends on
the frame rate. Both numbers are taken verbatim from the input
scene, mental ray does not change or verify either number. If
the frame time is omitted in the .mi file, it is set to 0.0.
- x_offset
The X offset of the rendered image. The default value is 0.0
which means that the image will be centered on the camera's axis.
- y_offset
The Y offset of the rendered image. The default value is 0.0
which means that the image will be centered on the camera's axis.
- userdata
User data blocks are independent named toplevel scene entities
that hold structured or unstructured data of any kind.
Structured data is declared much like shader parameters, while
unstructured data is a raw byte stream with a fixed size. User
data is useful for large amounts of shared scene data.
The options field in the state contains all rendering options
specified in the scene, and possibly overridden by the command line.
Since the number of options is very large, and since they are rarely
used in a shader, the description can be found at the end of this
section, on page
.
The state variables in the next table describe an eye (primary) ray.
There is one eye ray for every sample that contributes to a pixel
in the output image. If a material shader that evaluates a material hit
by a primary ray casts secondary reflection, refraction, transparency,
light, or shadow rays, all shaders called as a consequence will inherit
these variables unmodified:
type |
name |
content |
miScalar |
raster_x |
X coordinate of image pixel |
miScalar |
raster_y |
Y coordinate of image pixel |
miFunction * |
shader |
current shader |
miLock |
global_lock |
lock shared by all shaders |
short |
thread |
current thread |
- raster_x
The X coordinate of the point in raster space to be rendered.
Raster space is the pixel grid of the rendered image file, with
0/0 at the lower left corner.
- raster_y
The Y coordinate of the point in raster space to be rendered.
In output shaders executing in parallel mode because
state - > dist is nonzero, it contains the number of
the first scanline of the scanline block to write.
- shader
This pointer points to a data structure describing the current
shader. The fields usable by shaders are lock, which is a
lock shared by all calls to this shader, miTag
next_function for chained shaders such as lens shaders, and
char parameters[] which contains the shader parameters.
The latter is redundant for the current shader because the
parameter pointer is also passed as the third shader argument,
but it can be used to find the parameters of parent shaders.
This should be used with care because the C data structure of
parent shader parameter lists is not generally known.
- Note that mental ray 3.x no longer supports state - > shader - > user.p. It is necessary to use mi_query
with miQ_FUNC_USERPTR to retrieve the user pointer.
This method works in mental ray 2.1 as well.
- global_lock
This lock is shared by all shaders, regardless of their name.
It can be used to lock critical sections common to all shaders.
For example, it could be used to protect a nonreentrant
user-defined random-number generator, or initialization of a
more specific set of locks. It is pre-initialized
by mental ray; do not initialize or delete it.
- thread
The current thread number. This is a
faster way of finding the thread number than calling
mi_par_localvpu2.1. Note that mental ray 3.0 may create
and destroy threads at any time, and may create threads with
higher numbers than specified on the command line with -threads. The thread number should not be used to index
static arrays in mental ray 3.x because there is no way to
compute the necessary size of this array when allocating it!
- count3.1
This field is valid only in light shaders. It specifies the
number of times the light shader has already been called in
order to oversample an area light source. It is 0 for the
first call. The shader may change this value just before
returning (miBoolean)2, which aborts the sample loop
and changes the value that the material shader will divide by
to compute the average. In particular, a light shader for a
user area light might set the count to 1 so that the material
shader considers each sample as a separate light. This is
useful for natural light ``chrome dome'' illumination.
The absence of state - > shader - > user.p and a fixed
upper limit on the number of threads are the two major differences
between mental ray 2.x and 3.x that impact shader development. See
page
for porting instructions.
Whenever a ray is cast the following state variables are set to describe
the ray:
type |
name |
content |
miState * |
parent |
state of parent shader |
miState * |
child |
state of child shader |
miRay_type |
type |
type of ray: reflect, light... |
miCBoolean |
scanline |
from scanline algorithm |
void * |
cache |
RC intersection cache |
miVector |
org |
start point of the ray |
miVector |
dir |
direction of the ray |
float |
time |
shutter interval time |
miTag |
volume |
volume shader of primitive |
miTag |
environment |
environment shader |
int |
reflection_level |
current reflection ray depth |
int |
refraction_level |
current refraction ray depth |
int |
face |
facing flag for sub-rays |
- parent
Points to the state of the parent ray. In
the first lens shader, it is NULL. In subsequent lens
shaders, it points to the previous lens shader. In the material
shader that is called when the primary ray hits an object, it
points to the last lens shader's state, or is NULL if no
lens shader has been applied. For material shaders called when
a secondary reflection or refraction ray hits an object, it
points to the parent material shader that cast the ray. In
light shaders and environment shaders, it points to the state
of the shader which requested the light or environment lookup.
For shadow shaders, it points to the state of the light shader
that started the shadow trace. In volume shaders, its value is
the same as for a material or light shader of the same ray.
- child
Points to the state of the most recent
child ray. After a function that created a separate state
returns, this state is still accessible to the caller of the
function through this pointer. For example, mi_trace_refraction constructs a state when hitting
geometry before calling the material shader attached to that
geometry with this state. After it returns, the new state can
be accessed by the caller of mi_trace_refraction to
access state - > user, state - > label, and
all other local information.
- type
Specifies the reason for this ray. This is an
enumerator. Some values became available in mental ray 3.0
to allow shaders to differentiate, but the underlying features
were already present in mental ray 2.1. This may require
shader changes to add case statements to existing
switch blocks.
=4cm6cm
- miRAY_EYE
primary rays from the camera.
- miRAY_TRANSPARENT
transparency rays cast by a material shader.
- miRAY_REFRACT
refraction rays cast by a material shader.
- miRAY_REFLECT
reflection rays cast by a material shader.
- miRAY_SHADOW
light rays cast from a light source.
- miRAY_LIGHT
rays cast by a material shader when a light source is
evaluated (which may result in the light source casting
shadow rays back).
- miRAY_ENVIRONMENT
rays that sample an environment (reflection) map.
- miRAY_DISPLACE
is set for displacement shaders.
- miRAY_OUTPUT3.x
is set for output shaders.
- miRAY_FINALGATHER3.x
is set for finalgather rays originating at the final
gather point.
- miRAY_LM_VERTEX3.x
is set for lightmap shaders in vertex scan mode.
- miRAY_LM_MESH3.x
is set for lightmap shaders in mesh output mode.
- miRAY_PROBE3.1
is used by rays cast by mi_trace_probe in mental
ray 3.1. Earlier versions used miRAY_NONE.
- miRAY_NONE
is a catch-all for other types of rays.
- miPHOTON_LIGHT
is a photon emitted from a light source.
- miPHOTON_REFLECT_SPECULAR
is a photon reflected specularly from a surface.
- miPHOTON_REFLECT_GLOSSY
is a photon reflected glossily from a surface.
- miPHOTON_REFLECT_DIFFUSE
is a photon reflected diffusely from a surface.
- miPHOTON_TRANSMIT_SPECULAR
is a photon transmitted specularly through a surface.
- miPHOTON_TRANSMIT_GLOSSY
is a photon transmitted glossily through a surface.
- miPHOTON_TRANSMIT_DIFFUSE
is a photon transmitted diffusely through a surface.
- miPHOTON_TRANSPARENT
is a photon transmitted directly (ie., without refraction)
through a surface.
- miPHOTON_ABSORB3.x
is a photon being absorbed.
- miPHOTON_SCATTER_VOLUME3.x
is a photon scattered in a volume.
- miPHOTON_EMIT_CAUSTIC3.x
is a caustics photon to be cast by a photon emitter
shader attached to a light source.
- miPHOTON_EMIT_GLOBILLUM3.x
is a global illumination photon to be cast by a photon
emitter shader attached to a light source.
- The ray type (state - > type) can be queried with the
following macros:
- =4cm6cm
- miRAY_PRIMARY(raytype)
is true if the raytype is a primary or a transparency ray.
- miRAY_SECONDARY(raytype)
is true if the raytype corresponds to a ray generated
at an intersection point.
- miRAY_PHOTON(raytype)
is true if the raytype is one of the miPHOTON_*
rays. This macro can be used to separate the photon tracing
part of a shader from the regular ray tracing part.
- scanline
This flag is set if the current intersection was
found by means of the scanline algorithm.
- cache
This variable is used by the renderer internally to improve speed.
Its existence determines which shaders may call which tracing
functions. By setting this pointer to 0, the shader can ease these
restrictions and call tracing functions that are not normally legal
for this type of shader. For details, see the section Shaders
and Trace Functions below.
- org
The origin (start point) of the ray in internal space. In
the primary material shader, it is set by the last lens shader,
or is (0, 0, 0) if there is no lens shader and the default
non-orthogonal pinhole camera is used. In all other material
shaders, it is the previous intersection point. In light and
shadow shaders, it is the origin of the light source. If the
light source does not have an origin, it is undefined.
- dir
The direction of the ray in internal space. This is
basically the normalized difference between point and
org, pointing towards the current intersection point
(except in the case of directional light sources that have no
origin; in this case the light direction is used). Light and
non-segmented shadow rays point from the light source to the
intersection.
- time
The time of the ray in the shutter interval. If motion blurring
is turned off by setting the shutter time to 0.0 (or to the
shutter delay3.1 value), the time is fixed at the
shutter value. Otherwise, it is systematically sampled in the
range from the shutter delay3.1 to the shutter time.
- volume
The volume shader to be applied to the ray.
The volume shader is called immediately after the material
shader returns, without any change to the state. The volume
shader changes the result color of the material shader to take
the distance the ray to the
material has traveled into account. For primary
rays this is the volume of the camera, for reflection and
light rays the volume of the
parent, and for refraction and transparency rays the refraction_volume of the parent. Note that the
mi_trace_refract and mi_trace_transparent functions
copy refraction_volume to volume to ensure that
sub-shaders use the volume shader that
applies to the interior of the object. Volume shaders are also
applied to light rays. This state variable is ignored in
autovolume3.x mode.
- environment
The active environment shader. For
primary rays this is the environment of the camera. For
reflection and refraction rays the active shader is taken from
the material, if it specifies an environment shader. If it does
not, the environment shader defaults to the environment shader
in the camera, if present. The purpose of the environment shader
is to provide a color if a ray leaves the scene entirely.
- reflection_level
The reflection level of the ray. It may range
from 0 for primary rays to reflection_depth minus one.
The trace_depth imposes another limit: The sum of reflection_level and refraction_level must be one less
than trace_depth. A shader may decrement or reset the
reflection level to circumvent the restrictions imposed by the
trace depth state variables. The level fields are also used
during photon tracing, and measure the photon trace depths in
this case.
- refraction_level
The refraction level of the ray. This is equivalent to the
reflection level but applies to refraction and transparency (which
is a variation of refraction that does not take the index of
refraction into account) rays. A shader may decrement or reset
the refraction level to circumvent the restrictions imposed by
the trace depth state variables.
- face
This field is initialized with state - > options - > face, but can be changed by shaders before casting a secondary
ray with functions such as mi_trace_reflection. The
secondary ray will then obey the changed face flag.
The variables in the next table are closely related to the previous. They
describe the intersection of the ray with an object, and give information
about that object and how it was hit.
type |
name |
content |
miTag |
refraction_volume |
volume shader for refraction |
miUint |
label |
object label for label file |
miTag |
instance |
instance of object |
miTag |
light_instance |
instance of light |
miScalar [4] |
bary |
barycentric coordinates |
miVector |
point |
intersection (ray end) point |
miVector |
normal |
interpolated normal at point |
miVector |
normal_geom |
geometry normal at point |
miCBoolean |
inv_normal |
true if normals were inverted |
miScalar |
dot_nd |
dot prod of normal and dir |
double |
dist |
length of the ray |
double |
material |
material of hit primitive |
void * |
pri |
identifies hit box |
int |
pri_idx |
identifies hit primitive in box |
double |
shadow_tol |
safe zone to prevent self-shadows |
miScalar |
ior |
index of refraction of medium |
miScalar |
ior_in |
index of refr. of previous medium |
- refraction_volume
The volume at the other side of the object.
This is set to the volume shader of the material. It will be
applied to refraction rays. This is implemented by copying refraction_volume to volume (which is the shader that
gets called when the material shader returns) in the mi_trace_refract and mi_trace_transparent functions.
The material shader may decide that the ray is leaving and not
entering the object, and look in the state's parents for an
outside volume shader. This state variable is ignored in
autovolume3.x mode.
- label
The label of the hit object. Every object may contain a label
that is made available by this variable. When the primary
material shader returns, the label is copied from the state
to the ``tag'' frame buffer, if one was created by an appropriate
output statement in the camera. The primary
material shader is free to change this variable to any value to
put different values into the tag frame buffer.
- instance
The instance of the object containing the primitive hit by the
ray.
- light_instance
If the ray is a light ray or the corresponding
shadow ray: the light instance. If the ray hit
a visible area light source, light_instance is set to
that light instance.
- bary
The three barycentric coordinates
of the intersection in the hit primitive. The fourth value is
reserved for implicit patches and is not currently used.
Barycentric coordinates are weights that specify the contribution
by each vertex or control point. The sum of all barycentric
coordinates is 1.
- point
The intersection point (end point of the ray) in internal space.
- normal
The (interpolated) surface normal at the intersection point if
vertex normals are present, or the uninterpolated geometric
normal of the primitive otherwise, in internal space. It
points to the side of the primitive from which it is hit by the
ray, and is normalized to within the precision of a float.
Care should be taken when calculating the length of the normal;
the result of this calculation might be very slightly greater
than 1 because a float has only a little over six
significant digits. This can cause math functions like acos
to return NaN (Not a Number, an illegal result), which
usually results in white pixels in the output if the NaN
finds its way into a result color.
- normal_geom
The uninterpolated normal of the hit primitive in internal
space. It points to that side of the primitive from which it
is hit by the ray. It is normalized.
- inv_normal
If a ray hits geometry from behind (that is, if the dot product
of the ray direction and the normal is positive), mental ray
inverts both normal and normal_geom and sets inv_normal to miTRUE.
- dot_nd
The dot product of the normal and the direction (after the normals
have been inverted in the case of backfacing geometry). In the case
of light rays, it is the negative dot product of the light ray
direction and the normal at the point which is to be illuminated.
- dist
The length of the ray, which is the distance from org
to point if there is an origin, in internal space. A
value lower or equal to 0.0 indicates that no intersection was
found, and that the length is infinite. In output shaders,
it is 0 for sequential shaders or the number of scanlines to
write, beginning at raster_y, for parallel output
shaders.
- material
The material of the primitive hit by the ray. (If a visible
area light source has been hit, material is set to the
inherited instance material, if available.) The data can be
accessed using mi_db_access followed by mi_db_unpin.
This is generally not necessary because all relevant information
is also available in the state.
- pri
This number uniquely identifies the current box. All primitives
are grouped in boxes. When casting light rays, mental ray may
check whether the primitive's normal is pointing away from the
light and ignore the light in this case; for this reason some
shaders, such as ray-marching volume shaders,
assign 0 to pri before sampling a light. Shaders other
than volume shaders should restore pri before returning.
When a visible area light source is hit, pri is set to
NULL. Some mi_query modes do not work if pri has
been modified.
- pri_idx
Together with pri, this number uniquely identifies the
primitive in the current box. This value is used by mental ray
internally.
- shadow_tol
If a shadow ray is found to intersect the primitive in shadow,
at a distance of less than this tolerance, the intersection is
ignored. This prevents self-shadowing in the case of numerical
inaccuracies.
- ior
This field is intended for use by material shaders that need to
keep track of the index of refraction for inside/outside determination. It is not used by mental ray. The
mi_mtl_refraction_index shader interface function stores
the index of refraction of the medium the ray travels through in
this state variable.
- ior_in
Like ior, this field helps the shader with inside/outside
calculations. It contains the ``previous'' index of refraction,
in the medium the ray was traveling through before the intersection.
Like ior, ior_in is neither set nor used by mental ray,
it exists to allow the material shader to inherit the previous index
of refraction to subsequent shaders.
The following table is an extension to the previous. These variables give
information about the intersection point for texture mapping. They are
defined when the ray has hit a textured object:
type |
name |
content |
miVector * |
tex_list |
list of texture coordinates |
miVector * |
bump_x_list |
list of X bump basis vectors |
miVector * |
bump_y_list |
list of Y bump basis vectors |
miVector |
tex |
texture coord (tex shaders) |
miVector |
motion |
interpolated motion vector |
miVector * |
derivs[5] |
list of surface derivatives |
- tex_list
A pointer to an array containing the texture coordinates of the
intersection point in all texture spaces. When material
shaders that support multiple textures on a surface call a
texture lookup function, they must specify which texture
coordinate to use, usually by choosing one of the texture
vertices in tex_list and copying it to tex.
- bump_x_list
A pointer to an array containing the x bump basis vectors
in all texture spaces. The vectors are in object space.
The scene must have been prepared to contain or compute these
vectors. They are very rarely used because normally shader
compute the basis vectors on the fly.
- bump_y_list
A pointer to an array containing the y bump basis vectors
in all texture spaces. The vectors are in object space.
- tex
The texture coordinates where the texture should be evaluated.
This variable is available only in texture shaders; it is set
by the caller (for example, a texture lookup from a material
shader).
- motion
The motion vector of the intersection point.
If the object has no motion vectors (m statements in the
vertices in the scene description file), the motion vector is
a null vector.
- derivs[ ]
A pointer to an array containing the surface derivative
vectors. If the object is a free-form surface object, the
surface derivative vectors derivs[0] ... derivs[4] contain dx/du,
dx/dv, d2x/du2, d2x/dv2,
d2x/dudv, respectively.
Here x denotes the intersection point. For polygonal
objects the surface derivatives are taken from the .mi
file. If the object has no first derivative vectors, the first
two vectors are null vectors. If the object has no second
derivative vectors, the last three vectors are null
vectors. Since surface derivatives are calculated
approximately, the vectors dx/du,
dx/dv and the normal vector at the
intersection point are not necessarily orthogonal to each
other.
Finally, the user field allows a shader to store a pointer to an
arbitrary data structure in the shader. Subsequent shaders called as a
result of operations done by this shader (such as casting a reflection
ray or evaluating a light or a texture) inherit the pointer and can
read and write this shader's local data. Sub-shaders can also find
other parent's user data by following state parent pointers, see above.
With this method, extra parameters can be provided to and extra return
values received from sub-shaders.
However, once the shader that has set the user pointer returns, the user
pointer is lost. Its purpose is to pass information to sub-shaders down
the call graph, not to pass information from one invocation of a shader
to the next (for example, to the next primary ray). This implies that it
is not a good idea to use mi_mem_allocate to obtain the pointer
because by definition this could result in millions of allocations, which
is inefficient. Long-term shader user data should be stored in the
shader user pointer (obtainable with the miQ_FUNC_USERPTR mode
of mi_query) instead, typically allocated in the init shader
and released in the exit shader.
The user variables are initialized to 0.
type |
name |
content |
void * |
user |
user data pointer |
int |
user_size |
user data size (optional) |
The shader pointer can be used to access the shader parameters, as state- >parameters. This is redundant for the current shader
because this pointer is also passed as the third shader argument, but
it can be used to find a parent shader's parameters.
The option data structure pointed to by state - > options has
the following format, split here over three tables due to its size. The
option structure may never be written to by shaders.
type |
name |
content |
int |
min_samples |
minimum sampling level |
int |
max_samples |
maximum sampling level |
miColor |
contrast |
sampling contrast |
miColor |
time_contrast |
temporal sampling contrast |
miBoolean |
samplelock |
noise animation locking on/off |
char |
render_space |
coordinate space: 'c' for camera
space, 'o' for object space |
int |
task_size |
rendered image rectangle size |
miCBoolean |
pixel_preview |
selective pixel sampling mode |
miCBoolean |
task_preview |
selective task sampling mode |
miCBoolean |
visible_lights |
have visible area lights in the
scene |
miBoolean |
strips |
tessellation to strips and fans |
miCBoolean |
no_lens |
disable lens shaders |
miCBoolean |
no_volume |
disable volume shaders |
miCBoolean |
no_geometry |
disable geometry shaders |
miCBoolean |
no_displace |
disable displace shaders |
miUint1 |
no_output |
disable output shaders |
miCBoolean |
no_merge |
disable surface merging |
miTag |
userdata |
optional user data blocks |
miApprox |
approx |
approximation override |
miApprox |
approx_displace |
displacement approximation override |
miTag |
contour_contrast |
contour contrast shader |
miTag |
contour_store |
contour store shader |
miTag |
inh_funcdecl |
inheritance/traversal declaration |
miUint1 |
diagnostic_mode |
miSCENE_DIAG_ flag bitmap |
float |
diag_photon_density3.x |
density for diagnostic
photon mode |
float |
diag_grid_size |
grid size for diagnostic grid mode |
miBoolean |
desaturate3.x |
fade to white, no clipping |
miBoolean |
dither3.x |
enable frame buffer dithering |
miBoolean |
nopremult3.x |
disable premultiplication |
int |
colorclip3.x |
color clipping modes |
float |
gamma3.x |
frame buffer gamma value, 1 for none |
miColor |
luminance_weight3.x |
weights to calculate
luminance |
int |
no_images |
highest frame buffer index plus 1 |
miPointer |
image [ ] |
frame buffers for output shaders |
miImg_type |
image_types [ ] |
image types of frame buffers |
miUint4 |
write_image[ ] |
bit 0: sample, bit 1: write |
miBoolean |
interp_image[ ] |
interpolate frame buffer |
Rendering algorithm options:
type |
name |
content |
miBoolean |
trace |
ray tracing turned on? |
miBoolean |
scanline |
scanline mode turned on? |
miBoolean |
motion |
motion blur turned on? |
float |
shutter_delay3.1 |
shutter open time for motion
blur |
float |
shutter |
shutter close time for motion blur |
miCBoolean |
autovolume3.x |
automatic volume
management |
char |
filter |
nonlocal sampling filter: 'b' for
box, 't' for triangle, 'g' for Gauss,
'm' for Mitchell, or 'l' for Lanczos |
float |
filter_size_x |
filter size in x |
float |
filter_size_y |
filter size in y |
int |
reflection_depth |
max reflection trace depth |
int |
refraction_depth |
max refraction trace depth |
int |
trace_depth |
max combined trace depth |
char |
face |
'f' for front, 'b' for back, or 'a'
for both faces |
char |
field |
'o' for odd or 'e' for even fields,
0 for frames |
float |
jitter |
sample jittering: 0 for off, 1 for
on |
char |
shadow |
0 for off, 1 for normal, 's' for
segmented, 'l' for sorted |
char |
use_shadow_maps |
use shadow maps for rendering |
miCBoolean |
rendering_shadow_maps |
currently working on a
shadow map rectangle |
char |
recompute_shadow_maps |
'n' for reuse, 'y' for rebuild |
miCBoolean |
shadow_map_motion |
motion blurred shadowmaps |
char |
acceleration |
ray tracing algorithm: 'b' for BSP,
'g' for grid |
short |
grid_res[3]3.1 |
grid resolution in world space: X,
Y, Z |
short |
grid_max_depth3.1 |
maximum grid nesting |
short |
grid_max_size3.1 |
maximum grid leaf size |
float |
grid_max_size2.1 |
grid resolution correction |
int |
space_max_size |
maximum BSP leaf size |
int |
space_max_depth |
maximum BSP nesting |
int |
space_max_mem |
maximum bsp memory in MB, 0 for
unlimited |
Global illumination options:
type |
name |
content |
int |
photon_reflection_depth |
max photon reflection trace
depth |
int |
photon_refraction_depth |
max photon refraction trace
depth |
int |
photon_trace_depth |
max combined photon trace depth |
miTag |
photonmap_file |
photon map file name |
miTag |
finalgather_file3.x |
finalgather map file name |
miBoolean |
photonmap_rebuild |
rebuild photon map, don't reuse |
miCBoolean |
finalgather_rebuild3.x |
rebuild final gather map |
miBoolean |
caustic |
caustics on/off |
int |
caustic_accuracy |
number of caustic photons in
estimate |
float |
caustic_radius |
maximum distance for caustic photons
in estimate |
float |
caustic_filter_const |
filter constant for caustics |
char |
caustic_filter |
caustic filter type: 'b' for box,
'c' for cone, 'g' for Gauss |
miUint1 |
caustic_flag |
default caustic flag for objects |
miBoolean |
globillum |
global illumination on/off |
int |
globillum_accuracy |
number of globillum photons in
estimate |
float |
globillum_radius |
maximum distance for globillum
photons in estimate |
miUint1 |
globillum_flag |
default globillum flag for objects |
int |
photonvol_accuracy |
number of volume photons in estimate
float |
int |
finalgather |
final gathering: 0 for off, 1 for on,
or 'f' for fastlookup3.x |
int |
finalgather_rays |
number of rays per final gather
point |
float |
finalgather_maxradius |
maximum distance between final
gather points |
float |
finalgather_minradius |
minimum distance between final
gather points |
miCBoolean |
finalgather_view3.x |
final gather radii are
specified in raster pixels |
miUint1 |
n_motion_vectors3.1 |
motion transformation
path length |
- min_samples
The minimum oversampling level. 0 means one sample per pixel
on average (mental ray actually samples corners, not centers
of pixels). 1 means subdivide once, which results in four
subpixels. 2 means each subpixel is subdivided again, resulting
in 16 subpixels, and so on. -1 means one sample per four pixels,
etc.
- max_samples
After initial subdivision controlled by min_samples,
pixels are further subdivided if the contrast demands it, up
to the level determined by max_samples.
- contrast
If two neighboring samples sre more different than the contrast,
the pixel is subdivided unless the max_samples limit has
been reached.
- time_contrast
Same as contrast, but is applied to sampling during motion
blurring, where higher contrasts are usually sufficient to
achieve acceptable quality.
- samplelock
If enabled, mental ray attempts to cast the same samples in
each frame, which means that the grainyness due to low sampling
stays in place, instead of flickering. This is achieved by not
initializing sampling sequences with the frame number. This has
an effect only where the image doesn't change because otherwise
oversampling will cast different samples.
- render_space
This is 'o' for object space and 'c' for camera space. Camera
space rendering is supported for compatibility with mental ray
1.x, but not recommended for new scenes.
- task_size
The size of one image rectangle into which the image to render
is subdivided. The default is 32 or 64.
- pixel_preview
This is enabled during interactive rendering, where mental ray
renders only those pixels that are affected by a user change,
usually by tuning a shader parameter.
- task_preview
This is enabled if the application has entered a mode where
only certain image rectangles are rendered.
- visible_lights
This is true if there are any lights marked ``visible'' in the
currently rendered scene.
- strips
The tessellator will attempt to pack triangles into strips and
fans. This is not useful for rendering with mental ray, and in
fact incurs overhead due to strip and fan construction, but it
can greatly improve the performance of OpenGL viewers.
- no_*
These flags disable lens, volume, geometry, displace, and
output shader calls, respectively, or edge merging. They are
useful for quick preview rendering. Shaders may still
explicitly call the disabled shaders, but mental ray won't.
- userdata
User data blocks are independent named toplevel scene entities
that hold structured or unstructured data of any kind.
Structured data is declared much like shader parameters, while
unstructured data is a raw byte stream with a fixed size. User
data is useful for large amounts of shared scene data.
- approx
May be set to any approximation method, which will override
approximations specified in objects. This is useful for quick
preview rendering where geometric precision does not matter. This
is disabled if the method is set to miAPPROX_STYLE_NONE.
- approx_displace
This is the same as approx, but applies to displacement
approximations in objects.
- contour_contrast
The contour contrast shader, or 0.
- contour_store
The contour store shader, or 0.
- inh_funcdecl
The declaration of the inheritance function or traversal
function3.1, or 0.
- diagnostic_mode
If nonzero, enables various diagnostic modes that put false-color
diagnostic data on top of the rendered image. The modes are:
- miSCENE_DIAG_SAMPLES shows where image samples were taken.
- miSCENE_DIAG_PHOTON_D shows photon density.
- miSCENE_DIAG_PHOTON_I shows photon irradiance.
- miSCENE_DIAG_GRID_O overlays object-space grid lines.
- miSCENE_DIAG_GRID_W overlays world-space grid lines.
- miSCENE_DIAG_GRID_C overlays camera-space grid lines.
- miSCENE_DIAG_BSP_D shows the BSP tree depth.
- miSCENE_DIAG_BSP_L shows the BSP leaf size.
- miSCENE_DIAG_FG3.x shows final gather points.
- diag_photon_density
Calibrates the colors for the photon diagnostic modes.
- diag_grid_size
Determines the grid line distance in the grid diagnostic modes.
- desaturate3.x
Enables fading colors to white, instead of clipping individual
components, when storing colors in 8-bit or 16-bit frame buffers.
This and the following four fields used to be accessible with
the mi_img_getmode shader interface function in
mental ray 2.1, but have moved into the options in mental ray 3.0.
- dither3.x
Enables dithering when storing colors in 8-bit or 16-bit frame
buffers.
- nopremult3.x
Disables premultiplication, and stores unpremultiplied colors
in frame buffers.
- colorclip3.x
Selects the color clipping mode applied when storing colors in
8-bit or 16-bit frame buffers, to make sure that RGB do not
exceed alpha in premultiplication mode:
- miIMG_COLORCLIP_RGB preserves RGB and adjusts alpha if
necessary.
- miIMG_COLORCLIP_ALPHA preserves alpha and adjusts RGB
if necessary.
- miIMG_COLORCLIP_RAW disables color clipping.
- gamma3.x
The gamma value applied when storing colors in 8-bit or 16-bit
frame buffers. 1.0 disables gamma correction.
- luminance_weight3.x
The weights applied to RGB by the mi_luminance shader
interface function to compute a luminance value.
- no_images
The number of the highest defined frame buffer, plus 1. See
image below for frame buffer numbers.
- image[ ]
An array of pointers to frame buffers. It is available only
in output shaders. The type is miPointer to ensure
network transparency, requiring access with image[i].p;
the real type is miImg_image *. The array is indexed
with the predefined indices, each corresponding to one of the
standard frame buffers that are enabled with appropriate
output statements. If a frame buffer was not enabled, the
corresponding pointer is 0. The predefined indices are:
- miRC_IMAGE_RGBA is the standard color image frame buffer.
- miRC_IMAGE_Z contains object depths.
- miRC_IMAGE_N contains normal vectors.
- miRC_IMAGE_M contains motion vectors.
- miRC_IMAGE_TAG contains object labels.
- miRC_IMAGE_COVERAGE3.x contains coverage fractions
of the object that contributed most to this pixel. If enabled,
the Z, N, M, and TAG frame buffers contain values from that
object.
- miRC_IMAGE_PPREV2.1 contains shader bitmaps used
for pixel previewing (interactive rendering).
- miRC_IMAGE_USERis the first of the eight user frame
buffers.
- All frame buffers have the same resolution as specified in
the camera. The frame buffer pointers can be passed to the
buffer access functions, mi_img_get_color,
mi_img_put_color, etc. For each type of frame buffer,
there are functions to retrieve and store a pixel value that
accept the frame buffer pointer as their first argument.
Motion vector data can be accessed with the normal-vector
access functions; the data format is identical.
- image_types[ ]
Contains the type of each defined frame buffer.
- write_image[ ]
For each defined frame buffer, bit 0 is set if the frame buffer
is sampled, and bit 1 is set if the frame buffer is written.
- interp_image[ ]
For each defined frame buffer, the flag is set if the frame
buffer is interpolated (``+'' was set in the scene) or aliased
(``-'' was set in the scene).
Rendering algorithm options in the state- >options
structure:
- trace
If this flag is miTRUE, secondary ray tracing
(reflection and refraction) is enabled. If it is miFALSE,
only eye and transparency rays are evaluated, refraction rays
degenerate to transparency rays, lens shaders cannot modify the
ray origin and direction, and no shadows are computed regardless
of the shadow flag.
- scanline
If this flag is miTRUE, the scanline algorithm is enabled
for primary rays. If scanline is miFALSE, primary
rays are cast using pure ray tracing, which may slow down the
rendering process.
- motion
If this flag is miTRUE, motion blurring is enabled; if it
is miFALSE, motion blurring is disabled even if motion
vectors are present.
- shutter
If motion is set to miTRUE, the shutter determines
the length of time the shutter is open, which controls the
length of the blur. 1.0 means that the blur is as long as the
motion vectors of motion transformations dictate.
- shutter_delay3.1
If motion is set to miTRUE, the shutter delay
determines the time the shutter opens. It closes at the
shutter time, which must be equal to or greater than
shutter_delay. A shutter range of 0...1 means that the blur
uses the entire range of the motion vectors, motion
path3.1, or motion transformations.
- autovolume3.x
If set, mental ray will keep track of which volumes a point is
in. The shader can then use the shader interface
functions mi_volume_num_shaders, mi_volume_cur_shader,
mi_volume_user_color, and mi_volume_tags.
- filter
Nonlocal filtering weighs samples according to their distance
from the pixel center. Possible values are 'b' for box,
't' for triangle, and 'g' for gauss.
- filter_size_x
Contains the filter width for collecting image samples into
frame buffer pixels.
- filter_size_y
Contains the filter height.
- reflection_depth
The maximal allowed number of recursive
reflections. A reflection ray will only by cast when this limit
is not exceeded. If set to 0, no secondary
reflection rays will be cast. See reflection_level below.
- refraction_depth
The maximal allowed number of recursive refractions. A refraction
ray will only be cast if this number is not exceeded. If set to 0,
no secondary
refraction or transparency rays will be cast. See refraction_level below.
- trace_depth
The maximal summed trace depth. mental ray will allow this many
segments of the ray tree when it is followed through the scene,
with any combination of reflections and refractions
permitted by the previous two values until the total trace depth
is reached. A ray will only be cast if this number is not exceeded.
- face
This variable specifies whether front-facing, back-facing, or
all triangles are taken into account. All others are ignored,
resulting in speed improvements. This is also called back
face culling. The possible values are 'f' (front), 'b' (back), and 'a' (all).
- field
Field rendering, if turned on, renders only
the even or odd scanlines of an image. Two successive renders
are then combined to a full frame, resulting in smoother
animations. 0 turns off field rendering, 'e' renders
only even scanlines (top is odd), and 'o' renders only odd
scanlines.
- jitter
If set to 1.0, jittering is enabled for samples smaller than a
pixel. If set to 0.0, jittering is disabled. Other values are
not legal.
- shadow
This ASCII character controls shadow casting.
If it is 0, shadows are disabled (shadow off);
if it is 1, normal shadows are computed in undefined order
with volume shaders applied to the light ray (shadow on);
if it is 'l', shadow shaders are called in sorted order
from the light source towards the illumination point (shadow sort);
if it is 's', shadows are computed by tracing the segments
between the illumination point, the occluding objects and the
light source and applying volume shaders to these segments (shadow
segment).
- use_shadow_maps
Enables shadow maps if set to miTRUE.
- rendering_shadow_maps
If set to miTRUE, mental ray is currently rendering a
piece of a shadow map. Shaders will never see miTRUE
because no shaders are called during shadow map rendering
by mental ray 2.1 or 3.0.
- recompute_shadow_maps
If set to 'y', shadow maps will be recomputed even if
shadow map files were found. If set to 'n', shadow map
files will be used if available. To use shadow map files, the
shadow-casting light sources must specify a shadow map file name.
- shadow_map_motion
If set to miTRUE, shadow maps will contain object motion
blur, which will extend the shadows in the direction of motion.
- acceleration
The ray tracing algorithm. This is either 'b' (a BSP
algorithm), or 'g' (a hierarchical uniform grid algorithm
only available in mental ray 2.1 and 3.1 but not 3.0). Note
that by default, primary rays are computed using a scanline
algorithm if possible.
- grid_res[ ]3.1
Controls the number of grid voxels in world space, in each
dimension, if the acceleration algorithm is grid.
- grid_max_depth3.1
Controls the number of levels of the grid tree, formed if a
grid voxel of one level contains too much geometry and must be
subdivided by a subgrid on a lower level. It has an effect only
if the acceleration algorithm is grid.
- grid_max_size3.1
Controls the allowed complexity of a grid voxel before the voxel
must be subdivided. It has an effect only if the acceleration
algorithm is grid. If the grid_max_depth limit was
reached, mental ray may exceed grid_max_size.
- grid_max_size2.1
mental ray 2.1 had a different non-adaptive and non-recursive
grid algorithm with only one parameter, a floating-point size
that adjusts the resolution computed by mental ray. 1.0 accepts
mental ray's resolution estimate, larger values increase the
resolution, and smaller values decrease it. It has an effect
only if the acceleration algorithm is grid.
- space_max_depth3.1
Controls the number of levels of the BSP tree, formed if a
BSP voxel of one level contains too much geometry and must be
subdivided by a subvoxel on a lower level. It has an effect only
if the acceleration algorithm is BSP.
- space_max_size
Controls the allowed complexity of a BSP voxel before the voxel
must be subdivided. It has an effect only if the acceleration
algorithm is BSP. If the space_max_depth limit was
reached, mental ray may exceed space_max_size.
- space_max_mem
Limits the memory used by the BSP tree to the specified number
of megabytes. This is mostly an emergency brake because it may
result in an unbalanced BSP tree.
Global illumination options in the state- >options
structure:
- photon_reflection_depth
The maximal allowed number of recursive
photon reflections. Similar to reflection_depth. Default
is 5.
- photon_refraction_depth
The maximal allowed number of photon refractions. Similar to
refraction_depth. Default is 5.
- photon_trace_depth
The maximal summed photon trace depth. The maximum number of
photon bounces is limited by this number. Default is 5.
- photonmap_file
The name of the file where photon maps will be loaded and
stored. This is a tag; the actual string can be accessed with
mi_db_access.
- finalgather_file
The name of the file where final gathering point maps will
be loaded and stored. Note that unlike photon maps, final gather
maps can be extended, and will grow over time unless periodically
deleted.
- photonmap_rebuild
If set, the photon map file, if specified, will not be loaded,
and the photon map is rebuilt from scratch. It will still be
written if photonmap_file is defined.
- finalgather_rebuild
If set, the final gather map file, if specified, will not be
loaded, and the final gather map is rebuilt from scratch. It
will still be written if finalgather_file is defined.
- caustic
Specifies whether caustics are being simulated or not.
- caustic_accuracy
The maximum number of photons to use when computing a caustic
irradiance estimate.
- caustic_radius
The radius around the current point in which the caustic
irradiance estimate will look for photons.
- caustic_filter_const
The filter constant for caustic estimates within the caustic
radius.
- caustic_filter
The type of filter to apply to the photons within the caustic
radius: 'b' for box, 'c' for cone, or 'g' for Gaussian.
- caustic_flag
If bits 0 or 1 is set, all instances in the scene DAG will
behave as if they had bit 0 or 1, respectively, set as well.
Bit 0 enables photon casting and bit 1 enables photon
reception. This is useful to make all objects in the scene
contribute to photon tracing, if the scene was built without
photon flags. Older scene creators may not know about these
instance flags and leave them undefined.
- globillum
Specifies whether global illumination is being simulated
or not.
- globillum_accuracy
The maximum number of photons to use when computing a global
illumination irradiance estimate.
- globillum_radius
The radius around the current point in which the global
illumination irradiance estimate will look for photons.
- globillum_flag
The same as caustic_flag, except that it applies to
global illumination, not caustics.
- photonvol_accuracy
The maximum number of photons to use when computing a volume
global illumination irradiance estimate.
- photonvol_radius
The radius around the current point in which the volume global
illumination irradiance estimate will look for photons.
- finalgather
Specifies whether illumination is computed with final
gathering. Final gathering can be combined with global
illumination and caustics.
- finalgather_rays
The number of rays cast for each final gather point.
mental ray 2.1 always casts exactly this number, while
mental ray 3.x have an adaptive optimizer that may decide to
cast fewer rays than this number, but will never exceed it.
- finalgather_maxradius
The maximum distance between final gather points. If a final
gathering estimate is needed and no final gather point is
within this radius, a new final gather point is computed.
- finalgather_minradius
The minimum distance between final gather points. Final gather
points will be avoided if they would be closer than this to
another final gather point.
- finalgather_view3.x
If set, this flag switches final gather radii to raster pixels
instead of world space units. This causes final gathering to
be view-dependent:
distant objects will receive fewer final gather points than
close objects.
- n_motion_vectors3.1
Specifies the number of segments to be used for motion paths
that approximate transformation motion.
The default is 1; the maximum number is 15. Larger numbers
allow transform motion paths that are more smoothly curved,
but also reduce performance.
The following table describes which state variables are available in
which types of shaders:
G |
geometry shader |
D |
displacement shader |
P |
photon shader and photon volume shader |
E |
photon emitter shader |
Le |
lens shader |
M |
material shader and texture shader |
V |
volume shader |
Lg |
light shader |
S |
shadow shader |
Cs |
contour store shader |
C |
contour contrast shader and contour shader |
Lm |
lightmap shader |
O |
output shader |
IE |
shader init or exit function |
As an exception, a shader instance init function may use all the state
variables that the shader itself may used. This does not apply to
shader init functions, shader exit functions, and shader instance exit
functions, all of which have only very limited access.
In the following table,
- r
means that the shader may read this variable but should not
modify it because it may have unknown effects on parent or
child shaders.
- R
means that the shader may read this variable but may never
modify it because shader interface functions or other parts
of mental ray depend on unchanged values.
- rw
means that the shader may read or write this variable; if it
writes it is good practice to restore the original contents
before returning to avoid surprises in parent or volume shaders.
pri, in particular, must be restored. Most shaders
do not need to modify most of these.
- x
means that the shader is free to read and write, and need not
restore any values. These are ``scratchpad'' variables for
shader communication, and not used by mental ray.
- -
means that the shader may neither read nor write this field.
Its contents are undefined.
In the case of the options and camera variables, the shader
may write neither the pointer nor any field of the options and camera
structures. Note that during rendering (between the rendering and
rendering finished messages), the camera and the options may
differ from the scene file specifications because phenomenon
requirements and conflict detection may make adjustments. For example,
a lens shader might have requested ray tracing to be turned off even
though it was turned on in the scene file. In this case, shaders
called during rendering would see a trace flag that is off, and
other shaders such as geometry or displacement shaders do not.
variable |
G |
D |
P |
E |
Le |
M |
V |
Lg |
S |
Cs |
C |
O |
Lm |
IE |
version |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
camera_inst |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
camera |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
options |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
global_lock1 |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
raster_x |
- |
- |
- |
- |
R |
R |
R |
R |
R |
R |
- |
- |
- |
- |
raster_y |
- |
- |
- |
- |
R |
R |
R |
R |
R |
R |
- |
R |
- |
- |
parent |
- |
- |
R |
R |
R |
R |
R |
R |
R |
R |
- |
- |
- |
- |
type |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
- |
R |
- |
- |
scanline |
- |
- |
- |
- |
r |
r |
r |
r |
r |
r |
- |
- |
- |
- |
inv_normal |
- |
- |
r |
- |
r |
r |
r |
r |
- |
r |
- |
- |
- |
- |
variable |
G |
D |
P |
E |
Le |
M |
V |
Lg |
S |
Cs |
C |
O |
Lm |
IE |
reflection_level |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
refraction_level |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
face |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
r- |
- |
- |
- |
- |
org |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
dir |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
rw |
- |
- |
- |
- |
dist |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
R |
- |
- |
time |
- |
- |
R |
R |
R |
R |
R |
R |
R |
R |
- |
- |
- |
- |
ior |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
- |
- |
ior_in |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
- |
- |
material |
- |
r |
r |
r |
- |
r |
r |
r |
r |
r |
- |
- |
- |
- |
volume |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
environment |
- |
- |
- |
- |
rw |
rw |
rw |
- |
- |
rw |
- |
- |
- |
- |
refraction_volume |
- |
- |
rw |
rw |
- |
rw |
rw |
- |
- |
rw |
- |
- |
- |
- |
label |
- |
r |
r |
r |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
R |
- |
instance |
R |
R |
R |
- |
R |
R |
R |
R |
R |
R |
- |
- |
R |
- |
light_instance |
- |
- |
- |
R |
- |
- |
R2 |
R |
R |
- |
- |
- |
- |
- |
pri3 |
- |
- |
r |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
pri_idx |
- |
- |
r |
- |
r |
r |
r |
r |
r |
r |
- |
- |
- |
- |
variable |
G |
D |
P |
E |
Le |
M |
V |
Lg |
S |
Cs |
C |
O |
Lm |
IE |
bary[4] |
- |
- |
r |
- |
r |
r |
r |
r |
r |
r |
- |
- |
- |
- |
point |
- |
r |
r |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
normal |
- |
r |
r |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
normal_geom |
- |
- |
r |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
dot_nd |
- |
- |
r |
- |
rw |
rw |
rw |
rw |
- |
rw |
- |
- |
- |
- |
shadow_tol |
- |
- |
r |
- |
r |
r |
r |
r |
r |
r |
r |
- |
- |
- |
tex_list |
- |
rw |
rw |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
bump_x_list |
- |
- |
rw |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
bump_y_list |
- |
- |
rw |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
motion |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
derivs4 |
- |
- |
rw |
- |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
- |
- |
tex |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
- |
- |
shader |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
child |
- |
- |
R |
R |
R |
R |
R |
R |
R |
R |
- |
- |
- |
- |
thread |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
count3.1 |
- |
- |
- |
- |
- |
- |
- |
rw |
- |
- |
- |
- |
- |
- |
user |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
user_size |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
x |
|
1 |
global_lock is accessed with mi_lock and
mi_unlock only. |
|
2 |
If state - > type is miRAY_SHADOW |
|
3 |
Set to 0 to cast rays from empty space. Do not set to other values. |
|
4 |
If the object contains surface derivatives |
See page
for a similar table listing available shader
interface functions.
Next: 3.5 Shader Parameter Declarations
Up: 3. Using and Writing
Previous: 3.3 Shader Type Overview
Copyright 2002 by mental images