vkDestroyAccelerationStructureKHR - Destroy an acceleration structure object

Valid Usage

• The ::accelerationStructure feature must be enabled

• All submitted commands that refer to accelerationStructure must have completed execution
• If AllocationCallbacks were provided when accelerationStructure was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when accelerationStructure was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If accelerationStructure is not NULL_HANDLE, accelerationStructure must be a valid AccelerationStructureKHR handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If accelerationStructure is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to accelerationStructure must be externally synchronized

See Also

VK_KHR_acceleration_structure, AccelerationStructureKHR, AllocationCallbacks, Device

vkCmdCopyAccelerationStructureKHR - Copy an acceleration structure

Description

This command copies the pInfo->src acceleration structure to the pInfo->dst acceleration structure in the manner specified by pInfo->mode.

Accesses to pInfo->src and pInfo->dst must be synchronized with the PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR pipeline stage or the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage, and an access type of ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate.

Valid Usage

• The ::accelerationStructure feature must be enabled

• The buffer used to create pInfo->src must be bound to device memory
• The buffer used to create pInfo->dst must be bound to device memory

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyAccelerationStructureInfoKHR structure
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

See Also

VK_KHR_acceleration_structure, CommandBuffer, CopyAccelerationStructureInfoKHR

vkCopyAccelerationStructureKHR - Copy an acceleration structure on the host

Description

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

Valid Usage

• The ::accelerationStructureHostCommands

• If deferredOperation is not NULL_HANDLE, it must be a valid DeferredOperationKHR object
• Any previous deferred operation that was associated with deferredOperation must be complete
• The buffer used to create pInfo->src must be bound to host-visible device memory
• The buffer used to create pInfo->dst must be bound to host-visible device memory feature must be enabled
• The buffer used to create pInfo->src must be bound to memory that was not allocated with multiple instances
• The buffer used to create pInfo->dst must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

• device must be a valid Device handle

• If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle
• pInfo must be a valid pointer to a valid CopyAccelerationStructureInfoKHR structure
• If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_KHR_acceleration_structure, CopyAccelerationStructureInfoKHR, DeferredOperationKHR, Device

vkCmdCopyAccelerationStructureToMemoryKHR - Copy an acceleration structure to device memory

Description

Accesses to pInfo->src must be synchronized with the PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR pipeline stage or the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage, and an access type of ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. Accesses to the buffer indicated by pInfo->dst.deviceAddress must be synchronized with the PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR pipeline stage or the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage, and an and an access type of ACCESS_TRANSFER_WRITE_BIT.

This command produces the same results as copyAccelerationStructureToMemoryKHR, 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 cmdCopyMemoryToAccelerationStructureKHR or copyMemoryToAccelerationStructureKHR.

The defined header structure for the serialized data consists of:

• UUID_SIZE bytes of data matching PhysicalDeviceIDProperties::driverUUID
• UUID_SIZE bytes of data identifying the compatibility for comparison using getDeviceAccelerationStructureCompatibilityKHR
• A 64-bit integer of the total size matching the value queried using QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR
• A 64-bit integer of the deserialized size to be passed in to AccelerationStructureCreateInfoKHR::size
• A 64-bit integer of the count of the number of acceleration structure handles following. This value matches the value queried using QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR. This will be zero for a bottom-level acceleration structure. For top-level acceleration structures this number is implementation-dependent; the number of and ordering of the handles may not match the instance descriptions which were used to build the acceleration structure.

The corresponding handles matching the values returned by getAccelerationStructureDeviceAddressKHR or getAccelerationStructureHandleNV 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

• The ::accelerationStructure feature must be enabled

• pInfo->dst.deviceAddress must be a valid device address for a buffer bound to device memory
• pInfo->dst.deviceAddress must be aligned to 256 bytes
• If the buffer pointed to by pInfo->dst.deviceAddress is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer used to create pInfo->src must be bound to device memory

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyAccelerationStructureToMemoryInfoKHR structure
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

See Also

VK_KHR_acceleration_structure, CommandBuffer, CopyAccelerationStructureToMemoryInfoKHR

vkCopyAccelerationStructureToMemoryKHR - Serialize an acceleration structure on the host

Description

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

