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`, VkClusterAccelerationStructureCommandsInfoNV::`srcInfosCount` and VkClusterAccelerationStructureCommandsInfoNV::`addressResolutionFlags` 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-10446
  The scratch memory of the cluster acceleration structure specified in VkClusterAccelerationStructureCommandsInfoNV::`scratchData` must 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::`scratchData` 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-10455
  The memory regions specified in VkClusterAccelerationStructureCommandsInfoNV::`dstAddressesArray` must 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-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 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

Command Properties

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

## 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-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0