vkCopyMemoryToImageEXT - Copy data from host memory into an image

Description

This command is functionally similar to cmdCopyBufferToImage2, except it is executed on the host and reads from host memory instead of a buffer.

Valid Usage

• The hostImageCopy feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pCopyMemoryToImageInfo must be a valid pointer to a valid CopyMemoryToImageInfoEXT structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_INITIALIZATION_FAILED
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_MEMORY_MAP_FAILED

See Also

VK_EXT_host_image_copy, CopyMemoryToImageInfoEXT, Device

vkCopyImageToMemoryEXT - Copy image data into host memory

Description

This command is functionally similar to cmdCopyImageToBuffer2, except it is executed on the host and writes to host memory instead of a buffer.

Valid Usage

• The hostImageCopy feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pCopyImageToMemoryInfo must be a valid pointer to a valid CopyImageToMemoryInfoEXT structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_INITIALIZATION_FAILED
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_MEMORY_MAP_FAILED

See Also

VK_EXT_host_image_copy, CopyImageToMemoryInfoEXT, Device

vkCopyImageToImageEXT - Copy image data using the host

Description

This command is functionally similar to cmdCopyImage2, except it is executed on the host.

Valid Usage

• The hostImageCopy feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pCopyImageToImageInfo must be a valid pointer to a valid CopyImageToImageInfoEXT structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_INITIALIZATION_FAILED
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_MEMORY_MAP_FAILED

See Also

VK_EXT_host_image_copy, CopyImageToImageInfoEXT, Device

vkTransitionImageLayoutEXT - Perform an image layout transition on the host

Return Codes

Success

• SUCCESS

Failure

• ERROR_INITIALIZATION_FAILED
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_MEMORY_MAP_FAILED

See Also

VK_EXT_host_image_copy, Device, HostImageLayoutTransitionInfoEXT

VkPhysicalDeviceHostImageCopyFeaturesEXT - Structure indicating support for copies to or from images from host memory

Members

This structure describes the following feature:

Description

If the PhysicalDeviceHostImageCopyFeaturesEXT structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDeviceHostImageCopyFeaturesEXT can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_EXT_host_image_copy, Bool32, StructureType

VkPhysicalDeviceHostImageCopyPropertiesEXT - Structure enumerating image layouts supported by an implementation for host memory copies

Description

If the PhysicalDeviceHostImageCopyPropertiesEXT structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

If pCopyDstLayouts is NULL, then the number of image layouts that are supported in CopyMemoryToImageInfoEXT::dstImageLayout and CopyImageToImageInfoEXT::dstImageLayout is returned in copyDstLayoutCount. Otherwise, copyDstLayoutCount must be set by the user to the number of elements in the pCopyDstLayouts array, and on return the variable is overwritten with the number of values actually written to pCopyDstLayouts. If the value of copyDstLayoutCount is less than the number of image layouts that are supported, at most copyDstLayoutCount values will be written to pCopyDstLayouts. The implementation must include the IMAGE_LAYOUT_GENERAL image layout in pCopyDstLayouts.

If pCopySrcLayouts is NULL, then the number of image layouts that are supported in CopyImageToMemoryInfoEXT::srcImageLayout and CopyImageToImageInfoEXT::srcImageLayout is returned in copySrcLayoutCount. Otherwise, copySrcLayoutCount must be set by the user to the number of elements in the pCopySrcLayouts array, and on return the variable is overwritten with the number of values actually written to pCopySrcLayouts. If the value of copySrcLayoutCount is less than the number of image layouts that are supported, at most copySrcLayoutCount values will be written to pCopySrcLayouts. The implementation must include the IMAGE_LAYOUT_GENERAL image layout in pCopySrcLayouts.

The optimalTilingLayoutUUID value can be used to ensure compatible data layouts when using the HOST_IMAGE_COPY_MEMCPY_EXT flag in copyMemoryToImageEXT and copyImageToMemoryEXT.

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES_EXT

• If copySrcLayoutCount is not 0, and pCopySrcLayouts is not NULL, pCopySrcLayouts must be a valid pointer to an array of copySrcLayoutCount ImageLayout values
• If copyDstLayoutCount is not 0, and pCopyDstLayouts is not NULL, pCopyDstLayouts must be a valid pointer to an array of copyDstLayoutCount ImageLayout values

