Module vulkano::acceleration_structure

source ·
Expand description

An opaque data structure that is used to accelerate spatial queries on geometry data.

Acceleration structures contain geometry data, arranged in such a way that the device can easily search through the data and check for intersections between the geometry and rays (lines). The geometry data can consist of either triangles, or axis-aligned bounding boxes (AABBs).

Acceleration structures come in two forms: top-level and bottom-level. A bottom-level acceleration structure holds the actual geometry data, while a top-level structure contains instances of (references to) one or more bottom-level structures. A top-level structure is intended to contain the whole rendered scene (or the relevant parts of it), while a bottom-level structure may contain individual objects within the scene. This two-level arrangement allows you to easily rearrange the scene, adding and removing parts of it as needed.

Building an acceleration structure

When an acceleration structure object is created, it is in an uninitialized state and contains garbage data. To be able to use it for anything, you must first build the structure on the device, using the build_acceleration_structure or build_acceleration_structure_indirect command buffer commands. You use BuildAccelerationStructureMode::Build to build a structure from scratch.

When specifying geometry data for an acceleration structure build, certain triangle, AABB or instance values mark that item as inactive. An inactive item is completely ignored within the acceleration structure, and acts as if it’s not there. The following special values make an item inactive:

Updating an acceleration structure

Once an acceleration structure is built, if it was built previously with the BuildAccelerationStructureFlags::ALLOW_UPDATE flag, then it is possible to update the structure with new data. You use BuildAccelerationStructureMode::Update for this, which specifies the source acceleration structure to use as a starting point for the update. This can be the same as the destination structure (the update will happen in-place), or a different one.

An update operation is limited in which parts of the data it may change. You may change most buffers and their contents, as well as strides and offsets:

No other values may be changed, including in particular the variant or number of elements in AccelerationStructureBuildGeometryInfo::geometries, and the value of AccelerationStructureBuildRangeInfo::primitive_count. The enum variants and data in AccelerationStructureGeometryTrianglesData::index_data must not be changed, but it is allowed to specify a new index buffer, as long as it contains the exact same indices as the old one.

An update operation may not change the inactive status of an item: active items must remain active in the update and inactive items must remain inactive.

Accessing an acceleration structure in a shader

Acceleration structures can be bound to and accessed in any shader type. They are accessed as descriptors, like buffers and images, and are declared in GLSL with

layout (set = N, binding = N) uniform accelerationStructureEXT nameOfTheVariable;

You must enable either the GL_EXT_ray_query or the GL_EXT_ray_tracing GLSL extensions in the shader to use this.

On the Vulkano side, you can then create a descriptor set layout using DescriptorType::AccelerationStructure as a descriptor type, and write the acceleration structure to a descriptor set using WriteDescriptorSet::acceleration_structure.

Structs

Enums

Type Aliases