36. Acceleration Structures

36.1. Acceleration Structures

Acceleration structures are data structures used by the implementation to efficiently manage scene geometry as it is traversed during a ray tracing query. The application is responsible for managing acceleration structure objects (see Acceleration Structures), including allocation, destruction, executing builds or updates, and synchronizing resources used during ray tracing queries.

There are two types of acceleration structures, top level acceleration structures and bottom level acceleration structures.

image/svg+xml Top-Level Acceleration Structure Bottom-LevelAccelerationStructure Bottom-LevelAccelerationStructure Transformand shadinginformation Transformand shadinginformation Transformand shadinginformation
Figure 24. Acceleration Structure
Caption

The diagram shows the relationship between top and bottom level acceleration structures.

36.1.1. Geometry

Geometries refer to a triangle or axis-aligned bounding box.

36.1.2. Top Level Acceleration Structures

Opaque acceleration structure for an array of instances. The descriptor or device address referencing this is the starting point for traversal.

The top level acceleration structure takes a reference to any bottom level acceleration structure referenced by its instances. Those bottom level acceleration structure objects must be valid when the top level acceleration structure is accessed.

36.1.3. Bottom Level Acceleration Structures

Opaque acceleration structure for an array of geometries.

36.1.4. Acceleration Structure Update Rules

The API defines two types of operations to produce acceleration structures from geometry:

  • A build operation is used to construct an acceleration structure.

  • An update operation is used to modify an existing acceleration structure.

An update operation imposes certain constraints on the input, in exchange for considerably faster execution. When performing an update, the application is required to provide a full description of the acceleration structure, but is prohibited from changing anything other than instance definitions, transform matrices, and vertex or AABB positions. All other aspects of the description must exactly match the one from the original build.

More precisely, the application must not use an update operation to do any of the following:

  • Change primitives or instances from active to inactive (as defined in Inactive Primitives and Instances).

  • Change the index or vertex formats of triangle geometry.

  • Change triangle geometry transform pointers from null to non-null or vice versa.

  • Change the number of geometries or instances in the structure.

  • Change the geometry flags for any geometry in the structure.

  • Change the number of vertices or primitives for any geometry in the structure.

36.1.5. Inactive Primitives and Instances

Acceleration structures allow the use of particular input values to signal inactive primitives or instances.

An inactive triangle is one for which the first (X) component of each vertex is NaN. If any other vertex component is NaN, and the first is not, the behavior is undefined. If the vertex format does not have a NaN representation, then all triangles are considered active.

An inactive instance is one whose acceleration structure handle is VK_NULL_HANDLE.

An inactive AABB is one for which the minimum X coordinate is NaN. If any other component is NaN, and the first is not, the behavior is undefined.

In the above definitions, "NaN" refers to any type of NaN. Signaling, non-signaling, quiet, loud, or otherwise.

An inactive object is considered invisible to all rays, and should not be represented in the acceleration structure. Implementations should ensure that the presence of inactive objects does not seriously degrade traversal performance.

Inactive objects are counted in the auto-generated index sequences which are provided to shaders via InstanceId and PrimitiveId SPIR-V decorations. This allows objects in the scene to change freely between the active and inactive states, without affecting the layout of any arrays which are being indexed using the ID values.

Any transition between the active and inactive states requires a full acceleration structure rebuild. Applications must not perform an acceleration structure update where an object is active in the source acceleration structure but would be inactive in the destination, or vice versa.

36.1.6. Building Acceleration Structures

To build an acceleration structure call:

// Provided by VK_NV_ray_tracing
void vkCmdBuildAccelerationStructureNV(
    VkCommandBuffer                             commandBuffer,
    const VkAccelerationStructureInfoNV*        pInfo,
    VkBuffer                                    instanceData,
    VkDeviceSize                                instanceOffset,
    VkBool32                                    update,
    VkAccelerationStructureNV                   dst,
    VkAccelerationStructureNV                   src,
    VkBuffer                                    scratch,
    VkDeviceSize                                scratchOffset);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pInfo contains the shared information for the acceleration structure’s structure.

  • instanceData is the buffer containing an array of VkAccelerationStructureInstanceKHR structures defining acceleration structures. This parameter must be NULL for bottom level acceleration structures.

  • instanceOffset is the offset in bytes (relative to the start of instanceData) at which the instance data is located.

  • update specifies whether to update the dst acceleration structure with the data in src.

  • dst is a pointer to the target acceleration structure for the build.

  • src is a pointer to an existing acceleration structure that is to be used to update the dst acceleration structure.

  • scratch is the VkBuffer that will be used as scratch memory for the build.

  • scratchOffset is the offset in bytes relative to the start of scratch that will be used as a scratch memory.

Accesses to dst, src, and scratch must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCmdBuildAccelerationStructureNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBuildAccelerationStructureNV-pInfo-parameter
    pInfo must be a valid pointer to a valid VkAccelerationStructureInfoNV structure

  • VUID-vkCmdBuildAccelerationStructureNV-instanceData-parameter
    If instanceData is not VK_NULL_HANDLE, instanceData must be a valid VkBuffer handle

  • VUID-vkCmdBuildAccelerationStructureNV-dst-parameter
    dst must be a valid VkAccelerationStructureNV handle

  • VUID-vkCmdBuildAccelerationStructureNV-src-parameter
    If src is not VK_NULL_HANDLE, src must be a valid VkAccelerationStructureNV handle

  • VUID-vkCmdBuildAccelerationStructureNV-scratch-parameter
    scratch must be a valid VkBuffer handle

  • VUID-vkCmdBuildAccelerationStructureNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBuildAccelerationStructureNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBuildAccelerationStructureNV-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBuildAccelerationStructureNV-commonparent
    Each of commandBuffer, dst, instanceData, scratch, and src that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

To build acceleration structures call:

// Provided by VK_KHR_acceleration_structure
void vkCmdBuildAccelerationStructuresKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    infoCount,
    const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
    const VkAccelerationStructureBuildRangeInfoKHR* const* ppBuildRangeInfos);
  • commandBuffer is the command buffer into which the command will be recorded.

  • infoCount is the number of acceleration structures to build. It specifies the number of the pInfos structures and ppBuildRangeInfos pointers that must be provided.

  • pInfos is an array of infoCount VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure.

  • ppBuildRangeInfos is an array of infoCount pointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. Each ppBuildRangeInfos[i] is an array of pInfos[i].geometryCount VkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pInfos[i].

The vkCmdBuildAccelerationStructuresKHR command provides the ability to initiate multiple acceleration structures builds, however there is no ordering or synchronization implied between any of the individual acceleration structure builds.

Note

This means that an application cannot build a top-level acceleration structure in the same vkCmdBuildAccelerationStructuresKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds.

Accesses to the acceleration structure scratch buffers as identified by the VkAccelerationStructureBuildGeometryInfoKHRscratchData buffer device addresses must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR. Similarly for accesses to each VkAccelerationStructureBuildGeometryInfoKHRsrcAccelerationStructure and VkAccelerationStructureBuildGeometryInfoKHRdstAccelerationStructure.

Accesses to other input buffers as identified by any used values of VkAccelerationStructureGeometryTrianglesDataKHRvertexData, VkAccelerationStructureGeometryTrianglesDataKHRindexData, VkAccelerationStructureGeometryTrianglesDataKHRtransformData, VkAccelerationStructureGeometryAabbsDataKHRdata, and VkAccelerationStructureGeometryInstancesDataKHRdata must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_SHADER_READ_BIT.

