VkCopyImageToMemoryInfoEXT(3)

# VkCopyImageToMemoryInfoEXT(3) Manual Page

## Name

VkCopyImageToMemoryInfoEXT - Structure specifying parameters of an image to host memory copy command

Loading… please wait.

## C Specification

The `VkCopyImageToMemoryInfoEXT` structure is defined as:

    // Provided by VK_EXT_host_image_copy
    typedef struct VkCopyImageToMemoryInfoEXT {
        VkStructureType                  sType;
        const void*                      pNext;
        VkHostImageCopyFlagsEXT          flags;
        VkImage                          srcImage;
        VkImageLayout                    srcImageLayout;
        uint32_t                         regionCount;
        const VkImageToMemoryCopyEXT*    pRegions;
    } VkCopyImageToMemoryInfoEXT;

## Members

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `flags` is a bitmask of VkHostImageCopyFlagBitsEXT values describing additional copy parameters.

- `srcImage` is the source image.

- `srcImageLayout` is the layout of the source image subresources for the copy.

- `regionCount` is the number of regions to copy.

- `pRegions` is a pointer to an array of VkImageToMemoryCopyEXT structures specifying the regions to copy.

## Description

`vkCopyImageToMemoryEXT` does not check whether the device memory associated with `srcImage` is currently in use before performing the copy. The application must guarantee that any previously submitted command that writes to the copy regions has completed before the host performs the copy.

Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

Valid Usage

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-09109
  If `srcImage` is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-09111
  If the stencil aspect of `srcImage` is accessed, and `srcImage` was not created with separate stencil usage, `srcImage` must have been created with `VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT` set in VkImageCreateInfo::`usage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-09112
  If the stencil aspect of `srcImage` is accessed, and `srcImage` was created with separate stencil usage, `srcImage` must have been created with `VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT` set in VkImageStencilUsageCreateInfo::`stencilUsage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-09113
  If non-stencil aspects of `srcImage` are accessed, `srcImage` must have been created with `VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT` set in VkImageCreateInfo::`usage`

- VUID-VkCopyImageToMemoryInfoEXT-imageOffset-09114
  If `flags` contains `VK_HOST_IMAGE_COPY_MEMCPY_EXT`, the `x`, `y`, and `z` members of the `imageOffset` member of each element of `pRegions` must be `0`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-09115
  If `flags` contains `VK_HOST_IMAGE_COPY_MEMCPY_EXT`, the `imageExtent` member of each element of `pRegions` must equal the extents of `srcImage` identified by `imageSubresource`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07966
  If `srcImage` is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single `VkDeviceMemory` object

- VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07967
  The `imageSubresource.mipLevel` member of each element of `pRegions` must be less than the `mipLevels` specified in VkImageCreateInfo when `srcImage` was created

- VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07968
  If `imageSubresource.layerCount` is not `VK_REMAINING_ARRAY_LAYERS`, `imageSubresource.baseArrayLayer` + `imageSubresource.layerCount` of each element of `pRegions` must be less than or equal to the `arrayLayers` specified in VkImageCreateInfo when `srcImage` was created

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07969
  `srcImage` must not have been created with `flags` containing `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`

- VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07970
  The image region specified by each element of `pRegions` must be contained within the specified `imageSubresource` of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07971
  For each element of `pRegions`, `imageOffset.x` and (`imageExtent.width` + `imageOffset.x`) must both be greater than or equal to `0` and less than or equal to the width of the specified `imageSubresource` of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07972
  For each element of `pRegions`, `imageOffset.y` and (`imageExtent.height` + `imageOffset.y`) must both be greater than or equal to `0` and less than or equal to the height of the specified `imageSubresource` of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07973
  `srcImage` must have a sample count equal to `VK_SAMPLE_COUNT_1_BIT`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07979
  If `srcImage` is of type `VK_IMAGE_TYPE_1D`, then for each element of `pRegions`, `imageOffset.y` must be `0` and `imageExtent.height` must be `1`