This command produces the same results as cmdCopyAccelerationStructureToMemoryKHR, 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 cmdCopyMemoryToAccelerationStructureKHR or copyMemoryToAccelerationStructureKHR.

Valid Usage

• The ::accelerationStructureHostCommands feature must be enabled

• If deferredOperation is not NULL_HANDLE, it must be a valid DeferredOperationKHR object
• Any previous deferred operation that was associated with deferredOperation must be complete
• The buffer used to create pInfo->src must be bound to host-visible device memory
• pInfo->dst.hostAddress must be a valid host pointer
• pInfo->dst.hostAddress must be aligned to 16 bytes
• The buffer used to create pInfo->src must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

• device must be a valid Device handle

• If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle
• pInfo must be a valid pointer to a valid CopyAccelerationStructureToMemoryInfoKHR structure
• If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_KHR_acceleration_structure, CopyAccelerationStructureToMemoryInfoKHR, DeferredOperationKHR, Device

vkCmdCopyMemoryToAccelerationStructureKHR - Copy device memory to an acceleration structure

Description

Accesses to pInfo->dst must be synchronized with the PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR pipeline stage or the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage, and an access type of ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR. Accesses to the buffer indicated by pInfo->src.deviceAddress must be synchronized with the PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR pipeline stage or the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage, and an access type of ACCESS_TRANSFER_READ_BIT.

This command can accept acceleration structures produced by either cmdCopyAccelerationStructureToMemoryKHR or copyAccelerationStructureToMemoryKHR.

The structure provided as input to deserialize is as described in cmdCopyAccelerationStructureToMemoryKHR, 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

• The ::accelerationStructure feature must be enabled

• pInfo->src.deviceAddress must be a valid device address for a buffer bound to device memory
• pInfo->src.deviceAddress must be aligned to 256 bytes
• If the buffer pointed to by pInfo->src.deviceAddress is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer used to create pInfo->dst must be bound to device memory

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyMemoryToAccelerationStructureInfoKHR structure
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

See Also

VK_KHR_acceleration_structure, CommandBuffer, CopyMemoryToAccelerationStructureInfoKHR

vkCopyMemoryToAccelerationStructureKHR - Deserialize an acceleration structure on the host

Description

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

This command can accept acceleration structures produced by either cmdCopyAccelerationStructureToMemoryKHR or copyAccelerationStructureToMemoryKHR.

Valid Usage

• The ::accelerationStructureHostCommands feature must be enabled

• If deferredOperation is not NULL_HANDLE, it must be a valid DeferredOperationKHR object
• Any previous deferred operation that was associated with deferredOperation must be complete
• pInfo->src.hostAddress must be a valid host pointer
• pInfo->src.hostAddress must be aligned to 16 bytes
• The buffer used to create pInfo->dst must be bound to host-visible device memory
• The buffer used to create pInfo->dst must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

• device must be a valid Device handle

• If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle
• pInfo must be a valid pointer to a valid CopyMemoryToAccelerationStructureInfoKHR structure
• If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_KHR_acceleration_structure, CopyMemoryToAccelerationStructureInfoKHR, DeferredOperationKHR, Device

vkCmdWriteAccelerationStructuresPropertiesKHR - Write acceleration structure result parameters to query results.

Description

Accesses to any of the acceleration structures listed in pAccelerationStructures must be synchronized with the PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR pipeline stage or the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage, and an access type of ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.

• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then the value written out is the number of bytes required by a compacted acceleration structure.
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then the value written out is the number of bytes required by a serialized acceleration structure.

Valid Usage

• The ::accelerationStructure feature must be enabled

• queryPool must have been created with a queryType matching queryType
• The queries identified by queryPool and firstQuery must be unavailable
• The buffer used to create each acceleration structure in pAccelerationStructures must be bound to device memory
• The sum of query plus accelerationStructureCount must be less than or equal to the number of queries in queryPool
• All acceleration structures in pAccelerationStructures must have been built prior to the execution of this command
• All acceleration structures in pAccelerationStructures must have been built with BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR
• queryType must be QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid AccelerationStructureKHR handles
• queryType must be a valid QueryType value
• queryPool must be a valid QueryPool handle
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope
• accelerationStructureCount must be greater than 0
• Each of commandBuffer, queryPool, and the elements of pAccelerationStructures must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