Valid Usage
  • VUID-vkCmdBuildAccelerationStructuresKHR-mode-04628
    The mode member of each element of pInfos must be a valid VkBuildAccelerationStructureModeKHR value

  • VUID-vkCmdBuildAccelerationStructuresKHR-srcAccelerationStructure-04629
    If the srcAccelerationStructure member of any element of pInfos is not VK_NULL_HANDLE, the srcAccelerationStructure member must be a valid VkAccelerationStructureKHR handle

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-04630
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be VK_NULL_HANDLE

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03403
    The srcAccelerationStructure member of any element of pInfos must not be the same acceleration structure as the dstAccelerationStructure member of any other element of pInfos

  • VUID-vkCmdBuildAccelerationStructuresKHR-dstAccelerationStructure-03698
    The dstAccelerationStructure member of any element of pInfos must not be the same acceleration structure as the dstAccelerationStructure member of any other element of pInfos

  • VUID-vkCmdBuildAccelerationStructuresKHR-dstAccelerationStructure-03800
    The dstAccelerationStructure member of any element of pInfos must be a valid VkAccelerationStructureKHR handle

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03699
    For each element of pInfos, if its type member is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of VkAccelerationStructureCreateInfoKHR::type equal to either VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03700
    For each element of pInfos, if its type member is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of VkAccelerationStructureCreateInfoKHR::type equal to either VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR or VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03663
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, inactive primitives in its srcAccelerationStructure member must not be made active

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03664
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, active primitives in its srcAccelerationStructure member must not be made inactive

  • VUID-vkCmdBuildAccelerationStructuresKHR-None-03407
    The dstAccelerationStructure member of any element of pInfos must not be referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos

  • VUID-vkCmdBuildAccelerationStructuresKHR-dstAccelerationStructure-03701
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the srcAccelerationStructure member of any other element of pInfos with a mode equal to VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresKHR-dstAccelerationStructure-03702
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the dstAccelerationStructure member of any other element of pInfos, which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresKHR-dstAccelerationStructure-03703
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any element of pInfos (including the same element), which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresKHR-scratchData-03704
    The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any other element of pInfos, which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresKHR-scratchData-03705
    The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the srcAccelerationStructure member of any element of pInfos with a mode equal to VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR (including the same element), which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresKHR-dstAccelerationStructure-03706
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing any acceleration structure referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos, which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03666
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be VK_NULL_HANDLE

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03667
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must have been built before with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in VkAccelerationStructureBuildGeometryInfoKHR::flags

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03668
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure and dstAccelerationStructure members must either be the same VkAccelerationStructureKHR, or not have any memory aliasing

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03758
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its geometryCount member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03759
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its flags member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03760
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its type member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03761
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, its geometryType member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03762
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, its flags member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03763
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.vertexFormat member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03764
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.maxVertex member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03765
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.indexType member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03766
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData member was NULL when srcAccelerationStructure was last built, then it must be NULL.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03767
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData member was not NULL when srcAccelerationStructure was last built, then it may not be NULL.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03768
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, and geometry.triangles.indexType is not VK_INDEX_TYPE_NONE_KHR, then the value of each index referenced index must be the same as the corresponding index value when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-primitiveCount-03769
    For each VkAccelerationStructureBuildRangeInfoKHR referenced by this command, its primitiveCount member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-firstVertex-03770
    For each VkAccelerationStructureBuildRangeInfoKHR referenced by this command, if the corresponding geometry uses indices, its firstVertex member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03801
    For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, the corresponding ppBuildRangeInfos[i][j].primitiveCount must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03707
    For each element of pInfos, the buffer used to create its dstAccelerationStructure member must be bound to device memory

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03708
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the buffer used to create its srcAccelerationStructure member must be bound to device memory

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03709
    For each element of pInfos, the buffer used to create each acceleration structure referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR must be bound to device memory

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03671
    If pInfos[i].mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, all addresses between pInfos[i].scratchData.deviceAddress and pInfos[i].scratchData.deviceAddress + N - 1 must be in the buffer device address range of the same buffer, where N is given by the buildScratchSize member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03672
    If pInfos[i].mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, all addresses between pInfos[i].scratchData.deviceAddress and pInfos[i].scratchData.deviceAddress + N - 1 must be in the buffer device address range of the same buffer, where N is given by the updateScratchSize member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count

  • VUID-vkCmdBuildAccelerationStructuresKHR-geometry-03673
    The buffers from which the buffer device addresses for all of the geometry.triangles.vertexData, geometry.triangles.indexData, geometry.triangles.transformData, geometry.aabbs.data, and geometry.instances.data members of all pInfos[i].pGeometries and pInfos[i].ppGeometries must have been created with the VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR usage flag

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03674
    The buffer from which the buffer device address pInfos[i].scratchData.deviceAddress is queried must have been created with VK_BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03802
    For each element of pInfos, its scratchData.deviceAddress member must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03803
    For each element of pInfos, if scratchData.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03710
    For each element of pInfos, its scratchData.deviceAddress member must be a multiple of VkPhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03804
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, geometry.triangles.vertexData.deviceAddress must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03805
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.vertexData.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03711
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, geometry.triangles.vertexData.deviceAddress must be aligned to the size in bytes of the smallest component of the format in vertexFormat

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03806
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not VK_INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.deviceAddress must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03807
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not VK_INDEX_TYPE_NONE_KHR, if geometry.triangles.indexData.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03712
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, and with geometry.triangles.indexType not equal to VK_INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.deviceAddress must be aligned to the size in bytes of the type in indexType

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03808
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is not 0, it must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03809
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03810
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is not 0, it must be aligned to 16 bytes

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03811
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.deviceAddress must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03812
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR, if geometry.aabbs.data.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03714
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.deviceAddress must be aligned to 8 bytes

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03715
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is VK_FALSE, geometry.instances.data.deviceAddress must be aligned to 16 bytes

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03716
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is VK_TRUE, geometry.instances.data.deviceAddress must be aligned to 8 bytes

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03717
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is VK_TRUE, each element of geometry.instances.data.deviceAddress in device memory must be aligned to 16 bytes

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03813
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, geometry.instances.data.deviceAddress must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03814
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, if geometry.instances.data.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03815
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, each VkAccelerationStructureInstanceKHR::accelerationStructureReference value in geometry.instances.data.deviceAddress must be a valid device address containing a value obtained from vkGetAccelerationStructureDeviceAddressKHR

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-03675
    For each pInfos[i], dstAccelerationStructure must have been created with a value of VkAccelerationStructureCreateInfoKHR::size greater than or equal to the memory size required by the build operation, as returned by vkGetAccelerationStructureBuildSizesKHR with pBuildInfo = pInfos[i] and with each element of the pMaxPrimitiveCounts array greater than or equal to the equivalent ppBuildRangeInfos[i][j].primitiveCount values for j in [0,pInfos[i].geometryCount)

  • VUID-vkCmdBuildAccelerationStructuresKHR-ppBuildRangeInfos-03676
    Each element of ppBuildRangeInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount VkAccelerationStructureBuildRangeInfoKHR structures

Valid Usage (Implicit)
  • VUID-vkCmdBuildAccelerationStructuresKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBuildAccelerationStructuresKHR-pInfos-parameter
    pInfos must be a valid pointer to an array of infoCount valid VkAccelerationStructureBuildGeometryInfoKHR structures

  • VUID-vkCmdBuildAccelerationStructuresKHR-ppBuildRangeInfos-parameter
    ppBuildRangeInfos must be a valid pointer to an array of infoCount VkAccelerationStructureBuildRangeInfoKHR structures

  • VUID-vkCmdBuildAccelerationStructuresKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBuildAccelerationStructuresKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBuildAccelerationStructuresKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBuildAccelerationStructuresKHR-infoCount-arraylength
    infoCount must be greater than 0

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

To build acceleration structures with some parameters sourced on the device call:

// Provided by VK_KHR_acceleration_structure
void vkCmdBuildAccelerationStructuresIndirectKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    infoCount,
    const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
    const VkDeviceAddress*                      pIndirectDeviceAddresses,
    const uint32_t*                             pIndirectStrides,
    const uint32_t* const*                      ppMaxPrimitiveCounts);
  • commandBuffer is the command buffer into which the command will be recorded.

  • infoCount is the number of acceleration structures to build.

  • pInfos is an array of infoCount VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure.

  • pIndirectDeviceAddresses is an array of infoCount buffer device addresses which point to pInfos[i]→geometryCount VkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pInfos[i].

  • pIndirectStrides is an array of infoCount byte strides between elements of pIndirectDeviceAddresses.

  • ppMaxPrimitiveCounts is an array of infoCount arrays of pInfo[i]→geometryCount values indicating the maximum number of primitives that will be built by this command for each geometry.

Accesses to acceleration structures, scratch buffers, vertex buffers, index buffers, and instance buffers must be synchronized as with vkCmdBuildAccelerationStructuresKHR.

Accesses to any element of pIndirectDeviceAddresses must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_INDIRECT_COMMAND_READ_BIT.

