rayQueryGetIntersectionObjectToWorldEXT in GLSL

This article explains how the rayQueryGetIntersectionObjectToWorldEXT function retrieves the active instance transform matrix during hardware-accelerated ray tracing in GLSL. It details the underlying two-level acceleration structure (TLAS and BLAS), the internal tracking of ray traversal state, and the extraction and formatting of the 3x4 affine transformation matrix from instance metadata into GLSL's mat4x3 representation.

The function rayQueryGetIntersectionObjectToWorldEXT is provided by the GL_EXT_ray_query extension. Its GLSL signature is:

mat4x3 rayQueryGetIntersectionObjectToWorldEXT(rayQueryEXT rayQuery, bool committed);

To extract the matrix, the ray-tracing pipeline relies on a two-level acceleration structure hierarchy. The bottom-level acceleration structure (BLAS) contains geometry defined in local object space. The top-level acceleration structure (TLAS) aggregates multiple BLAS instances to build the overall scene in world space. In Vulkan, each instance registered in a TLAS contains an explicit 3x4 affine transformation matrix (VkTransformMatrixKHR) alongside flags and a pointer to the target BLAS.

When a ray query executes, the traversal unit traverses the TLAS. Upon identifying a candidate instance bounding box, the ray descends into the referenced BLAS. During this transition, the traversal hardware uses the instance's 3x4 matrix to transform the ray from world space into object space. Simultaneously, the hardware state associated with the rayQueryEXT object records a reference or copy of this active instance metadata, including its original transformation matrix.

When calling rayQueryGetIntersectionObjectToWorldEXT, the boolean committed parameter specifies which intersection state to read:

  • Setting committed to false instructs the query to read the matrix associated with the current uncommitted candidate intersection during an ongoing traversal loop.
  • Setting committed to true retrieves the matrix associated with the confirmed, closest hit stored once traversal has fully completed.

The underlying hardware inspects the ray query register state corresponding to the specified intersection, locates the active instance entry, and reads its 3x4 affine matrix. Because Vulkan instance transforms are defined as row-major 3x4 arrays (\(3 \times 4\) elements: three rows representing the basis vectors and translation), the intrinsic reconstructs these values into GLSL’s standard column-major mat4x3 format (four columns of vec3). The first three columns represent the transformed rotation, scale, and shear axes, while the fourth column represents the world-space translation vector.