vkCmdBuildClusterAccelerationStructureIndirectNV(3)

# vkCmdBuildClusterAccelerationStructureIndirectNV(3) Manual Page

## Name

vkCmdBuildClusterAccelerationStructureIndirectNV - Build or move cluster acceleration structures

Loading… please wait.

## C Specification

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

    // Provided by VK_NV_cluster_acceleration_structure
    void vkCmdBuildClusterAccelerationStructureIndirectNV(
        VkCommandBuffer                             commandBuffer,
        const VkClusterAccelerationStructureCommandsInfoNV* pCommandInfos);

## Parameters

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

## Description

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::`dstSizesArray` must 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::`srcInfosCount` must 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->srcInfosArray` must 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

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Outside | Outside | VK_QUEUE_COMPUTE_BIT | Action

Conditional Rendering

vkCmdBuildClusterAccelerationStructureIndirectNV is not affected by conditional rendering

## See Also

VK_NV_cluster_acceleration_structure, VkClusterAccelerationStructureCommandsInfoNV, VkCommandBuffer

## Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0