See Also

VK_EXT_host_image_copy, Bool32, ImageLayout, StructureType

VkMemoryToImageCopyEXT - Structure specifying a host memory to image copy operation

Description

This structure is functionally similar to BufferImageCopy2, except it defines host memory as the source of copy instead of a buffer. In particular, the same data packing rules and restrictions as that structure apply here as well.

Valid Usage

• pHostPointer must point to memory that is large enough to contain all memory locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

• The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
• memoryRowLength must be 0, or greater than or equal to the width member of imageExtent
• memoryImageHeight must be 0, or greater than or equal to the height member of imageExtent
• The aspectMask member of imageSubresource must only have a single bit set
• imageExtent.width must not be 0
• imageExtent.height must not be 0
• imageExtent.depth must not be 0

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY_EXT

• pNext must be NULL
• pHostPointer must be a pointer value
• imageSubresource must be a valid ImageSubresourceLayers structure

See Also

VK_EXT_host_image_copy, CopyMemoryToImageInfoEXT, Extent3D, ImageSubresourceLayers, Offset3D, StructureType

VkImageToMemoryCopyEXT - Structure specifying an image to host memory copy operation

Description

This structure is functionally similar to BufferImageCopy2, except it defines host memory as the target of copy instead of a buffer. In particular, the same data packing rules and restrictions as that structure apply here as well.

Valid Usage

• pHostPointer must point to memory that is large enough to contain all memory locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

• The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory
• memoryRowLength must be 0, or greater than or equal to the width member of imageExtent
• memoryImageHeight must be 0, or greater than or equal to the height member of imageExtent
• The aspectMask member of imageSubresource must only have a single bit set
• imageExtent.width must not be 0
• imageExtent.height must not be 0
• imageExtent.depth must not be 0

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY_EXT

• pNext must be NULL
• pHostPointer must be a pointer value
• imageSubresource must be a valid ImageSubresourceLayers structure

See Also

VK_EXT_host_image_copy, CopyImageToMemoryInfoEXT, Extent3D, ImageSubresourceLayers, Offset3D, StructureType

VkCopyMemoryToImageInfoEXT - Structure specifying parameters of host memory to image copy command

Description

copyMemoryToImageEXT does not check whether the device memory associated with dstImage is currently in use before performing the copy. The application must guarantee that any previously submitted command that reads from or 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

• If dstImage is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory

• If the stencil aspect of dstImage is accessed, and dstImage was not created with separate stencil usage, dstImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageCreateInfo::usage
• If the stencil aspect of dstImage is accessed, and dstImage was created with separate stencil usage, dstImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageStencilUsageCreateInfo::stencilUsage
• If non-stencil aspects of dstImage are accessed, dstImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageCreateInfo::usage
• If flags contains HOST_IMAGE_COPY_MEMCPY_EXT, the x, y, and z members of the imageOffset member of each element of pRegions must be 0
• If flags contains HOST_IMAGE_COPY_MEMCPY_EXT, the imageExtent member of each element of pRegions must equal the extents of dstImage identified by imageSubresource
• If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single DeviceMemory object
• The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
• If imageSubresource.layerCount is not REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
• dstImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
• The image region specified by each element of pRegions must be contained within the specified imageSubresource of dstImage
• 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 dstImage
• 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 dstImage
• dstImage must have a sample count equal to SAMPLE_COUNT_1_BIT
• If dstImage is of type IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1
• 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 dstImage
• If dstImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1
• For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the Format of dstImage
• For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the Format of dstImage
• For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the Format of dstImage
• 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 Format of dstImage
• 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 Format of dstImage
• 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 Format of dstImage
• For each element of pRegions, imageSubresource.aspectMask must specify aspects present in dstImage
• If dstImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit
• If dstImage is of type IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1
• For each element of pRegions, memoryRowLength must be a multiple of the texel block extent width of the Format of dstImage
• For each element of pRegions, memoryImageHeight must be a multiple of the texel block extent height of the Format of dstImage
• For each element of pRegions, memoryRowLength divided by the texel block extent width and then multiplied by the texel block size of dstImage must be less than or equal to 231-1
• dstImageLayout must specify the current layout of the image subresources of dstImage specified in pRegions
• dstImageLayout must be one of the image layouts returned in PhysicalDeviceHostImageCopyPropertiesEXT::pCopyDstLayouts
• If flags includes HOST_IMAGE_COPY_MEMCPY_EXT, for each region in pRegions, memoryRowLength and memoryImageHeight must both be 0

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO_EXT

