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_ray_tracing
    typedef struct VkAccelerationStructureBuildGeometryInfoKHR {
        VkStructureType                                     sType;
        const void*                                         pNext;
        VkAccelerationStructureTypeKHR                      type;
        VkBuildAccelerationStructureFlagsKHR                flags;
        VkBool32                                            update;
        VkAccelerationStructureKHR                          srcAccelerationStructure;
        VkAccelerationStructureKHR                          dstAccelerationStructure;
        VkBool32                                            geometryArrayOfPointers;
        uint32_t                                            geometryCount;
        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.

- `update` specifies whether to update `dstAccelerationStructure` with the data in `srcAccelerationStructure` or not.

- `srcAccelerationStructure` points to an existing acceleration structure that is to be used to update the `dst` acceleration structure when `update` is `VK_TRUE`.

- `dstAccelerationStructure` points to the target acceleration structure for the build.

- `geometryArrayOfPointers` specifies whether `ppGeometries` is used as a pointer to an array of pointers or a pointer to a pointer to an array.

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

- `ppGeometries` is either a pointer to an array of pointers to VkAccelerationStructureGeometryKHR structures if `geometryArrayOfPointers` is `VK_TRUE`, or a pointer to a pointer to an array of VkAccelerationStructureGeometryKHR structures if it is `VK_FALSE`. Each element of the array describes the data used to build each acceleration structure geometry.

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

## Description

| Note Elements of `ppGeometries` are accessed as follows, based on `geometryArrayOfPointers`:
    if (geometryArrayOfPointers) {
        use *(ppGeometries[i]);
    } else {
        use (*ppGeometries)[i];
    }

Valid Usage

- If `update` is `VK_TRUE`, `srcAccelerationStructure` must not be VK_NULL_HANDLE

- If `update` is `VK_TRUE`, `srcAccelerationStructure` must have been built before with `VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR` set in VkAccelerationStructureBuildGeometryInfoKHR::`flags`

- `scratchData` must have been created with `VK_BUFFER_USAGE_RAY_TRACING_BIT_KHR` usage flag

- If `update` is `VK_TRUE`, the `srcAccelerationStructure` and `dstAccelerationStructure` objects must either be the same object or not have any memory aliasing

Valid Usage (Implicit)

- `sType` must be `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR`

- `pNext` must be `NULL` or a pointer to a valid instance of VkDeferredOperationInfoKHR

- The `sType` value of each struct in the `pNext` chain must be unique

- `type` must be a valid VkAccelerationStructureTypeKHR value

- `flags` must be a valid combination of VkBuildAccelerationStructureFlagBitsKHR values

- If `srcAccelerationStructure` is not VK_NULL_HANDLE, `srcAccelerationStructure` must be a valid VkAccelerationStructureKHR handle

- `dstAccelerationStructure` must be a valid VkAccelerationStructureKHR handle

- `scratchData` must be a valid VkDeviceOrHostAddressKHR union

- 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, `VkBool32`, VkBuildAccelerationStructureFlagsKHR, VkDeviceOrHostAddressKHR, VkStructureType, vkBuildAccelerationStructureKHR, vkCmdBuildAccelerationStructureIndirectKHR, vkCmdBuildAccelerationStructureKHR

## 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 (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0