VkAccelerationStructureBuildGeometryInfoKHR(3)

# VkAccelerationStructureBuildGeometryInfoKHR(3) Manual Page

## Name

VkAccelerationStructureBuildGeometryInfoKHR - Structure specifying the geometry data used to build an acceleration structure

## C Specification

The `VkAccelerationStructureBuildGeometryInfoKHR` structure is defined as:

    // Provided by VK_KHR_acceleration_structure
    typedef struct VkAccelerationStructureBuildGeometryInfoKHR {
        VkStructureType                                     sType;
        const void*                                         pNext;
        VkAccelerationStructureTypeKHR                      type;
        VkBuildAccelerationStructureFlagsKHR                flags;
        VkBuildAccelerationStructureModeKHR                 mode;
        VkAccelerationStructureKHR                          srcAccelerationStructure;
        VkAccelerationStructureKHR                          dstAccelerationStructure;
        uint32_t                                            geometryCount;
        const VkAccelerationStructureGeometryKHR*           pGeometries;
        const VkAccelerationStructureGeometryKHR* const*    ppGeometries;
        VkDeviceOrHostAddressKHR                            scratchData;
    } VkAccelerationStructureBuildGeometryInfoKHR;

## Members

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `type` is a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure being built.

- `flags` is a bitmask of VkBuildAccelerationStructureFlagBitsKHR specifying additional parameters of the acceleration structure.

- `mode` is a VkBuildAccelerationStructureModeKHR value specifying the type of operation to perform.

- `srcAccelerationStructure` is a pointer to an existing acceleration structure that is to be used to update the `dstAccelerationStructure` acceleration structure when `mode` is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR.

- `dstAccelerationStructure` is a pointer to the target acceleration structure for the build.

- `geometryCount` specifies the number of geometries that will be built into `dstAccelerationStructure`.

- `pGeometries` is a pointer to an array of VkAccelerationStructureGeometryKHR structures.

- `ppGeometries` is a pointer to an array of pointers to VkAccelerationStructureGeometryKHR structures.

- `scratchData` is the device or host address of memory that will be used as scratch memory for the build.

## Description

Only one of `pGeometries` or `ppGeometries` can be a valid pointer, the other must be `NULL`. Each element of the non-`NULL` array describes the data used to build each acceleration structure geometry.

For bottom-level acceleration structures, the index of each element of the `pGeometries` or `ppGeometries` members of VkAccelerationStructureBuildGeometryInfoKHR is used as the geometry index during ray traversal. The geometry index is available in ray shaders via the `RayGeometryIndexKHR` built-in, and is used to determine hit and intersection shaders executed during traversal. The geometry index is available to ray queries via the `OpRayQueryGetIntersectionGeometryIndexKHR` instruction.

Setting VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in `flags` indicates that this build is a motion top level acceleration structure. A motion top level uses instances of format VkAccelerationStructureMotionInstanceNV if VkAccelerationStructureGeometryInstancesDataKHR::`arrayOfPointers` is VK_FALSE.

If VkAccelerationStructureGeometryInstancesDataKHR::`arrayOfPointers` is VK_TRUE, the pointer for each element of the array of instance pointers consists of 4 bits of VkAccelerationStructureMotionInstanceTypeNV in the low 4 bits of the pointer identifying the type of structure at the pointer. The device address accessed is the value in the array with the low 4 bits set to zero. The structure at the pointer is one of VkAccelerationStructureInstanceKHR, VkAccelerationStructureMatrixMotionInstanceNV or VkAccelerationStructureSRTMotionInstanceNV, depending on the type value encoded in the low 4 bits.

A top level acceleration structure with either motion instances or vertex motion in its instances must set VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in `flags`.

Members `srcAccelerationStructure` and `dstAccelerationStructure` may be the same or different for an update operation (when `mode` is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR). If they are the same, the update happens in-place. Otherwise, the target acceleration structure is updated and the source is not modified.