• pNext must be NULL
• flags must be a valid combination of HostImageCopyFlagBitsEXT values
• dstImage must be a valid Image handle
• dstImageLayout must be a valid ImageLayout value
• pRegions must be a valid pointer to an array of regionCount valid MemoryToImageCopyEXT structures
• regionCount must be greater than 0

See Also

VK_EXT_host_image_copy, HostImageCopyFlagsEXT, Image, ImageLayout, MemoryToImageCopyEXT, StructureType, copyMemoryToImageEXT

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

Description

copyImageToMemoryEXT 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

• If srcImage is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory

• If the stencil aspect of srcImage is accessed, and srcImage was not created with separate stencil usage, srcImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageCreateInfo::usage
• If the stencil aspect of srcImage is accessed, and srcImage was created with separate stencil usage, srcImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageStencilUsageCreateInfo::stencilUsage
• If non-stencil aspects of srcImage are accessed, srcImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageCreateInfo::usage
• If flags contains HOST_IMAGE_COPY_MEMCPY_EXT, the x, y, and z members of the imageOffset member of each element of pRegions must be 0
• If flags contains HOST_IMAGE_COPY_MEMCPY_EXT, the imageExtent member of each element of pRegions must equal the extents of srcImage identified by imageSubresource
• If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single DeviceMemory object
• The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
• If imageSubresource.layerCount is not REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
• srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
• The image region specified by each element of pRegions must be contained within the specified imageSubresource of srcImage
• 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
• 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
• srcImage must have a sample count equal to SAMPLE_COUNT_1_BIT
• If srcImage is of type IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1
• 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
• If srcImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1
• For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the Format of srcImage
• For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the Format of srcImage
• For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the Format of srcImage
• 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 Format of srcImage
• 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 Format of srcImage
• 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 Format of srcImage
• For each element of pRegions, imageSubresource.aspectMask must specify aspects present in srcImage
• 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
• If srcImage is of type IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1
• For each element of pRegions, memoryRowLength must be a multiple of the texel block extent width of the Format of srcImage
• For each element of pRegions, memoryImageHeight must be a multiple of the texel block extent height of the Format of srcImage
• 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
• srcImageLayout must specify the current layout of the image subresources of srcImage specified in pRegions
• srcImageLayout must be one of the image layouts returned in PhysicalDeviceHostImageCopyPropertiesEXT::pCopySrcLayouts
• If flags includes HOST_IMAGE_COPY_MEMCPY_EXT, for each region in pRegions, memoryRowLength and memoryImageHeight must both be 0

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXT

• pNext must be NULL
• flags must be a valid combination of HostImageCopyFlagBitsEXT values
• srcImage must be a valid Image handle
• srcImageLayout must be a valid ImageLayout value
• pRegions must be a valid pointer to an array of regionCount valid ImageToMemoryCopyEXT structures
• regionCount must be greater than 0

See Also

VK_EXT_host_image_copy, HostImageCopyFlagsEXT, Image, ImageLayout, ImageToMemoryCopyEXT, StructureType, copyImageToMemoryEXT

VkCopyImageToImageInfoEXT - Structure specifying parameters of an image to image host copy command

Description

copyImageToImageEXT does not check whether the device memory associated with srcImage or dstImage 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.

Valid Usage

• srcImage and dstImage must have been created with identical image creation parameters

