VKCMDCOPYBUFFER(3)

NAME
vkCmdCopyBuffer - Copy data between buffer regions.

C SPECIFICATION

    void vkCmdCopyBuffer(
        VkCommandBuffer                             commandBuffer,
        VkBuffer                                    srcBuffer,
        VkBuffer                                    dstBuffer,
        uint32_t                                    regionCount,
        const VkBufferCopy*                         pRegions);

PARAMETERS

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

srcBuffer
    The buffer containing the data to be copied.

dstBuffer
    The buffer into which data will be copied.

regionCount
    The number of regions of data to copy.

pRegions
    An array of regionCount regions of data to be copied.

DESCRIPTION

vkCmdCopyBuffer copies regions of data from a source buffer to a destination buffer. regionCount regions are copied from srcBuffer to dstBuffer. Each region is represented by a member of the pRegions array, which is an array of the VkBufferCopy structure, whose definition is:

    typedef struct VkBufferCopy {
        VkDeviceSize    srcOffset;
        VkDeviceSize    dstOffset;
        VkDeviceSize    size;
    } VkBufferCopy;

If any two or more regions within pRegions overlap, the resulting data will be undefined. It is recommended, but not required, that the regions given in pRegions start on multiples of four bytes and have a length which is a multiple of four bytes.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • srcBuffer must be a valid VkBuffer handle

    • dstBuffer must be a valid VkBuffer handle

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

    • The size member of a given element of pRegions must be greater than 0

    • The srcOffset member of a given element of pRegions must be less than the size of srcBuffer

    • The dstOffset member of a given element of pRegions must be less than the size of dstBuffer

    • The size member of a given element of pRegions must be less than or equal to the size of srcBuffer minus srcOffset

    • The size member of a given element of pRegions must be less than or equal to the size of dstBuffer minus dstOffset

    • The union of the source regions, and the union of the 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

    • 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 vkCmdCopyBuffer 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

vkCmdCopyImage, vkCmdCopyBufferToImage, 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.