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-firstVertex-03770
For each element ofpInfos, if itsmodemember isVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for eachVkAccelerationStructureGeometryKHRstructure referred to by itspGeometriesorppGeometriesmembers, if the geometry uses indices, thefirstVertexmember 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-03675
For eachpInfos[i],dstAccelerationStructuremust have been created with a value of VkAccelerationStructureCreateInfoKHR::sizegreater than or equal to the memory size required by the build operation, as returned by vkGetAccelerationStructureBuildSizesKHR withpBuildInfo=pInfos[i] and with each element of thepMaxPrimitiveCountsarray greater than or equal to the equivalentppBuildRangeInfos[i][j].primitiveCountvalues forjin [0,pInfos[i].geometryCount) -
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.