VkClusterAccelerationStructureCommandsInfoNV(3)

Name

VkClusterAccelerationStructureCommandsInfoNV - Structure describing parameters for building for moving an acceleration structure

C Specification

The VkClusterAccelerationStructureCommandsInfoNV structure is defined as:

// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureCommandsInfoNV {
    VkStructureType                                           sType;
    void*                                                     pNext;
    VkClusterAccelerationStructureInputInfoNV                 input;
    VkDeviceAddress                                           dstImplicitData;
    VkDeviceAddress                                           scratchData;
    VkStridedDeviceAddressRegionKHR                           dstAddressesArray;
    VkStridedDeviceAddressRegionKHR                           dstSizesArray;
    VkStridedDeviceAddressRegionKHR                           srcInfosArray;
    VkDeviceAddress                                           srcInfosCount;
    VkClusterAccelerationStructureAddressResolutionFlagsNV    addressResolutionFlags;
} VkClusterAccelerationStructureCommandsInfoNV;

Members

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
input is VkClusterAccelerationStructureInputInfoNV structure describing the build or move parameters for the cluster acceleration structure.
dstImplicitData is the device address for memory where the implicit build of cluster acceleration structure will be saved. If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV or VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, this value is ignored.
scratchData is the device address of scratch memory that will be used during cluster acceleration structure move or build.
dstAddressesArray is a VkStridedDeviceAddressRegionKHR that specifies addresses and stride for moved or built cluster acceleration structures, depending on the value of VkClusterAccelerationStructureInputInfoNV::opMode. If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV and VkStridedDeviceAddressRegionKHR::deviceAddress is not 0, then the implementation writes the cluster addresses to the specified region. If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, the implementation reads the cluster addresses from the specified region. If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, this member is ignored.
dstSizesArray is a VkStridedDeviceAddressRegionKHR containing sizes of moved or built cluster acceleration structures. If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV or VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, then the sizes are saved. If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, then the sizes are read from.
srcInfosArray is a VkStridedDeviceAddressRegionKHR where input data for the build or move operation is read from. If the stride is 0, the structures are assumed to be packed tightly. Its format is dependent on VkClusterAccelerationStructureInputInfoNV::opType as per the table below.

input.opType

Format of srcInfosArray

VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NV

VkClusterAccelerationStructureMoveObjectsInfoNV

VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_CLUSTERS_BOTTOM_LEVEL_NV

VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV

VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_NV

VkClusterAccelerationStructureBuildTriangleClusterInfoNV

VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_TEMPLATE_NV

VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV

VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_INSTANTIATE_TRIANGLE_CLUSTER_NV

VkClusterAccelerationStructureInstantiateClusterInfoNV

VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_GET_CLUSTER_TEMPLATE_INDICES_NV

VkClusterAccelerationStructureGetTemplateIndicesInfoNV

srcInfosCount is the device address of memory containing the count of number of build or move operations to perform. The actual value is the minimum of this value and the value specified in input.maxAccelerationStructureCount. If this value is 0, the count is determined by input.maxAccelerationStructureCount alone.
addressResolutionFlags is a bitmask of VkClusterAccelerationStructureAddressResolutionFlagBitsNV values specifying how an implementation will interpret the device addresses in this structure.

Description

Valid Usage

