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

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 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.
The leaf instance of the object containing the primitive hit by the ray.
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:
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.
contains the parameter value along the length of the hair, with 0 at the first vertex defined, and 1 at the last.
The intersection (end point) of the ray in internal space. In material shaders, but also in light and shadow shaders, it is the point on the current geometric surface. In volume shaders, it is the end point of the volume segment, or undefined of the ray has unlimited length.
In displacement shaders, the point is given in object space.
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.
In displacement shaders, the normal is given in object space.
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.
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 constructs 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, 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.
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.
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.
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.

Copyright © 1986-2011 by mental images GmbH