vkCreateAccelerationStructure2KHR(3)

# vkCreateAccelerationStructure2KHR(3) Manual Page

## Name

vkCreateAccelerationStructure2KHR - Create a new acceleration structure object using a device address

## C Specification

To create an acceleration structure using a device address, call:

    // Provided by VK_KHR_acceleration_structure with VK_KHR_device_address_commands
    VkResult vkCreateAccelerationStructure2KHR(
        VkDevice                                    device,
        const VkAccelerationStructureCreateInfo2KHR* pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkAccelerationStructureKHR*                 pAccelerationStructure);

## Parameters

- `device` is the logical device that creates the acceleration structure object.

- `pCreateInfo` is a pointer to a VkAccelerationStructureCreateInfo2KHR structure containing parameters affecting creation of the acceleration structure.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

- `pAccelerationStructure` is a pointer to a `VkAccelerationStructureKHR` handle in which the resulting acceleration structure object is returned.

## Description

Similar to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into an acceleration structure is determined by the parameters of VkAccelerationStructureCreateInfo2KHR.

The acceleration structure data is stored in the object referred to by `VkAccelerationStructureCreateInfo2KHR`::`addressRange.address`.

Once the `VkAccelerationStructureKHR` object has been created, it must be populated by acceleration structure build or acceleration structure copy commands such as vkCmdBuildAccelerationStructuresKHR and vkCmdCopyAccelerationStructureKHR. Acceleration structures created with this command must not be used by host commands.

Note | The expected usage for a trace capture/replay tool is that it will serialize and later deserialize the acceleration structure data using acceleration structure copy commands. During capture the tool will use vkCmdCopyAccelerationStructureToMemoryKHR with a `mode` of VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR, and vkCmdCopyMemoryToAccelerationStructureKHR with a `mode` of VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR during replay.

Valid Usage

- VUID-vkCreateAccelerationStructure2KHR-accelerationStructure-03611
  The `VkPhysicalDeviceAccelerationStructureFeaturesKHR`::`accelerationStructure` feature must be enabled

- VUID-vkCreateAccelerationStructure2KHR-deviceAddressCommands-13086
  The `VkPhysicalDeviceDeviceAddressCommandsFeaturesKHR`::`deviceAddressCommands` feature must be enabled

Valid Usage (Implicit)

- VUID-vkCreateAccelerationStructure2KHR-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkCreateAccelerationStructure2KHR-pCreateInfo-parameter
  `pCreateInfo` must be a valid pointer to a valid VkAccelerationStructureCreateInfo2KHR structure

- VUID-vkCreateAccelerationStructure2KHR-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkCreateAccelerationStructure2KHR-pAccelerationStructure-parameter
  `pAccelerationStructure` must be a valid pointer to a VkAccelerationStructureKHR handle

- VUID-vkCreateAccelerationStructure2KHR-device-queuecount
  The device must have been created with at least `1` queue

Return Codes

On success, this command returns

  - VK_SUCCESS

On failure, this command returns

  - VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

  - VK_ERROR_OUT_OF_HOST_MEMORY

  - VK_ERROR_UNKNOWN

  - VK_ERROR_VALIDATION_FAILED

## See Also

VK_KHR_acceleration_structure, VK_KHR_device_address_commands, VkAccelerationStructureCreateInfo2KHR, VkAccelerationStructureKHR, VkAllocationCallbacks, VkDevice

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