VUID-VkClusterAccelerationStructureCommandsInfoNV-opMode-12309
If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV, VkClusterAccelerationStructureCommandsInfoNV::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 valid VkDeviceAddress
VUID-VkClusterAccelerationStructureCommandsInfoNV-opMode-12310
If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV and input.opType is not VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NV, the memory 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 must be equal to or larger than the VkAccelerationStructureBuildSizesInfoKHR::accelerationStructureSize value returned from vkGetClusterAccelerationStructureBuildSizesNV with same input parameters
VUID-VkClusterAccelerationStructureCommandsInfoNV-opMode-12311
If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV and input.opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NV, the memory 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, must be equal to or larger than the sum of all the built acceleration structures that are being moved
VUID-VkClusterAccelerationStructureCommandsInfoNV-input-10469
If input.opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NV, the total memory moved must not be larger than the size provided in VkClusterAccelerationStructureMoveObjectsInputNV::maxMovedBytes
VUID-VkClusterAccelerationStructureCommandsInfoNV-opMode-12312
If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, VkClusterAccelerationStructureCommandsInfoNV::dstSizesArray, or the address indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstSizesArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_SIZES_ARRAY_BIT_NV, must be a valid VkDeviceAddress
VUID-VkClusterAccelerationStructureCommandsInfoNV-opMode-12313
If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, the address in VkClusterAccelerationStructureCommandsInfoNV::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 valid VkDeviceAddress
VUID-VkClusterAccelerationStructureCommandsInfoNV-opMode-12314
If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, the addresses 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 be large enough to accommodate built or moved clusters
VUID-VkClusterAccelerationStructureCommandsInfoNV-opMode-12315
If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, the buffers in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray, or the buffers indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV, must not overlap
VUID-VkClusterAccelerationStructureCommandsInfoNV-opMode-12316
If VkClusterAccelerationStructureInputInfoNV::opMode is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, the addresses in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray, or the addresses indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV, must be aligned based on the cluster acceleration structure type and its alignment properties as described in VkPhysicalDeviceClusterAccelerationStructurePropertiesNV
VUID-VkClusterAccelerationStructureCommandsInfoNV-dstAddressesArray-10474
The stride in dstAddressesArray must be greater than or equal to 8
VUID-VkClusterAccelerationStructureCommandsInfoNV-dstSizesArray-10475
The stride in dstSizesArray must be greater than or equal to 4
VUID-VkClusterAccelerationStructureCommandsInfoNV-srcInfosArray-10476
The stride in srcInfosArray must be greater than the type of structure the address is describing
VUID-VkClusterAccelerationStructureCommandsInfoNV-input-12317
If input.opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_NV, then depending on the VkClusterAccelerationStructureInputInfoNV::opMode, VkClusterAccelerationStructureCommandsInfoNV::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, or addresses specified in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray, or the addresses indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV, must be aligned to VkPhysicalDeviceClusterAccelerationStructurePropertiesNV::clusterByteAlignment
VUID-VkClusterAccelerationStructureCommandsInfoNV-input-12318
If input.opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_TEMPLATE_NV, then depending on the VkClusterAccelerationStructureInputInfoNV::opMode, VkClusterAccelerationStructureCommandsInfoNV::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, or addresses specified in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray, or the addresses indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV, must be aligned to VkPhysicalDeviceClusterAccelerationStructurePropertiesNV::clusterTemplateByteAlignment
VUID-VkClusterAccelerationStructureCommandsInfoNV-input-12319
If input.opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_INSTANTIATE_TRIANGLE_CLUSTER_NV, then depending on the VkClusterAccelerationStructureInputInfoNV::opMode, VkClusterAccelerationStructureCommandsInfoNV::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, or addresses specified in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray, or the addresses indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV, must be aligned to VkPhysicalDeviceClusterAccelerationStructurePropertiesNV::clusterByteAlignment
VUID-VkClusterAccelerationStructureCommandsInfoNV-scratchData-12320
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 to VkPhysicalDeviceClusterAccelerationStructurePropertiesNV::clusterScratchByteAlignment
VUID-VkClusterAccelerationStructureCommandsInfoNV-buildScratchSize-12321
If the buildScratchSize member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetClusterAccelerationStructureBuildSizesNV is not 0, then 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 a valid VkDeviceAddress
VUID-VkClusterAccelerationStructureCommandsInfoNV-srcInfosCount-12322
VkClusterAccelerationStructureCommandsInfoNV::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 4-byte aligned
VUID-VkClusterAccelerationStructureCommandsInfoNV-input-12323
If input.opType is VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_CLUSTERS_BOTTOM_LEVEL_NV, the total and per argument number of cluster acceleration structures referenced in VkClusterAccelerationStructureCommandsInfoNV::srcInfosArray, or the structures indirectly referenced in VkClusterAccelerationStructureCommandsInfoNV::srcInfosArray when VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags contains VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_ARRAY_BIT_NV, must be equal or less than the maximum values with which memory requirements were queried in vkGetClusterAccelerationStructureBuildSizesNV with VkClusterAccelerationStructureOpInputNV::pClustersBottomLevel

Valid Usage (Implicit)

VUID-VkClusterAccelerationStructureCommandsInfoNV-sType-sType
sType must be VK_STRUCTURE_TYPE_CLUSTER_ACCELERATION_STRUCTURE_COMMANDS_INFO_NV
VUID-VkClusterAccelerationStructureCommandsInfoNV-pNext-pNext
pNext must be NULL
VUID-VkClusterAccelerationStructureCommandsInfoNV-input-parameter
input must be a valid VkClusterAccelerationStructureInputInfoNV structure
VUID-VkClusterAccelerationStructureCommandsInfoNV-dstImplicitData-parameter
If dstImplicitData is not 0, dstImplicitData must be a valid VkDeviceAddress value
VUID-VkClusterAccelerationStructureCommandsInfoNV-scratchData-parameter
scratchData must be a valid VkDeviceAddress value
VUID-VkClusterAccelerationStructureCommandsInfoNV-srcInfosCount-parameter
If srcInfosCount is not 0, srcInfosCount must be a valid VkDeviceAddress value
VUID-VkClusterAccelerationStructureCommandsInfoNV-addressResolutionFlags-parameter
addressResolutionFlags must be a valid combination of VkClusterAccelerationStructureAddressResolutionFlagBitsNV values

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.