See Also

VK_KHR_acceleration_structure, AccelerationStructureKHR, CommandBuffer, QueryPool, QueryType

vkWriteAccelerationStructuresPropertiesKHR - Query acceleration structure meta-data on the host

Description

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

Valid Usage

• The ::accelerationStructureHostCommands feature must be enabled

• All acceleration structures in pAccelerationStructures must have been built prior to the execution of this command
• All acceleration structures in pAccelerationStructures must have been built with BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR
• queryType must be QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then stride must be a multiple of the size of DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then pData must point to a DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then stride must be a multiple of the size of DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then pData must point to a DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then stride must be a multiple of the size of DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then pData must point to a DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, then stride must be a multiple of the size of DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, then pData must point to a DeviceSize
• dataSize must be greater than or equal to accelerationStructureCount*stride
• The buffer used to create each acceleration structure in pAccelerationStructures must be bound to host-visible device memory
• 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)

• device must be a valid Device handle

• pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid AccelerationStructureKHR handles
• queryType must be a valid QueryType value
• pData must be a valid pointer to an array of dataSize bytes
• accelerationStructureCount must be greater than 0
• dataSize must be greater than 0
• Each element of pAccelerationStructures must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_KHR_acceleration_structure, AccelerationStructureKHR, Device, QueryType

vkGetDeviceAccelerationStructureCompatibilityKHR - Check if a serialized acceleration structure is compatible with the current device

Valid Usage

• The ::accelerationStructure feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pVersionInfo must be a valid pointer to a valid AccelerationStructureVersionInfoKHR structure
• pCompatibility must be a valid pointer to a AccelerationStructureCompatibilityKHR value

See Also

VK_KHR_acceleration_structure, AccelerationStructureCompatibilityKHR, AccelerationStructureVersionInfoKHR, Device

vkCreateAccelerationStructureKHR - Create a new acceleration structure object

Description

Similar to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into an acceleration structure is determined by the parameters of AccelerationStructureCreateInfoKHR.

The acceleration structure data is stored in the object referred to by AccelerationStructureCreateInfoKHR::buffer. Once memory has been bound to that buffer, it must be populated by acceleration structure build or acceleration structure copy commands such as cmdBuildAccelerationStructuresKHR, buildAccelerationStructuresKHR, cmdCopyAccelerationStructureKHR, and copyAccelerationStructureKHR.

Note

The expected usage for a trace capture/replay tool is that it will serialize and later deserialize the acceleration structure data using acceleration structure copy commands. During capture the tool will use copyAccelerationStructureToMemoryKHR or cmdCopyAccelerationStructureToMemoryKHR with a mode of COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR, and copyMemoryToAccelerationStructureKHR or cmdCopyMemoryToAccelerationStructureKHR with a mode of COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR during replay.

The input buffers passed to acceleration structure build commands will be referenced by the implementation for the duration of the command. After the command completes, the acceleration structure may hold a reference to any acceleration structure specified by an active instance contained therein. Apart from this referencing, acceleration structures must be fully self-contained. The application can reuse or free any memory which was used by the command as an input or as scratch without affecting the results of ray traversal.

Valid Usage

• The ::accelerationStructure feature must be enabled

• If AccelerationStructureCreateInfoKHR::deviceAddress is not zero, the accelerationStructureCaptureReplay feature must be enabled
• If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid AccelerationStructureCreateInfoKHR structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pAccelerationStructure must be a valid pointer to a AccelerationStructureKHR handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

See Also

VK_KHR_acceleration_structure, AccelerationStructureCreateInfoKHR, AccelerationStructureKHR, AllocationCallbacks, Device

A convenience wrapper to make a compatible pair of calls to createAccelerationStructureKHR and destroyAccelerationStructureKHR

To ensure that destroyAccelerationStructureKHR is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkCmdBuildAccelerationStructuresKHR - Build an acceleration structure

Description

The cmdBuildAccelerationStructuresKHR 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 cmdBuildAccelerationStructuresKHR 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 AccelerationStructureBuildGeometryInfoKHR::scratchData buffer device addresses must be synchronized with the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of (ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR | ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR). Accesses to each AccelerationStructureBuildGeometryInfoKHR::srcAccelerationStructure and AccelerationStructureBuildGeometryInfoKHR::dstAccelerationStructure must be synchronized with the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, as appropriate.

