VKCMDCOPYBUFFERTOIMA(3)

NAME
vkCmdCopyBufferToImage - Copy data from a buffer into an image.

C SPECIFICATION

    void vkCmdCopyBufferToImage(
        VkCommandBuffer                             commandBuffer,
        VkBuffer                                    srcBuffer,
        VkImage                                     dstImage,
        VkImageLayout                               dstImageLayout,
        uint32_t                                    regionCount,
        const VkBufferImageCopy*                    pRegions);

PARAMETERS

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

srcBuffer
    The buffer from which data is to be sourced.

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

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

regionCount
    The number of image regions to update.

pRegions
    An array of regionCount regions to update.

DESCRIPTION

vkCmdCopyBufferToImage copies regionCount regions of data from srcBuffer into dstImage. pRegions points to an array of VkBufferImageCopy structures which describe the regions to be copied. The definition of VkBufferImageCopy 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

    • srcBuffer must be a valid VkBuffer handle

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

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

    • The image 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

    • srcBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag

    • dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

    • dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

    • 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

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

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.