rayQueryGetIntersectionGeometryIndexEXT in GLSL

This article provides a concise guide to the rayQueryGetIntersectionGeometryIndexEXT function in GLSL ray queries, explaining the specific data it returns and how it fits into the Vulkan ray tracing pipeline. By reading this guide, you will understand how to identify which geometry inside a bottom-level acceleration structure (BLAS) was hit by a ray and how to use this index to access corresponding mesh data and material attributes.

What the Function Returns

In GLSL, rayQueryGetIntersectionGeometryIndexEXT returns an integer (int) that represents the zero-based index of the geometry within a bottom-level acceleration structure (BLAS) where the intersection occurred.

When constructing a BLAS in Vulkan, developers often pass an array of VkAccelerationStructureGeometryKHR structures representing multiple meshes or sub-meshes (such as individual parts of a composite 3D model). The geometry index corresponds directly to the position of the hit geometry within that array:

  • 0: The first geometry defined in the BLAS.
  • 1: The second geometry defined in the BLAS, and so on.

Syntax and Parameters

The function signature is defined as follows:

int rayQueryGetIntersectionGeometryIndexEXT(rayQueryEXT rayQuery, bool committed);
  • rayQuery: The active ray query object being processed.
  • committed: A boolean flag determining which intersection state to query. Passing true queries the currently committed (confirmed closest or final) intersection, while passing false queries the current candidate (provisional) intersection during traversal.

Role in the Ray Tracing Hierarchy

To properly access per-primitive data, ray queries provide a three-tiered hierarchy of identifiers:

  1. Instance Index / Custom Index: Identifies the specific instance of a BLAS placed within the top-level acceleration structure (TLAS), retrieved using rayQueryGetIntersectionInstanceCustomIndexEXT or rayQueryGetIntersectionInstanceIdEXT.
  2. Geometry Index: Identifies the specific sub-mesh or geometry within that BLAS, retrieved via rayQueryGetIntersectionGeometryIndexEXT.
  3. Primitive Index: Identifies the specific triangle or procedural primitive within that geometry, retrieved via rayQueryGetIntersectionPrimitiveIndexEXT.

Practical Use Cases

Knowing the geometry index is essential when a single BLAS contains multiple distinct surfaces. Common use cases include:

  • Material Retrieval: Mapping the hit surface to a specific material ID or descriptor offset when sub-meshes share a single BLAS but have different textures or shading properties.
  • Vertex and Index Buffer Access: Selecting the correct buffer addresses or offsets from a buffer device address table to fetch the triangle vertices for normal and UV interpolation.
  • Hit Masking and Filtering: Executing conditional logic during candidate intersection handling based on the type or category of geometry encountered.