Accesses to other input buffers as identified by any used values of AccelerationStructureGeometryMotionTrianglesDataNV::vertexData, AccelerationStructureGeometryTrianglesDataKHR::vertexData, AccelerationStructureGeometryTrianglesDataKHR::indexData, AccelerationStructureGeometryTrianglesDataKHR::transformData, AccelerationStructureGeometryAabbsDataKHR::data, and AccelerationStructureGeometryInstancesDataKHR::data must be synchronized with the PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of ACCESS_SHADER_READ_BIT.

Valid Usage

• The ::accelerationStructure feature must be enabled

• The mode member of each element of pInfos must be a valid BuildAccelerationStructureModeKHR value
• If the srcAccelerationStructure member of any element of pInfos is not NULL_HANDLE, the srcAccelerationStructure member must be a valid AccelerationStructureKHR handle
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be NULL_HANDLE
• 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
• 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
• The dstAccelerationStructure member of any element of pInfos must be a valid AccelerationStructureKHR handle
• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of AccelerationStructureCreateInfoKHR::type equal to either ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of AccelerationStructureCreateInfoKHR::type equal to either ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR or ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, inactive primitives in its srcAccelerationStructure member must not be made active
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, active primitives in its srcAccelerationStructure member must not be made inactive
• 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 GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos
• 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 BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, which is accessed by this command
• 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
• 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
• 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
• 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 BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR (including the same element), which is accessed by this command
• 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 GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos, which is accessed by this command
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must have previously been constructed with BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in AccelerationStructureBuildGeometryInfoKHR::flags in the build
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure and dstAccelerationStructure members must either be the same AccelerationStructureKHR, or not have any memory aliasing
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its geometryCount member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its flags member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its type member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR 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
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR 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
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.vertexFormat member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.maxVertex member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.indexType member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData address was NULL when srcAccelerationStructure was last built, then it must be NULL
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData address was not NULL when srcAccelerationStructure was last built, then it must not be NULL
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, and geometry.triangles.indexType is not 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
• For each AccelerationStructureBuildRangeInfoKHR referenced by this command, its primitiveCount member must have the same value which was specified when srcAccelerationStructure was last built
• For each AccelerationStructureBuildRangeInfoKHR 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
• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, the corresponding ppBuildRangeInfos[i][j].primitiveCount must be less than or equal to PhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount
• For each element of pInfos, the buffer used to create its dstAccelerationStructure member must be bound to device memory
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the buffer used to create its srcAccelerationStructure member must be bound to device memory
• 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 GEOMETRY_TYPE_INSTANCES_KHR must be bound to device memory
• If pInfos[i].mode is 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 AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count
• If pInfos[i].mode is 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 AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count
• 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 are queried must have been created with the BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR usage flag
• The buffer from which the buffer device address pInfos[i].scratchData.deviceAddress is queried must have been created with BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag
• For each element of pInfos, its scratchData.deviceAddress member must be a valid device address obtained from getBufferDeviceAddress
• 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 DeviceMemory object
• For each element of pInfos, its scratchData.deviceAddress member must be a multiple of PhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, geometry.triangles.vertexData.deviceAddress must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.deviceAddress must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, and with geometry.triangles.indexType not equal to INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.deviceAddress must be aligned to the size in bytes of the type in indexType
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is not 0, it must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is not 0, it must be aligned to 16 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.deviceAddress must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.deviceAddress must be aligned to 8 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is FALSE, geometry.instances.data.deviceAddress must be aligned to 16 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is TRUE, geometry.instances.data.deviceAddress must be aligned to 8 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is TRUE, each element of geometry.instances.data.deviceAddress in device memory must be aligned to 16 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, geometry.instances.data.deviceAddress must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, each AccelerationStructureInstanceKHR::accelerationStructureReference value in geometry.instances.data.deviceAddress must be a valid device address containing a value obtained from getAccelerationStructureDeviceAddressKHR or 0
• For each pInfos[i], dstAccelerationStructure must have been created with a value of AccelerationStructureCreateInfoKHR::size greater than or equal to the memory size required by the build operation, as returned by getAccelerationStructureBuildSizesKHR 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)
• Each element of ppBuildRangeInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount AccelerationStructureBuildRangeInfoKHR structures

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfos must be a valid pointer to an array of infoCount valid AccelerationStructureBuildGeometryInfoKHR structures
• ppBuildRangeInfos must be a valid pointer to an array of infoCount AccelerationStructureBuildRangeInfoKHR structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope
• infoCount must be greater than 0

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