Valid Usage
  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-mode-04628
    The mode member of each element of pInfos must be a valid VkBuildAccelerationStructureModeKHR value

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-srcAccelerationStructure-04629
    If the srcAccelerationStructure member of any element of pInfos is not VK_NULL_HANDLE, the srcAccelerationStructure member must be a valid VkAccelerationStructureKHR handle

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-04630
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be VK_NULL_HANDLE

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03403
    The srcAccelerationStructure member of any element of pInfos must not be the same acceleration structure as the dstAccelerationStructure member of any other element of pInfos

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-dstAccelerationStructure-03698
    The dstAccelerationStructure member of any element of pInfos must not be the same acceleration structure as the dstAccelerationStructure member of any other element of pInfos

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-dstAccelerationStructure-03800
    The dstAccelerationStructure member of any element of pInfos must be a valid VkAccelerationStructureKHR handle

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03699
    For each element of pInfos, if its type member is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of VkAccelerationStructureCreateInfoKHR::type equal to either VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03700
    For each element of pInfos, if its type member is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of VkAccelerationStructureCreateInfoKHR::type equal to either VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR or VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03663
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, inactive primitives in its srcAccelerationStructure member must not be made active

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03664
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, active primitives in its srcAccelerationStructure member must not be made inactive

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-None-03407
    The dstAccelerationStructure member of any element of pInfos must not be referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-dstAccelerationStructure-03701
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the srcAccelerationStructure member of any other element of pInfos with a mode equal to VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-dstAccelerationStructure-03702
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the dstAccelerationStructure member of any other element of pInfos, which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-dstAccelerationStructure-03703
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any element of pInfos (including the same element), which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-scratchData-03704
    The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any other element of pInfos, which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-scratchData-03705
    The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the srcAccelerationStructure member of any element of pInfos with a mode equal to VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR (including the same element), which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-dstAccelerationStructure-03706
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing any acceleration structure referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos, which is accessed by this command

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03666
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be VK_NULL_HANDLE

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03667
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must have been built before with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in VkAccelerationStructureBuildGeometryInfoKHR::flags

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03668
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure and dstAccelerationStructure members must either be the same VkAccelerationStructureKHR, or not have any memory aliasing

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03758
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its geometryCount member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03759
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its flags member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03760
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its type member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03761
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, its geometryType member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03762
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, its flags member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03763
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.vertexFormat member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03764
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.maxVertex member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03765
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.indexType member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03766
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData member was NULL when srcAccelerationStructure was last built, then it must be NULL.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03767
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData member was not NULL when srcAccelerationStructure was last built, then it may not be NULL.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03768
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, and geometry.triangles.indexType is not VK_INDEX_TYPE_NONE_KHR, then the value of each index referenced index must be the same as the corresponding index value when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-primitiveCount-03769
    For each VkAccelerationStructureBuildRangeInfoKHR referenced by this command, its primitiveCount member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-firstVertex-03770
    For each VkAccelerationStructureBuildRangeInfoKHR referenced by this command, if the corresponding geometry uses indices, its firstVertex member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03801
    For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, the corresponding ppMaxPrimitiveCounts[i][j] must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03707
    For each element of pInfos, the buffer used to create its dstAccelerationStructure member must be bound to device memory

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03708
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the buffer used to create its srcAccelerationStructure member must be bound to device memory

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03709
    For each element of pInfos, the buffer used to create each acceleration structure referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR must be bound to device memory

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03671
    If pInfos[i].mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, all addresses between pInfos[i].scratchData.deviceAddress and pInfos[i].scratchData.deviceAddress + N - 1 must be in the buffer device address range of the same buffer, where N is given by the buildScratchSize member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03672
    If pInfos[i].mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, all addresses between pInfos[i].scratchData.deviceAddress and pInfos[i].scratchData.deviceAddress + N - 1 must be in the buffer device address range of the same buffer, where N is given by the updateScratchSize member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-geometry-03673
    The buffers from which the buffer device addresses for all of the geometry.triangles.vertexData, geometry.triangles.indexData, geometry.triangles.transformData, geometry.aabbs.data, and geometry.instances.data members of all pInfos[i].pGeometries and pInfos[i].ppGeometries must have been created with the VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR usage flag

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03674
    The buffer from which the buffer device address pInfos[i].scratchData.deviceAddress is queried must have been created with VK_BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03802
    For each element of pInfos, its scratchData.deviceAddress member must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03803
    For each element of pInfos, if scratchData.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03710
    For each element of pInfos, its scratchData.deviceAddress member must be a multiple of VkPhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03804
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, geometry.triangles.vertexData.deviceAddress must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03805
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.vertexData.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03711
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, geometry.triangles.vertexData.deviceAddress must be aligned to the size in bytes of the smallest component of the format in vertexFormat

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03806
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not VK_INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.deviceAddress must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03807
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not VK_INDEX_TYPE_NONE_KHR, if geometry.triangles.indexData.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03712
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, and with geometry.triangles.indexType not equal to VK_INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.deviceAddress must be aligned to the size in bytes of the type in indexType

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03808
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is not 0, it must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03809
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03810
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is not 0, it must be aligned to 16 bytes

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03811
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.deviceAddress must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03812
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR, if geometry.aabbs.data.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03714
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.deviceAddress must be aligned to 8 bytes

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03715
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is VK_FALSE, geometry.instances.data.deviceAddress must be aligned to 16 bytes

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03716
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is VK_TRUE, geometry.instances.data.deviceAddress must be aligned to 8 bytes

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03717
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is VK_TRUE, each element of geometry.instances.data.deviceAddress in device memory must be aligned to 16 bytes

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03813
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, geometry.instances.data.deviceAddress must be a valid device address obtained from vkGetBufferDeviceAddress

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03814
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, if geometry.instances.data.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03815
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, each VkAccelerationStructureInstanceKHR::accelerationStructureReference value in geometry.instances.data.deviceAddress must be a valid device address containing a value obtained from vkGetAccelerationStructureDeviceAddressKHR

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03645
    For any element of pIndirectDeviceAddresses, if the buffer from which it was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03646
    For any element of pIndirectDeviceAddresses[i], all device addresses between pIndirectDeviceAddresses[i] and pIndirectDeviceAddresses[i] + (pInfos[i]→geometryCount × pIndirectStrides[i]) - 1 must be in the buffer device address range of the same buffer

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03647
    For any element of pIndirectDeviceAddresses, the buffer from which it was queried must have been created with the VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03648
    Each element of pIndirectDeviceAddresses must be a multiple of 4

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectStrides-03787
    Each element of pIndirectStrides must be a multiple of 4

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-commandBuffer-03649
    commandBuffer must not be a protected command buffer

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-accelerationStructureIndirectBuild-03650
    The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureIndirectBuild feature must be enabled

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03651
    Each VkAccelerationStructureBuildRangeInfoKHR structure referenced by any element of pIndirectDeviceAddresses must be a valid VkAccelerationStructureBuildRangeInfoKHR structure

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03652
    pInfos[i].dstAccelerationStructure must have been created with a value of VkAccelerationStructureCreateInfoKHR::size greater than or equal to the memory size required by the build operation, as returned by vkGetAccelerationStructureBuildSizesKHR with pBuildInfo = pInfos[i] and pMaxPrimitiveCounts = ppMaxPrimitiveCounts[i]

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-ppMaxPrimitiveCounts-03653
    Each ppMaxPrimitiveCounts[i][j] must be greater than or equal to the the primitiveCount value specified by the VkAccelerationStructureBuildRangeInfoKHR structure located at pIndirectDeviceAddresses[i] + (j × pIndirectStrides[i])

Valid Usage (Implicit)
  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-parameter
    pInfos must be a valid pointer to an array of infoCount valid VkAccelerationStructureBuildGeometryInfoKHR structures

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-parameter
    pIndirectDeviceAddresses must be a valid pointer to an array of infoCount VkDeviceAddress values

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectStrides-parameter
    pIndirectStrides must be a valid pointer to an array of infoCount uint32_t values

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-ppMaxPrimitiveCounts-parameter
    ppMaxPrimitiveCounts must be a valid pointer to an array of infoCount uint32_t values

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBuildAccelerationStructuresIndirectKHR-infoCount-arraylength
    infoCount must be greater than 0

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

The VkAccelerationStructureBuildGeometryInfoKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureBuildGeometryInfoKHR {
    VkStructureType                                     sType;
    const void*                                         pNext;
    VkAccelerationStructureTypeKHR                      type;
    VkBuildAccelerationStructureFlagsKHR                flags;
    VkBuildAccelerationStructureModeKHR                 mode;
    VkAccelerationStructureKHR                          srcAccelerationStructure;
    VkAccelerationStructureKHR                          dstAccelerationStructure;
    uint32_t                                            geometryCount;
    const VkAccelerationStructureGeometryKHR*           pGeometries;
    const VkAccelerationStructureGeometryKHR* const*    ppGeometries;
    VkDeviceOrHostAddressKHR                            scratchData;
} VkAccelerationStructureBuildGeometryInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • type is a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure being built.

  • flags is a bitmask of VkBuildAccelerationStructureFlagBitsKHR specifying additional parameters of the acceleration structure.

  • mode is a VkBuildAccelerationStructureModeKHR value specifying the type of operation to perform.

  • srcAccelerationStructure points to an existing acceleration structure that is to be used to update the dst acceleration structure when mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR.

  • dstAccelerationStructure points to the target acceleration structure for the build.

  • geometryCount specifies the number of geometries that will be built into dstAccelerationStructure.

  • pGeometries is a pointer to an array of VkAccelerationStructureGeometryKHR structures.

  • ppGeometries is a pointer to an array of pointers to VkAccelerationStructureGeometryKHR structures.

  • scratchData is the device or host address to memory that will be used as scratch memory for the build.

Only one of pGeometries or ppGeometries can be a valid pointer, the other must be NULL. Each element of the non-NULL array describes the data used to build each acceleration structure geometry.

The index of each element of the pGeometries or ppGeometries members of VkAccelerationStructureBuildGeometryInfoKHR is used as the geometry index during ray traversal. The geometry index is available in ray shaders via the RayGeometryIndexKHR built-in, and is used to determine hit and intersection shaders executed during traversal. The geometry index is available to ray queries via the OpRayQueryGetIntersectionGeometryIndexKHR instruction.

Valid Usage
  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03654
    type must not be VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-pGeometries-03788
    Only one of pGeometries or ppGeometries can be a valid pointer, the other must be NULL

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03789
    If type is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, the geometryType member of elements of either pGeometries or ppGeometries must be VK_GEOMETRY_TYPE_INSTANCES_KHR

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03790
    If type is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, geometryCount must be 1

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03791
    If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR the geometryType member of elements of either pGeometries or ppGeometries must not be VK_GEOMETRY_TYPE_INSTANCES_KHR

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03792
    If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR then the geometryType member of each geometry in either pGeometries or ppGeometries must be the same

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03793
    If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR then geometryCount must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxGeometryCount

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03794
    If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the geometryType member of either pGeometries or ppGeometries is VK_GEOMETRY_TYPE_AABBS_KHR, the total number of AABBs in all geometries must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxPrimitiveCount

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03795
    If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the geometryType member of either pGeometries or ppGeometries is VK_GEOMETRY_TYPE_TRIANGLES_KHR, the total number of triangles in all geometries must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxPrimitiveCount

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-03796
    If flags has the VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR bit set, then it must not have the VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR bit set

