C Specification

To copy data from an image object to another image object using the host, call:

// Provided by VK_VERSION_1_4
VkResult vkCopyImageToImage(
    VkDevice                                    device,
    const VkCopyImageToImageInfo*               pCopyImageToImageInfo);

or the equivalent command

// Provided by VK_EXT_host_image_copy
VkResult vkCopyImageToImageEXT(
    VkDevice                                    device,
    const VkCopyImageToImageInfo*               pCopyImageToImageInfo);

Parameters

  • device is the device which owns pCopyImageToImageInfo->srcImage and pCopyImageToImageInfo->dstImage.

  • pCopyImageToImageInfo is a pointer to a VkCopyImageToImageInfo structure describing the copy parameters.

Description

This command is functionally similar to vkCmdCopyImage2, except it is executed on the host. The memory of pCopyImageToImageInfo->srcImage and pCopyImageToImageInfo->dstImage is accessed by the host as if coherent.

Note

If the device has written to the memory of pCopyImageToImageInfo->srcImage, 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.

Because queue submissions automatically make host memory visible to the device, there would not be a need for a memory barrier before using the results of this copy operation in pCopyMemoryToImageInfo->dstImage on the device.

Valid Usage (Implicit)
  • VUID-vkCopyImageToImage-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyImageToImage-pCopyImageToImageInfo-parameter
    pCopyImageToImageInfo must be a valid pointer to a valid VkCopyImageToImageInfo structure

Return Codes
On success, this command returns
  • VK_SUCCESS

On failure, this command returns
  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_MEMORY_MAP_FAILED

See Also

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

SPDX-License-Identifier: CC-BY-4.0