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
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
On failure, this command returns

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