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

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.

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