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 importance3.6 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 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.

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

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

normal_geom

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.

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 3.2 and later construct 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: 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.

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. The mi_mtl_refraction_index shader interface function stores the index of refraction of the medium the ray travels through in this state variable.

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

importance3.6

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.

Copyright © 1986-2008 by mental images GmbH