vkGetAccelerationStructureBuildSizesKHR(3)

C Specification

To get the build sizes for an acceleration structure, call:

// Provided by VK_KHR_acceleration_structure
void vkGetAccelerationStructureBuildSizesKHR(
    VkDevice                                    device,
    VkAccelerationStructureBuildTypeKHR         buildType,
    const VkAccelerationStructureBuildGeometryInfoKHR* pBuildInfo,
    const uint32_t*                             pMaxPrimitiveCounts,
    VkAccelerationStructureBuildSizesInfoKHR*   pSizeInfo);

Parameters

device is the logical device that will be used for creating the acceleration structure.
buildType defines whether host or device operations (or both) are being queried for.
pBuildInfo is a pointer to a VkAccelerationStructureBuildGeometryInfoKHR structure describing parameters of a build operation.
pMaxPrimitiveCounts is a pointer to an array of pBuildInfo->geometryCount uint32_t values defining the number of primitives built into each geometry.
pSizeInfo is a pointer to a VkAccelerationStructureBuildSizesInfoKHR structure which returns the size required for an acceleration structure and the sizes required for the scratch buffers, given the build parameters. The size requirements for a scratch buffer may be zero.

Description

The srcAccelerationStructure, dstAccelerationStructure, and mode members of pBuildInfo are ignored. Any VkDeviceOrHostAddressKHR or VkDeviceOrHostAddressConstKHR members of pBuildInfo are ignored by this command, except that the hostAddress member of VkAccelerationStructureGeometryTrianglesDataKHR::transformData will be examined to check if it is NULL.

An acceleration structure created with the accelerationStructureSize returned by this command supports any build or update with a VkAccelerationStructureBuildGeometryInfoKHR structure and array of VkAccelerationStructureBuildRangeInfoKHR structures subject to the following properties:

The build command is a host build command, and buildType is VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR
The build command is a device build command, and buildType is VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR
For VkAccelerationStructureBuildGeometryInfoKHR:
- Its type, and flags members are equal to pBuildInfo->type and pBuildInfo->flags, respectively.
- geometryCount is less than or equal to pBuildInfo->geometryCount.
- For each element of either pGeometries or ppGeometries at a given index, its geometryType member is equal to pBuildInfo->geometryType.
- For each element of either pGeometries or ppGeometries at a given index, its flags member is equal to the corresponding member of the same element in pBuildInfo.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, the vertexFormat and indexType members of geometry.triangles are equal to the corresponding members of the same element in pBuildInfo.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, the maxVertex member of geometry.triangles is less than or equal to the corresponding member of the same element in pBuildInfo.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the applicable address in the transformData member of geometry.triangles is not NULL, the corresponding transformData.hostAddress parameter in pBuildInfo is not NULL.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numTriangles member of the VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain is less than or equal to the corresponding member of the same element in pBuildInfo
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the numVertices member of the VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain is less than or equal to the corresponding member of the same element in pBuildInfo
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxPrimitiveIndex member of the VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain is less than or equal to the corresponding member of the same element in pBuildInfo
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the maxGeometryIndex member of the VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain is less than or equal to the corresponding member of the same element in pBuildInfo
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, the format member of the VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX structure in the pNext chain is equal to the corresponding member of the same element in pBuildInfo
For each VkAccelerationStructureBuildRangeInfoKHR corresponding to the VkAccelerationStructureBuildGeometryInfoKHR:
- Its primitiveCount member is less than or equal to the corresponding element of pMaxPrimitiveCounts.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the pNext chain contains VkAccelerationStructureTrianglesOpacityMicromapEXT the corresponding member of pBuildInfo also contains VkAccelerationStructureTrianglesOpacityMicromapEXT and with an equivalent micromap.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the pNext chain contains VkAccelerationStructureTrianglesDisplacementMicromapNV the corresponding member of pBuildInfo also contains VkAccelerationStructureTrianglesDisplacementMicromapNV and with an equivalent micromap.
For each VkAccelerationStructureBuildRangeInfoKHR corresponding to the VkAccelerationStructureBuildGeometryInfoKHR:
- Its primitiveCount member is less than or equal to the corresponding element of pMaxPrimitiveCounts.

Similarly, the updateScratchSize value will support any build command specifying the VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR mode under the above conditions, and the buildScratchSize value will support any build command specifying the VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR mode under the above conditions.

Valid Usage

VUID-vkGetAccelerationStructureBuildSizesKHR-accelerationStructure-08933
The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructure feature must be enabled
VUID-vkGetAccelerationStructureBuildSizesKHR-device-03618
If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled
VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03619
If pBuildInfo->geometryCount is not 0, pMaxPrimitiveCounts must be a valid pointer to an array of pBuildInfo->geometryCount uint32_t values
VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03785
If pBuildInfo->pGeometries or pBuildInfo->ppGeometries has a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, each pMaxPrimitiveCounts[i] must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount

Valid Usage (Implicit)

VUID-vkGetAccelerationStructureBuildSizesKHR-device-parameter
device must be a valid VkDevice handle
VUID-vkGetAccelerationStructureBuildSizesKHR-buildType-parameter
buildType must be a valid VkAccelerationStructureBuildTypeKHR value
VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-parameter
pBuildInfo must be a valid pointer to a valid VkAccelerationStructureBuildGeometryInfoKHR structure
VUID-vkGetAccelerationStructureBuildSizesKHR-pMaxPrimitiveCounts-parameter
If pMaxPrimitiveCounts is not NULL, pMaxPrimitiveCounts must be a valid pointer to an array of pBuildInfo->geometryCount uint32_t values
VUID-vkGetAccelerationStructureBuildSizesKHR-pSizeInfo-parameter
pSizeInfo must be a valid pointer to a VkAccelerationStructureBuildSizesInfoKHR structure

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

SPDX-License-Identifier: CC-BY-4.0

vkGetAccelerationStructureBuildSizesKHR(3) Manual Page

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright