Vulkan.Extensions.VK_KHR_acceleration_structure

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 source acceleration structure pInfo->src must have been constructed prior to the execution of this command on the device

• If the source acceleration structure pInfo->src was constructed through deserialization, all micromap arrays the acceleration structure references that were not replaced by an acceleration structure update command must have been deserialized using the serialized data of the corresponding micromaps used to originally build the acceleration structure prior to the execution of this command on the device

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 QUEUE_COMPUTE_BIT operations

• This command must only be called outside of a render pass instance

• This command must not be called between suspended render pass instances

• 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

'

Conditional Rendering

vkCmdCopyAccelerationStructureKHR is not affected by conditional rendering

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 feature must be enabled

• Any previous deferred operation that was associated with deferredOperation must be complete

• pInfo->src must be bound to host-visible device memory

• pInfo->dst must be bound to host-visible device memory

• pInfo->src must be bound to memory that was not allocated with multiple instances

• pInfo->dst must be bound to memory that was not allocated with multiple instances

• The source acceleration structure pInfo->src must have been constructed prior to the execution of this command

• If the source acceleration structure pInfo->src was constructed through deserialization, all micromap arrays the acceleration structure references that were not replaced by an acceleration structure update command must have been deserialized using the serialized data of the corresponding micromaps used to originally build the acceleration structure prior to the execution of this command

• pInfo->src must have been created with createAccelerationStructureKHR

• pInfo->dst must have been created with createAccelerationStructureKHR

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

• OPERATION_DEFERRED_KHR

• OPERATION_NOT_DEFERRED_KHR

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

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

For a top-level or bottom-level acceleration structure, this is followed by: * 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

For a top-level acceleration structure, the remainder of the serialized header consists of:

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

For a bottom-level acceleration structure, the remainder of the serialized header consists of:

• A 64-bit integer consisting of two packed 32 bit values. The high 32 bits are 0xFFFFFFFF to indicate a block-based format, and the low 32 bits contain the number of serialized blocks that follow

• For each block:

  • A 32-bit unsigned integer indicating the block type corresponding to values in the AccelerationStructureSerializedBlockTypeKHR enumeration

  • A 32-bit reserved value for alignment

  • A 64-bit unsigned integer indicating the number of block buffer device addresses that follow the block header

  • An array of 64-bit buffer device addresses, with the count matching the previous value

If the block type is ACCELERATION_STRUCTURE_SERIALIZED_BLOCK_TYPE_OPACITY_MICROMAP_KHR, the corresponding buffer device addresses are tightly packed in the buffer and match the values returned by getBufferDeviceAddressKHR for the underlying buffer objects for the opacity micromaps. An implementation may either return NULL for a geometry with no opacity micromap or only return valid device address entries in the array. Similar to the above, the application must provide a mapping between the valid buffer device addresses and the original application-generated opacity micromaps when deserializing. If the implementation returned NULL addresses for geometry without micromaps, the application must provide NULL device addresses mapped to those when deserializing.

The addresses of micromaps provided to deserializing must be compatible with the micromaps that were used for building the acceleration structure that was serialized. They must be created before deserializing with identical type and createFlags except for the ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR flag set.

Before using the deserialized acceleration structure, the micromaps must be deserialized using the serialized output of the micromap that was originally referenced by the serialized acceleration structure, or, if the acceleration structure was originally built with the BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR, the application may replace the micromap with a newly constructed micromap, using the normal update rules.

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 DeviceAddress

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

• If pInfo->src was built with a type of ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, pInfo->dst.deviceAddress must be aligned to 128 bytes

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 QUEUE_COMPUTE_BIT operations

• This command must only be called outside of a render pass instance

• This command must not be called between suspended render pass instances

• 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

'

Conditional Rendering

vkCmdCopyAccelerationStructureToMemoryKHR is not affected by conditional rendering

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

• Any previous deferred operation that was associated with deferredOperation must be complete

• 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

• pInfo->src must not be bound to memory that was allocated with multiple instances

• pInfo->src must have been created with createAccelerationStructureKHR

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

