VKCMDCOPYIMAGETOBUFF(3)

NAME
vkCmdCopyImageToBuffer - Copy image data into a buffer.

C SPECIFICATION

    void vkCmdCopyImageToBuffer(
        VkCommandBuffer                             commandBuffer,
        VkImage                                     srcImage,
        VkImageLayout                               srcImageLayout,
        VkBuffer                                    dstBuffer,
        uint32_t                                    regionCount,
        const VkBufferImageCopy*                    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.

dstBuffer
    The buffer that is to receive the copied data.

regionCount
    The number of regions to copy.

pRegions
    An array of regionCount regions to copy.

DESCRIPTION

vkCmdCopyImageToBuffer copies image data into a buffer object. srcImage specifies the image that is to be the source of the data. dstBuffer is the buffer into which the data is to be copied. pRegions points to an array of regionCount VkBufferImageCopy structures, the definition of which is:

    typedef struct VkBufferImageCopy {
        VkDeviceSize                bufferOffset;
        uint32_t                    bufferRowLength;
        uint32_t                    bufferImageHeight;
        VkImageSubresourceLayers    imageSubresource;
        VkOffset3D                  imageOffset;
        VkExtent3D                  imageExtent;
    } VkBufferImageCopy;

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • srcImage must be a valid VkImage handle

    • srcImageLayout must be a valid VkImageLayout value

    • dstBuffer must be a valid VkBuffer handle

    • pRegions must be a pointer to an array of regionCount valid VkBufferImageCopy 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 dstBuffer must have been created, allocated or retrieved from the same VkDevice

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

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

    • 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

    • srcImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

    • 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

    • dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

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 vkCmdCopyImageToBuffer 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

vkCmdCopyBufferToImage, vkCmdCopyImage

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.