VulkanHub
Function Prototype

vkCmdBuildClusterAccelerationStructureIndirectNV

Build or move cluster acceleration structures

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 and VkClusterAccelerationStructureCommandsInfoNV::srcInfosCountmust 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-clusterAccelerationStructure-10443

The VkPhysicalDeviceClusterAccelerationStructureFeaturesNV::clusterAccelerationStructure feature must be enabled

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pNext-10444

The pNext chain of the bound ray tracing pipeline must include a VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV structure

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

The scratch memory of the cluster acceleration structure specified in VkClusterAccelerationStructureCommandsInfoNV::scratchData, or the memory indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::scratchData when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NV, must be larger than or equal to the scratch size queried with vkGetClusterAccelerationStructureBuildSizesNV

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-scratchData-12301

The scratch address of the cluster acceleration structure specified in VkClusterAccelerationStructureCommandsInfoNV::scratchData, or the address indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::scratchData when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NV, must 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-10832

If pCommandInfos→input.opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_GET_CLUSTER_TEMPLATE_INDICES_NV, pCommandInfos→srcInfosArray must be an array of VkClusterAccelerationStructureGetTemplateIndicesInfoNV 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-12302

The memory regions specified in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray, or the memory indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV, must not overlap with each other or with pCommandInfos→scratchData, or the memory indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::scratchData when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NV

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-dstImplicitData-12303

The memory region specified in VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData, or the memory indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_IMPLICIT_DATA_BIT_NV, for multiple acceleration structure builds must not overlap with pCommandInfos→scratchData, or the memory indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::scratchData when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NV

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-12304

pCommandInfos→scratchData, or the address indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::scratchData when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NV, must be a device address allocated to the application from a buffer created with the VK_BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag set

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-12305

pCommandInfos→srcInfosArray, or the address indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::srcInfosArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_ARRAY_BIT_NV, must be a device address range allocated to the application from a buffer created with the VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR usage flag set

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-12306

pCommandInfos→srcInfosCount, or the address indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::srcInfosCount when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_COUNT_BIT_NV, must be a device address allocated to the application from a buffer created with the VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR usage flag set

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-12307

pCommandInfos→dstAddressesArray, or the address indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV, must be a device address range allocated to the application from a buffer created with the VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR usage flag set

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-12308

pCommandInfos→dstImplicitData, or the address indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_IMPLICIT_DATA_BIT_NV, must be a device address allocated to the application from a buffer created with the VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR usage flag set

Valid Usage (Implicit)

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-commandBuffer-parameter

commandBuffer must be a valid VkCommandBuffer handle

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-pCommandInfos-parameter

pCommandInfos must be a valid pointer to a valid VkClusterAccelerationStructureCommandsInfoNV structure

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-commandBuffer-recording

commandBuffer must be in the recording state

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT operations

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-renderpass

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

VUID-vkCmdBuildClusterAccelerationStructureIndirectNV-suspended

This command must not be called between suspended render pass instances

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