Valid Usage

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03654
  `type` must not be VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-pGeometries-03788
  If `geometryCount` is not `0`, exactly one of `pGeometries` or `ppGeometries` must be a valid pointer, the other must be `NULL`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03789
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, the `geometryType` member of elements of either `pGeometries` or `ppGeometries` must be VK_GEOMETRY_TYPE_INSTANCES_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03790
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, `geometryCount` must be `1`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03791
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR the `geometryType` member of elements of either `pGeometries` or `ppGeometries` must not be VK_GEOMETRY_TYPE_INSTANCES_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03792
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR then the `geometryType` member of each geometry in either `pGeometries` or `ppGeometries` must be the same

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03793
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR then `geometryCount` must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::`maxGeometryCount`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-10884
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the `geometryType` member of either `pGeometries` or `ppGeometries` is VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, then `geometryCount` must be `1`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03794
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the `geometryType` member of either `pGeometries` or `ppGeometries` is VK_GEOMETRY_TYPE_AABBS_KHR, the total number of AABBs in all geometries must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::`maxPrimitiveCount`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03795
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the `geometryType` member of either `pGeometries` or `ppGeometries` is VK_GEOMETRY_TYPE_TRIANGLES_KHR, the total number of triangles in all geometries must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::`maxPrimitiveCount`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-03796
  If `flags` has the VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR bit set, then it must not have the VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR bit set

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-dstAccelerationStructure-04927
  If `dstAccelerationStructure` was created with VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV set in VkAccelerationStructureCreateInfoKHR::`createFlags`, VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV must be set in `flags`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-04928
  If VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV is set in `flags`, `dstAccelerationStructure` must have been created with VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV set in VkAccelerationStructureCreateInfoKHR::`createFlags`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-04929
  If VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV is set in `flags`, `type` must not be VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11558
  If `flags` has the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR bit set then it must not have the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT bit set

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11709
  If `flags` has the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT bit set, the `VkPhysicalDeviceOpacityMicromapFeaturesEXT`::`micromap` feature must be enabled

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11710
  If `flags` has the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR bit set, the `VkPhysicalDeviceOpacityMicromapFeaturesKHR`::`micromap` or `VkPhysicalDeviceOpacityMicromapFeaturesEXT`::`micromap` feature must be enabled

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11711
  If `flags` has the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_KHR bit set, the `VkPhysicalDeviceOpacityMicromapFeaturesKHR`::`micromap` or `VkPhysicalDeviceOpacityMicromapFeaturesEXT`::`micromap` feature must be enabled

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-micromap-11559
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, the `VkPhysicalDeviceOpacityMicromapFeaturesKHR`::`micromap` feature must be enabled

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-geometryCount-11560
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, `geometryCount` must be `1`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-geometryType-11561
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, the `geometryType` member of elements of either `pGeometries` or `ppGeometries` must be VK_GEOMETRY_TYPE_MICROMAP_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-geometryType-11707
  If `type` is not VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, the `geometryType` member of elements of either `pGeometries` or `ppGeometries` must not be VK_GEOMETRY_TYPE_MICROMAP_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11562
  If `type` is VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, `flags` must only include the following bits:

  - VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR

  - VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR

  - VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR

  - VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-11563
  If `flags` includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, `type` must be VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-format-11712
  If `flags` includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of `pGeometries` or `ppGeometries`, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its `pNext` chain, each element of its `pUsageCounts` or `ppUsageCounts` members must have its `format` member equal to VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-subdivisionLevel-11564
  If `flags` does not include VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of `pGeometries` or `ppGeometries`, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its `pNext` chain, for each element of its `pUsageCounts` or `ppUsageCounts` members, if its `format` member is VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR, its `subdivisionLevel` member must be less than or equal to `maxOpacity4StateSubdivisionLevel`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-subdivisionLevel-11565
  If `flags` includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of `pGeometries` or `ppGeometries`, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its `pNext` chain, for each element of its `pUsageCounts` or `ppUsageCounts` members, its `subdivisionLevel` member must be less than or equal to `maxOpacityLossy4StateSubdivisionLevel`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-format-11713
  If `flags` includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of `pGeometries` or `ppGeometries`, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its `pNext` chain, each element of its `triangleArray` member must have its `format` member equal to VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-subdivisionLevel-11566
  If `flags` does not include VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of `pGeometries` or `ppGeometries`, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its `pNext` chain, for each element of its `triangleArray` member, if its `format` member is VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR, its `subdivisionLevel` member must be less than or equal to `maxOpacity4StateSubdivisionLevel`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-subdivisionLevel-11567
  If `flags` includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of `pGeometries` or `ppGeometries`, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its `pNext` chain, for each element of its `triangleArray` member, its `subdivisionLevel` member must be less than or equal to `maxOpacityLossy4StateSubdivisionLevel`

Valid Usage (Implicit)

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-parameter
  `type` must be a valid VkAccelerationStructureTypeKHR value

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-parameter
  `flags` must be a valid combination of VkBuildAccelerationStructureFlagBitsKHR values

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-pGeometries-parameter
  If `geometryCount` is not `0`, and `pGeometries` is not `NULL`, `pGeometries` must be a valid pointer to an array of `geometryCount` valid VkAccelerationStructureGeometryKHR structures

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-ppGeometries-parameter
  If `geometryCount` is not `0`, and `ppGeometries` is not `NULL`, `ppGeometries` must be a valid pointer to an array of `geometryCount` valid pointers to valid VkAccelerationStructureGeometryKHR structures

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-commonparent
  Both of `dstAccelerationStructure`, and `srcAccelerationStructure` that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

## See Also

VK_KHR_acceleration_structure, VkAccelerationStructureGeometryKHR, VkAccelerationStructureKHR, VkAccelerationStructureTypeKHR, VkBuildAccelerationStructureFlagsKHR, VkBuildAccelerationStructureModeKHR, VkDeviceOrHostAddressKHR, VkStructureType, vkBuildAccelerationStructuresKHR, vkCmdBuildAccelerationStructuresIndirectKHR, vkCmdBuildAccelerationStructuresKHR, vkGetAccelerationStructureBuildSizesKHR

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

SPDX-License-Identifier: CC-BY-4.0