VKCMDCOPYIMAGE(3)

NAME
vkCmdCopyImage - Copy data between images

C SPECIFICATION

To copy data between image objects, call:

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

PARAMETERS

    • commandBuffer is the command buffer into which the command will be recorded.

    • srcImage is the source image.

    • srcImageLayout is the current layout of the source image subresource.

    • dstImage is the destination image.

    • dstImageLayout is the current layout of the destination image subresource.

    • regionCount is the number of regions to copy.

    • pRegions is a pointer to an array of VkImageCopy structures specifying the regions to copy.

DESCRIPTION

Each region in pRegions is copied from the source image to the same region of the destination image. srcImage and dstImage can be the same image or alias the same memory.

Copies are done layer by layer starting with baseArrayLayer member of srcSubresource for the source and dstSubresource for the destination. layerCount layers are copied to the destination image.

The formats of srcImage and dstImage must be compatible. Formats are considered compatible if their element size is the same between both formats. For example, VK_FORMAT_R8G8B8A8_UNORM is compatible with VK_FORMAT_R32_UINT because both texels are 4 bytes in size. Depth/stencil formats must match exactly.

vkCmdCopyImage allows copying between size-compatible compressed and uncompressed internal formats. Formats are size-compatible if the element size of the uncompressed format is equal to the element size (compressed texel block size) of the compressed format. Such a copy does not perform on-the-fly compression or decompression. When copying from an uncompressed format to a compressed format, each texel of uncompressed data of the source image is copied as a raw value to the corresponding compressed texel block of the destination image. When copying from a compressed format to an uncompressed format, each compressed texel block of the source image is copied as a raw value to the corresponding texel of uncompressed data in the destination image. Thus, for example, it is legal to copy between a 128-bit uncompressed format and a compressed format which has a 128-bit sized compressed texel block representing 4x4 texels (using 8 bits per texel), or between a 64-bit uncompressed format and a compressed format which has a 64-bit sized compressed texel block representing 4x4 texels (using 4 bits per texel).

When copying between compressed and uncompressed formats the extent members represent the texel dimensions of the source image and not the destination. When copying from a compressed image to an uncompressed image the image texel dimensions written to the uncompressed image will be source extent divided by the compressed texel block dimensions. When copying from an uncompressed image to a compressed image the image texel dimensions written to the compressed image will be the source extent multiplied by the compressed texel block dimensions. In both cases the number of bytes read and the number of bytes written will be identical.

Copying to or from block-compressed images is typically done in multiples of the compressed texel block size. For this reason the extent must be a multiple of the compressed texel block dimension. There is one exception to this rule which is required to handle compressed images created with dimensions that are not a multiple of the compressed texel block dimensions: if the srcImage is compressed, then:

    • If extent.width is not a multiple of the compressed texel block width, then (extent.width + srcOffset.x) must equal the image subresource width.

    • If extent.height is not a multiple of the compressed texel block height, then (extent.height + srcOffset.y) must equal the image subresource height.

    • If extent.depth is not a multiple of the compressed texel block depth, then (extent.depth + srcOffset.z) must equal the image subresource depth.

Similarly, if the dstImage is compressed, then:

    • If extent.width is not a multiple of the compressed texel block width, then (extent.width + dstOffset.x) must equal the image subresource width.

    • If extent.height is not a multiple of the compressed texel block height, then (extent.height + dstOffset.y) must equal the image subresource height.

    • If extent.depth is not a multiple of the compressed texel block depth, then (extent.depth + dstOffset.z) must equal the image subresource depth.

This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.

vkCmdCopyImage can be used to copy image data between multisample images, but both images must have the same number of samples. Valid Usage

    • 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

    • If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

    • 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

    • If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

    • 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
Valid Usage (Implicit)

    • 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, dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice
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 | Transfer graphics compute | Transfer

SEE ALSO

VkCommandBuffer, VkImage, VkImageCopy, VkImageLayout

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdCopyImage

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.