See Also

VK_KHR_acceleration_structure, AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureBuildRangeInfoKHR, CommandBuffer

vkCmdBuildAccelerationStructuresIndirectKHR - Build an acceleration structure with some parameters provided on the device

Description

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

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

Valid Usage

• The ::accelerationStructureIndirectBuild feature must be enabled

• The mode member of each element of pInfos must be a valid BuildAccelerationStructureModeKHR value
• If the srcAccelerationStructure member of any element of pInfos is not NULL_HANDLE, the srcAccelerationStructure member must be a valid AccelerationStructureKHR handle
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be NULL_HANDLE
• 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
• 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
• The dstAccelerationStructure member of any element of pInfos must be a valid AccelerationStructureKHR handle
• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of AccelerationStructureCreateInfoKHR::type equal to either ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of AccelerationStructureCreateInfoKHR::type equal to either ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR or ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, inactive primitives in its srcAccelerationStructure member must not be made active
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, active primitives in its srcAccelerationStructure member must not be made inactive
• 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 GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos
• 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 BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, which is accessed by this command
• 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
• 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
• 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
• 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 BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR (including the same element), which is accessed by this command
• 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 GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos, which is accessed by this command
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must have previously been constructed with BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in AccelerationStructureBuildGeometryInfoKHR::flags in the build
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure and dstAccelerationStructure members must either be the same AccelerationStructureKHR, or not have any memory aliasing
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its geometryCount member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its flags member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its type member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR 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
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR 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
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.vertexFormat member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.maxVertex member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.indexType member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData address was NULL when srcAccelerationStructure was last built, then it must be NULL
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData address was not NULL when srcAccelerationStructure was last built, then it must not be NULL
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, and geometry.triangles.indexType is not 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
• For each AccelerationStructureBuildRangeInfoKHR referenced by this command, its primitiveCount member must have the same value which was specified when srcAccelerationStructure was last built
• For each AccelerationStructureBuildRangeInfoKHR 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
• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, the corresponding ppMaxPrimitiveCounts[i][j] must be less than or equal to PhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount
• For each element of pInfos, the buffer used to create its dstAccelerationStructure member must be bound to device memory
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the buffer used to create its srcAccelerationStructure member must be bound to device memory
• 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 GEOMETRY_TYPE_INSTANCES_KHR must be bound to device memory
• If pInfos[i].mode is 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 AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count
• If pInfos[i].mode is 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 AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count
• 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 are queried must have been created with the BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR usage flag
• The buffer from which the buffer device address pInfos[i].scratchData.deviceAddress is queried must have been created with BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag
• For each element of pInfos, its scratchData.deviceAddress member must be a valid device address obtained from getBufferDeviceAddress
• 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 DeviceMemory object
• For each element of pInfos, its scratchData.deviceAddress member must be a multiple of PhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, geometry.triangles.vertexData.deviceAddress must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.deviceAddress must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, and with geometry.triangles.indexType not equal to INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.deviceAddress must be aligned to the size in bytes of the type in indexType
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is not 0, it must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.deviceAddress is not 0, it must be aligned to 16 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.deviceAddress must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.deviceAddress must be aligned to 8 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is FALSE, geometry.instances.data.deviceAddress must be aligned to 16 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is TRUE, geometry.instances.data.deviceAddress must be aligned to 8 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, if geometry.arrayOfPointers is TRUE, each element of geometry.instances.data.deviceAddress in device memory must be aligned to 16 bytes
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, geometry.instances.data.deviceAddress must be a valid device address obtained from getBufferDeviceAddress
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of 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 DeviceMemory object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, each AccelerationStructureInstanceKHR::accelerationStructureReference value in geometry.instances.data.deviceAddress must be a valid device address containing a value obtained from getAccelerationStructureDeviceAddressKHR or 0
• 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 DeviceMemory object
• 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
• For any element of pIndirectDeviceAddresses, the buffer from which it was queried must have been created with the BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
• Each element of pIndirectDeviceAddresses must be a multiple of 4
• Each element of pIndirectStrides must be a multiple of 4
• commandBuffer must not be a protected command buffer
• Each AccelerationStructureBuildRangeInfoKHR structure referenced by any element of pIndirectDeviceAddresses must be a valid AccelerationStructureBuildRangeInfoKHR structure
• pInfos[i].dstAccelerationStructure must have been created with a value of AccelerationStructureCreateInfoKHR::size greater than or equal to the memory size required by the build operation, as returned by getAccelerationStructureBuildSizesKHR with pBuildInfo = pInfos[i] and pMaxPrimitiveCounts = ppMaxPrimitiveCounts[i]
• Each ppMaxPrimitiveCounts[i][j] must be greater than or equal to the primitiveCount value specified by the AccelerationStructureBuildRangeInfoKHR structure located at pIndirectDeviceAddresses[i] + (j × pIndirectStrides[i])

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfos must be a valid pointer to an array of infoCount valid AccelerationStructureBuildGeometryInfoKHR structures
• pIndirectDeviceAddresses must be a valid pointer to an array of infoCount DeviceAddress values
• pIndirectStrides must be a valid pointer to an array of infoCount uint32_t values
• ppMaxPrimitiveCounts must be a valid pointer to an array of infoCount uint32_t values
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope
• infoCount must be greater than 0

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

