C Specification
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);Parameters
- 
deviceis theVkDevicefor which the acceleration structures are being built.
- 
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command.
- 
infoCountis the number of acceleration structures to build. It specifies the number of thepInfosstructures andppBuildRangeInfospointers that must be provided.
- 
pInfosis a pointer to an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure.
- 
ppBuildRangeInfosis a pointer to an array ofinfoCountpointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. EachppBuildRangeInfos[i] is a pointer to an array ofpInfos[i].geometryCountVkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i].
Description
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. | 
- 
VUID-vkBuildAccelerationStructuresKHR-accelerationStructureHostCommands-03581 
 TheVkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureHostCommandsfeature must be enabled
- 
VUID-vkBuildAccelerationStructuresKHR-mode-04628 
 Themodemember of each element ofpInfosmust be a valid VkBuildAccelerationStructureModeKHR value
- 
VUID-vkBuildAccelerationStructuresKHR-srcAccelerationStructure-04629 
 If thesrcAccelerationStructuremember of any element ofpInfosis not VK_NULL_HANDLE, thesrcAccelerationStructuremember must be a valid VkAccelerationStructureKHR handle
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-04630 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, itssrcAccelerationStructuremember must not be VK_NULL_HANDLE
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03403 
 ThesrcAccelerationStructuremember of any element ofpInfosmust not be the same acceleration structure as thedstAccelerationStructuremember of any other element ofpInfos
- 
VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03698 
 ThedstAccelerationStructuremember of any element ofpInfosmust not be the same acceleration structure as thedstAccelerationStructuremember of any other element ofpInfos
- 
VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03800 
 ThedstAccelerationStructuremember of any element ofpInfosmust be a valid VkAccelerationStructureKHR handle
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03699 
 For each element ofpInfos, if itstypemember isVK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, itsdstAccelerationStructuremember must have been created with a value of VkAccelerationStructureCreateInfoKHR::typeequal to eitherVK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHRorVK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03700 
 For each element ofpInfos, if itstypemember isVK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR, itsdstAccelerationStructuremember must have been created with a value of VkAccelerationStructureCreateInfoKHR::typeequal to eitherVK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHRorVK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03663 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, inactive primitives in itssrcAccelerationStructuremember must not be made active
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03664 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, active primitives in itssrcAccelerationStructuremember must not be made inactive
- 
VUID-vkBuildAccelerationStructuresKHR-None-03407 
 ThedstAccelerationStructuremember of any element ofpInfosmust not be referenced by thegeometry.instances.datamember of any element ofpGeometriesorppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_INSTANCES_KHRin any other element ofpInfos
- 
VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03701 
 The range of memory backing thedstAccelerationStructuremember of any element ofpInfosthat is accessed by this command must not overlap the memory backing thesrcAccelerationStructuremember of any other element ofpInfoswith amodeequal toVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, which is accessed by this command
- 
VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03702 
 The range of memory backing thedstAccelerationStructuremember of any element ofpInfosthat is accessed by this command must not overlap the memory backing thedstAccelerationStructuremember of any other element ofpInfos, which is accessed by this command
- 
VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03703 
 The range of memory backing thedstAccelerationStructuremember of any element ofpInfosthat is accessed by this command must not overlap the memory backing thescratchDatamember of any element ofpInfos(including the same element), which is accessed by this command
- 
VUID-vkBuildAccelerationStructuresKHR-scratchData-03704 
 The range of memory backing thescratchDatamember of any element ofpInfosthat is accessed by this command must not overlap the memory backing thescratchDatamember of any other element ofpInfos, which is accessed by this command