Valid Usage (Implicit)
  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-parameter
    type must be a valid VkAccelerationStructureTypeKHR value

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-parameter
    flags must be a valid combination of VkBuildAccelerationStructureFlagBitsKHR values

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-pGeometries-parameter
    If geometryCount is not 0, and pGeometries is not NULL, pGeometries must be a valid pointer to an array of geometryCount valid VkAccelerationStructureGeometryKHR structures

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-ppGeometries-parameter
    If geometryCount is not 0, and ppGeometries is not NULL, ppGeometries must be a valid pointer to an array of geometryCount valid pointers to valid VkAccelerationStructureGeometryKHR structures

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-scratchData-parameter
    scratchData must be a valid VkDeviceOrHostAddressKHR union

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-commonparent
    Both of dstAccelerationStructure, and srcAccelerationStructure that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkBuildAccelerationStructureModeKHR enumeration is defined as:

// Provided by VK_KHR_acceleration_structure
typedef enum VkBuildAccelerationStructureModeKHR {
    VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR = 0,
    VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR = 1,
} VkBuildAccelerationStructureModeKHR;
  • VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR specifies that the destination acceleration structure will be built using the specified geometries.

  • VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR specifies that the destination acceleration structure will be built using data in a source acceleration structure, updated by the specified geometries.

The VkDeviceOrHostAddressKHR union is defined as:

// Provided by VK_KHR_acceleration_structure
typedef union VkDeviceOrHostAddressKHR {
    VkDeviceAddress    deviceAddress;
    void*              hostAddress;
} VkDeviceOrHostAddressKHR;
  • deviceAddress is a buffer device address as returned by the vkGetBufferDeviceAddressKHR command.

  • hostAddress is a host memory address.

The VkDeviceOrHostAddressConstKHR union is defined as:

// Provided by VK_KHR_acceleration_structure
typedef union VkDeviceOrHostAddressConstKHR {
    VkDeviceAddress    deviceAddress;
    const void*        hostAddress;
} VkDeviceOrHostAddressConstKHR;
  • deviceAddress is a buffer device address as returned by the vkGetBufferDeviceAddressKHR command.

  • hostAddress is a const host memory address.

The VkAccelerationStructureGeometryKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryKHR {
    VkStructureType                           sType;
    const void*                               pNext;
    VkGeometryTypeKHR                         geometryType;
    VkAccelerationStructureGeometryDataKHR    geometry;
    VkGeometryFlagsKHR                        flags;
} VkAccelerationStructureGeometryKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • geometryType describes which type of geometry this VkAccelerationStructureGeometryKHR refers to.

  • geometry is a VkAccelerationStructureGeometryDataKHR union describing the geometry data for the relevant geometry type.

  • flags is a bitmask of VkGeometryFlagBitsKHR values describing additional properties of how the geometry should be built.

Valid Usage
Valid Usage (Implicit)
  • VUID-VkAccelerationStructureGeometryKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_KHR

  • VUID-VkAccelerationStructureGeometryKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureGeometryKHR-geometryType-parameter
    geometryType must be a valid VkGeometryTypeKHR value

  • VUID-VkAccelerationStructureGeometryKHR-triangles-parameter
    If geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, the triangles member of geometry must be a valid VkAccelerationStructureGeometryTrianglesDataKHR structure

  • VUID-VkAccelerationStructureGeometryKHR-aabbs-parameter
    If geometryType is VK_GEOMETRY_TYPE_AABBS_KHR, the aabbs member of geometry must be a valid VkAccelerationStructureGeometryAabbsDataKHR structure

  • VUID-VkAccelerationStructureGeometryKHR-instances-parameter
    If geometryType is VK_GEOMETRY_TYPE_INSTANCES_KHR, the instances member of geometry must be a valid VkAccelerationStructureGeometryInstancesDataKHR structure

  • VUID-VkAccelerationStructureGeometryKHR-flags-parameter
    flags must be a valid combination of VkGeometryFlagBitsKHR values

The VkAccelerationStructureGeometryDataKHR union is defined as:

// Provided by VK_KHR_acceleration_structure
typedef union VkAccelerationStructureGeometryDataKHR {
    VkAccelerationStructureGeometryTrianglesDataKHR    triangles;
    VkAccelerationStructureGeometryAabbsDataKHR        aabbs;
    VkAccelerationStructureGeometryInstancesDataKHR    instances;
} VkAccelerationStructureGeometryDataKHR;

The VkAccelerationStructureGeometryTrianglesDataKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryTrianglesDataKHR {
    VkStructureType                  sType;
    const void*                      pNext;
    VkFormat                         vertexFormat;
    VkDeviceOrHostAddressConstKHR    vertexData;
    VkDeviceSize                     vertexStride;
    uint32_t                         maxVertex;
    VkIndexType                      indexType;
    VkDeviceOrHostAddressConstKHR    indexData;
    VkDeviceOrHostAddressConstKHR    transformData;
} VkAccelerationStructureGeometryTrianglesDataKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • vertexFormat is the VkFormat of each vertex element.

  • vertexData is a device or host address to memory containing vertex data for this geometry.

  • maxVertex is the highest index of a vertex that will be addressed by a build command using this structure.

  • vertexStride is the stride in bytes between each vertex.

  • indexType is the VkIndexType of each index element.

  • indexData is a device or host address to memory containing index data for this geometry.

  • transformData is a device or host address to memory containing an optional reference to a VkTransformMatrixKHR structure defining a transformation that should be applied to vertices in this geometry.

Note

Unlike the stride for vertex buffers in VkVertexInputBindingDescription for graphics pipelines which must not exceed maxVertexInputBindingStride, vertexStride for acceleration structure geometry is instead restricted to being a 32-bit value.

Valid Usage
  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexStride-03735
    vertexStride must be a multiple of the size in bytes of the smallest component of vertexFormat

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexStride-03819
    vertexStride must be less than or equal to 232-1

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexFormat-03797
    vertexFormat must support the VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR in VkFormatProperties::bufferFeatures as returned by vkGetPhysicalDeviceFormatProperties2

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-indexType-03798
    indexType must be VK_INDEX_TYPE_UINT16, VK_INDEX_TYPE_UINT32, or VK_INDEX_TYPE_NONE_KHR

Valid Usage (Implicit)
  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_TRIANGLES_DATA_KHR

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexFormat-parameter
    vertexFormat must be a valid VkFormat value

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexData-parameter
    vertexData must be a valid VkDeviceOrHostAddressConstKHR union

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-indexType-parameter
    indexType must be a valid VkIndexType value

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-indexData-parameter
    indexData must be a valid VkDeviceOrHostAddressConstKHR union

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-transformData-parameter
    transformData must be a valid VkDeviceOrHostAddressConstKHR union

The VkTransformMatrixKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkTransformMatrixKHR {
    float    matrix[3][4];
} VkTransformMatrixKHR;

or the equivalent

// Provided by VK_NV_ray_tracing
typedef VkTransformMatrixKHR VkTransformMatrixNV;
  • matrix is a 3x4 row-major affine transformation matrix.

Valid Usage
  • VUID-VkTransformMatrixKHR-matrix-03799
    The first three columns of matrix must define an invertible 3x3 matrix

The VkAccelerationStructureGeometryAabbsDataKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryAabbsDataKHR {
    VkStructureType                  sType;
    const void*                      pNext;
    VkDeviceOrHostAddressConstKHR    data;
    VkDeviceSize                     stride;
} VkAccelerationStructureGeometryAabbsDataKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • data is a device or host address to memory containing VkAabbPositionsKHR structures containing position data for each axis-aligned bounding box in the geometry.

  • stride is the stride in bytes between each entry in data. The stride must be a multiple of 8.

Valid Usage
  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-stride-03545
    stride must be a multiple of 8

  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-stride-03820
    stride must be less than or equal to 232-1

Valid Usage (Implicit)
  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_AABBS_DATA_KHR

  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-data-parameter
    data must be a valid VkDeviceOrHostAddressConstKHR union

The VkAabbPositionsKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAabbPositionsKHR {
    float    minX;
    float    minY;
    float    minZ;
    float    maxX;
    float    maxY;
    float    maxZ;
} VkAabbPositionsKHR;

or the equivalent

// Provided by VK_NV_ray_tracing
typedef VkAabbPositionsKHR VkAabbPositionsNV;
  • minX is the x position of one opposing corner of a bounding box.

  • minY is the y position of one opposing corner of a bounding box.

  • minZ is the z position of one opposing corner of a bounding box.

  • maxX is the x position of the other opposing corner of a bounding box.

  • maxY is the y position of the other opposing corner of a bounding box.

  • maxZ is the z position of the other opposing corner of a bounding box.

Valid Usage
  • VUID-VkAabbPositionsKHR-minX-03546
    minX must be less than or equal to maxX

  • VUID-VkAabbPositionsKHR-minY-03547
    minY must be less than or equal to maxY

  • VUID-VkAabbPositionsKHR-minZ-03548
    minZ must be less than or equal to maxZ

The VkAccelerationStructureGeometryInstancesDataKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryInstancesDataKHR {
    VkStructureType                  sType;
    const void*                      pNext;
    VkBool32                         arrayOfPointers;
    VkDeviceOrHostAddressConstKHR    data;
} VkAccelerationStructureGeometryInstancesDataKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • arrayOfPointers specifies whether data is used as an array of addresses or just an array.

  • data is either the address of an array of device or host addresses referencing individual VkAccelerationStructureInstanceKHR structures if arrayOfPointers is VK_TRUE, or the address of an array of VkAccelerationStructureInstanceKHR structures.