• OPERATION_DEFERRED_KHR

• OPERATION_NOT_DEFERRED_KHR

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

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.

The application must also provide any required micromap addresses in the header as described in https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#serialized-as-header.

Valid Usage

• The ::accelerationStructure feature must be enabled

• pInfo->src.deviceAddress must be a valid DeviceAddress

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

• If the serialized acceleration structure in pInfo->src was originally built with a type of ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, pInfo->src.deviceAddress must be aligned to 128 bytes

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 QUEUE_COMPUTE_BIT operations

• This command must only be called outside of a render pass instance

• This command must not be called between suspended render pass instances

• 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

'

Conditional Rendering

vkCmdCopyMemoryToAccelerationStructureKHR is not affected by conditional rendering

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

• 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

• pInfo->dst must be bound to host-visible device memory

• pInfo->dst must be bound to memory that was not allocated with multiple instances

• pInfo->dst must have been created with createAccelerationStructureKHR

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

• OPERATION_DEFERRED_KHR

• OPERATION_NOT_DEFERRED_KHR

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

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.

• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then the value written out is the number of bytes required by the acceleration structure.

• QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR specifies a serialization acceleration structure pointer count query.

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 sum of firstQuery plus accelerationStructureCount must be less than or equal to the number of queries in queryPool

• All acceleration structures in pAccelerationStructures must have been constructed prior to the execution of this command on the device

• 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

• All acceleration structures in pAccelerationStructures must have been built with ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR if queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR

• Each element of pAccelerationStructures must be fully backed by physical memory

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 QUEUE_COMPUTE_BIT operations

• This command must only be called outside of a render pass instance

• This command must not be called between suspended render pass instances

• 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

'

Conditional Rendering

vkCmdWriteAccelerationStructuresPropertiesKHR is not affected by conditional rendering

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

• All acceleration structures in pAccelerationStructures must have been built with ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR if queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR

• Each element of pAccelerationStructures must be fully backed by physical memory

• 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

• Each element of pAccelerationStructures must be bound to host-visible device memory

• Each acceleration structure in pAccelerationStructures must have been created with createAccelerationStructureKHR

• Each element of pAccelerationStructures must be bound to memory that was not allocated with multiple instances

• All acceleration structures in pAccelerationStructures must have been constructed prior to the execution of this command

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_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

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.

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.

Memory does not need to be bound to the underlying buffer when createAccelerationStructureKHR is called.

Valid Usage

• The ::accelerationStructure feature must be enabled

• If AccelerationStructureCreateInfoKHR::deviceAddress is not zero, the accelerationStructureCaptureReplay 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

• The device must have been created with at least 1 queue

Return Codes

Success

• SUCCESS

Failure

• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

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.

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. Similarly, the application cannot build a bottom-level acceleration structure in the same cmdBuildAccelerationStructuresKHR call as the associated micromaps 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.

The input buffers passed to this commands will be referenced by the implementation for the duration of this command’s execution on the device.

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. Micromaps must always 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 future commands, provided proper synchronization is used as described below.

A AccelerationStructureBuildRangeInfoKHR structure is not used when building an acceleration structure with any of the following geometry types, and must be NULL: GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX GEOMETRY_TYPE_MICROMAP_KHR

The required alignment of the device addresses passed in to parameters below might not be provided by the base address of a Buffer created with the correct usage flags and must still be manually aligned by the application code.

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, AccelerationStructureGeometryMicromapDataKHR::data, AccelerationStructureGeometryMicromapDataKHR::triangleArray, AccelerationStructureDenseGeometryFormatTrianglesDataAMDX::compressedData, 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

• Each element of ppBuildRangeInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount AccelerationStructureBuildRangeInfoKHR structures if the pInfos[i].type is not one of:

  • GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX

  • ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR

• For each element of pInfos[i] whose pGeometries or ppGeometries members have a geometryType of GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, ppBuildRangeInfos[i] must be NULL

• For each element of pInfos[i] whose pGeometries or ppGeometries members have a geometryType of GEOMETRY_TYPE_MICROMAP_KHR, ppBuildRangeInfos[i] must be NULL

• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, its mode must equal BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR

• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, its srcAccelerationStructure must be NULL_HANDLE

• For each element of pInfos, if its type member is ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, its dstAccelerationStructure member must have been created with a value of AccelerationStructureCreateInfoKHR::type equal to either ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR or ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

• The dstAccelerationStructure member of any element of pInfos must not be referenced by any AccelerationStructureTrianglesOpacityMicromapKHR::micromap member included in the pNext chain of any geometry.triangles member of any element of pGeometries or ppGeometries 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 any AccelerationStructureTrianglesOpacityMicromapKHR::micromap member included in the pNext chain of any geometry.triangles member of any element of pGeometries or ppGeometries in any other element of pInfos, which is accessed by this command

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries, if it includes a AccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, its data and triangleArray members must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries, if it includes a AccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, the buffers from which the buffer device addresses for its data and triangleArray members are queried must have been created with the BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR usage flag

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries, if it includes a AccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, its data and triangleArray members must be a multiple of 128

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries, if it includes a AccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, each element of its triangleArray member must specify an access within the range of the Buffer that data was retrieved from, given by [dataOffset, dataOffset triangleSize] where triangleSize is calculated using its format and subdivisionLevel members rounded up to the nearest byte

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries, if it includes a AccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, the range of [triangleArray, triangleArray + (triangleArrayStride * numTriangles)] must be within the range of the Buffer from which the triangleArray member was retrieved from, where numTriangles is the sum of count of all elements of pUsageCounts or ppUsageCounts

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries, if it includes a AccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, each element of its geometry.triangleArray member must have a format with a valid value from OpacityMicromapFormatKHR

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries, if it includes a AccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, for each element of its triangleArray member with a format equal to OPACITY_MICROMAP_FORMAT_2_STATE_KHR, subdivisionLevel must be less than or equal to maxOpacity2StateSubdivisionLevel

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType equal to GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles member includes a AccelerationStructureTrianglesOpacityMicromapKHR structure in its pNext chain, the micromap’s indexType member is not INDEX_TYPE_NONE_KHR, and micromap is not NULL_HANDLE, for each index in indexBuffer[j] greater than zero where j is within the range [0, numTrianglesInGeometry - 1] where numTrianglesInGeometry is equal to ppBuildRangeInfos[i]→primitiveCount, index plus baseTriangle must be less than or equal to numTriangles, where numTriangles is given by the sum of all count parameters in the pUsageCounts or ppUsageCounts provided to the micromap’s build command

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType equal to GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles member includes a AccelerationStructureTrianglesOpacityMicromapKHR structure in its pNext chain, and the micromap’s indexType member is not INDEX_TYPE_NONE_KHR, indexBuffer (indexStride * numTrianglesInGeometry) must be within the range of the Buffer from which the indexBuffer device address was obtained from where numTrianglesInGeometry is equal to ppBuildRangeInfos[i]→primitiveCount

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType equal to GEOMETRY_TYPE_TRIANGLES_KHR, if its geometry.triangles member includes a AccelerationStructureTrianglesOpacityMicromapKHR structure in its pNext chain, the micromap’s indexType member is not INDEX_TYPE_NONE_KHR, and micromap is NULL_HANDLE, for each index in indexBuffer[j] where j is within the range from [0, numTrianglesInGeometry - 1], index must be a valid OpacityMicromapSpecialIndexKHR value where numTrianglesInGeometry is equal to ppBuildRangeInfos[i]→primitiveCount

• 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

• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, srcAccelerationStructure must be fully backed by physical memory

• 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, its dstAccelerationStructure member must be fully backed by physical memory

• 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

• For each element of pInfos, if an acceleration structure is referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, it must be fully backed by physical memory

• 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numTriangles member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numVertices member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxPrimitiveIndex member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxGeometryIndex member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the format member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the dataSize member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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, 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 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, the primitiveCount member of its corresponding AccelerationStructureBuildRangeInfoKHR structure 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

• If pInfos[i].mode is BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, and N is not 0, 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, and N is not 0, 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 set