- VUID-VkCopyImageToMemoryInfoEXT-imageOffset-09104
  For each element of `pRegions`, `imageOffset.z` and (`imageExtent.depth` + `imageOffset.z`) must both be greater than or equal to `0` and less than or equal to the depth of the specified `imageSubresource` of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07980
  If `srcImage` is of type `VK_IMAGE_TYPE_1D` or `VK_IMAGE_TYPE_2D`, then for each element of `pRegions`, `imageOffset.z` must be `0` and `imageExtent.depth` must be `1`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07274
  For each element of `pRegions`, `imageOffset.x` must be a multiple of the texel block extent width of the VkFormat of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07275
  For each element of `pRegions`, `imageOffset.y` must be a multiple of the texel block extent height of the VkFormat of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07276
  For each element of `pRegions`, `imageOffset.z` must be a multiple of the texel block extent depth of the VkFormat of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-00207
  For each element of `pRegions`, if the sum of `imageOffset.x` and `extent.width` does not equal the width of the subresource specified by `srcSubresource`, `extent.width` must be a multiple of the texel block extent width of the VkFormat of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-00208
  For each element of `pRegions`, if the sum of `imageOffset.y` and `extent.height` does not equal the height of the subresource specified by `srcSubresource`, `extent.height` must be a multiple of the texel block extent height of the VkFormat of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-00209
  For each element of `pRegions`, if the sum of `imageOffset.z` and `extent.depth` does not equal the depth of the subresource specified by `srcSubresource`, `extent.depth` must be a multiple of the texel block extent depth of the VkFormat of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-09105
  For each element of `pRegions`, `imageSubresource.aspectMask` must specify aspects present in `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07981
  If `srcImage` has a multi-planar image format, then for each element of `pRegions`, `imageSubresource.aspectMask` must be a single valid multi-planar aspect mask bit

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-07983
  If `srcImage` is of type `VK_IMAGE_TYPE_3D`, for each element of `pRegions`, `imageSubresource.baseArrayLayer` must be `0` and `imageSubresource.layerCount` must be `1`

- VUID-VkCopyImageToMemoryInfoEXT-memoryRowLength-09106
  For each element of `pRegions`, `memoryRowLength` must be a multiple of the texel block extent width of the VkFormat of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-memoryImageHeight-09107
  For each element of `pRegions`, `memoryImageHeight` must be a multiple of the texel block extent height of the VkFormat of `srcImage`

- VUID-VkCopyImageToMemoryInfoEXT-memoryRowLength-09108
  For each element of `pRegions`, `memoryRowLength` divided by the texel block extent width and then multiplied by the texel block size of `srcImage` must be less than or equal to 231-1

- VUID-VkCopyImageToMemoryInfoEXT-srcImageLayout-09064
  `srcImageLayout` must specify the current layout of the image subresources of `srcImage` specified in `pRegions`

- VUID-VkCopyImageToMemoryInfoEXT-srcImageLayout-09065
  `srcImageLayout` must be one of the image layouts returned in VkPhysicalDeviceHostImageCopyPropertiesEXT::`pCopySrcLayouts`

- VUID-VkCopyImageToMemoryInfoEXT-flags-09394
  If `flags` includes `VK_HOST_IMAGE_COPY_MEMCPY_EXT`, for each region in `pRegions`, `memoryRowLength` and `memoryImageHeight` must both be 0

Valid Usage (Implicit)

- VUID-VkCopyImageToMemoryInfoEXT-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXT`

- VUID-VkCopyImageToMemoryInfoEXT-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkCopyImageToMemoryInfoEXT-flags-parameter
  `flags` must be a valid combination of VkHostImageCopyFlagBitsEXT values

- VUID-VkCopyImageToMemoryInfoEXT-srcImage-parameter
  `srcImage` must be a valid VkImage handle

- VUID-VkCopyImageToMemoryInfoEXT-srcImageLayout-parameter
  `srcImageLayout` must be a valid VkImageLayout value

- VUID-VkCopyImageToMemoryInfoEXT-pRegions-parameter
  `pRegions` must be a valid pointer to an array of `regionCount` valid VkImageToMemoryCopyEXT structures

- VUID-VkCopyImageToMemoryInfoEXT-regionCount-arraylength
  `regionCount` must be greater than `0`

## See Also

VK_EXT_host_image_copy, VkHostImageCopyFlagsEXT, VkImage, VkImageLayout, VkImageToMemoryCopyEXT, VkStructureType, vkCopyImageToMemoryEXT

## 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-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0