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.

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
is set for output shaders.
miRAY_FINALGATHER
is set for finalgather rays originating at the final gather point.
miRAY_LM_VERTEX
is set for lightmap shader in vertex scan mode.
miRAY_LM_MESH
is set for lightmap shader in mesh output mode.
miRAY_PROBE
is used by rays cast by mi_trace_probe in mental ray 3.1 or later. 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
is a photon being absorbed.
miPHOTON_SCATTER_VOLUME
is a photon scattered in a volume.
miPHOTON_EMIT_CAUSTIC
is a caustics photon to be cast by a photon emitter shader attached to a light source.
miPHOTON_EMIT_GLOBILLUM
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:

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 rendering algorithm.

cache

Deprecated 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 delay value), the time is fixed at the shutter value. Otherwise, it is systematically sampled in the range from the shutter delay 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_refraction 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 autovolume 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. In mental ray 3.4 and later, it will be initialized to 0 by mental ray, so shaders can overwrite it but not read the default value.