• If pInfos[i].mode is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, and the size reported by updateScratchSize member of the AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count is non-zero, pInfos[i].scratchData.deviceAddress must be a device address allocated to the application from a buffer created with the BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag set

• If pInfos[i].mode is BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, and the size reported by buildScratchSize member of the AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count is non-zero, pInfos[i].scratchData.deviceAddress must be a device address allocated to the application from a buffer created with the BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag set

• For each element of pInfos, its scratchData.deviceAddress member must be a multiple of PhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment

• For each 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 DeviceAddress

• For each 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 of the format specified in vertexFormat, in bytes, if that format is a packed format

  • the component size of the format specified in vertexFormat, in bytes, if that format is not a packed format

• For each 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 DeviceAddress

• For each 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 each 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 DeviceAddress

• For each 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 each 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 DeviceAddress

• For each 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 each 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 each 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 each 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 each 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 DeviceAddress

• For each 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 0 or a value obtained from getAccelerationStructureDeviceAddressKHR for a valid bottom level acceleration structure

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, if GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_KHR is set in AccelerationStructureInstanceKHR::flags then geometry.instances.data.deviceAddress must refer to an acceleration structure that was built with BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_KHR set in AccelerationStructureBuildGeometryInfoKHR::flags

• commandBuffer must not be a protected command buffer

• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapKHR in the geometry.triangles.pNext chain with a valid micromap member, then the micromap member must have been constructed prior to this command’s execution on the device

• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapKHR in the geometry.triangles.pNext chain with a valid micromap member, then the micromap member must have been built with a type of ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR

• 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 the same geometry in the original build of srcAccelerationStructure was built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain with a valid micromap member, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must be included in the in the geometry.triangles.pNext chain with a valid micromap member

• 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 the same geometry in the original build of srcAccelerationStructure was built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain with its micromap member equal to NULL_HANDLE, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must be included in the in the geometry.triangles.pNext chain with its micromap member equal to NULL_HANDLE

• 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 the same geometry in the original build of srcAccelerationStructure was not built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must not be included in the in the geometry.triangles.pNext chain

• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure was originally built without the BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR flag, and srcAccelerationStructure was constructed by deserialization with cmdCopyMemoryToAccelerationStructureKHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, and the same geometry in the original build of srcAccelerationStructure was built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain with a valid micromap member, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must be included in the in the geometry.triangles.pNext chain with a micromap that was deserialized from the serialized data of the micromap in the original build of srcAccelerationStructure

• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure was originally built without either the BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT or the BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR flags, and srcAccelerationStructure was not constructed by deserialization with cmdCopyMemoryToAccelerationStructureKHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, and the same geometry in the original build of srcAccelerationStructure was built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain with a valid micromap member, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must be included in the in the geometry.triangles.pNext chain with the same micromap handle as the original build

• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapEXT in the geometry.triangles.pNext chain, then its micromap member must have been constructed prior to this command’s execution on the device

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapEXT in the geometry.triangles.pNext chain, and its indexType is INDEX_TYPE_NONE_KHR, then its indexBuffer.deviceAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapEXT in the geometry.triangles.pNext chain, and its indexType is not INDEX_TYPE_NONE_KHR, then its indexBuffer.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, if AccelerationStructureGeometrySpheresDataNV::indexType is INDEX_TYPE_NONE_KHR, then its indexData.deviceAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, if AccelerationStructureGeometrySpheresDataNV::indexType is not INDEX_TYPE_NONE_KHR, then its indexData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, AccelerationStructureGeometrySpheresDataNV::vertexData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, AccelerationStructureGeometrySpheresDataNV::radiusData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, if AccelerationStructureGeometryLinearSweptSpheresDataNV::indexType is INDEX_TYPE_NONE_KHR, then its indexData.deviceAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, if AccelerationStructureGeometryLinearSweptSpheresDataNV::indexType is not INDEX_TYPE_NONE_KHR, then its indexData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, AccelerationStructureGeometryLinearSweptSpheresDataNV::vertexData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, AccelerationStructureGeometryLinearSweptSpheresDataNV::radiusData.deviceAddress must be a valid DeviceAddress

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

  • 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) or,

  • the result of querying the corresponding QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, if updating a compacted acceleration structure

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureGeometryMotionTrianglesDataNV in the geometry.triangles.pNext chain, then its vertexData.deviceAddress must be a valid DeviceAddress

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 QUEUE_COMPUTE_BIT operations

