VKCMDCOPYIMAGE(3)

NAME
vkCmdCopyImage - Copy data between images.

C SPECIFICATION

    void vkCmdCopyImage(
        VkCommandBuffer                             commandBuffer,
        VkImage                                     srcImage,
        VkImageLayout                               srcImageLayout,
        VkImage                                     dstImage,
        VkImageLayout                               dstImageLayout,
        uint32_t                                    regionCount,
        const VkImageCopy*                          pRegions);

PARAMETERS

commandBuffer
    The command buffer into which the copy command is to be placed.

srcImage
    The image that is the source for the data.

srcImageLayout
    The layout of the source image at the time of the copy operation.

dstImage
    The image that is to be the destination for the copy.

dstImageLayout
    The layout of the destination image at the time of the copy operation.

regionCount
    The number of regions to copy.

pRegions
    An array of regionCount regions to copy.

DESCRIPTION

vkCmdCopyImage copies regionCount regions of image data between srcImage and dstImage. Each region is described by an element of the array pointed to by pRegions, which is an array of VkImageCopy, the definition of which is:

    typedef struct VkImageCopy {
        VkImageSubresourceLayers    srcSubresource;
        VkOffset3D                  srcOffset;
        VkImageSubresourceLayers    dstSubresource;
        VkOffset3D                  dstOffset;
        VkExtent3D                  extent;
    } VkImageCopy;

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • srcImage must be a valid VkImage handle

    • srcImageLayout must be a valid VkImageLayout value

    • dstImage must be a valid VkImage handle

    • dstImageLayout must be a valid VkImageLayout value

    • pRegions must be a pointer to an array of regionCount valid VkImageCopy structures

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support transfer, graphics or compute operations

    • This command must only be called outside of a render pass instance

    • regionCount must be greater than 0

    • Each of commandBuffer, srcImage and dstImage must have been created, allocated or retrieved from the same VkDevice

    • The source region specified by a given element of pRegions must be a region that is contained within srcImage

    • The destination region specified by a given element of pRegions must be a region that is contained within dstImage

    • The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

    • srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

    • srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

    • srcImageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

    • dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

    • dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

    • dstImageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

    • The VkFormat of each of srcImage and dstImage must be compatible, as defined below

    • The sample count of srcImage and dstImage must match

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Outside | TRANSFER GRAPHICS COMPUTE

NOTES

Although vkCmdCopyBufferToImage does not generate errors or return a value, enabled validation layers may detect possible error conditions or potentially undefined behavior and report this via some other means.

SEE ALSO

vkCmdCopyBuffer, vkCmdCopyImageToBuffer, vkCmdCopyBufferToImage

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.