vkCmdCopyAccelerationStructureToMemoryKHR

To copy an acceleration structure to device memory call:

void vkCmdCopyAccelerationStructureToMemoryKHR(
    VkCommandBuffer commandBuffer,
    const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);

pub fn cmd_copy_acceleration_structure_to_memory_khr(
    command_buffer: vk::CommandBuffer,
    p_info: *const vk::CopyAccelerationStructureToMemoryInfoKHR,
);

• commandBuffer is the command buffer into which the command will be recorded.
• pInfo is a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.

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.