• This command must only be called outside of a render pass instance

• This command must not be called between suspended render pass instances

• 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

'

Conditional Rendering

vkCmdBuildAccelerationStructuresKHR is not affected by conditional rendering

See Also

VK_KHR_acceleration_structure, AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureBuildRangeInfoKHR, CommandBuffer

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

Description

Accesses to any device memory referenced by this command 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

• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, srcAccelerationStructure must be fully backed by physical memory

• 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, its dstAccelerationStructure member must be fully backed by physical memory

• 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

• For each element of pInfos, if an acceleration structure is referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, it must be fully backed by physical memory

• 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numTriangles member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numVertices member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxPrimitiveIndex member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxGeometryIndex member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the format member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the dataSize member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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, 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 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, the primitiveCount member of its corresponding AccelerationStructureBuildRangeInfoKHR structure 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

• If pInfos[i].mode is BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, and N is not 0, 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, and N is not 0, 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 set

• If pInfos[i].mode is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, and the size reported by updateScratchSize member of the AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count is non-zero, pInfos[i].scratchData.deviceAddress must be a device address allocated to the application from a buffer created with the BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag set

• If pInfos[i].mode is BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, and the size reported by buildScratchSize member of the AccelerationStructureBuildSizesInfoKHR structure returned from a call to getAccelerationStructureBuildSizesKHR with an identical AccelerationStructureBuildGeometryInfoKHR structure and primitive count is non-zero, pInfos[i].scratchData.deviceAddress must be a device address allocated to the application from a buffer created with the BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag set

• For each element of pInfos, its scratchData.deviceAddress member must be a multiple of PhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment

• For each 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 DeviceAddress

• For each 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 of the format specified in vertexFormat, in bytes, if that format is a packed format

  • the component size of the format specified in vertexFormat, in bytes, if that format is not a packed format

• For each 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 DeviceAddress

• For each 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 each 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 DeviceAddress

• For each 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 each 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 DeviceAddress

• For each 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 each 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 each 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 each 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 each 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 DeviceAddress

• For each 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 0 or a value obtained from getAccelerationStructureDeviceAddressKHR for a valid bottom level acceleration structure

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, if GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_KHR is set in AccelerationStructureInstanceKHR::flags then geometry.instances.data.deviceAddress must refer to an acceleration structure that was built with BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_KHR set in AccelerationStructureBuildGeometryInfoKHR::flags

• commandBuffer must not be a protected command buffer

• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapKHR in the geometry.triangles.pNext chain with a valid micromap member, then the micromap member must have been constructed prior to this command’s execution on the device

• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapKHR in the geometry.triangles.pNext chain with a valid micromap member, then the micromap member must have been built with a type of ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR

• 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 the same geometry in the original build of srcAccelerationStructure was built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain with a valid micromap member, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must be included in the in the geometry.triangles.pNext chain with a valid micromap member

• 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 the same geometry in the original build of srcAccelerationStructure was built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain with its micromap member equal to NULL_HANDLE, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must be included in the in the geometry.triangles.pNext chain with its micromap member equal to NULL_HANDLE

• 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 the same geometry in the original build of srcAccelerationStructure was not built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must not be included in the in the geometry.triangles.pNext chain

• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure was originally built without the BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR flag, and srcAccelerationStructure was constructed by deserialization with cmdCopyMemoryToAccelerationStructureKHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, and the same geometry in the original build of srcAccelerationStructure was built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain with a valid micromap member, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must be included in the in the geometry.triangles.pNext chain with a micromap that was deserialized from the serialized data of the micromap in the original build of srcAccelerationStructure

• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, its srcAccelerationStructure was originally built without either the BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT or the BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR flags, and srcAccelerationStructure was not constructed by deserialization with cmdCopyMemoryToAccelerationStructureKHR, then for each AccelerationStructureGeometryKHR structure referred to by its pGeometries or ppGeometries members, if geometryType is GEOMETRY_TYPE_TRIANGLES_KHR, and the same geometry in the original build of srcAccelerationStructure was built with an instance of AccelerationStructureTrianglesOpacityMicromapKHR in its geometry.triangles.pNext chain with a valid micromap member, then an instance of AccelerationStructureTrianglesOpacityMicromapKHR must be included in the in the geometry.triangles.pNext chain with the same micromap handle as the original build

• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapEXT in the geometry.triangles.pNext chain, then its micromap member must have been constructed prior to this command’s execution on the device

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapEXT in the geometry.triangles.pNext chain, and its indexType is INDEX_TYPE_NONE_KHR, then its indexBuffer.deviceAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapEXT in the geometry.triangles.pNext chain, and its indexType is not INDEX_TYPE_NONE_KHR, then its indexBuffer.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, if AccelerationStructureGeometrySpheresDataNV::indexType is INDEX_TYPE_NONE_KHR, then its indexData.deviceAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, if AccelerationStructureGeometrySpheresDataNV::indexType is not INDEX_TYPE_NONE_KHR, then its indexData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, AccelerationStructureGeometrySpheresDataNV::vertexData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, AccelerationStructureGeometrySpheresDataNV::radiusData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, if AccelerationStructureGeometryLinearSweptSpheresDataNV::indexType is INDEX_TYPE_NONE_KHR, then its indexData.deviceAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, if AccelerationStructureGeometryLinearSweptSpheresDataNV::indexType is not INDEX_TYPE_NONE_KHR, then its indexData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, AccelerationStructureGeometryLinearSweptSpheresDataNV::vertexData.deviceAddress must be a valid DeviceAddress

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, AccelerationStructureGeometryLinearSweptSpheresDataNV::radiusData.deviceAddress must be a valid DeviceAddress

• For each 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 each element of pIndirectDeviceAddresses, the buffer from which it was queried must have been created with the BUFFER_USAGE_INDIRECT_BUFFER_BIT usage flag set

• Each element of pIndirectDeviceAddresses must be a multiple of 4

• Each element of pIndirectStrides must be a multiple of 4

• 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])

• For any element of pInfos, its type member must not be ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR

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 QUEUE_COMPUTE_BIT operations

• This command must only be called outside of a render pass instance

• This command must not be called between suspended render pass instances

• 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

'

Conditional Rendering

vkCmdBuildAccelerationStructuresIndirectKHR is not affected by conditional rendering

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.

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

• For each element of pInfos, if its mode member is BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, srcAccelerationStructure must be fully backed by physical memory

• 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, its dstAccelerationStructure member must be fully backed by physical memory

• 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

• For each element of pInfos, if an acceleration structure is referenced by the geometry.instances.data member of any element of pGeometries or ppGeometries with a geometryType of GEOMETRY_TYPE_INSTANCES_KHR, it must be fully backed by physical memory

• 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numTriangles member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numVertices member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxPrimitiveIndex member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxGeometryIndex member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the format member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the dataSize member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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, 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 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, the primitiveCount member of its corresponding AccelerationStructureBuildRangeInfoKHR structure 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 either:

  • 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) or,

  • the result of querying the corresponding QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, if updating a compacted acceleration structure

• Any previous deferred operation that was associated with deferredOperation must be complete

• Each element of ppBuildRangeInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount AccelerationStructureBuildRangeInfoKHR structures

• For each element of pInfos, its dstAccelerationStructure member must have been created with createAccelerationStructureKHR

• For each element of pInfos, 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, its srcAccelerationStructure member must have been created with createAccelerationStructureKHR

• 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 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 have been created with createAccelerationStructureKHR