• If srcImage is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory
• If the stencil aspect of srcImage is accessed, and srcImage was not created with separate stencil usage, srcImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageCreateInfo::usage
• If the stencil aspect of srcImage is accessed, and srcImage was created with separate stencil usage, srcImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageStencilUsageCreateInfo::stencilUsage
• If non-stencil aspects of srcImage are accessed, srcImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageCreateInfo::usage
• If flags contains HOST_IMAGE_COPY_MEMCPY_EXT, the x, y, and z members of the srcOffset member of each element of pRegions must be 0
• If flags contains HOST_IMAGE_COPY_MEMCPY_EXT, the extent member of each element of pRegions must equal the extents of srcImage identified by srcSubresource
• If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single DeviceMemory object
• The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when srcImage was created
• If srcSubresource.layerCount is not REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when srcImage was created
• srcImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
• The image region specified by each element of pRegions must be contained within the specified srcSubresource of srcImage
• For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage
• For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage
• If srcImage is of type IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1
• For each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage
• If srcImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1
• For each element of pRegions, srcOffset.x must be a multiple of the texel block extent width of the Format of srcImage
• For each element of pRegions, srcOffset.y must be a multiple of the texel block extent height of the Format of srcImage
• For each element of pRegions, srcOffset.z must be a multiple of the texel block extent depth of the Format of srcImage
• For each element of pRegions, if the sum of srcOffset.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 Format of srcImage
• For each element of pRegions, if the sum of srcOffset.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 Format of srcImage
• For each element of pRegions, if the sum of srcOffset.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 Format of srcImage
• For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage
• If srcImage has a multi-planar image format, then for each element of pRegions, srcSubresource.aspectMask must be a single valid multi-planar aspect mask bit
• If srcImage is of type IMAGE_TYPE_3D, for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and srcSubresource.layerCount must be 1
• If dstImage is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory
• If the stencil aspect of dstImage is accessed, and dstImage was not created with separate stencil usage, dstImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageCreateInfo::usage
• If the stencil aspect of dstImage is accessed, and dstImage was created with separate stencil usage, dstImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageStencilUsageCreateInfo::stencilUsage
• If non-stencil aspects of dstImage are accessed, dstImage must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in ImageCreateInfo::usage
• If flags contains HOST_IMAGE_COPY_MEMCPY_EXT, the x, y, and z members of the dstOffset member of each element of pRegions must be 0
• If flags contains HOST_IMAGE_COPY_MEMCPY_EXT, the extent member of each element of pRegions must equal the extents of dstImage identified by dstSubresource
• If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single DeviceMemory object
• The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in ImageCreateInfo when dstImage was created
• If dstSubresource.layerCount is not REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in ImageCreateInfo when dstImage was created
• dstImage must not have been created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT
• The image region specified by each element of pRegions must be contained within the specified dstSubresource of dstImage
• For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage
• For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage
• If dstImage is of type IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1
• For each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage
• If dstImage is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1
• For each element of pRegions, dstOffset.x must be a multiple of the texel block extent width of the Format of dstImage
• For each element of pRegions, dstOffset.y must be a multiple of the texel block extent height of the Format of dstImage
• For each element of pRegions, dstOffset.z must be a multiple of the texel block extent depth of the Format of dstImage
• For each element of pRegions, if the sum of dstOffset.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 Format of dstImage
• For each element of pRegions, if the sum of dstOffset.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 Format of dstImage
• For each element of pRegions, if the sum of dstOffset.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 Format of dstImage
• For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage
• If dstImage has a multi-planar image format, then for each element of pRegions, dstSubresource.aspectMask must be a single valid multi-planar aspect mask bit
• If dstImage is of type IMAGE_TYPE_3D, for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1
• srcImageLayout must specify the current layout of the image subresources of srcImage specified in pRegions
• dstImageLayout must specify the current layout of the image subresources of dstImage specified in pRegions
• srcImageLayout must be one of the image layouts returned in PhysicalDeviceHostImageCopyPropertiesEXT::pCopySrcLayouts
• dstImageLayout must be one of the image layouts returned in PhysicalDeviceHostImageCopyPropertiesEXT::pCopyDstLayouts

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO_EXT

• pNext must be NULL
• flags must be a valid combination of HostImageCopyFlagBitsEXT values
• srcImage must be a valid Image handle
• srcImageLayout must be a valid ImageLayout value
• dstImage must be a valid Image handle
• dstImageLayout must be a valid ImageLayout value
• pRegions must be a valid pointer to an array of regionCount valid ImageCopy2 structures
• regionCount must be greater than 0
• Both of dstImage, and srcImage must have been created, allocated, or retrieved from the same Device

