vkBuildAccelerationStructuresKHR

To build acceleration structures on the host, call:

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 a pointer to an array of infoCount pointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. Each ppBuildRangeInfos[i] is a pointer to 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.

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-accelerationStructureHostCommands-03581

The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureHostCommands feature must be enabled

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 pInfosmust 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 pInfosmust 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 pInfosmust 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 pInfosmust 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-03667

For each element of pInfos, if its mode member is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must have previously been constructed with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in VkAccelerationStructureBuildGeometryInfoKHR::flags in the build

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 address 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 address was not NULL when srcAccelerationStructure was last built, then it must 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 must be the same as the corresponding index value when srcAccelerationStructure was last built

VUID-vkBuildAccelerationStructuresKHR-primitiveCount-03769

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, the primitiveCount member of its corresponding VkAccelerationStructureBuildRangeInfoKHR structure 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-10126

For each pInfos[i], dstAccelerationStructure must have been created with a value of VkAccelerationStructureCreateInfoKHR::size greater than or equal to either:

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) or,
the result of querying the corresponding VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, if updating a compacted acceleration structure ::

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-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-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.hostAddressmust 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

VUID-vkBuildAccelerationStructuresKHR-pInfos-03777

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

VUID-vkBuildAccelerationStructuresKHR-pInfos-04930

For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR with VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV set, each accelerationStructureReference in any structure in VkAccelerationStructureMotionInstanceNV value in geometry.instances.data.hostAddress must be a valid VkAccelerationStructureKHR object

vkBuildAccelerationStructuresKHR

Valid Usage

Valid Usage (Implicit)