# 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 a VkStructureType value identifying 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. If `deviceAddress` is zero, no specific address is requested.

## Description

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. Applications and tools should avoid mixing application-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 `createFlags` 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-deviceAddress-09488
  If `deviceAddress` is not zero, it must have been retrieved from an identically created acceleration structure, except for `buffer` and `deviceAddress`

- VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09489
  If `deviceAddress` is not zero, `buffer` must have been created identically to the `buffer` used to create the acceleration structure from which `deviceAddress` was retrieved, except for VkBufferOpaqueCaptureAddressCreateInfo::`opaqueCaptureAddress`

- VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09490
  If `deviceAddress` is not zero, `buffer` must have been created with a VkBufferOpaqueCaptureAddressCreateInfo::`opaqueCaptureAddress` that was retrieved from vkGetBufferOpaqueCaptureAddress for the `buffer` that was used to create the acceleration structure from which `deviceAddress` was retrieved

- 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-createFlags-04954
  If `VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV` is set in `createFlags` 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-createFlags-04955
  If any geometry includes `VkAccelerationStructureGeometryMotionTrianglesDataNV` then `createFlags` 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0