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

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

SPDX-License-Identifier: CC-BY-4.0