vkBuildAccelerationStructuresKHR(3)

# vkBuildAccelerationStructuresKHR(3) Manual Page

## Name

vkBuildAccelerationStructuresKHR - Build an acceleration structure on the host

Loading… please wait.

## C Specification

To build acceleration structures on the host, call:

    // Provided by VK_KHR_acceleration_structure
    VkResult vkBuildAccelerationStructuresKHR(
        VkDevice                                    device,
        VkDeferredOperationKHR                      deferredOperation,
        uint32_t                                    infoCount,
        const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
        const VkAccelerationStructureBuildRangeInfoKHR* const* ppBuildRangeInfos);

## Parameters

- `device` is the `VkDevice` for which the acceleration structures are being built.

- `deferredOperation` is an optional VkDeferredOperationKHR to request deferral for this command.

- `infoCount` is the number of acceleration structures to build. It specifies the number of the `pInfos` structures and `ppBuildRangeInfos` pointers that must be provided.

- `pInfos` is a pointer to an array of `infoCount` VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure.

- `ppBuildRangeInfos` is a pointer to an array of `infoCount` pointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. Each `ppBuildRangeInfos`[i] is a pointer to an array of `pInfos`[i].`geometryCount` VkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by `pInfos`[i].

## Description

This command fulfills the same task as vkCmdBuildAccelerationStructuresKHR but is executed by the host.

The `vkBuildAccelerationStructuresKHR` command provides the ability to initiate multiple acceleration structures builds, however there is no ordering or synchronization implied between any of the individual acceleration structure builds.

| Note This means that an application cannot build a top-level acceleration structure in the same vkBuildAccelerationStructuresKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds.

Valid Usage

- VUID-vkBuildAccelerationStructuresKHR-accelerationStructureHostCommands-03581
  The `VkPhysicalDeviceAccelerationStructureFeaturesKHR`::`accelerationStructureHostCommands` feature must be enabled

- VUID-vkBuildAccelerationStructuresKHR-mode-04628
  The `mode` member of each element of `pInfos` must be a valid VkBuildAccelerationStructureModeKHR value

- VUID-vkBuildAccelerationStructuresKHR-srcAccelerationStructure-04629
  If the `srcAccelerationStructure` member of any element of `pInfos` is not VK_NULL_HANDLE, the `srcAccelerationStructure` member must be a valid VkAccelerationStructureKHR handle

- VUID-vkBuildAccelerationStructuresKHR-pInfos-04630
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, its `srcAccelerationStructure` member must not be VK_NULL_HANDLE

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03403
  The `srcAccelerationStructure` member of any element of `pInfos` must not be the same acceleration structure as the `dstAccelerationStructure` member of any other element of `pInfos`

- VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03698
  The `dstAccelerationStructure` member of any element of `pInfos` must not be the same acceleration structure as the `dstAccelerationStructure` member of any other element of `pInfos`

- VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03800
  The `dstAccelerationStructure` member of any element of `pInfos` must be a valid VkAccelerationStructureKHR handle

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03699
  For each element of `pInfos`, if its `type` member is `VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR`, its `dstAccelerationStructure` member must have been created with a value of VkAccelerationStructureCreateInfoKHR::`type` equal to either `VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR` or `VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR`

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03700
  For each element of `pInfos`, if its `type` member is `VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR`, its `dstAccelerationStructure` member must have been created with a value of VkAccelerationStructureCreateInfoKHR::`type` equal to either `VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR` or `VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR`

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03663
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, inactive primitives in its `srcAccelerationStructure` member must not be made active

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03664
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, active primitives in its `srcAccelerationStructure` member must not be made inactive

- VUID-vkBuildAccelerationStructuresKHR-None-03407
  The `dstAccelerationStructure` member of any element of `pInfos` must not be referenced by the `geometry.instances.data` member of any element of `pGeometries` or `ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_INSTANCES_KHR` in any other element of `pInfos`

- VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03701
  The range of memory backing the `dstAccelerationStructure` member of any element of `pInfos` that is accessed by this command must not overlap the memory backing the `srcAccelerationStructure` member of any other element of `pInfos` with a `mode` equal to `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, which is accessed by this command

- VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03702
  The range of memory backing the `dstAccelerationStructure` member of any element of `pInfos` that is accessed by this command must not overlap the memory backing the `dstAccelerationStructure` member of any other element of `pInfos`, which is accessed by this command

- VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03703
  The range of memory backing the `dstAccelerationStructure` member of any element of `pInfos` that is accessed by this command must not overlap the memory backing the `scratchData` member of any element of `pInfos` (including the same element), which is accessed by this command

- VUID-vkBuildAccelerationStructuresKHR-scratchData-03704
  The range of memory backing the `scratchData` member of any element of `pInfos` that is accessed by this command must not overlap the memory backing the `scratchData` member of any other element of `pInfos`, which is accessed by this command

- VUID-vkBuildAccelerationStructuresKHR-scratchData-03705
  The range of memory backing the `scratchData` member of any element of `pInfos` that is accessed by this command must not overlap the memory backing the `srcAccelerationStructure` member of any element of `pInfos` with a `mode` equal to `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR` (including the same element), which is accessed by this command

- VUID-vkBuildAccelerationStructuresKHR-dstAccelerationStructure-03706
  The range of memory backing the `dstAccelerationStructure` member of any element of `pInfos` that is accessed by this command must not overlap the memory backing any acceleration structure referenced by the `geometry.instances.data` member of any element of `pGeometries` or `ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_INSTANCES_KHR` in any other element of `pInfos`, which is accessed by this command

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03667
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, its `srcAccelerationStructure` member must have previously been constructed with `VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR` set in VkAccelerationStructureBuildGeometryInfoKHR::`flags` in the build

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03668
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, its `srcAccelerationStructure` and `dstAccelerationStructure` members must either be the same VkAccelerationStructureKHR, or not have any memory aliasing

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03758
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, its `geometryCount` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03759
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, its `flags` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03760
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, its `type` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03761
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, then for each `VkAccelerationStructureGeometryKHR` structure referred to by its `pGeometries` or `ppGeometries` members, its `geometryType` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03762
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, then for each `VkAccelerationStructureGeometryKHR` structure referred to by its `pGeometries` or `ppGeometries` members, its `flags` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03763
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, then for each `VkAccelerationStructureGeometryKHR` structure referred to by its `pGeometries` or `ppGeometries` members, if `geometryType` is `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, its `geometry.triangles.vertexFormat` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03764
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, then for each `VkAccelerationStructureGeometryKHR` structure referred to by its `pGeometries` or `ppGeometries` members, if `geometryType` is `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, its `geometry.triangles.maxVertex` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03765
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, then for each `VkAccelerationStructureGeometryKHR` structure referred to by its `pGeometries` or `ppGeometries` members, if `geometryType` is `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, its `geometry.triangles.indexType` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03766
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, then for each `VkAccelerationStructureGeometryKHR` structure referred to by its `pGeometries` or `ppGeometries` members, if `geometryType` is `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, if its `geometry.triangles.transformData` address was `NULL` when `srcAccelerationStructure` was last built, then it must be `NULL`

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03767
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, then for each `VkAccelerationStructureGeometryKHR` structure referred to by its `pGeometries` or `ppGeometries` members, if `geometryType` is `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, if its `geometry.triangles.transformData` address was not `NULL` when `srcAccelerationStructure` was last built, then it must not be `NULL`

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03768
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, then for each `VkAccelerationStructureGeometryKHR` structure referred to by its `pGeometries` or `ppGeometries` members, if `geometryType` is `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, and `geometry.triangles.indexType` is not `VK_INDEX_TYPE_NONE_KHR`, then the value of each index referenced must be the same as the corresponding index value when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-primitiveCount-03769
  For each `VkAccelerationStructureBuildRangeInfoKHR` referenced by this command, its `primitiveCount` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-firstVertex-03770
  For each `VkAccelerationStructureBuildRangeInfoKHR` referenced by this command, if the corresponding geometry uses indices, its `firstVertex` member must have the same value which was specified when `srcAccelerationStructure` was last built

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03801
  For each element of `pInfos`[i].`pGeometries` or `pInfos`[i].`ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_INSTANCES_KHR`, the corresponding `ppBuildRangeInfos`[i][j].`primitiveCount` must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::`maxInstanceCount`

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03675
  For each `pInfos`[i], `dstAccelerationStructure` must have been created with a value of VkAccelerationStructureCreateInfoKHR::`size` greater than or equal to the memory size required by the build operation, as returned by vkGetAccelerationStructureBuildSizesKHR with `pBuildInfo` = `pInfos`[i] and with each element of the `pMaxPrimitiveCounts` array greater than or equal to the equivalent `ppBuildRangeInfos`[i][j].`primitiveCount` values for `j` in [0,`pInfos`[i].`geometryCount`)

- VUID-vkBuildAccelerationStructuresKHR-ppBuildRangeInfos-03676
  Each element of `ppBuildRangeInfos`[i] must be a valid pointer to an array of `pInfos`[i].`geometryCount` `VkAccelerationStructureBuildRangeInfoKHR` structures

- VUID-vkBuildAccelerationStructuresKHR-deferredOperation-03677
  If `deferredOperation` is not VK_NULL_HANDLE, it must be a valid VkDeferredOperationKHR object

- VUID-vkBuildAccelerationStructuresKHR-deferredOperation-03678
  Any previous deferred operation that was associated with `deferredOperation` must be complete

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03722
  For each element of `pInfos`, the `buffer` used to create its `dstAccelerationStructure` member must be bound to host-visible device memory

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03723
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR` the `buffer` used to create its `srcAccelerationStructure` member must be bound to host-visible device memory

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03724
  For each element of `pInfos`, the `buffer` used to create each acceleration structure referenced by the `geometry.instances.data` member of any element of `pGeometries` or `ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_INSTANCES_KHR` must be bound to host-visible device memory

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03725
  If `pInfos`[i].`mode` is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR`, all addresses between `pInfos`[i].`scratchData.hostAddress` and `pInfos`[i].`scratchData.hostAddress` + N - 1 must be valid host memory, where N is given by the `buildScratchSize` member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03726
  If `pInfos`[i].`mode` is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`, all addresses between `pInfos`[i].`scratchData.hostAddress` and `pInfos`[i].`scratchData.hostAddress` + N - 1 must be valid host memory, where N is given by the `updateScratchSize` member of the VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to vkGetAccelerationStructureBuildSizesKHR with an identical VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03771
  For any element of `pInfos`[i].`pGeometries` or `pInfos`[i].`ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, `geometry.triangles.vertexData.hostAddress` must be a valid host address

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03772
  For any element of `pInfos`[i].`pGeometries` or `pInfos`[i].`ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, if `geometry.triangles.indexType` is not `VK_INDEX_TYPE_NONE_KHR`, `geometry.triangles.indexData.hostAddress` must be a valid host address

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03773
  For any element of `pInfos`[i].`pGeometries` or `pInfos`[i].`ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_TRIANGLES_KHR`, if `geometry.triangles.transformData.hostAddress` is not `0`, it must be a valid host address

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03774
  For any element of `pInfos`[i].`pGeometries` or `pInfos`[i].`ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_AABBS_KHR`, `geometry.aabbs.data.hostAddress` must be a valid host address

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03775
  For each element of `pInfos`, the `buffer` used to create its `dstAccelerationStructure` member must be bound to memory that was not allocated with multiple instances

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03776
  For each element of `pInfos`, if its `mode` member is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR` the `buffer` used to create its `srcAccelerationStructure` member must be bound to memory that was not allocated with multiple instances

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03777
  For each element of `pInfos`, the `buffer` used to create each acceleration structure referenced by the `geometry.instances.data` member of any element of `pGeometries` or `ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_INSTANCES_KHR` must be bound to memory that was not allocated with multiple instances

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03778
  For any element of `pInfos`[i].`pGeometries` or `pInfos`[i].`ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_INSTANCES_KHR`, `geometry.instances.data.hostAddress` must be a valid host address

- VUID-vkBuildAccelerationStructuresKHR-pInfos-03779
  For any element of `pInfos`[i].`pGeometries` or `pInfos`[i].`ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_INSTANCES_KHR`, each VkAccelerationStructureInstanceKHR::`accelerationStructureReference` value in `geometry.instances.data.hostAddress` must be a valid VkAccelerationStructureKHR object

- VUID-vkBuildAccelerationStructuresKHR-pInfos-04930
  For any element of `pInfos`[i].`pGeometries` or `pInfos`[i].`ppGeometries` with a `geometryType` of `VK_GEOMETRY_TYPE_INSTANCES_KHR` with `VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV` set, each `accelerationStructureReference` in any structure in VkAccelerationStructureMotionInstanceNV value in `geometry.instances.data.hostAddress` must be a valid VkAccelerationStructureKHR object

Valid Usage (Implicit)

- VUID-vkBuildAccelerationStructuresKHR-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkBuildAccelerationStructuresKHR-deferredOperation-parameter
  If `deferredOperation` is not VK_NULL_HANDLE, `deferredOperation` must be a valid VkDeferredOperationKHR handle

- VUID-vkBuildAccelerationStructuresKHR-pInfos-parameter
  `pInfos` must be a valid pointer to an array of `infoCount` valid VkAccelerationStructureBuildGeometryInfoKHR structures

- VUID-vkBuildAccelerationStructuresKHR-ppBuildRangeInfos-parameter
  `ppBuildRangeInfos` must be a valid pointer to an array of `infoCount` VkAccelerationStructureBuildRangeInfoKHR structures

- VUID-vkBuildAccelerationStructuresKHR-infoCount-arraylength
  `infoCount` must be greater than `0`

- VUID-vkBuildAccelerationStructuresKHR-deferredOperation-parent
  If `deferredOperation` is a valid handle, it must have been created, allocated, or retrieved from `device`

Return Codes

On success, this command returns

  - `VK_SUCCESS`

  - `VK_OPERATION_DEFERRED_KHR`

  - `VK_OPERATION_NOT_DEFERRED_KHR`

On failure, this command returns

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

## See Also

VK_KHR_acceleration_structure, VkAccelerationStructureBuildGeometryInfoKHR, VkAccelerationStructureBuildRangeInfoKHR, VkDeferredOperationKHR, VkDevice

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

SPDX-License-Identifier: CC-BY-4.0