Understanding accelerationStructureEXT in GLSL

This article explains how the accelerationStructureEXT uniform type exposes top-level acceleration structures (TLAS) within GLSL for Vulkan ray tracing. It covers the definition and declaration of the uniform type, its connection to the Vulkan API through descriptor bindings, and how it is utilized within shader stages to execute hardware-accelerated ray traversal across scene geometry.

The Role of the Top-Level Acceleration Structure

Hardware-accelerated ray tracing in Vulkan utilizes a two-level hierarchy of acceleration structures: Bottom-Level Acceleration Structures (BLAS), which contain actual geometric primitives like triangles, and Top-Level Acceleration Structures (TLAS), which contain instances of these BLAS with associated transformation matrices. To query this hierarchy in shaders, GLSL requires an abstract representation of the entire scene graph. The accelerationStructureEXT uniform type fulfills this role by providing a handle directly to the TLAS.

Enabling the Extension and Declaring the Uniform

To use the accelerationStructureEXT type in GLSL, the ray tracing extension must first be enabled in the shader preamble:

#version 460
#extension GL_EXT_ray_tracing : require

Once enabled, the TLAS is declared as an opaque uniform variable using standard descriptor set and binding layouts:

layout(set = 0, binding = 0) uniform accelerationStructureEXT topLevelAS;

Like textures or samplers, accelerationStructureEXT is an opaque type. It cannot be instantiated, modified, or mathematically manipulated directly within shader code. Instead, it functions purely as an input handle to ray traversal operations.

CPU-Side Descriptor Binding

In the host application (Vulkan), this uniform corresponds to the descriptor type VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR.

The connection between the GLSL uniform and the physical GPU memory occurs through descriptor writes. The host application populates a VkWriteDescriptorSetAccelerationStructureKHR structure with the VkAccelerationStructureKHR handle created for the TLAS, chaining it to a standard VkWriteDescriptorSet via the pNext pointer. During pipeline execution, the driver resolves the opaque uniform in the shader to the 64-bit GPU device address where the TLAS data resides.

Utilizing the Uniform in Shaders

The accelerationStructureEXT handle is passed directly into built-in ray-traversal functions depending on whether a full ray tracing pipeline or inline ray queries are being used.

In Ray Tracing Pipelines (Ray Generation, Closest Hit)

In dedicated ray tracing stages, the TLAS is passed as the first parameter to the traceRayEXT function:

traceRayEXT(
    topLevelAS,           // Acceleration structure handle
    rayFlags,             // Ray flags (e.g., gl_RayFlagsOpaqueEXT)
    cullMask,             // 8-bit instance inclusion mask
    sbtRecordOffset,      // Shader binding table offset
    sbtRecordStride,      // Shader binding table stride
    missIndex,            // Miss shader index
    origin,               // Ray origin (vec3)
    tMin,                 // Minimum ray distance
    direction,            // Ray direction (vec3)
    tMax,                 // Maximum ray distance
    payloadLocation       // Ray payload location identifier
);

In Ray Queries (Compute, Fragment, or Vertex Shaders)

When using inline ray queries via GL_EXT_ray_query, the uniform initializes the query object:

rayQueryEXT rayQuery;
rayQueryInitializeEXT(rayQuery, topLevelAS, rayFlags, cullMask, origin, tMin, direction, tMax);

Internal Execution

When traceRayEXT or rayQueryInitializeEXT is invoked with an accelerationStructureEXT argument, the shader compiler translates the handle into internal SPIR-V instructions (OpTypeAccelerationStructureKHR). At execution time, the GPU’s fixed-function ray tracing hardware or driver-implemented compute loops use the address behind this handle to walk the bounding volume hierarchy (BVH) nodes of the TLAS, transform incoming rays into instance-local space, and test for intersections against the referenced BLAS geometry.