VkAccelerationStructureBuildGeometryInfoKHR(3)

# VkAccelerationStructureBuildGeometryInfoKHR(3) Manual Page

## Name

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

Loading… please wait.

## 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 the type of 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` points to an existing acceleration structure that is to be used to update the `dst` acceleration structure when `mode` is `VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR`.

- `dstAccelerationStructure` points 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 to 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.

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.

Valid Usage

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

- VUID-VkAccelerationStructureBuildGeometryInfoKHR-pGeometries-03788
  Only one of `pGeometries` or `ppGeometries` can 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-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

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

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

SPDX-License-Identifier: CC-BY-4.0