Function Prototype

vkCmdBuildClusterAccelerationStructureIndirectNV

Build or move cluster acceleration structures
primary / secondary
outside
compute
action

To build or move a cluster acceleration structure or a cluster acceleration structure template call:

void vkCmdBuildClusterAccelerationStructureIndirectNV(
    VkCommandBuffer                     commandBuffer,
    const VkClusterAccelerationStructureCommandsInfoNV*  pCommandInfos);
  • commandBuffer is the command buffer into which the command is recorded.
  • pCommandInfos is a pointer to a VkClusterAccelerationStructureCommandsInfoNV structure containing parameters required for building or moving the cluster acceleration structure.

Similar to vkCmdBuildAccelerationStructuresKHR, this command may initiate multiple acceleration structures builds and there is no ordering or synchronization implied between any of the individual acceleration structure builds. Accesses to the acceleration structure scratch memory as identified by the VkClusterAccelerationStructureCommandsInfoNV::scratchData must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

pipeline stage and an access type of (VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR | VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR).

Accesses to each VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData, VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray and VkClusterAccelerationStructureCommandsInfoNV::dstSizesArraymust be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.

Accesses to memory with input data as identified by any used values of VkClusterAccelerationStructureCommandsInfoNV::srcInfosArray, VkClusterAccelerationStructureCommandsInfoNV::srcInfosCount and VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlagsmust be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

pipeline stage and an access type of VK_ACCESS_INDIRECT_COMMAND_READ_BIT.

Valid Usage

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10445

pCommandInfos→input::maxAccelerationStructureCount must be less than or equal to the value used in pInfo→maxAccelerationStructureCount in vkGetClusterAccelerationStructureBuildSizesNV to determine the memory requirements for the build operation

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-scratchData-10446

The scratch memory of the cluster acceleration structure specified in VkClusterAccelerationStructureCommandsInfoNV::scratchDatamust be larger than or equal to the scratch size queried with vkGetClusterAccelerationStructureBuildSizesNV

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-scratchData-10447

The scratch address of the cluster acceleration structure specified in VkClusterAccelerationStructureCommandsInfoNV::scratchDatamust be aligned based on the cluster acceleration structure type and its alignment properties as queried with VkPhysicalDeviceClusterAccelerationStructurePropertiesNV

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10448

If pCommandInfos→input::opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NV, pCommandInfos→srcInfosArray must be an array of VkClusterAccelerationStructureMoveObjectsInfoNV structures

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10449

If pCommandInfos→input::opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_CLUSTERS_BOTTOM_LEVEL_NV, pCommandInfos→srcInfosArray must be an array of VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV structures

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10450

If pCommandInfos→input::opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_NV, pCommandInfos→srcInfosArray must be an array of VkClusterAccelerationStructureBuildTriangleClusterInfoNV structures

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10451

If pCommandInfos→input::opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_TEMPLATE_NV, pCommandInfos→srcInfosArray must be an array of VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV structures

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10452

If pCommandInfos→input::opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_INSTANTIATE_TRIANGLE_CLUSTER_NV, pCommandInfos→srcInfosArray must be an array of VkClusterAccelerationStructureInstantiateClusterInfoNV structures

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10453

The value in pCommandInfos→srcInfosCount must be less than or equal to pCommandInfos→input::maxAccelerationStructureCount

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10454

The number of inputs specified in pCommandInfos→srcInfosArraymust be greater than or equal to pCommandInfos→srcInfosCount

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-dstAddressesArray-10455

The memory regions specified in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArraymust not overlap with each other or with pCommandInfos→scratchData

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-dstImplicitData-10456

The memory region specified in VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData for multiple acceleration structure builds must not overlap with pCommandInfos→scratchData

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10457

The buffer from which the buffer device address for pCommandInfos→scratchData is queried must have been created with the VK_BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10458

The buffers from which the buffer device addresses for pCommandInfos→srcInfosArray, pCommandInfos→srcInfosCount and pCommandInfos→addressResolutionFlags are queried must have been created with the VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR usage flag

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10459

The buffers from which the buffer device addresses for pCommandInfos→dstImplicitData and pCommandInfos→dstAddressesArray are queried must have been created with the VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR usage flag

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10460

If pCommandInfos→dstImplicitData is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10461

If pCommandInfos→scratchData is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10462

If pCommandInfos→srcInfosCount is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10463

If the addresses specified in pCommandInfos→dstAddressesArray are the address of a non-sparse buffer then they each must be bound completely and contiguously to a single VkDeviceMemory object

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10464

If the addresses specified in pCommandInfos→dstSizesArray are the address of a non-sparse buffer then they each must be bound completely and contiguously to a single VkDeviceMemory object

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-10465

If the addresses specified in pCommandInfos→srcInfosArray are the address of a non-sparse buffer then they each must be bound completely and contiguously to a single VkDeviceMemory object

Valid Usage (Implicit)

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support compute operations

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-renderpass

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

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-videocoding

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 VkCommandPool that commandBuffer was allocated from must be externally synchronized ::