vkCmdCopyAccelerationStructureToMemoryKHR(3)

# vkCmdCopyAccelerationStructureToMemoryKHR(3) Manual Page

## Name

vkCmdCopyAccelerationStructureToMemoryKHR - Copy an acceleration structure to device memory

## C Specification

To copy an acceleration structure to device memory call:

    // Provided by VK_KHR_acceleration_structure
    void vkCmdCopyAccelerationStructureToMemoryKHR(
        VkCommandBuffer                             commandBuffer,
        const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);

## Parameters

- `commandBuffer` is the command buffer into which the command will be recorded.

- `pInfo` is a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.

## Description

Accesses to `pInfo->src` must be synchronized with the VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR pipeline stage or the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage, and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. Accesses to the buffer indicated by `pInfo->dst.deviceAddress` must be synchronized with the VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR pipeline stage or the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage, and an access type of VK_ACCESS_TRANSFER_WRITE_BIT.

This command produces the same results as vkCopyAccelerationStructureToMemoryKHR, but writes its result to a device address, and is executed on the device rather than the host. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.

The defined header structure for the serialized data consists of:

- VK_UUID_SIZE bytes of data matching `VkPhysicalDeviceIDProperties`::`driverUUID`

- VK_UUID_SIZE bytes of data identifying the compatibility for comparison using vkGetDeviceAccelerationStructureCompatibilityKHR

For a top-level or bottom-level acceleration structure, this is followed by: * A 64-bit integer of the total size matching the value queried using VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR * A 64-bit integer of the deserialized size to be passed in to `VkAccelerationStructureCreateInfoKHR`::`size`

For a top-level acceleration structure, the remainder of the serialized header consists of:

- A 64-bit integer of the count of the number of acceleration structure handles following. This value matches the value queried using VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR. For top-level acceleration structures this number is implementation-dependent; the number of and ordering of the handles may not match the instance descriptions which were used to build the acceleration structure.

The corresponding handles matching the values returned by vkGetAccelerationStructureDeviceAddressKHR or vkGetAccelerationStructureHandleNV are tightly packed in the buffer following the count. The application is expected to store a mapping between those handles and the original application-generated bottom-level acceleration structures to provide when deserializing.

For a bottom-level acceleration structure, the remainder of the serialized header consists of:

- A 64-bit integer consisting of two packed 32 bit values. The high 32 bits are 0xFFFFFFFF to indicate a block-based format, and the low 32 bits contain the number of serialized blocks that follow

- For each block:

  - A 32-bit unsigned integer indicating the block type corresponding to values in the VkAccelerationStructureSerializedBlockTypeKHR enumeration

  - A 32-bit reserved value for alignment

  - A 64-bit unsigned integer indicating the number of block buffer device addresses that follow the block header

  - An array of 64-bit buffer device addresses, with the count matching the previous value

If the block type is VK_ACCELERATION_STRUCTURE_SERIALIZED_BLOCK_TYPE_OPACITY_MICROMAP_KHR, the corresponding buffer device addresses are tightly packed in the buffer and match the values returned by vkGetBufferDeviceAddressKHR for the underlying buffer objects for the opacity micromaps. An implementation may either return `NULL` for a geometry with no opacity micromap or only return valid device address entries in the array. Similar to the above, the application must provide a mapping between the valid buffer device addresses and the original application-generated opacity micromaps when deserializing. If the implementation returned `NULL` addresses for geometry without micromaps, the application must provide `NULL` device addresses mapped to those when deserializing.

The addresses of micromaps provided to deserializing must be compatible with the micromaps that were used for building the acceleration structure that was serialized. They must be created before deserializing with identical `type` and `createFlags` except for the VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR flag set.

Before using the deserialized acceleration structure, the micromaps must be deserialized using the serialized output of the micromap that was originally referenced by the serialized acceleration structure, or, if the acceleration structure was originally built with the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR, the application may replace the micromap with a newly constructed micromap, using the normal update rules.

The serialized data is written to the buffer (or read from the buffer) according to the host endianness.

Valid Usage

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-accelerationStructure-08926
  The `VkPhysicalDeviceAccelerationStructureFeaturesKHR`::`accelerationStructure` feature must be enabled

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03739
  `pInfo->dst.deviceAddress` must be a valid VkDeviceAddress

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03740
  `pInfo->dst.deviceAddress` must be aligned to `256` bytes

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-11699
  If `pInfo->src` was built with a `type` of VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, `pInfo->dst.deviceAddress` must be aligned to `128` bytes

Valid Usage (Implicit)

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-parameter
  `pInfo` must be a valid pointer to a valid VkCopyAccelerationStructureToMemoryInfoKHR structure

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-recording
  `commandBuffer` must be in the recording state

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-cmdpool
  The `VkCommandPool` that `commandBuffer` was allocated from must support VK_QUEUE_COMPUTE_BIT operations

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-renderpass
  This command must only be called outside of a render pass instance

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-suspended
  This command must not be called between suspended render pass instances

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-videocoding
  This command must only be called outside of a video coding scope

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

- Host access to the `VkCommandPool` that `commandBuffer` was allocated from must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Outside | Outside | VK_QUEUE_COMPUTE_BIT | Action

Conditional Rendering

vkCmdCopyAccelerationStructureToMemoryKHR is not affected by conditional rendering

## See Also

VK_KHR_acceleration_structure, VkCommandBuffer, VkCopyAccelerationStructureToMemoryInfoKHR

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