C Specification

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

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 the data in buffer memory as a subregion of a larger two- or three-dimensional image, and control the addressing calculations of data in buffer memory. 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, the data in buffer memory must be in the the range [0,1] or undefined results occur.

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.

Valid Usage
• If the calling command’s VkImage parameter’s format is not a depth/stencil format or a multi-planar format, then bufferOffset must be a multiple of the format’s element size

• If the calling command’s VkImage parameter’s format is a multi-planar format, then bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in ../../html/vkspec.html#features-formats-compatible-planes

• bufferOffset must be a multiple of 4

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

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

• imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the image subresource width where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format

• imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the image subresource height where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format

• If the calling command’s srcImage (vkCmdCopyImageToBuffer) or dstImage (vkCmdCopyBufferToImage) is of type VK_IMAGE_TYPE_1D, then imageOffset.y must be 0 and imageExtent.height must be 1.

• imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the image subresource depth

• If the calling command’s srcImage (vkCmdCopyImageToBuffer) or dstImage (vkCmdCopyBufferToImage) is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then imageOffset.z must be 0 and imageExtent.depth must be 1

• If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, bufferRowLength must be a multiple of the compressed texel block width

• If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, bufferImageHeight must be a multiple of the compressed texel block height

• If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, all members of imageOffset must be a multiple of the corresponding dimensions of the compressed texel block

• If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, bufferOffset must be a multiple of the compressed texel block size in bytes

• If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.width must be a multiple of the compressed texel block width or (imageExtent.width + imageOffset.x) must equal the image subresource width

• If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.height must be a multiple of the compressed texel block height or (imageExtent.height + imageOffset.y) must equal the image subresource height

• If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.depth must be a multiple of the compressed texel block depth or (imageExtent.depth + imageOffset.z) must equal the image subresource depth

• The aspectMask member of imageSubresource must specify aspects present in the calling command’s VkImage parameter

• If the calling command’s VkImage parameter’s format is a multi-planar format, then the aspectMask member of imageSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT (with VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with three planes)

• The aspectMask member of imageSubresource must only have a single bit set

• If the calling command’s VkImage parameter is of VkImageType VK_IMAGE_TYPE_3D, the baseArrayLayer and layerCount members of imageSubresource must be 0 and 1, respectively

• When copying to the depth aspect of an image subresource, the data in the source buffer must be in the range [0,1]

Valid Usage (Implicit)
• imageSubresource must be a valid VkImageSubresourceLayers structure