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
`miTag`	`material`	material of hit primitive
`void *`	`pri`	completely identifies the hit primitive
`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
`miScalar`	`importance`	importance of the current ray

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_refraction 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 autovolume mode.

label

The label of the hit object. Every object may contain a label identifier, which is an arbitrary 32bit integer number. That value 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 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 leaf 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. This is the leaf instance resulting from preprocessing and multiple instancing resolution (see mi_inclusive_lightlist).

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.

For hair, which is not based on triangles, the barycentric coordinates have a different meaning:

bary[0]: contains the parameter value along the width of the hair, with 0 at the left edge and 1 at the right edge, with respect to the direction going from the root of the hair to the tip, and lying in the plane perpendicular to the ray direction.
bary[1]: contains the parameter value along the length of the hair, with 0 at the first vertex defined, and 1 at the last.

normal

The interpolated surface normal at the intersection point if vertex normals are present, or the non-interpolated 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 a single-precision float value. 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 value has only a little over six significant digits. This can cause math functions like acos (arc cosine) to return NaN (Not a Number, an illegal result), which usually results in white pixels or black pixels in the output image if the NaN finds its way into a result color.

For hair, this is the interpolated normal facing in the ray direction.

normal_geom

The non-interpolated 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.

For hair, this is the tangent of the first segment of the hair. This is an approximation to the normal at the scalp, and can be useful for certain shading models.

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. This does not happen in shadow shaders, where dot_nd is undefined.

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. In a volume shader, dot_nd is undefined because there is no surface normal; however, mental ray constructs an artificial surface point to return a useful dot_nd value.

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 primitive hit. 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.

Note, that in mental ray 3.5 and earlier versions, the pri has only identified the object, and pri_idx was used to identify the primitive index. The pri_idx is not available any more. In order to identify the primitive index, the mi_query mode miQ_PRI_INDEX can be used.

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.

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, the ior_in field is neither set nor used by mental ray. It exists to allow material shaders to inherit the previous index of refraction to subsequent shaders.

importance

This field contains a factor that controls how much the current ray is likely to contribute to the final image. The field is used by functions like mi_compute_irradiance to distribute and track computational efforts properly.