vkCmdCopyAccelerationStructureToMemoryKHR(3)

# vkCmdCopyAccelerationStructureToMemoryKHR(3) Manual Page

## Name

vkCmdCopyAccelerationStructureToMemoryKHR - Copy an acceleration structure to device memory

Loading… please wait.

## 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 an a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.

## Description

Accesses to `pInfo`->`src` must be synchronized with 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_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

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

- A 64-bit integer of the count of the number of acceleration structure handles following. This will be zero for a bottom-level acceleration structure. 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. The serialized data is written to the buffer (or read from the buffer) according to the host endianness.

Valid Usage

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03739
  `pInfo`->`dst.deviceAddress` must be a valid device address for a buffer bound to device memory.

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

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03741
  If the buffer pointed to by `pInfo`->`dst.deviceAddress` is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

- VUID-vkCmdCopyAccelerationStructureToMemoryKHR-None-03559
  The `buffer` used to create `pInfo`->`src` must be bound to device memory

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 compute operations

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

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 | Supported Queue Types | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Outside | Compute |

## See Also

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

SPDX-License-Identifier: CC-BY-4.0