reportIntersectionEXT in GLSL Intersection Shaders

In Vulkan ray tracing pipelines, the reportIntersectionEXT function serves as the bridge between custom procedural geometry intersection logic and the core ray traversal hardware. Used exclusively within GLSL intersection shaders, its primary purpose is to report a valid ray-primitive hit back to the ray tracing pipeline, providing the hit distance along the ray and a custom hit classification identifier.

Why the Function Is Needed

While standard ray tracing hardware automatically handles intersections for triangle meshes, custom geometries—such as spheres, analytical bounding volumes, capsules, or signed distance fields (SDFs)—require custom intersection algorithms.

When a ray intersects the bounding box of a procedural primitive, the intersection shader is invoked. The shader performs mathematical tests to determine if and where the ray intersects the surface. Once a valid intersection is found, the shader must explicitly notify the traversal engine. That notification is executed using reportIntersectionEXT.

Function Signature and Parameters

The function signature is defined as:

bool reportIntersectionEXT(float hitT, uint hitKind);
  • hitT: A floating-point value representing the parametric distance along the ray where the intersection occurred (\(P(t) = O + t \cdot D\)). This value must lie within the current ray interval defined by gl_RayTminEXT and gl_RayTmaxEXT.
  • hitKind: An unsigned 8-bit integer (values 0 to 127 are typically user-defined, while values 128 to 255 are reserved for built-in behavior). This identifier is passed along the pipeline and can be queried in subsequent any-hit and closest-hit shaders using the gl_HitKindEXT built-in variable to distinguish between different types of surfaces or intersection events.

Return Value and Pipeline Behavior

The reportIntersectionEXT function returns a boolean value indicating whether the reported intersection was accepted or rejected by the traversal engine:

  • Returns true: The intersection is within the valid range and was accepted. If an any-hit shader is bound, it is invoked immediately to evaluate the hit. If the any-hit shader does not call ignoreIntersectionEXT(), the current maximum ray range (gl_RayTmaxEXT) shrinks to hitT, ensuring that future tests only search for closer intersections.
  • Returns false: The intersection was rejected. This occurs if hitT falls outside the current [gl_RayTminEXT, gl_RayTmaxEXT] bounds, if the any-hit shader rejected the hit via ignoreIntersectionEXT(), or if the ray traversal was terminated early.

Handling Multiple Intersections

If a ray intersects a procedural object at multiple locations (such as the entry and exit points of a sphere), the intersection shader can calculate both points and call reportIntersectionEXT multiple times. Reporting the closer hit first is standard practice, as an accepted hit immediately contracts gl_RayTmaxEXT, allowing the pipeline to discard any subsequent potential hits that are farther away.