C Specification

For both vkCmdCopyBufferToImage and vkCmdCopyImageToBuffer, each element of pRegions is a structure defined as:

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

Members

  • bufferOffset is the offset in bytes from the start of the buffer object where the image data is copied from or to.

  • bufferRowLength and bufferImageHeight specify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to the imageExtent.

  • imageSubresource is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data.

  • imageOffset selects the initial x, y, z offsets in texels of the sub-region of the source or destination image data.

  • imageExtent is the size in texels of the image to copy in width, height and depth.

Description

When copying to or from a depth or stencil aspect, the data in buffer memory uses a layout that is a (mostly) tightly packed representation of the depth or stencil data. Specifically:

  • data copied to or from the stencil aspect of any depth/stencil format is tightly packed with one VK_FORMAT_S8_UINT value per texel.

  • data copied to or from the depth aspect of a VK_FORMAT_D16_UNORM or VK_FORMAT_D16_UNORM_S8_UINT format is tightly packed with one VK_FORMAT_D16_UNORM value per texel.

  • data copied to or from the depth aspect of a VK_FORMAT_D32_SFLOAT or VK_FORMAT_D32_SFLOAT_S8_UINT format is tightly packed with one VK_FORMAT_D32_SFLOAT value per texel.

  • data copied to or from the depth aspect of a VK_FORMAT_X8_D24_UNORM_PACK32 or VK_FORMAT_D24_UNORM_S8_UINT format is packed with one 32-bit word per texel with the D24 value in the LSBs of the word, and undefined values in the eight MSBs.

Note

To copy both the depth and stencil aspects of a depth/stencil format, two entries in pRegions can be used, where one specifies the depth aspect in imageSubresource, and the other specifies the stencil aspect.

Because depth or stencil aspect buffer to image copies may require format conversions on some implementations, they are not supported on queues that do not support graphics.

When copying to a depth aspect, and the VK_EXT_depth_range_unrestricted extension is not enabled, the data in buffer memory must be in the range [0,1], or the resulting values are undefined.

Copies are done layer by layer starting with image layer baseArrayLayer member of imageSubresource. layerCount layers are copied from the source image or to the destination image.

For purpose of valid usage statements here and in related copy commands, a blocked image is defined as:

  • an image with a single-plane, “_422” format, which is treated as a format with a 2 × 1 compressed texel block, or

  • a compressed image.

Valid Usage

  • VUID-VkBufferImageCopy-bufferRowLength-00195
    bufferRowLength must be 0, or greater than or equal to the width member of imageExtent

  • VUID-VkBufferImageCopy-bufferImageHeight-00196
    bufferImageHeight must be 0, or greater than or equal to the height member of imageExtent

  • VUID-VkBufferImageCopy-aspectMask-00212
    The aspectMask member of imageSubresource must only have a single bit set

  • VUID-VkBufferImageCopy-imageExtent-06659
    imageExtent.width must not be 0

  • VUID-VkBufferImageCopy-imageExtent-06660
    imageExtent.height must not be 0

  • VUID-VkBufferImageCopy-imageExtent-06661
    imageExtent.depth must not be 0

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, VkDeviceSize, VkExtent3D, VkImageSubresourceLayers, VkOffset3D, vkCmdCopyBufferToImage, vkCmdCopyImageToBuffer

Document Notes

For more information, see the Vulkan Specification

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

Copyright

Copyright 2014-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0