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: used by rays cast by mi_trace_probe.
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. For area lights, it is the point on the virtual surface. If the light source does not have an origin, the value 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. Volume shaders are also applied to light rays. This state variable is ignored in autovolume mode.

Note The mi_trace_refraction and mi_trace_refraction functions copy refraction_volume to volume to ensure that sub-shaders use the volume shader that applies to the interior of the object.

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 can be changed by shaders before casting a secondary ray with functions such as mi_trace_reflection. The secondary ray will then obey the changed face flag. The field will be initialized to 0 by mental ray, in which case the face setting from the scene description will take precedence, like render option and face flags on objects and instances. Setting this value to 'f' (front), 'b' (back), or 'a' (both) will overwrite that default value.