See Also

VK_KHR_acceleration_structure, AccelerationStructureBuildGeometryInfoKHR, CommandBuffer, DeviceAddress

vkBuildAccelerationStructuresKHR - Build an acceleration structure on the host

Description

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

The buildAccelerationStructuresKHR 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 buildAccelerationStructuresKHR 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

• The ::accelerationStructureHostCommands feature must be enabled

• The mode member of each element of pInfos must be a valid BuildAccelerationStructureModeKHR value
• If the srcAccelerationStructure member of any element of pInfos is not NULL_HANDLE, the srcAccelerationStructure member must be a valid AccelerationStructureKHR handle
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must not be NULL_HANDLE
• 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
• 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
• The dstAccelerationStructure member of any element of pInfos must be a valid AccelerationStructureKHR handle
• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of AccelerationStructureCreateInfoKHR::type equal to either ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR, its dstAccelerationStructure member must have been created with a value of AccelerationStructureCreateInfoKHR::type equal to either ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR or ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, inactive primitives in its srcAccelerationStructure member must not be made active
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, active primitives in its srcAccelerationStructure member must not be made inactive
• 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 GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos
• 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 BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, which is accessed by this command
• 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
• 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
• 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
• 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 BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR (including the same element), which is accessed by this command
• 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 GEOMETRY_TYPE_INSTANCES_KHR in any other element of pInfos, which is accessed by this command
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure member must have previously been constructed with BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in AccelerationStructureBuildGeometryInfoKHR::flags in the build
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure and dstAccelerationStructure members must either be the same AccelerationStructureKHR, or not have any memory aliasing
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its geometryCount member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its flags member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its type member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR 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
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR 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
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.vertexFormat member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.maxVertex member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, its geometry.triangles.indexType member must have the same value which was specified when srcAccelerationStructure was last built
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData address was NULL when srcAccelerationStructure was last built, then it must be NULL
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles.transformData address was not NULL when srcAccelerationStructure was last built, then it must not be NULL
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, and geometry.triangles.indexType is not 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
• For each AccelerationStructureBuildRangeInfoKHR referenced by this command, its primitiveCount member must have the same value which was specified when srcAccelerationStructure was last built
• For each AccelerationStructureBuildRangeInfoKHR 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
• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, the corresponding ppBuildRangeInfos[i][j].primitiveCount must be less than or equal to PhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount
• For each pInfos[i], dstAccelerationStructure must have been created with a value of AccelerationStructureCreateInfoKHR::size greater than or equal to the memory size required by the build operation, as returned by getAccelerationStructureBuildSizesKHR 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)
• Each element of ppBuildRangeInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount AccelerationStructureBuildRangeInfoKHR structures
• If deferredOperation is not NULL_HANDLE, it must be a valid DeferredOperationKHR object
• Any previous deferred operation that was associated with deferredOperation must be complete
• For each element of pInfos, the buffer used to create its dstAccelerationStructure member must be bound to host-visible device memory
• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the buffer used to create its srcAccelerationStructure member must be bound to host-visible device memory
• 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 GEOMETRY_TYPE_INSTANCES_KHR must be bound to host-visible device memory
• If pInfos[i].mode is 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 AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count
• If pInfos[i].mode is 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 AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, geometry.triangles.vertexData.hostAddress must be a valid host address
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.indexType is not INDEX_TYPE_NONE_KHR, geometry.triangles.indexData.hostAddress must be a valid host address
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if geometry.triangles.transformData.hostAddress is not 0, it must be a valid host address
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_AABBS_KHR, geometry.aabbs.data.hostAddress must be a valid host address
• 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
• For each element of pInfos, if its mode member is 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
• 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 GEOMETRY_TYPE_INSTANCES_KHR must be bound to memory that was not allocated with multiple instances
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, geometry.instances.data.hostAddress must be a valid host address
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, each AccelerationStructureInstanceKHR::accelerationStructureReference value in geometry.instances.data.hostAddress must be a valid AccelerationStructureKHR object
• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR with BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV set, each accelerationStructureReference in any structure in AccelerationStructureMotionInstanceNV value in geometry.instances.data.hostAddress must be a valid AccelerationStructureKHR object