- 
VUID-vkBuildAccelerationStructuresKHR-scratchData-03705 
 The range of memory backing thescratchDatamember of any element ofpInfosthat is accessed by this command must not overlap the memory backing thesrcAccelerationStructuremember of any element ofpInfoswith amodeequal toVK_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 thedstAccelerationStructuremember of any element ofpInfosthat is accessed by this command must not overlap the memory backing any acceleration structure referenced by thegeometry.instances.datamember of any element ofpGeometriesorppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_INSTANCES_KHRin any other element ofpInfos, which is accessed by this command
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03667 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, itssrcAccelerationStructuremember must have previously been constructed withVK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHRset in VkAccelerationStructureBuildGeometryInfoKHR::flagsin the build
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03668 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, itssrcAccelerationStructureanddstAccelerationStructuremembers must either be the same VkAccelerationStructureKHR, or not have any memory aliasing
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03758 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, itsgeometryCountmember must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03759 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, itsflagsmember must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03760 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, itstypemember must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03761 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, itsgeometryTypemember must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03762 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, itsflagsmember must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03763 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, ifgeometryTypeisVK_GEOMETRY_TYPE_TRIANGLES_KHR, itsgeometry.triangles.vertexFormatmember must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03764 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, ifgeometryTypeisVK_GEOMETRY_TYPE_TRIANGLES_KHR, itsgeometry.triangles.maxVertexmember must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03765 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, ifgeometryTypeisVK_GEOMETRY_TYPE_TRIANGLES_KHR, itsgeometry.triangles.indexTypemember must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03766 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, ifgeometryTypeisVK_GEOMETRY_TYPE_TRIANGLES_KHR, if itsgeometry.triangles.transformDataaddress wasNULLwhensrcAccelerationStructurewas last built, then it must beNULL
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03767 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, ifgeometryTypeisVK_GEOMETRY_TYPE_TRIANGLES_KHR, if itsgeometry.triangles.transformDataaddress was notNULLwhensrcAccelerationStructurewas last built, then it must not beNULL
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03768 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, ifgeometryTypeisVK_GEOMETRY_TYPE_TRIANGLES_KHR, andgeometry.triangles.indexTypeis notVK_INDEX_TYPE_NONE_KHR, then the value of each index referenced must be the same as the corresponding index value whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-primitiveCount-03769 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, theprimitiveCountmember of its correspondingVkAccelerationStructureBuildRangeInfoKHRstructure must have the same value which was specified whensrcAccelerationStructurewas last built
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03801 
 For each element ofpInfos[i].pGeometriesorpInfos[i].ppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_INSTANCES_KHR, the correspondingppBuildRangeInfos[i][j].primitiveCountmust be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-10126 
 For eachpInfos[i],dstAccelerationStructuremust have been created with a value of VkAccelerationStructureCreateInfoKHR::sizegreater 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 thepMaxPrimitiveCountsarray greater than or equal to the equivalentppBuildRangeInfos[i][j].primitiveCountvalues forjin [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 ofppBuildRangeInfos[i] must be a valid pointer to an array ofpInfos[i].geometryCountVkAccelerationStructureBuildRangeInfoKHRstructures
- 
VUID-vkBuildAccelerationStructuresKHR-deferredOperation-03678 
 Any previous deferred operation that was associated withdeferredOperationmust be complete
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03722 
 For each element ofpInfos, thebufferused to create itsdstAccelerationStructuremember must be bound to host-visible device memory
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03723 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHRthebufferused to create itssrcAccelerationStructuremember must be bound to host-visible device memory
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03724 
 For each element ofpInfos, thebufferused to create each acceleration structure referenced by thegeometry.instances.datamember of any element ofpGeometriesorppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_INSTANCES_KHRmust be bound to host-visible device memory
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03725 
 IfpInfos[i].modeisVK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, all addresses betweenpInfos[i].scratchData.hostAddressandpInfos[i].scratchData.hostAddress+ N - 1 must be valid host memory, where N is given by thebuildScratchSizemember of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03726 
 IfpInfos[i].modeisVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, all addresses betweenpInfos[i].scratchData.hostAddressandpInfos[i].scratchData.hostAddress+ N - 1 must be valid host memory, where N is given by theupdateScratchSizemember 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 ofpInfos[i].pGeometriesorpInfos[i].ppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_TRIANGLES_KHR,geometry.triangles.vertexData.hostAddressmust be a valid host address
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03772 
 For any element ofpInfos[i].pGeometriesorpInfos[i].ppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_TRIANGLES_KHR, ifgeometry.triangles.indexTypeis notVK_INDEX_TYPE_NONE_KHR,geometry.triangles.indexData.hostAddressmust be a valid host address
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03773 
 For any element ofpInfos[i].pGeometriesorpInfos[i].ppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_TRIANGLES_KHR, ifgeometry.triangles.transformData.hostAddressis not0, it must be a valid host address
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03774 
 For any element ofpInfos[i].pGeometriesorpInfos[i].ppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_AABBS_KHR,geometry.aabbs.data.hostAddressmust be a valid host address
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03775 
 For each element ofpInfos, thebufferused to create itsdstAccelerationStructuremember must be bound to memory that was not allocated with multiple instances
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03776 
 For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHRthebufferused to create itssrcAccelerationStructuremember must be bound to memory that was not allocated with multiple instances
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03777 
 For each element ofpInfos, thebufferused to create each acceleration structure referenced by thegeometry.instances.datamember of any element ofpGeometriesorppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_INSTANCES_KHRmust be bound to memory that was not allocated with multiple instances
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03778 
 For any element ofpInfos[i].pGeometriesorpInfos[i].ppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_INSTANCES_KHR,geometry.instances.data.hostAddressmust be a valid host address
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-03779 
 For any element ofpInfos[i].pGeometriesorpInfos[i].ppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_INSTANCES_KHR, each VkAccelerationStructureInstanceKHR::accelerationStructureReferencevalue ingeometry.instances.data.hostAddressmust be a valid VkAccelerationStructureKHR object
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-04930 
 For any element ofpInfos[i].pGeometriesorpInfos[i].ppGeometrieswith ageometryTypeofVK_GEOMETRY_TYPE_INSTANCES_KHRwithVK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NVset, eachaccelerationStructureReferencein any structure in VkAccelerationStructureMotionInstanceNV value ingeometry.instances.data.hostAddressmust be a valid VkAccelerationStructureKHR object
- 
VUID-vkBuildAccelerationStructuresKHR-device-parameter 
 devicemust be a valid VkDevice handle
- 
VUID-vkBuildAccelerationStructuresKHR-deferredOperation-parameter 
 IfdeferredOperationis not VK_NULL_HANDLE,deferredOperationmust be a valid VkDeferredOperationKHR handle
- 
VUID-vkBuildAccelerationStructuresKHR-pInfos-parameter 
 pInfosmust be a valid pointer to an array ofinfoCountvalid VkAccelerationStructureBuildGeometryInfoKHR structures
- 
VUID-vkBuildAccelerationStructuresKHR-ppBuildRangeInfos-parameter 
 ppBuildRangeInfosmust be a valid pointer to an array ofinfoCountVkAccelerationStructureBuildRangeInfoKHR structures
- 
VUID-vkBuildAccelerationStructuresKHR-infoCount-arraylength 
 infoCountmust be greater than0
- 
VUID-vkBuildAccelerationStructuresKHR-deferredOperation-parent 
 IfdeferredOperationis a valid handle, it must have been created, allocated, or retrieved fromdevice
- On success, this command returns
- 
- 
VK_SUCCESS
- 
VK_OPERATION_DEFERRED_KHR
- 
VK_OPERATION_NOT_DEFERRED_KHR
 
- 
- On failure, this command returns
- 
- 
VK_ERROR_OUT_OF_HOST_MEMORY
- 
VK_ERROR_OUT_OF_DEVICE_MEMORY
 
- 
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.