rayQueryGetIntersectionInstanceCustomIndexEXT in GLSL

In inline GLSL ray queries via the GL_EXT_ray_query extension, rayQueryGetIntersectionInstanceCustomIndexEXT returns the user-defined custom index of the acceleration structure instance involved in an intersection. This function outputs an unsigned integer (uint) that directly corresponds to the application-provided instance identifier, allowing developers to identify specific objects, materials, or metadata buffers during traversal without executing dedicated ray tracing pipeline hit shaders.

Function Signature

uint rayQueryGetIntersectionInstanceCustomIndexEXT(rayQueryEXT rayQuery, bool committed);

Parameters and Return Value

  • rayQuery: The ray query object tracking the traversal state.
  • committed: A boolean flag determining which intersection to query:
    • true: Returns the custom index for the currently committed intersection (the closest confirmed hit so far).
    • false: Returns the custom index for the current candidate intersection being processed (such as during custom intersection handling or an any-hit scenario).
  • Return Value (uint): A 24-bit unsigned integer representing the instance's custom index.

Host-Side Relationship

The value returned by this function is defined when building the top-level acceleration structure (TLAS) on the host API:

  • In Vulkan, it corresponds to the 24-bit instanceCustomIndex field inside the VkAccelerationStructureInstanceKHR structure.
  • In Direct3D 12, it corresponds to the InstanceID field in D3D12_RAYTRACING_INSTANCE_DESC (equivalent to HLSL's InstanceID()).

Common Use Cases

Because inline ray queries execute within standard compute, fragment, or vertex stages rather than a full ray tracing pipeline, hit groups cannot be invoked automatically. rayQueryGetIntersectionInstanceCustomIndexEXT bridges this gap by enabling:

  • Bindless Material Indexing: Storing an index directly into a global buffer array to look up textures, PBR parameters, and vertex data for the intersected object.
  • Object Identification: Determining whether an intersected surface belongs to a dynamic or static mesh, opaque geometry, or a specific gameplay entity.
  • Shadow and Ambient Occlusion Filtering: Differentiating between instances that should cast shadows or contribute to ambient occlusion calculations.