Keywords: main

Next: 3.5 Shader Parameter Declarations Up: 3. Using and Writing Previous: 3.3 Shader Type Overview
Subsections

- 3.4.1 Frame
- 3.4.2 Image Samples
- 3.4.3 Rays
- 3.4.4 Intersection
- 3.4.5 Textures, Motion, Derivatives
- 3.4.6 User Fields
- 3.4.7 Options
- 3.4.8 State Variables by Shader Type

# 3.4 State Variables

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:

## 3.4.1 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` | `userdata`3.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 .

## 3.4.2 Image Samples

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.

## 3.4.3 Rays

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_OUTPUT`3.x is set for output shaders.

- `miRAY_FINALGATHER`3.x is set for finalgather rays originating at the final gather point.

- `miRAY_LM_VERTEX`3.x is set for lightmap shaders in vertex scan mode.

- `miRAY_LM_MESH`3.x is set for lightmap shaders in mesh output mode.

- `miRAY_PROBE`3.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_ABSORB`3.x is a photon being absorbed.

- `miPHOTON_SCATTER_VOLUME`3.x is a photon scattered in a volume.

- `miPHOTON_EMIT_CAUSTIC`3.x is a caustics photon to be cast by a photon emitter shader attached to a light source.

- `miPHOTON_EMIT_GLOBILLUM`3.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.

## 3.4.4 Intersection

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.

## 3.4.5 Textures, Motion, Derivatives

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.

## 3.4.6 User Fields

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.

## 3.4.7 Options

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_density`3.x | density for diagnostic photon mode
`float` | `diag_grid_size` | grid size for diagnostic grid mode
`miBoolean` | `desaturate`3.x | fade to white, no clipping
`miBoolean` | `dither`3.x | enable frame buffer dithering
`miBoolean` | `nopremult`3.x | disable premultiplication
`int` | `colorclip`3.x | color clipping modes
`float` | `gamma`3.x | frame buffer gamma value, 1 for none
`miColor` | `luminance_weight`3.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_delay`3.1 | shutter open time for motion blur
`float` | `shutter` | shutter close time for motion blur
`miCBoolean` | `autovolume`3.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_depth`3.1 | maximum grid nesting
`short` | `grid_max_size`3.1 | maximum grid leaf size
`float` | `grid_max_size`2.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_file`3.x | finalgather map file name
`miBoolean` | `photonmap_rebuild` | rebuild photon map, don't reuse
`miCBoolean` | `finalgather_rebuild`3.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_view`3.x | final gather radii are specified in raster pixels
`miUint1` | `n_motion_vectors`3.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_FG`3.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_COVERAGE`3.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_PPREV`2.1 contains shader bitmaps used for pixel previewing (interactive rendering).

- `miRC_IMAGE_USER`is 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.

## 3.4.8 State Variables by Shader Type

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