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`3.6	importance of the current ray

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.

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.

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).

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.

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.

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.

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.

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.

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 3.2 and later construct an artificial surface point to return a useful dot_nd value.

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.

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.

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: 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. pri_idx is removed in mental ray 3.6. In order to identify the primitive index, the mi_query mode miQ_PRI_INDEX3.6 can be used.

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.

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.

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.

This field contains a factor with each current ray is likely to contribute to the final image. The field is used by functions like mi_compute_irradiance in order to distribute computational efforts properly.