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.
It is recommended to call the state parameter that shaders receive
as a formal parameter state because some macros provided in the
mi_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 mi_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 below. 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 |
miRc_options * |
options |
general rendering options |
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 |
x_offset2.1 |
x offset of image in pixels |
float |
y_offset2.1 |
y offset of image in pixels |
The option data structure pointed to by option has the following
format. The option structure may not be written to by shaders.
type |
name |
content |
miBoolean |
trace |
ray tracing turned on? |
miBoolean |
scanline |
scanline mode turned on? |
miBoolean |
motion |
motion blur turned on? |
char |
shadow |
no, normal, segmented, sorted |
char |
filter |
nonlocal sampling filter |
char |
acceleration |
ray tracing algorithm |
char |
face |
front, back, or both faces |
char |
field |
odd or even fields, or off |
int |
reflection_depth |
max reflection trace depth |
int |
refraction_depth |
max refraction trace depth |
int |
trace_depth |
max combined trace depth |
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 |
miBoolean |
samplelock |
noise animation locking on/off |
miBoolean |
caustic |
caustics on/off |
miBoolean |
globillum2.1 |
global illumination on/off |
miBoolean |
finalgather2.1 |
final gather on/off |
miPointer |
image [ ] |
frame buffers for output shaders |
- 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 following parameters are in the state- >camera structure:
- 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.
- 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_offset2.1 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_offset2.1 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.
The following parameters are 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.
- 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).
- 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.
- acceleration
The ray tracing algorithm. This is either 'c' (an algorithm
based on ray classification), or 'b' (a BSP algorithm), or
'g' (a hierarchical uniform grid algorithm). The latter two
are often, but by no means always, faster. Note that by default,
primary rays are computed using a scanline algorithm if possible.
- 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.
- 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.
- 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.
- caustic
Specifies whether caustics are being simulated or not.
- globillum2.1 Specifies whether global illumination is being simulated or not.
- finalgather2.1 Specifies whether illumination is computed with final
gathering. Final gathering can be combined with global illumination
and caustics.
- samplelock
Whether to let the sampling of area light sources, motion blur, and
depht-of-field be static or depend on the frame number.
The default is on, meaning static sampling.
- 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 miRC_IMAGE_RGBA, miRC_IMAGE_Z, miRC_IMAGE_N, miRC_IMAGE_M, and miRC_IMAGE_TAG,
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.
-
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.
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 mode2.1because
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.
- 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_localvpu.
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 |
- 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:
=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_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_TRANSPARENT
is a photon transmitted directly (ie., without refraction)
through a surface.
- The ray type (state->type) can be queried using 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, the time is always 0. Otherwise, it is systematically
sampled in the range from 0 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.
- 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.
- 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 reflection level to circumvent the restrictions imposed by
the trace depth state variables.
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 |
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 r. 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.
- 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 negative 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
shaders2.1.
- 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.
- 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
x/
u,
x/
v,
x/
u2,
x/
v2,
x/
u
v, 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
x/
u,
x/
v 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 state - > shader - > user.p 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 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 |
|
T texture shader |
|
V volume shader |
|
Lg light shader |
|
S shadow shader |
|
Cs contour store shader |
|
C contour contrast shader and contour shader |
|
O output shader |
|
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 |
version |
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 |
camera |
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 |
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 |
reflection_level |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
refraction_level |
- |
- |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
rw |
- |
- |
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 |
- |
- |
instance |
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 |
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 |
child |
- |
- |
R |
R |
R |
R |
R |
R |
R |
R |
- |
- |
thread |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
R |
user |
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 |
|
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 2000 by mental images