See Also

VK_EXT_host_image_copy, HostImageCopyFlagsEXT, Image, ImageCopy2, ImageLayout, StructureType, copyImageToImageEXT

VkHostImageLayoutTransitionInfoEXT - Structure specifying the parameters of a host-side image layout transition

Description

transitionImageLayoutEXT does not check whether the device memory associated with an image is currently in use before performing the layout transition. The application must guarantee that any previously submitted command that reads from or writes to this subresource has completed before the host performs the layout transition.

Note

Image layout transitions performed on the host do not require queue family ownership transfers as the physical layout of the image will not vary between queue families for the layouts supported by this function.

Valid Usage

• image must have been created with IMAGE_USAGE_HOST_TRANSFER_BIT_EXT

• subresourceRange.baseMipLevel must be less than the mipLevels specified in ImageCreateInfo when image was created
• If subresourceRange.levelCount is not REMAINING_MIP_LEVELS, subresourceRange.baseMipLevel + subresourceRange.levelCount must be less than or equal to the mipLevels specified in ImageCreateInfo when image was created
• subresourceRange.baseArrayLayer must be less than the arrayLayers specified in ImageCreateInfo when image was created
• If subresourceRange.layerCount is not REMAINING_ARRAY_LAYERS, subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in ImageCreateInfo when image was created
• If image is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• If image has a color format that is single-plane, then the aspectMask member of subresourceRange must be IMAGE_ASPECT_COLOR_BIT
• If image has a color format and is not disjoint, then the aspectMask member of subresourceRange must be IMAGE_ASPECT_COLOR_BIT
• If image has a multi-planar format and the image is disjoint, then the aspectMask member of subresourceRange must include at least one multi-planar aspect mask bit or IMAGE_ASPECT_COLOR_BIT
• If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is enabled, then the aspectMask member of subresourceRange must include either or both IMAGE_ASPECT_DEPTH_BIT and IMAGE_ASPECT_STENCIL_BIT
• If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is not enabled, then the aspectMask member of subresourceRange must include both IMAGE_ASPECT_DEPTH_BIT and IMAGE_ASPECT_STENCIL_BIT
• If the aspectMask member of subresourceRange includes IMAGE_ASPECT_DEPTH_BIT, oldLayout and newLayout must not be one of IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
• If the aspectMask member of subresourceRange includes IMAGE_ASPECT_STENCIL_BIT, oldLayout and newLayout must not be one of IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
• oldLayout must be either IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources as specified in subresourceRange
• If oldLayout is not IMAGE_LAYOUT_UNDEFINED or IMAGE_LAYOUT_PREINITIALIZED, it must be one of the layouts in PhysicalDeviceHostImageCopyPropertiesEXT::pCopySrcLayouts
• newLayout must be one of the layouts in PhysicalDeviceHostImageCopyPropertiesEXT::pCopyDstLayouts

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXT

• pNext must be NULL
• image must be a valid Image handle
• oldLayout must be a valid ImageLayout value
• newLayout must be a valid ImageLayout value
• subresourceRange must be a valid ImageSubresourceRange structure

See Also

VK_EXT_host_image_copy, Image, ImageLayout, ImageSubresourceRange, StructureType, transitionImageLayoutEXT

VkSubresourceHostMemcpySizeEXT - Memory size needed to copy to or from an image on the host with VK_HOST_IMAGE_COPY_MEMCPY_EXT

Valid Usage (Implicit)

See Also

VK_EXT_host_image_copy, DeviceSize, StructureType

VkHostImageCopyDevicePerformanceQueryEXT - Struct containing information about optimality of device access

Description

The implementation may return FALSE in optimalDeviceAccess if identicalMemoryLayout is FALSE. If identicalMemoryLayout is TRUE, optimalDeviceAccess must be TRUE.

The implementation may return TRUE in optimalDeviceAccess while identicalMemoryLayout is FALSE. In this situation, any device performance impact should not be measurable.

If PhysicalDeviceImageFormatInfo2::format is a block-compressed format and getPhysicalDeviceImageFormatProperties2 returns SUCCESS, the implementation must return TRUE in optimalDeviceAccess.