Valid Usage (Implicit)
  • VUID-VkAccelerationStructureGeometryInstancesDataKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_INSTANCES_DATA_KHR

  • VUID-VkAccelerationStructureGeometryInstancesDataKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureGeometryInstancesDataKHR-data-parameter
    data must be a valid VkDeviceOrHostAddressConstKHR union

Acceleration structure instances can be built into top-level acceleration structures. Each acceleration structure instance is a separate entry in the top-level acceleration structure which includes all the geometry of a bottom-level acceleration structure at a transformed location. Multiple instances can point to the same bottom level acceleration structure.

An acceleration structure instance is defined by the structure:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureInstanceKHR {
    VkTransformMatrixKHR          transform;
    uint32_t                      instanceCustomIndex:24;
    uint32_t                      mask:8;
    uint32_t                      instanceShaderBindingTableRecordOffset:24;
    VkGeometryInstanceFlagsKHR    flags:8;
    uint64_t                      accelerationStructureReference;
} VkAccelerationStructureInstanceKHR;

or the equivalent

// Provided by VK_NV_ray_tracing
typedef VkAccelerationStructureInstanceKHR VkAccelerationStructureInstanceNV;
  • transform is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure.

  • instanceCustomIndex is a 24-bit user-specified index value accessible to ray shaders in the InstanceCustomIndexKHR built-in.

  • mask is an 8-bit visibility mask for the geometry. The instance may only be hit if rayMask & instance.mask != 0

  • instanceShaderBindingTableRecordOffset is a 24-bit offset used in calculating the hit shader binding table index.

  • flags is an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance.

  • accelerationStructureReference is either:

The C language spec does not define the ordering of bit-fields, but in practice, this struct produces the correct layout with existing compilers. The intended bit pattern is for the following:

  • instanceCustomIndex and mask occupy the same memory as if a single int32_t was specified in their place

    • instanceCustomIndex occupies the 24 least significant bits of that memory

    • mask occupies the 8 most significant bits of that memory

  • instanceShaderBindingTableRecordOffset and flags occupy the same memory as if a single int32_t was specified in their place

    • instanceShaderBindingTableRecordOffset occupies the 24 least significant bits of that memory

    • flags occupies the 8 most significant bits of that memory

If a compiler produces code that diverges from that pattern, applications must employ another method to set values according to the correct bit pattern.

Valid Usage (Implicit)

Possible values of flags in the instance modifying the behavior of that instance are:

// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryInstanceFlagBitsKHR {
    VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR = 0x00000001,
    VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR = 0x00000002,
    VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR = 0x00000004,
    VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR = 0x00000008,
  // Provided by VK_NV_ray_tracing
    VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV = VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_NV = VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV = VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV = VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR,
} VkGeometryInstanceFlagBitsKHR;

or the equivalent

// Provided by VK_NV_ray_tracing
typedef VkGeometryInstanceFlagBitsKHR VkGeometryInstanceFlagBitsNV;
  • VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR disables face culling for this instance.

  • VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR indicates that the front face of the triangle for culling purposes is the face that is counter clockwise in object space relative to the ray origin. Because the facing is determined in object space, an instance transform matrix does not change the winding, but a geometry transform does.

  • VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR causes this instance to act as though VK_GEOMETRY_OPAQUE_BIT_KHR were specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-V NoOpaqueKHR ray flag.

  • VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR causes this instance to act as though VK_GEOMETRY_OPAQUE_BIT_KHR were not specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-V OpaqueKHR ray flag.

VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR and VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR must not be used in the same flag.

// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkGeometryInstanceFlagsKHR;

or the equivalent

// Provided by VK_NV_ray_tracing
typedef VkGeometryInstanceFlagsKHR VkGeometryInstanceFlagsNV;

VkGeometryInstanceFlagsKHR is a bitmask type for setting a mask of zero or more VkGeometryInstanceFlagBitsKHR.

VkAccelerationStructureBuildRangeInfoKHR is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureBuildRangeInfoKHR {
    uint32_t    primitiveCount;
    uint32_t    primitiveOffset;
    uint32_t    firstVertex;
    uint32_t    transformOffset;
} VkAccelerationStructureBuildRangeInfoKHR;
  • primitiveCount defines the number of primitives for a corresponding acceleration structure geometry.

  • primitiveOffset defines an offset in bytes into the memory where primitive data is defined.

  • firstVertex is the index of the first vertex to build from for triangle geometry.

  • transformOffset defines an offset in bytes into the memory where a transform matrix is defined.

The primitive count and primitive offset are interpreted differently depending on the VkGeometryTypeKHR used:

Valid Usage

36.1.7. Copying Acceleration Structures

An additional command exists for copying acceleration structures without updating their contents. The acceleration structure object can be compacted in order to improve performance. Before copying, an application must query the size of the resulting acceleration structure.

To query acceleration structure size parameters call:

// Provided by VK_KHR_acceleration_structure
void vkCmdWriteAccelerationStructuresPropertiesKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    accelerationStructureCount,
    const VkAccelerationStructureKHR*           pAccelerationStructures,
    VkQueryType                                 queryType,
    VkQueryPool                                 queryPool,
    uint32_t                                    firstQuery);
  • commandBuffer is the command buffer into which the command will be recorded.

  • accelerationStructureCount is the count of acceleration structures for which to query the property.

  • pAccelerationStructures is a pointer to an array of existing previously built acceleration structures.

  • queryType is a VkQueryType value specifying the type of queries managed by the pool.

  • queryPool is the query pool that will manage the results of the query.

  • firstQuery is the first query index within the query pool that will contain the accelerationStructureCount number of results.

Accesses to any of the acceleration structures listed in pAccelerationStructures must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.

Valid Usage
  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02493
    queryPool must have been created with a queryType matching queryType

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02494
    The queries identified by queryPool and firstQuery must be unavailable

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-buffer-03736
    The buffer used to create each acceleration structure in pAccelerationStructures must be bound to device memory

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-accelerationStructures-03431
    All acceleration structures in pAccelerationStructures must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryType-03432
    queryType must be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

Valid Usage (Implicit)
  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-parameter
    pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid VkAccelerationStructureKHR handles

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryType-parameter
    queryType must be a valid VkQueryType value

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-parameter
    queryPool must be a valid VkQueryPool handle

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-accelerationStructureCount-arraylength
    accelerationStructureCount must be greater than 0

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commonparent
    Each of commandBuffer, queryPool, and the elements of pAccelerationStructures must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

To query acceleration structure size parameters call:

// Provided by VK_NV_ray_tracing
void vkCmdWriteAccelerationStructuresPropertiesNV(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    accelerationStructureCount,
    const VkAccelerationStructureNV*            pAccelerationStructures,
    VkQueryType                                 queryType,
    VkQueryPool                                 queryPool,
    uint32_t                                    firstQuery);
  • commandBuffer is the command buffer into which the command will be recorded.

  • accelerationStructureCount is the count of acceleration structures for which to query the property.

  • pAccelerationStructures is a pointer to an array of existing previously built acceleration structures.

  • queryType is a VkQueryType value specifying the type of queries managed by the pool.

  • queryPool is the query pool that will manage the results of the query.

  • firstQuery is the first query index within the query pool that will contain the accelerationStructureCount number of results.

Accesses to any of the acceleration structures listed in pAccelerationStructures must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.

Valid Usage
  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-03755
    queryPool must have been created with a queryType matching queryType

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-03756
    The queries identified by queryPool and firstQuery must be unavailable

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-accelerationStructure-03757
    accelerationStructure must be bound completely and contiguously to a single VkDeviceMemory object via vkBindAccelerationStructureMemoryNV

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-accelerationStructures-03431
    All acceleration structures in pAccelerationStructures must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryType-03432
    queryType must be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV

Valid Usage (Implicit)
  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-pAccelerationStructures-parameter
    pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid VkAccelerationStructureNV handles

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryType-parameter
    queryType must be a valid VkQueryType value

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-parameter
    queryPool must be a valid VkQueryPool handle

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-accelerationStructureCount-arraylength
    accelerationStructureCount must be greater than 0

  • VUID-vkCmdWriteAccelerationStructuresPropertiesNV-commonparent
    Each of commandBuffer, queryPool, and the elements of pAccelerationStructures must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

To copy an acceleration structure call:

// Provided by VK_NV_ray_tracing
void vkCmdCopyAccelerationStructureNV(
    VkCommandBuffer                             commandBuffer,
    VkAccelerationStructureNV                   dst,
    VkAccelerationStructureNV                   src,
    VkCopyAccelerationStructureModeKHR          mode);
  • commandBuffer is the command buffer into which the command will be recorded.

  • dst is the target acceleration structure for the copy.

  • src is the source acceleration structure for the copy.

  • mode is a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.

Accesses to src and dst must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate.

Valid Usage
  • VUID-vkCmdCopyAccelerationStructureNV-mode-03410
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR or VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR

  • VUID-vkCmdCopyAccelerationStructureNV-src-03411
    If mode is VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR, src must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR

  • VUID-vkCmdCopyAccelerationStructureNV-buffer-03718
    The buffer used to create src must be bound to device memory

  • VUID-vkCmdCopyAccelerationStructureNV-buffer-03719
    The buffer used to create dst must be bound to device memory

