VkAccelerationStructureCreateInfoKHR(3)

# VkAccelerationStructureCreateInfoKHR(3) Manual Page

## Name

VkAccelerationStructureCreateInfoKHR - Structure specifying the parameters of a newly created acceleration structure object

Loading… please wait.

## C Specification

The `VkAccelerationStructureCreateInfoKHR` structure is defined as:

    // Provided by VK_KHR_acceleration_structure
    typedef struct VkAccelerationStructureCreateInfoKHR {
        VkStructureType                          sType;
        const void*                              pNext;
        VkAccelerationStructureCreateFlagsKHR    createFlags;
        VkBuffer                                 buffer;
        VkDeviceSize                             offset;
        VkDeviceSize                             size;
        VkAccelerationStructureTypeKHR           type;
        VkDeviceAddress                          deviceAddress;
    } VkAccelerationStructureCreateInfoKHR;

## Members

- `sType` is the type of this structure.

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

- `createFlags` is a bitmask of VkAccelerationStructureCreateFlagBitsKHR specifying additional creation parameters of the acceleration structure.

- `buffer` is the buffer on which the acceleration structure will be stored.

- `offset` is an offset in bytes from the base address of the buffer at which the acceleration structure will be stored, and must be a multiple of `256`.

- `size` is the size required for the acceleration structure.

- `type` is a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure that will be created.

- `deviceAddress` is the device address requested for the acceleration structure if the `accelerationStructureCaptureReplay` feature is being used.

## Description

If `deviceAddress` is zero, no specific address is requested.

If `deviceAddress` is not zero, `deviceAddress` must be an address retrieved from an identically created acceleration structure on the same implementation. The acceleration structure must also be placed on an identically created `buffer` and at the same `offset`.

Applications should avoid creating acceleration structures with application-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR` errors.

| Note The expected usage for this is that a trace capture/replay tool will add the `VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT` flag to all buffers that use `VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT`, and will add `VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT` to all buffers used as storage for an acceleration structure where `deviceAddress` is not zero. This also means that the tool will need to add `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT` to memory allocations to allow the flag to be set where the application may not have otherwise required it. During capture the tool will save the queried opaque device addresses in the trace. During replay, the buffers will be created specifying the original address so any address values stored in the trace data will remain valid. Implementations are expected to separate such buffers in the GPU address space so normal allocations will avoid using these addresses. Apps/tools should avoid mixing app-provided and implementation-provided addresses for buffers created with `VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT`, to avoid address space allocation conflicts.

Applications should create an acceleration structure with a specific VkAccelerationStructureTypeKHR other than `VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR`.

| Note `VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR` is intended to be used by API translation layers. This can be used at acceleration structure creation time in cases where the actual acceleration structure type (top or bottom) is not yet known. The actual acceleration structure type must be specified as `VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR` or `VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR` when the build is performed.

If the acceleration structure will be the target of a build operation, the required size for an acceleration structure can be queried with vkGetAccelerationStructureBuildSizesKHR. If the acceleration structure is going to be the target of a compacting copy, vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR can be used to obtain the compacted size required.

If the acceleration structure will be the target of a build operation with `VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV` it must include `VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV` in `flags` and include VkAccelerationStructureMotionInfoNV as an extension structure in `pNext` with the number of instances as metadata for the object.

Valid Usage

- VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-03612
  If `deviceAddress` is not zero, `createFlags` must include `VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR`

- VUID-VkAccelerationStructureCreateInfoKHR-createFlags-03613
  If `createFlags` includes `VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR`, VkPhysicalDeviceAccelerationStructureFeaturesKHR::`accelerationStructureCaptureReplay` must be `VK_TRUE`

- VUID-VkAccelerationStructureCreateInfoKHR-buffer-03614
  `buffer` must have been created with a `usage` value containing `VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR`

- VUID-VkAccelerationStructureCreateInfoKHR-buffer-03615
  `buffer` must not have been created with `VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT`

- VUID-VkAccelerationStructureCreateInfoKHR-offset-03616
  The sum of `offset` and `size` must be less than the size of `buffer`

- VUID-VkAccelerationStructureCreateInfoKHR-offset-03734
  `offset` must be a multiple of `256` bytes

- VUID-VkAccelerationStructureCreateInfoKHR-flags-04954
  If `VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV` is set in `flags` and `type` is `VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR`, one member of the `pNext` chain must be a pointer to a valid instance of VkAccelerationStructureMotionInfoNV

- VUID-VkAccelerationStructureCreateInfoKHR-flags-04955
  If any geometry includes `VkAccelerationStructureGeometryMotionTrianglesDataNV` then `flags` must contain `VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV`

- VUID-VkAccelerationStructureCreateInfoKHR-createFlags-08108
  If `createFlags` includes `VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT`, the descriptorBufferCaptureReplay feature must be enabled

- VUID-VkAccelerationStructureCreateInfoKHR-pNext-08109
  If the `pNext` chain includes a VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, `createFlags` must contain `VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT`

Valid Usage (Implicit)

- VUID-VkAccelerationStructureCreateInfoKHR-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_KHR`

- VUID-VkAccelerationStructureCreateInfoKHR-pNext-pNext
  Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkAccelerationStructureMotionInfoNV or VkOpaqueCaptureDescriptorDataCreateInfoEXT

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

- VUID-VkAccelerationStructureCreateInfoKHR-createFlags-parameter
  `createFlags` must be a valid combination of VkAccelerationStructureCreateFlagBitsKHR values

- VUID-VkAccelerationStructureCreateInfoKHR-buffer-parameter
  `buffer` must be a valid VkBuffer handle

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

## See Also

VK_KHR_acceleration_structure, VkAccelerationStructureCreateFlagsKHR, VkAccelerationStructureTypeKHR, VkBuffer, `VkDeviceAddress`, `VkDeviceSize`, VkStructureType, vkCreateAccelerationStructureKHR

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

SPDX-License-Identifier: CC-BY-4.0