Valid Usage (Implicit)

• device must be a valid Device handle

• If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle
• pInfos must be a valid pointer to an array of infoCount valid AccelerationStructureBuildGeometryInfoKHR structures
• ppBuildRangeInfos must be a valid pointer to an array of infoCount AccelerationStructureBuildRangeInfoKHR structures
• infoCount must be greater than 0
• If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_KHR_acceleration_structure, AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureBuildRangeInfoKHR, DeferredOperationKHR, Device

vkGetAccelerationStructureDeviceAddressKHR - Query an address of a acceleration structure

Description

The 64-bit return value is an address of the acceleration structure, which can be used for device and shader operations that involve acceleration structures, such as ray traversal and acceleration structure building.

If the acceleration structure was created with a non-zero value of AccelerationStructureCreateInfoKHR::deviceAddress, the return value will be the same address.

If the acceleration structure was created with a type of ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR, the returned address must be consistent with the relative offset to other acceleration structures with type ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR allocated with the same Buffer. That is, the difference in returned addresses between the two must be the same as the difference in offsets provided at acceleration structure creation.

The returned address must be aligned to 256 bytes.

Note

The acceleration structure device address may be different from the buffer device address corresponding to the acceleration structure’s start offset in its storage buffer for acceleration structure types other than ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR.

Valid Usage

• The ::accelerationStructure feature must be enabled

• If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfo must be a valid pointer to a valid AccelerationStructureDeviceAddressInfoKHR structure

See Also

VK_KHR_acceleration_structure, AccelerationStructureDeviceAddressInfoKHR, Device

vkGetAccelerationStructureBuildSizesKHR - Retrieve the required size for an acceleration structure

Description

The srcAccelerationStructure, dstAccelerationStructure, and mode members of pBuildInfo are ignored. Any DeviceOrHostAddressKHR or DeviceOrHostAddressConstKHR members of pBuildInfo are ignored by this command, except that the hostAddress member of AccelerationStructureGeometryTrianglesDataKHR::transformData will be examined to check if it is NULL.

An acceleration structure created with the accelerationStructureSize returned by this command supports any build or update with a AccelerationStructureBuildGeometryInfoKHR structure and array of AccelerationStructureBuildRangeInfoKHR structures subject to the following properties:

• The build command is a host build command, and buildType is ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR
• The build command is a device build command, and buildType is ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR

• For AccelerationStructureBuildGeometryInfoKHR:

  • Its type, and flags members are equal to pBuildInfo->type and pBuildInfo->flags, respectively.
  • geometryCount is less than or equal to pBuildInfo->geometryCount.
  • For each element of either pGeometries or ppGeometries at a given index, its geometryType member is equal to pBuildInfo->geometryType.
  • For each element of either pGeometries or ppGeometries at a given index, its flags member is equal to the corresponding member of the same element in pBuildInfo.
  • For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to GEOMETRY_TYPE_TRIANGLES_KHR, the vertexFormat and indexType members of geometry.triangles are equal to the corresponding members of the same element in pBuildInfo.
  • For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to GEOMETRY_TYPE_TRIANGLES_KHR, the maxVertex member of geometry.triangles is less than or equal to the corresponding member of the same element in pBuildInfo.
  • For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to GEOMETRY_TYPE_TRIANGLES_KHR, if the applicable address in the transformData member of geometry.triangles is not NULL, the corresponding transformData.hostAddress parameter in pBuildInfo is not NULL.

• For each AccelerationStructureBuildRangeInfoKHR corresponding to the AccelerationStructureBuildGeometryInfoKHR:

  • Its primitiveCount member is less than or equal to the corresponding element of pMaxPrimitiveCounts.
  • For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to GEOMETRY_TYPE_TRIANGLES_KHR, if the pNext chain contains AccelerationStructureTrianglesOpacityMicromapEXT the corresponding member of pBuildInfo also contains AccelerationStructureTrianglesOpacityMicromapEXT and with an equivalent micromap.
  • For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to GEOMETRY_TYPE_TRIANGLES_KHR, if the pNext chain contains AccelerationStructureTrianglesDisplacementMicromapNV the corresponding member of pBuildInfo also contains AccelerationStructureTrianglesDisplacementMicromapNV and with an equivalent micromap.

Similarly, the updateScratchSize value will support any build command specifying the BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR mode under the above conditions, and the buildScratchSize value will support any build command specifying the BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR mode under the above conditions.

Valid Usage

• The ::accelerationStructure feature must be enabled

• If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled
• If pBuildInfo->geometryCount is not 0, pMaxPrimitiveCounts must be a valid pointer to an array of pBuildInfo->geometryCount uint32_t values
• If pBuildInfo->pGeometries or pBuildInfo->ppGeometries has a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, each pMaxPrimitiveCounts[i] must be less than or equal to PhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount

Valid Usage (Implicit)

• device must be a valid Device handle

• buildType must be a valid AccelerationStructureBuildTypeKHR value
• pBuildInfo must be a valid pointer to a valid AccelerationStructureBuildGeometryInfoKHR structure
• If pMaxPrimitiveCounts is not NULL, pMaxPrimitiveCounts must be a valid pointer to an array of pBuildInfo->geometryCount uint32_t values
• pSizeInfo must be a valid pointer to a AccelerationStructureBuildSizesInfoKHR structure

See Also

VK_KHR_acceleration_structure, AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureBuildSizesInfoKHR, AccelerationStructureBuildTypeKHR, Device

VkWriteDescriptorSetAccelerationStructureKHR - Structure specifying acceleration structure descriptor information

Valid Usage

• accelerationStructureCount must be equal to descriptorCount in the extended structure

• Each acceleration structure in pAccelerationStructures must have been created with a type of ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
• If the nullDescriptor feature is not enabled, each element of pAccelerationStructures must not be NULL_HANDLE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_KHR

• pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid or NULL_HANDLE AccelerationStructureKHR handles
• accelerationStructureCount must be greater than 0

See Also

VK_KHR_acceleration_structure, AccelerationStructureKHR, StructureType

VkPhysicalDeviceAccelerationStructureFeaturesKHR - Structure describing the acceleration structure features that can be supported by an implementation

Members

This structure describes the following features:

Description

If the PhysicalDeviceAccelerationStructureFeaturesKHR structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDeviceAccelerationStructureFeaturesKHR can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_KHR_acceleration_structure, Bool32, StructureType

VkPhysicalDeviceAccelerationStructurePropertiesKHR - Properties of the physical device for acceleration structure

Description

Due to the fact that the geometry, instance, and primitive counts are specified at acceleration structure creation as 32-bit values, maxGeometryCount, maxInstanceCount, and maxPrimitiveCount must not exceed 232-1.

If the PhysicalDeviceAccelerationStructurePropertiesKHR structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Limits specified by this structure must match those specified with the same name in PhysicalDeviceRayTracingPropertiesNV.

Valid Usage (Implicit)

See Also

VK_KHR_acceleration_structure, StructureType