Valid Usage (Implicit)
  • VUID-vkCmdCopyAccelerationStructureNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyAccelerationStructureNV-dst-parameter
    dst must be a valid VkAccelerationStructureNV handle

  • VUID-vkCmdCopyAccelerationStructureNV-src-parameter
    src must be a valid VkAccelerationStructureNV handle

  • VUID-vkCmdCopyAccelerationStructureNV-mode-parameter
    mode must be a valid VkCopyAccelerationStructureModeKHR value

  • VUID-vkCmdCopyAccelerationStructureNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyAccelerationStructureNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdCopyAccelerationStructureNV-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyAccelerationStructureNV-commonparent
    Each of commandBuffer, dst, and src must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

To copy an acceleration structure call:

// Provided by VK_KHR_acceleration_structure
void vkCmdCopyAccelerationStructureKHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyAccelerationStructureInfoKHR*   pInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pInfo is a pointer to a VkCopyAccelerationStructureInfoKHR structure defining the copy operation.

Accesses to pInfo->src and pInfo->dst must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate.

Valid Usage
  • VUID-vkCmdCopyAccelerationStructureKHR-buffer-03737
    The buffer used to create pInfo->src must be bound to device memory

  • VUID-vkCmdCopyAccelerationStructureKHR-buffer-03738
    The buffer used to create pInfo->dst must be bound to device memory

Valid Usage (Implicit)
  • VUID-vkCmdCopyAccelerationStructureKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyAccelerationStructureKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyAccelerationStructureInfoKHR structure

  • VUID-vkCmdCopyAccelerationStructureKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyAccelerationStructureKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdCopyAccelerationStructureKHR-renderpass
    This command must only be called outside of a render pass instance

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

The VkCopyAccelerationStructureInfoKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyAccelerationStructureInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkAccelerationStructureKHR            src;
    VkAccelerationStructureKHR            dst;
    VkCopyAccelerationStructureModeKHR    mode;
} VkCopyAccelerationStructureInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • src is the source acceleration structure for the copy.

  • dst is the target acceleration structure for the copy.

  • mode is a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.

Valid Usage
  • VUID-VkCopyAccelerationStructureInfoKHR-mode-03410
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR or VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR

  • VUID-VkCopyAccelerationStructureInfoKHR-src-03411
    If mode is VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR, src must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR

  • VUID-VkCopyAccelerationStructureInfoKHR-buffer-03718
    The buffer used to create src must be bound to device memory

  • VUID-VkCopyAccelerationStructureInfoKHR-buffer-03719
    The buffer used to create dst must be bound to device memory

Valid Usage (Implicit)
  • VUID-VkCopyAccelerationStructureInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_INFO_KHR

  • VUID-VkCopyAccelerationStructureInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyAccelerationStructureInfoKHR-src-parameter
    src must be a valid VkAccelerationStructureKHR handle

  • VUID-VkCopyAccelerationStructureInfoKHR-dst-parameter
    dst must be a valid VkAccelerationStructureKHR handle

  • VUID-VkCopyAccelerationStructureInfoKHR-mode-parameter
    mode must be a valid VkCopyAccelerationStructureModeKHR value

  • VUID-VkCopyAccelerationStructureInfoKHR-commonparent
    Both of dst, and src must have been created, allocated, or retrieved from the same VkDevice

Possible values of mode specifying additional operations to perform during the copy, are:

// Provided by VK_KHR_acceleration_structure
typedef enum VkCopyAccelerationStructureModeKHR {
    VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR = 0,
    VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR = 1,
    VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR = 2,
    VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR = 3,
  // Provided by VK_NV_ray_tracing
    VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV = VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR,
  // Provided by VK_NV_ray_tracing
    VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV = VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR,
} VkCopyAccelerationStructureModeKHR;

or the equivalent

// Provided by VK_NV_ray_tracing
typedef VkCopyAccelerationStructureModeKHR VkCopyAccelerationStructureModeNV;
  • VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR creates a direct copy of the acceleration structure specified in src into the one specified by dst. The dst acceleration structure must have been created with the same parameters as src.

  • VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR creates a more compact version of an acceleration structure src into dst. The acceleration structure dst must have been created with a size at least as large as that returned by vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR after the build of the acceleration structure specified by src.

  • VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR serializes the acceleration structure to a semi-opaque format which can be reloaded on a compatible implementation.

  • VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR deserializes the semi-opaque serialization format in the buffer to the acceleration structure.

To copy an acceleration structure to device memory call:

// Provided by VK_KHR_acceleration_structure
void vkCmdCopyAccelerationStructureToMemoryKHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);

Accesses to pInfo->src must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. Accesses to the buffer indicated by pInfo->dst.deviceAddress must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_TRANSFER_WRITE_BIT.

This command produces the same results as vkCopyAccelerationStructureToMemoryKHR, but writes its result to a device address, and is executed on the device rather than the host. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.

The defined header structure for the serialized data consists of:

  • VK_UUID_SIZE bytes of data matching VkPhysicalDeviceIDProperties::driverUUID

  • VK_UUID_SIZE bytes of data identifying the compatibility for comparison using vkGetDeviceAccelerationStructureCompatibilityKHR

  • A 64-bit integer of the total size matching the value queried using VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

  • A 64-bit integer of the deserialized size to be passed in to VkAccelerationStructureCreateInfoKHR::size

  • A 64-bit integer of the count of the number of acceleration structure handles following. This will be zero for a bottom-level acceleration structure.

The corresponding handles matching the values returned by vkGetAccelerationStructureDeviceAddressKHR or vkGetAccelerationStructureHandleNV are tightly packed in the buffer following the count. The application is expected to store a mapping between those handles and the original application-generated bottom-level acceleration structures to provide when deserializing. The serialized data is written to the buffer (or read from the buffer) according to the host endianness.

Valid Usage
  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03739
    pInfo->dst.deviceAddress must be a valid device address for a buffer bound to device memory.

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03740
    pInfo->dst.deviceAddress must be aligned to 256 bytes

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03741
    If the buffer pointed to by pInfo->dst.deviceAddress is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-None-03559
    The buffer used to create pInfo->src must be bound to device memory

Valid Usage (Implicit)
  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyAccelerationStructureToMemoryInfoKHR structure

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-renderpass
    This command must only be called outside of a render pass instance

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyAccelerationStructureToMemoryInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkAccelerationStructureKHR            src;
    VkDeviceOrHostAddressKHR              dst;
    VkCopyAccelerationStructureModeKHR    mode;
} VkCopyAccelerationStructureToMemoryInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • src is the source acceleration structure for the copy

  • dst is the device or host address to memory which is the target for the copy

  • mode is a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.

Valid Usage
  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-dst-03561
    The memory pointed to by dst must be at least as large as the serialization size of src, as reported by vkWriteAccelerationStructuresPropertiesKHR or vkCmdWriteAccelerationStructuresPropertiesKHR with a query type of VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-mode-03412
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR

Valid Usage (Implicit)
  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_TO_MEMORY_INFO_KHR

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-src-parameter
    src must be a valid VkAccelerationStructureKHR handle

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-dst-parameter
    dst must be a valid VkDeviceOrHostAddressKHR union

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-mode-parameter
    mode must be a valid VkCopyAccelerationStructureModeKHR value

To copy device memory to an acceleration structure call:

// Provided by VK_KHR_acceleration_structure
void vkCmdCopyMemoryToAccelerationStructureKHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyMemoryToAccelerationStructureInfoKHR* pInfo);

Accesses to pInfo->dst must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR. Accesses to the buffer indicated by pInfo->src.deviceAddress must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of VK_ACCESS_TRANSFER_READ_BIT.

This command can accept acceleration structures produced by either vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR.

The structure provided as input to deserialize is as described in vkCmdCopyAccelerationStructureToMemoryKHR, with any acceleration structure handles filled in with the newly-queried handles to bottom level acceleration structures created before deserialization. These do not need to be built at deserialize time, but must be created.

Valid Usage
  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03742
    pInfo->src.deviceAddress must be a valid device address for a buffer bound to device memory.

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03743
    pInfo->src.deviceAddress must be aligned to 256 bytes

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03744
    If the buffer pointed to by pInfo->src.deviceAddress is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-buffer-03745
    The buffer used to create pInfo->dst must be bound to device memory

Valid Usage (Implicit)
  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyMemoryToAccelerationStructureInfoKHR structure

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-renderpass
    This command must only be called outside of a render pass instance

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

The VkCopyMemoryToAccelerationStructureInfoKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyMemoryToAccelerationStructureInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkDeviceOrHostAddressConstKHR         src;
    VkAccelerationStructureKHR            dst;
    VkCopyAccelerationStructureModeKHR    mode;
} VkCopyMemoryToAccelerationStructureInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • src is the device or host address to memory containing the source data for the copy.

  • dst is the target acceleration structure for the copy.

  • mode is a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.

Valid Usage
  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-mode-03413
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-pInfo-03414
    The data in src must have a format compatible with the destination physical device as returned by vkGetDeviceAccelerationStructureCompatibilityKHR

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-dst-03746
    dst must have been created with a size greater than or equal to that used to serialize the data in src

