vkCopyImageToMemory(3)

Name

vkCopyImageToMemory - Copy image data into host memory

C Specification

To copy data from an image object to host memory, call:

// Provided by VK_VERSION_1_4
VkResult vkCopyImageToMemory(
    VkDevice                                    device,
    const VkCopyImageToMemoryInfo*              pCopyImageToMemoryInfo);

or the equivalent command

// Provided by VK_EXT_host_image_copy
VkResult vkCopyImageToMemoryEXT(
    VkDevice                                    device,
    const VkCopyImageToMemoryInfo*              pCopyImageToMemoryInfo);

Parameters

device is the device which owns pCopyImageToMemoryInfo->srcImage.
pCopyImageToMemoryInfo is a pointer to a VkCopyImageToMemoryInfo structure describing the copy parameters.

Description

This command is functionally similar to vkCmdCopyImageToBuffer2, except it is executed on the host and writes to host memory instead of a buffer. The memory of pCopyImageToMemoryInfo->srcImage is accessed by the host as if coherent.

If the device has written to the image memory, it is not automatically made available to the host. Before this copy command can be called, a memory barrier for this image must have been issued on the device with the second synchronization scope including VK_PIPELINE_STAGE_HOST_BIT and VK_ACCESS_HOST_READ_BIT.

Valid Usage (Implicit)

VUID-vkCopyImageToMemory-device-parameter
device must be a valid VkDevice handle
VUID-vkCopyImageToMemory-pCopyImageToMemoryInfo-parameter
pCopyImageToMemoryInfo must be a valid pointer to a valid VkCopyImageToMemoryInfo structure

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_INITIALIZATION_FAILED
VK_ERROR_MEMORY_MAP_FAILED
VK_ERROR_OUT_OF_DEVICE_MEMORY
VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_UNKNOWN
VK_ERROR_VALIDATION_FAILED

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.