Note

Applications can make use of optimalDeviceAccess to determine their resource copying strategy. If a resource is expected to be accessed more on device than on the host, and the implementation considers the resource sub-optimally accessed, it is likely better to use device copies instead.

Note

Layout not being identical yet still considered optimal for device access could happen if the implementation has different memory layout patterns, some of which are easier to access on the host.

Note

The most practical reason for optimalDeviceAccess to be FALSE is that host image access may disable framebuffer compression where it would otherwise have been enabled. This represents far more efficient host image access since no compression algorithm is required to read or write to the image, but it would impact device access performance. Some implementations may only set optimalDeviceAccess to FALSE if certain conditions are met, such as specific image usage flags or creation flags.

Valid Usage (Implicit)

See Also

VK_EXT_host_image_copy, Bool32, StructureType

VkHostImageCopyFlagBitsEXT - Bitmask specifying additional copy parameters

See Also

VK_EXT_host_image_copy, HostImageCopyFlagsEXT

VkImageSubresource2KHR - Structure specifying an image subresource

Valid Usage (Implicit)

See Also

VK_EXT_host_image_copy, VK_EXT_image_compression_control, VK_KHR_maintenance5, DeviceImageSubresourceInfoKHR, ImageSubresource, StructureType, getImageSubresourceLayout2EXT, getImageSubresourceLayout2KHR

VkSubresourceLayout2KHR - Structure specifying subresource layout

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_KHR

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of ImageCompressionPropertiesEXT or SubresourceHostMemcpySizeEXT
• The sType value of each struct in the pNext chain must be unique

See Also

VK_EXT_host_image_copy, VK_EXT_image_compression_control, VK_KHR_maintenance5, StructureType, SubresourceLayout, getDeviceImageSubresourceLayoutKHR, getImageSubresourceLayout2EXT, getImageSubresourceLayout2KHR

vkGetImageSubresourceLayout2KHR - Retrieve information about an image subresource

Description

getImageSubresourceLayout2KHR behaves similarly to getImageSubresourceLayout, with the ability to specify extended inputs via chained input structures, and to return extended information via chained output structures.

It is legal to call getImageSubresourceLayout2KHR with a image created with tiling equal to IMAGE_TILING_OPTIMAL, but the members of SubresourceLayout2KHR::subresourceLayout will have undefined values in this case.

Note

Structures chained from ImageSubresource2KHR::pNext will also be updated when tiling is equal to IMAGE_TILING_OPTIMAL.

Valid Usage

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

• The mipLevel member of pSubresource must be less than the mipLevels specified in ImageCreateInfo when image was created
• The arrayLayer member of pSubresource must be less than the arrayLayers specified in ImageCreateInfo when image was created
• If format of the image is a color format, tiling of the image is IMAGE_TILING_LINEAR or IMAGE_TILING_OPTIMAL, and does not have a multi-planar image format, the aspectMask member of pSubresource must be IMAGE_ASPECT_COLOR_BIT
• If format of the image has a depth component, the aspectMask member of pSubresource must contain IMAGE_ASPECT_DEPTH_BIT
• If format of the image has a stencil component, the aspectMask member of pSubresource must contain IMAGE_ASPECT_STENCIL_BIT
• If format of the image does not contain a stencil or depth component, the aspectMask member of pSubresource must not contain IMAGE_ASPECT_DEPTH_BIT or IMAGE_ASPECT_STENCIL_BIT
• If the tiling of the image is IMAGE_TILING_LINEAR and has a multi-planar image format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit
• If image was created with the EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle type, then image must be bound to memory
• If the tiling of the image is IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT and the index i must be less than the DrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount associated with the image’s format and ImageDrmFormatModifierPropertiesEXT::drmFormatModifier

Valid Usage (Implicit)

• device must be a valid Device handle

• image must be a valid Image handle
• pSubresource must be a valid pointer to a valid ImageSubresource2KHR structure
• pLayout must be a valid pointer to a SubresourceLayout2KHR structure
• image must have been created, allocated, or retrieved from device

See Also

VK_KHR_maintenance5, Device, Image, ImageSubresource2KHR, SubresourceLayout2KHR