Valid Usage (Implicit)
  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_MEMORY_TO_ACCELERATION_STRUCTURE_INFO_KHR

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-src-parameter
    src must be a valid VkDeviceOrHostAddressConstKHR union

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-dst-parameter
    dst must be a valid VkAccelerationStructureKHR handle

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-mode-parameter
    mode must be a valid VkCopyAccelerationStructureModeKHR value

To check if a serialized acceleration structure is compatible with the current device call:

// Provided by VK_KHR_acceleration_structure
void vkGetDeviceAccelerationStructureCompatibilityKHR(
    VkDevice                                    device,
    const VkAccelerationStructureVersionInfoKHR* pVersionInfo,
    VkAccelerationStructureCompatibilityKHR*    pCompatibility);
Valid Usage
  • VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-rayTracingPipeline-03661
    The rayTracingPipeline or rayQuery feature must be enabled

Valid Usage (Implicit)
  • VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-pVersionInfo-parameter
    pVersionInfo must be a valid pointer to a valid VkAccelerationStructureVersionInfoKHR structure

  • VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-pCompatibility-parameter
    pCompatibility must be a valid pointer to a VkAccelerationStructureCompatibilityKHR value

The VkAccelerationStructureVersionInfoKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureVersionInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    const uint8_t*     pVersionData;
} VkAccelerationStructureVersionInfoKHR;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pVersionData is a pointer to the version header of an acceleration structure as defined in vkCmdCopyAccelerationStructureToMemoryKHR

Note

pVersionData is a pointer to an array of 2*VK_UUID_SIZE uint8_t values instead of two VK_UUID_SIZE arrays as the expected use case for this member is to be pointed at the header of an previously serialized acceleration structure (via vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR) that is loaded in memory. Using arrays would necessitate extra memory copies of the UUIDs.

Valid Usage (Implicit)
  • VUID-VkAccelerationStructureVersionInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_INFO_KHR

  • VUID-VkAccelerationStructureVersionInfoKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureVersionInfoKHR-pVersionData-parameter
    pVersionData must be a valid pointer to an array of 2*VK_UUID_SIZE uint8_t values

Possible values of pCompatibility returned by vkGetDeviceAccelerationStructureCompatibilityKHR are:

// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureCompatibilityKHR {
    VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHR = 0,
    VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHR = 1,
} VkAccelerationStructureCompatibilityKHR;
  • VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHR when the pVersion version acceleration structure is compatibile with device.

  • VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHR when the pVersion version acceleration structure is not compatibile with device.

36.2. Host Acceleration Structure Operations

Implementations are also required to provide host implementations of the acceleration structure operations if the accelerationStructureHostCommands feature is enabled:

These commands are functionally equivalent to their device counterparts, except that they are executed on the host timeline, rather than being enqueued into command buffers.

All acceleration structures used by the host commands must be bound to host-visible memory, and all input data for acceleration structure builds must be referenced using host addresses instead of device addresses. Applications are not required to map acceleration structure memory when using the host commands.

Note

The vkBuildAccelerationStructuresKHR and vkCmdBuildAccelerationStructuresKHR may use different algorithms, and thus are not required to produce identical structures. The structures produced by these two commands may exhibit different memory footprints or traversal performance, but should strive to be similar where possible.

Apart from these details, the host and device operations are interchangable. For example, an application can use vkBuildAccelerationStructuresKHR to build a structure, compact it on the device using vkCmdCopyAccelerationStructureKHR, and serialize the result using vkCopyAccelerationStructureToMemoryKHR.

To build acceleration structures on the host, call:

// Provided by VK_KHR_acceleration_structure
VkResult vkBuildAccelerationStructuresKHR(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    uint32_t                                    infoCount,
    const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
    const VkAccelerationStructureBuildRangeInfoKHR* const* ppBuildRangeInfos);
  • device is the VkDevice for which the acceleration structures are being built.

  • deferredOperation is an optional VkDeferredOperationKHR to request deferral for this command.

  • infoCount is the number of acceleration structures to build. It specifies the number of the pInfos structures and ppBuildRangeInfos pointers that must be provided.

  • pInfos is a pointer to an array of infoCount VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure.

  • ppBuildRangeInfos is an array of infoCount pointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. Each ppBuildRangeInfos[i] is an array of pInfos[i].geometryCount VkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pInfos[i].

This command fulfills the same task as vkCmdBuildAccelerationStructuresKHR but is executed by the host.

The vkBuildAccelerationStructuresKHR command provides the ability to initiate multiple acceleration structures builds, however there is no ordering or synchronization implied between any of the individual acceleration structure builds.

Note

This means that an application cannot build a top-level acceleration structure in the same vkBuildAccelerationStructuresKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds.

Valid Usage
  • VUID-vkBuildAccelerationStructuresKHR-mode-04628
    The mode member of each element of pInfos must be a valid VkBuildAccelerationStructureModeKHR value

  • VUID-vkBuildAccelerationStructuresKHR-srcAccelerationStructure-04629
    If the srcAccelerationStructure member of any element of pInfos is not VK_NULL_HANDLE, the srcAccelerationStructure member must be a valid VkAccelerationStructureKHR handle

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-04630
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be VK_NULL_HANDLE

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03403
    The srcAccelerationStructure member of any element of pInfos must not be the same acceleration structure as the dstAccelerationStructure member of any other element of pInfos

  • VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03698
    The dstAccelerationStructure member of any element of pInfos must not be the same acceleration structure as the dstAccelerationStructure member of any other element of pInfos

  • VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03800
    The dstAccelerationStructure member of any element of pInfos must be a valid VkAccelerationStructureKHR handle

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03699
    For each element of pInfos, if its type member is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of VkAccelerationStructureCreateInfoKHR::type equal to either VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03700
    For each element of pInfos, if its type member is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of VkAccelerationStructureCreateInfoKHR::type equal to either VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR or VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03663
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, inactive primitives in its srcAccelerationStructure member must not be made active

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03664
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, active primitives in its srcAccelerationStructure member must not be made inactive

  • VUID-vkBuildAccelerationStructuresKHR-None-03407
    The dstAccelerationStructure member of any element of pInfos must not be referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos

  • VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03701
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the srcAccelerationStructure member of any other element of pInfos with a mode equal to VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, which is accessed by this command

  • VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03702
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the dstAccelerationStructure member of any other element of pInfos, which is accessed by this command

  • VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03703
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any element of pInfos (including the same element), which is accessed by this command

  • VUID-vkBuildAccelerationStructuresKHR-scratchData-03704
    The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any other element of pInfos, which is accessed by this command

  • VUID-vkBuildAccelerationStructuresKHR-scratchData-03705
    The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the srcAccelerationStructure member of any element of pInfos with a mode equal to VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR (including the same element), which is accessed by this command

  • VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03706
    The range of memory backing the dstAccelerationStructure member of any element of pInfos that is accessed by this command must not overlap the memory backing any acceleration structure referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos, which is accessed by this command

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03666
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be VK_NULL_HANDLE

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03667
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must have been built before with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in VkAccelerationStructureBuildGeometryInfoKHR::flags

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03668
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure and dstAccelerationStructure members must either be the same VkAccelerationStructureKHR, or not have any memory aliasing

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03758
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its geometryCount member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03759
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its flags member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03760
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its type member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03761
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, its geometryType member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03762
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, its flags member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03763
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.vertexFormat member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03764
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.maxVertex member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03765
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.indexType member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03766
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData member was NULL when srcAccelerationStructure was last built, then it must be NULL.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03767
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData member was not NULL when srcAccelerationStructure was last built, then it may not be NULL.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03768
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each VkAccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, and geometry.triangles.indexType is not VK_INDEX_TYPE_NONE_KHR, then the value of each index referenced index must be the same as the corresponding index value when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-primitiveCount-03769
    For each VkAccelerationStructureBuildRangeInfoKHR referenced by this command, its primitiveCount member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-firstVertex-03770
    For each VkAccelerationStructureBuildRangeInfoKHR referenced by this command, if the corresponding geometry uses indices, its firstVertex member must have the same value which was specified when srcAccelerationStructure was last built.

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03801
    For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, the corresponding ppBuildRangeInfos[i][j].primitiveCount must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03675
    For each pInfos[i], dstAccelerationStructure must have been created with a value of VkAccelerationStructureCreateInfoKHR::size greater than or equal to the memory size required by the build operation, as returned by vkGetAccelerationStructureBuildSizesKHR with pBuildInfo = pInfos[i] and with each element of the pMaxPrimitiveCounts array greater than or equal to the equivalent ppBuildRangeInfos[i][j].primitiveCount values for j in [0,pInfos[i].geometryCount)

  • VUID-vkBuildAccelerationStructuresKHR-ppBuildRangeInfos-03676
    Each element of ppBuildRangeInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount VkAccelerationStructureBuildRangeInfoKHR structures

  • VUID-vkBuildAccelerationStructuresKHR-deferredOperation-03677
    If deferredOperation is not VK_NULL_HANDLE, it must be a valid VkDeferredOperationKHR object

  • VUID-vkBuildAccelerationStructuresKHR-deferredOperation-03678
    Any previous deferred operation that was associated with deferredOperation must be complete

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03722
    For each element of pInfos, the buffer used to create its dstAccelerationStructure member must be bound to host-visible device memory

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03723
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the buffer used to create its srcAccelerationStructure member must be bound to host-visible device memory

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03724
    For each element of pInfos, the buffer used to create each acceleration structure referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR must be bound to host-visible device memory

  • VUID-vkBuildAccelerationStructuresKHR-accelerationStructureHostCommands-03581
    The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureHostCommands feature must be enabled

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03725
    If pInfos[i].mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, all addresses between pInfos[i].scratchData.hostAddress and pInfos[i].scratchData.hostAddress + N - 1 must be valid host memory, where N is given by the buildScratchSize member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03726
    If pInfos[i].mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, all addresses between pInfos[i].scratchData.hostAddress and pInfos[i].scratchData.hostAddress + N - 1 must be valid host memory, where N is given by the updateScratchSize member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03771
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, geometry.triangles.vertexData.hostAddress must be a valid host address

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03772
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not VK_INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.hostAddress must be a valid host address

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03773
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.hostAddress is not 0, it must be a valid host address

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03774
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.hostAddress must be a valid host address

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03775
    For each element of pInfos, the buffer used to create its dstAccelerationStructure member must be bound to memory that was not allocated with multiple instances

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03776
    For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the buffer used to create its srcAccelerationStructure member must be bound to memory that was not allocated with multiple instances

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03777
    For each element of pInfos, the buffer used to create each acceleration structure referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR must be bound to memory that was not allocated with multiple instances

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03778
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, geometry.instances.data.hostAddress must be a valid host address

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-03779
    For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, each VkAccelerationStructureInstanceKHR::accelerationStructureReference value in geometry.instances.data.hostAddress must be a valid VkAccelerationStructureKHR object