• For each element of pInfos, 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, and N is not 0, 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, and N is not 0, 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 each 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 each 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 each 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 each 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, 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, 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 each 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 each 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 each 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

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureGeometryMotionTrianglesDataNV in the geometry.triangles.pNext chain, then its vertexData.hostAddress must not be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapEXT in the geometry.triangles.pNext chain, and its indexType is INDEX_TYPE_NONE_KHR, then its indexBuffer.hostAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapEXT in the geometry.triangles.pNext chain, and its indexType is not INDEX_TYPE_NONE_KHR, then its indexBuffer.hostAddress must not be 0

• For any element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR, if there is an instance of AccelerationStructureTrianglesOpacityMicromapKHR in the geometry.triangles.pNext chain its micromap member must be NULL_HANDLE

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, AccelerationStructureGeometrySpheresDataNV::indexType is INDEX_TYPE_NONE_KHR, then its indexData.hostAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, AccelerationStructureGeometrySpheresDataNV::indexType is not INDEX_TYPE_NONE_KHR, then its indexData.hostAddress must not be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, AccelerationStructureGeometrySpheresDataNV::vertexData.hostAddress must not be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_SPHERES_NV, AccelerationStructureGeometrySpheresDataNV::radiusData.hostAddress must not be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, AccelerationStructureGeometryLinearSweptSpheresDataNV::indexType is INDEX_TYPE_NONE_KHR, then its indexData.hostAddress must be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, AccelerationStructureGeometryLinearSweptSpheresDataNV::indexType is not INDEX_TYPE_NONE_KHR, then its indexData.hostAddress must not be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, AccelerationStructureGeometryLinearSweptSpheresDataNV::vertexData.hostAddress must not be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries with a geometryType of GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV, AccelerationStructureGeometryLinearSweptSpheresDataNV::radiusData.hostAddress must not be 0

• For each element of pInfos[i].pGeometries or pInfos[i].ppGeometries, geometryType must not be GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX

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

• OPERATION_DEFERRED_KHR

• OPERATION_NOT_DEFERRED_KHR

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_acceleration_structure, AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureBuildRangeInfoKHR, DeferredOperationKHR, Device

vkGetAccelerationStructureDeviceAddressKHR - Query an address of an 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 createAccelerationStructure2KHR, the return value will be the same address as addressRange.address.

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

Otherwise, 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.

For acceleration structures created with createAccelerationStructureKHR, their 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

• If the buffer on which pInfo->accelerationStructure was placed is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object

• The buffer on which pInfo->accelerationStructure was placed must have been created with the BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT usage flag set

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, DeviceOrHostAddressConstKHR, or DeviceAddress 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 element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to GEOMETRY_TYPE_MICROMAP_KHR, the sum of usage information in either the pUsageCounts or ppUsageCounts members of the AccelerationStructureGeometryMicromapDataKHR structure in its pNext chain is equal to the sum of usage information in the corresponding members of pBuild info.

  • 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 AccelerationStructureTrianglesOpacityMicromapKHR the corresponding member of pBuildInfo also contains AccelerationStructureTrianglesOpacityMicromapKHR 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numTriangles member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numVertices member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxPrimitiveIndex member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxGeometryIndex member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain 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_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the format member of the AccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain is equal to the corresponding member of the same element in pBuildInfo

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

• For each AccelerationStructureBuildRangeInfoKHR corresponding to the AccelerationStructureBuildGeometryInfoKHR:

  • Its primitiveCount member is less than or equal to the corresponding element of pMaxPrimitiveCounts.

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 and pBuildInfo->type is not ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR , pMaxPrimitiveCounts must be a valid pointer to an array of pBuildInfo->geometryCount uint32_t values

• If pBuildInfo->type is ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, pMaxPrimitiveCounts must equal NULL

• If pBuildInfo->type is ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, buildType must equal ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR

• 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

• 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

Structure Chaining

Extends the structure

• WriteDescriptorSet

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. If the application wishes to use a Device with any features described by PhysicalDeviceAccelerationStructureFeaturesKHR, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

• DeviceCreateInfo

• PhysicalDeviceFeatures2

See Also

VK_KHR_acceleration_structure, Bool32, StructureType