VkBufferImageCopy(3)

# VkBufferImageCopy(3) Manual Page

## Name

VkBufferImageCopy - Structure specifying a buffer image copy operation

Loading... please wait.

## 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 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.

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 texel block 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 https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#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

Valid Usage (Implicit)

- `imageSubresource` must be a valid VkImageSubresourceLayers structure

## See Also

`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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.