Valid Usage (Implicit)
  • VUID-vkBuildAccelerationStructuresKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBuildAccelerationStructuresKHR-deferredOperation-parameter
    If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle

  • VUID-vkBuildAccelerationStructuresKHR-pInfos-parameter
    pInfos must be a valid pointer to an array of infoCount valid VkAccelerationStructureBuildGeometryInfoKHR structures

  • VUID-vkBuildAccelerationStructuresKHR-ppBuildRangeInfos-parameter
    ppBuildRangeInfos must be a valid pointer to an array of infoCount VkAccelerationStructureBuildRangeInfoKHR structures

  • VUID-vkBuildAccelerationStructuresKHR-infoCount-arraylength
    infoCount must be greater than 0

  • VUID-vkBuildAccelerationStructuresKHR-deferredOperation-parent
    If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To copy or compact an acceleration structure on the host, call:

// Provided by VK_KHR_acceleration_structure
VkResult vkCopyAccelerationStructureKHR(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    const VkCopyAccelerationStructureInfoKHR*   pInfo);

This command fulfills the same task as vkCmdCopyAccelerationStructureKHR but is executed by the host.

Valid Usage
  • VUID-vkCopyAccelerationStructureKHR-deferredOperation-03677
    If deferredOperation is not VK_NULL_HANDLE, it must be a valid VkDeferredOperationKHR object

  • VUID-vkCopyAccelerationStructureKHR-deferredOperation-03678
    Any previous deferred operation that was associated with deferredOperation must be complete

  • VUID-vkCopyAccelerationStructureKHR-buffer-03727
    The buffer used to create pInfo->src must be bound to host-visible device memory

  • VUID-vkCopyAccelerationStructureKHR-buffer-03728
    The buffer used to create pInfo->dst must be bound to host-visible device memory

  • VUID-vkCopyAccelerationStructureKHR-accelerationStructureHostCommands-03582
    The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureHostCommands feature must be enabled

  • VUID-vkCopyAccelerationStructureKHR-buffer-03780
    The buffer used to create pInfo->src must be bound to memory that was not allocated with multiple instances

  • VUID-vkCopyAccelerationStructureKHR-buffer-03781
    The buffer used to create pInfo->dst must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)
  • VUID-vkCopyAccelerationStructureKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyAccelerationStructureKHR-deferredOperation-parameter
    If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle

  • VUID-vkCopyAccelerationStructureKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyAccelerationStructureInfoKHR structure

  • VUID-vkCopyAccelerationStructureKHR-deferredOperation-parent
    If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To copy host accessible memory to an acceleration structure, call:

// Provided by VK_KHR_acceleration_structure
VkResult vkCopyMemoryToAccelerationStructureKHR(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    const VkCopyMemoryToAccelerationStructureInfoKHR* pInfo);

This command fulfills the same task as vkCmdCopyMemoryToAccelerationStructureKHR but is executed by the host.

This command can accept acceleration structures produced by either vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR.

Valid Usage
  • VUID-vkCopyMemoryToAccelerationStructureKHR-deferredOperation-03677
    If deferredOperation is not VK_NULL_HANDLE, it must be a valid VkDeferredOperationKHR object

  • VUID-vkCopyMemoryToAccelerationStructureKHR-deferredOperation-03678
    Any previous deferred operation that was associated with deferredOperation must be complete

  • VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-03729
    pInfo->src.hostAddress must be a valid host pointer

  • VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-03750
    pInfo->src.hostAddress must be aligned to 16 bytes

  • VUID-vkCopyMemoryToAccelerationStructureKHR-buffer-03730
    The buffer used to create pInfo->dst must be bound to host-visible device memory

  • VUID-vkCopyMemoryToAccelerationStructureKHR-accelerationStructureHostCommands-03583
    The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureHostCommands feature must be enabled

  • VUID-vkCopyMemoryToAccelerationStructureKHR-buffer-03782
    The buffer used to create pInfo->dst must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)
  • VUID-vkCopyMemoryToAccelerationStructureKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyMemoryToAccelerationStructureKHR-deferredOperation-parameter
    If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle

  • VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyMemoryToAccelerationStructureInfoKHR structure

  • VUID-vkCopyMemoryToAccelerationStructureKHR-deferredOperation-parent
    If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To copy an acceleration structure to host accessible memory, call:

// Provided by VK_KHR_acceleration_structure
VkResult vkCopyAccelerationStructureToMemoryKHR(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);

This command fulfills the same task as vkCmdCopyAccelerationStructureToMemoryKHR but is executed by the host.

This command produces the same results as vkCmdCopyAccelerationStructureToMemoryKHR, but writes its result directly to a host pointer, and is executed on the host rather than the device. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.

Valid Usage
  • VUID-vkCopyAccelerationStructureToMemoryKHR-deferredOperation-03677
    If deferredOperation is not VK_NULL_HANDLE, it must be a valid VkDeferredOperationKHR object

  • VUID-vkCopyAccelerationStructureToMemoryKHR-deferredOperation-03678
    Any previous deferred operation that was associated with deferredOperation must be complete

  • VUID-vkCopyAccelerationStructureToMemoryKHR-buffer-03731
    The buffer used to create pInfo->src must be bound to host-visible device memory

  • VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-03732
    pInfo->dst.hostAddress must be a valid host pointer

  • VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-03751
    pInfo->dst.hostAddress must be aligned to 16 bytes

  • VUID-vkCopyAccelerationStructureToMemoryKHR-accelerationStructureHostCommands-03584
    The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureHostCommands feature must be enabled

  • VUID-vkCopyAccelerationStructureToMemoryKHR-buffer-03783
    The buffer used to create pInfo->src must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)
  • VUID-vkCopyAccelerationStructureToMemoryKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyAccelerationStructureToMemoryKHR-deferredOperation-parameter
    If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle

  • VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyAccelerationStructureToMemoryInfoKHR structure

  • VUID-vkCopyAccelerationStructureToMemoryKHR-deferredOperation-parent
    If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

To query acceleration structure size parameters on the host, call:

// Provided by VK_KHR_acceleration_structure
VkResult vkWriteAccelerationStructuresPropertiesKHR(
    VkDevice                                    device,
    uint32_t                                    accelerationStructureCount,
    const VkAccelerationStructureKHR*           pAccelerationStructures,
    VkQueryType                                 queryType,
    size_t                                      dataSize,
    void*                                       pData,
    size_t                                      stride);
  • device is the device which owns the acceleration structures in pAccelerationStructures.

  • accelerationStructureCount is the count of acceleration structures for which to query the property.

  • pAccelerationStructures points to an array of existing previously built acceleration structures.

  • queryType is a VkQueryType value specifying the property to be queried.

  • dataSize is the size in bytes of the buffer pointed to by pData.

  • pData is a pointer to a user-allocated buffer where the results will be written.

  • stride is the stride in bytes between results for individual queries within pData.

This command fulfills the same task as vkCmdWriteAccelerationStructuresPropertiesKHR but is executed by the host.

Valid Usage
  • VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructures-03431
    All acceleration structures in pAccelerationStructures must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03432
    queryType must be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03448
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then stride must be a multiple of the size of VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03449
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then data must point to a VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03450
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then stride must be a multiple of the size of VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03451
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then data must point to a VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-dataSize-03452
    dataSize must be greater than or equal to accelerationStructureCount*stride

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03733
    The buffer used to create each acceleration structure in pAccelerationStructures must be bound to host-visible device memory

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructureHostCommands-03585
    The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureHostCommands feature must be enabled

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03784
    The buffer used to create each acceleration structure in pAccelerationStructures must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)
  • VUID-vkWriteAccelerationStructuresPropertiesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-parameter
    pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid VkAccelerationStructureKHR handles

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-parameter
    queryType must be a valid VkQueryType value

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructureCount-arraylength
    accelerationStructureCount must be greater than 0

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-parent
    Each element of pAccelerationStructures must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY