1785 lines
85 KiB
Plaintext
1785 lines
85 KiB
Plaintext
// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[[copies]]
|
|
= Copy Commands
|
|
|
|
An application can: copy buffer and image data using several methods
|
|
depending on the type of data transfer.
|
|
Data can: be copied between buffer objects with fname:vkCmdCopyBuffer and a
|
|
portion of an image can: be copied to another image with
|
|
fname:vkCmdCopyImage.
|
|
Image data can: also be copied to and from buffer memory using
|
|
fname:vkCmdCopyImageToBuffer and fname:vkCmdCopyBufferToImage.
|
|
Image data can: be blitted (with or without scaling and filtering) with
|
|
fname:vkCmdBlitImage.
|
|
Multisampled images can: be resolved to a non-multisampled image with
|
|
fname:vkCmdResolveImage.
|
|
|
|
|
|
== Common Operation
|
|
|
|
Some rules for valid operation are common to all copy commands:
|
|
|
|
* Copy commands must: be recorded outside of a render pass instance.
|
|
* For non-sparse resources, the union of the source regions in a given
|
|
buffer or image must: not overlap the union of the destination regions
|
|
in the same buffer or image.
|
|
* For sparse resources, the set of bytes used by all the source regions
|
|
must: not intersect the set of bytes used by all the destination
|
|
regions.
|
|
* Copy regions must: be non-empty.
|
|
* Regions must: not extend outside the bounds of the buffer or image
|
|
level, except that regions of compressed images can: extend as far as
|
|
the dimension of the image level rounded up to a complete compressed
|
|
texel block.
|
|
* Source image subresources must: be in either the
|
|
ename:VK_IMAGE_LAYOUT_GENERAL or
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL layout.
|
|
Destination image subresources must: be in the
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ename:VK_IMAGE_LAYOUT_GENERAL or
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL layout.
|
|
As a consequence, if an image subresource is used as both source and
|
|
destination of a copy, it must: be in the ename:VK_IMAGE_LAYOUT_GENERAL
|
|
layout.
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* Source images must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties.
|
|
* Destination images must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties.
|
|
endif::VK_KHR_maintenance1[]
|
|
* Source images must: have been created with the
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
|
|
images must: have been created with the
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
|
* Source buffers must: have been created with the
|
|
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
|
|
buffers must: have been created with the
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
|
|
|
All copy commands are treated as "`transfer`" operations for the purposes of
|
|
synchronization barriers.
|
|
|
|
|
|
[[copies-buffers]]
|
|
== Copying Data Between Buffers
|
|
|
|
[open,refpage='vkCmdCopyBuffer',desc='Copy data between buffer regions',type='protos']
|
|
--
|
|
|
|
To copy data between buffer objects, call:
|
|
|
|
include::../api/protos/vkCmdCopyBuffer.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcBuffer is the source buffer.
|
|
* pname:dstBuffer is the destination buffer.
|
|
* pname:regionCount is the number of regions to copy.
|
|
* pname:pRegions is a pointer to an array of slink:VkBufferCopy structures
|
|
specifying the regions to copy.
|
|
|
|
Each region in pname:pRegions is copied from the source buffer to the same
|
|
region of the destination buffer.
|
|
pname:srcBuffer and pname:dstBuffer can: be the same buffer or alias the
|
|
same memory, but the result is undefined if the copy regions overlap in
|
|
memory.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdCopyBuffer-size-00112]]
|
|
The pname:size member of each element of pname:pRegions must: be greater
|
|
than `0`
|
|
* [[VUID-vkCmdCopyBuffer-srcOffset-00113]]
|
|
The pname:srcOffset member of each element of pname:pRegions must: be
|
|
less than the size of pname:srcBuffer
|
|
* [[VUID-vkCmdCopyBuffer-dstOffset-00114]]
|
|
The pname:dstOffset member of each element of pname:pRegions must: be
|
|
less than the size of pname:dstBuffer
|
|
* [[VUID-vkCmdCopyBuffer-size-00115]]
|
|
The pname:size member of each element of pname:pRegions must: be less
|
|
than or equal to the size of pname:srcBuffer minus pname:srcOffset
|
|
* [[VUID-vkCmdCopyBuffer-size-00116]]
|
|
The pname:size member of each element of pname:pRegions must: be less
|
|
than or equal to the size of pname:dstBuffer minus pname:dstOffset
|
|
* [[VUID-vkCmdCopyBuffer-pRegions-00117]]
|
|
The union of the source regions, and the union of the destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
* [[VUID-vkCmdCopyBuffer-srcBuffer-00118]]
|
|
pname:srcBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
|
|
* [[VUID-vkCmdCopyBuffer-srcBuffer-00119]]
|
|
If pname:srcBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdCopyBuffer-dstBuffer-00120]]
|
|
pname:dstBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
|
|
* [[VUID-vkCmdCopyBuffer-dstBuffer-00121]]
|
|
If pname:dstBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
****
|
|
|
|
include::../validity/protos/vkCmdCopyBuffer.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBufferCopy',desc='Structure specifying a buffer copy operation',type='structs']
|
|
--
|
|
|
|
The sname:VkBufferCopy structure is defined as:
|
|
|
|
include::../api/structs/VkBufferCopy.txt[]
|
|
|
|
* pname:srcOffset is the starting offset in bytes from the start of
|
|
pname:srcBuffer.
|
|
* pname:dstOffset is the starting offset in bytes from the start of
|
|
pname:dstBuffer.
|
|
* pname:size is the number of bytes to copy.
|
|
|
|
include::../validity/structs/VkBufferCopy.txt[]
|
|
--
|
|
|
|
|
|
[[copies-images]]
|
|
== Copying Data Between Images
|
|
|
|
fname:vkCmdCopyImage performs image copies in a similar manner to a host
|
|
memcpy.
|
|
It does not perform general-purpose conversions such as scaling, resizing,
|
|
blending, color-space conversion, or format conversions.
|
|
Rather, it simply copies raw image data.
|
|
fname:vkCmdCopyImage can: copy between images with different formats,
|
|
provided the formats are compatible as defined below.
|
|
|
|
[open,refpage='vkCmdCopyImage',desc='Copy data between images',type='protos']
|
|
--
|
|
|
|
To copy data between image objects, call:
|
|
|
|
include::../api/protos/vkCmdCopyImage.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcImage is the source image.
|
|
* pname:srcImageLayout is the current layout of the source image
|
|
subresource.
|
|
* pname:dstImage is the destination image.
|
|
* pname:dstImageLayout is the current layout of the destination image
|
|
subresource.
|
|
* pname:regionCount is the number of regions to copy.
|
|
* pname:pRegions is a pointer to an array of slink:VkImageCopy structures
|
|
specifying the regions to copy.
|
|
|
|
Each region in pname:pRegions is copied from the source image to the same
|
|
region of the destination image.
|
|
pname:srcImage and pname:dstImage can: be the same image or alias the same
|
|
memory.
|
|
|
|
[[copies-images-format-compatibility]]
|
|
The formats of pname:srcImage and pname:dstImage must: be compatible.
|
|
Formats are considered compatible if their element size is the same between
|
|
both formats.
|
|
For example, ename:VK_FORMAT_R8G8B8A8_UNORM is compatible with
|
|
ename:VK_FORMAT_R32_UINT because both texels are 4 bytes in size.
|
|
Depth/stencil formats must: match exactly.
|
|
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
If the format of pname:srcImage or pname:dstImage is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,_multi-planar_ image
|
|
format>>, regions of each plane to be copied must: be specified separately
|
|
using the pname:srcSubresource and pname:dstSubresource members of the
|
|
slink:VkImageCopy structure.
|
|
In this case, the pname:aspectMask of the pname:srcSubresource or
|
|
pname:dstSubresource that refers to the multi-planar image must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR.
|
|
For the purposes of fname:vkCmdCopyImage, each plane of a multi-planar image
|
|
is treated as having the format listed in
|
|
<<features-formats-compatible-planes>> for the plane identified by the
|
|
pname:aspectMask of the corresponding subresource.
|
|
This applies both to elink:VkFormat and to coordinates used in the copy,
|
|
which correspond to texels in the _plane_ rather than how these texels map
|
|
to coordinates in the image as a whole.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
For example, the ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR plane of a
|
|
ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM_KHR image is compatible with an
|
|
image of format ename:VK_FORMAT_R8G8_UNORM and (less usefully) with the
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR plane of an image of format
|
|
ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16_KHR, as each
|
|
texel is 2 bytes in size.
|
|
====
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
fname:vkCmdCopyImage allows copying between size-compatible compressed and
|
|
uncompressed internal formats.
|
|
Formats are size-compatible if the element size of the uncompressed format
|
|
is equal to the element size (compressed texel block size) of the compressed
|
|
format.
|
|
Such a copy does not perform on-the-fly compression or decompression.
|
|
When copying from an uncompressed format to a compressed format, each texel
|
|
of uncompressed data of the source image is copied as a raw value to the
|
|
corresponding compressed texel block of the destination image.
|
|
When copying from a compressed format to an uncompressed format, each
|
|
compressed texel block of the source image is copied as a raw value to the
|
|
corresponding texel of uncompressed data in the destination image.
|
|
Thus, for example, it is legal to copy between a 128-bit uncompressed format
|
|
and a compressed format which has a 128-bit sized compressed texel block
|
|
representing 4{times}4 texels (using 8 bits per texel), or between a 64-bit
|
|
uncompressed format and a compressed format which has a 64-bit sized
|
|
compressed texel block representing 4{times}4 texels (using 4 bits per
|
|
texel).
|
|
|
|
When copying between compressed and uncompressed formats the pname:extent
|
|
members represent the texel dimensions of the source image and not the
|
|
destination.
|
|
When copying from a compressed image to an uncompressed image the image
|
|
texel dimensions written to the uncompressed image will be source extent
|
|
divided by the compressed texel block dimensions.
|
|
When copying from an uncompressed image to a compressed image the image
|
|
texel dimensions written to the compressed image will be the source extent
|
|
multiplied by the compressed texel block dimensions.
|
|
In both cases the number of bytes read and the number of bytes written will
|
|
be identical.
|
|
|
|
Copying to or from block-compressed images is typically done in multiples of
|
|
the compressed texel block size.
|
|
For this reason the pname:extent must: be a multiple of the compressed texel
|
|
block dimension.
|
|
There is one exception to this rule which is required: to handle compressed
|
|
images created with dimensions that are not a multiple of the compressed
|
|
texel block dimensions: if the pname:srcImage is compressed, then:
|
|
|
|
* If pname:extent.width is not a multiple of the compressed texel block
|
|
width, then [eq]#(pname:extent.width {plus} pname:srcOffset.x)# must:
|
|
equal the image subresource width.
|
|
* If pname:extent.height is not a multiple of the compressed texel block
|
|
height, then [eq]#(pname:extent.height {plus} pname:srcOffset.y)# must:
|
|
equal the image subresource height.
|
|
* If pname:extent.depth is not a multiple of the compressed texel block
|
|
depth, then [eq]#(pname:extent.depth {plus} pname:srcOffset.z)# must:
|
|
equal the image subresource depth.
|
|
|
|
Similarly, if the pname:dstImage is compressed, then:
|
|
|
|
* If pname:extent.width is not a multiple of the compressed texel block
|
|
width, then [eq]#(pname:extent.width {plus} pname:dstOffset.x)# must:
|
|
equal the image subresource width.
|
|
* If pname:extent.height is not a multiple of the compressed texel block
|
|
height, then [eq]#(pname:extent.height {plus} pname:dstOffset.y)# must:
|
|
equal the image subresource height.
|
|
* If pname:extent.depth is not a multiple of the compressed texel block
|
|
depth, then [eq]#(pname:extent.depth {plus} pname:dstOffset.z)# must:
|
|
equal the image subresource depth.
|
|
|
|
This allows the last compressed texel block of the image in each
|
|
non-multiple dimension to be included as a source or destination of the
|
|
copy.
|
|
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
"`etext:_422`" image formats that are not
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,_multi-planar_>> are
|
|
treated as having a 2{times}1 compressed texel block for the purposes of
|
|
these rules.
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
fname:vkCmdCopyImage can: be used to copy image data between multisample
|
|
images, but both images must: have the same number of samples.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdCopyImage-pRegions-00122]]
|
|
The source region specified by each element of pname:pRegions must: be a
|
|
region that is contained within pname:srcImage
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
if the pname:srcImage's elink:VkFormat is not a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>, and must: be a region that is contained within the plane being
|
|
copied if the pname:srcImage's elink:VkFormat is a multi-planar format
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-pRegions-00123]]
|
|
The destination region specified by each element of pname:pRegions must:
|
|
be a region that is contained within pname:dstImage
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
if the pname:dstImage's elink:VkFormat is not a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>, and must: be a region that is contained within the plane being
|
|
copied to if the pname:dstImage's elink:VkFormat is a multi-planar
|
|
format
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-pRegions-00124]]
|
|
The union of all source regions, and the union of all destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-00125]]
|
|
pname:srcImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-00126]]
|
|
pname:srcImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
|
|
ifndef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-00127]]
|
|
If pname:srcImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-01546]]
|
|
If pname:srcImage is non-sparse then the image or _disjoint_ plane to be
|
|
copied must: be bound completely and contiguously to a single
|
|
sname:VkDeviceMemory object
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-srcImageLayout-00128]]
|
|
pname:srcImageLayout must: specify the layout of the image subresources
|
|
of pname:srcImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyImage-srcImageLayout-00129]]
|
|
pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
|
|
or ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyImage-srcImageLayout-00129]]
|
|
pname:srcImageLayout must: be
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
|
|
ename:VK_IMAGE_LAYOUT_GENERAL, or
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImage-dstImage-00130]]
|
|
pname:dstImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImage-dstImage-00131]]
|
|
pname:dstImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
ifndef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-dstImage-00132]]
|
|
If pname:dstImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-dstImage-01547]]
|
|
If pname:dstImage is non-sparse then the image or _disjoint_ plane that
|
|
is the destination of the copy must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-dstImageLayout-00133]]
|
|
pname:dstImageLayout must: specify the layout of the image subresources
|
|
of pname:dstImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyImage-dstImageLayout-00134]]
|
|
pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
|
|
or ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyImage-dstImageLayout-01395]]
|
|
pname:dstImageLayout must: be
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
|
|
ename:VK_IMAGE_LAYOUT_GENERAL, or
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifndef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-00135]]
|
|
The elink:VkFormat of each of pname:srcImage and pname:dstImage must: be
|
|
compatible, as defined <<copies-images-format-compatibility, below>>
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-01548]]
|
|
If the elink:VkFormat of each of pname:srcImage and pname:dstImage is
|
|
not a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,_multi-planar
|
|
format_>>, the elink:VkFormat of each of pname:srcImage and
|
|
pname:dstImage must: be compatible, as defined
|
|
<<copies-images-format-compatibility, below>>
|
|
* [[VUID-vkCmdCopyImage-None-01549]]
|
|
In a copy to or from a plane of a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
image>>, the elink:VkFormat of the image and plane must: be compatible
|
|
according to <<features-formats-compatible-planes,the description of
|
|
compatible planes>> for the plane being copied
|
|
* [[VUID-vkCmdCopyImage-aspectMask-01550]]
|
|
When a copy is performed to or from an image with a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>, the pname:aspectMask of the pname:srcSubresource and/or
|
|
pname:dstSubresource that refers to the multi-planar image must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR (with
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR valid only for a elink:VkFormat
|
|
with three planes)
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-00136]]
|
|
The sample count of pname:srcImage and pname:dstImage must: match
|
|
* The pname:srcSubresource.mipLevel member of each element of
|
|
pname:pRegions must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when pname:srcImage was created
|
|
* The pname:dstSubresource.mipLevel member of each element of
|
|
pname:pRegions must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when pname:dstImage was created
|
|
* The [eq]#pname:srcSubresource.baseArrayLayer {plus}
|
|
pname:srcSubresource.layerCount# of each element of pname:pRegions must:
|
|
be less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when pname:srcImage was created
|
|
* The [eq]#pname:dstSubresource.baseArrayLayer {plus}
|
|
pname:dstSubresource.layerCount# of each element of pname:pRegions must:
|
|
be less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when pname:dstImage was created
|
|
****
|
|
|
|
include::../validity/protos/vkCmdCopyImage.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageCopy',desc='Structure specifying an image copy operation',type='structs']
|
|
--
|
|
|
|
The sname:VkImageCopy structure is defined as:
|
|
|
|
include::../api/structs/VkImageCopy.txt[]
|
|
|
|
* pname:srcSubresource and pname:dstSubresource are
|
|
slink:VkImageSubresourceLayers structures specifying the image
|
|
subresources of the images used for the source and destination image
|
|
data, respectively.
|
|
* pname:srcOffset and pname:dstOffset select the initial x, y, and z
|
|
offsets in texels of the sub-regions of the source and destination image
|
|
data.
|
|
* pname:extent is the size in texels of the source image to copy in
|
|
pname:width, pname:height and pname:depth.
|
|
|
|
ifdef::VK_KHR_maintenance1[]
|
|
For ename:VK_IMAGE_TYPE_3D images, copies are performed slice by slice
|
|
starting with the pname:z member of the pname:srcOffset or pname:dstOffset,
|
|
and copying pname:depth slices.
|
|
For images with multiple layers, copies are performed layer by layer
|
|
starting with the pname:baseArrayLayer member of the pname:srcSubresource or
|
|
pname:dstSubresource and copying pname:layerCount layers.
|
|
Image data can: be copied between images with different image types.
|
|
If one image is ename:VK_IMAGE_TYPE_3D and the other image is
|
|
ename:VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or
|
|
from a different layer.
|
|
endif::VK_KHR_maintenance1[]
|
|
ifndef::VK_KHR_maintenance1[]
|
|
Copies are done layer by layer starting with pname:baseArrayLayer member of
|
|
pname:srcSubresource for the source and pname:dstSubresource for the
|
|
destination.
|
|
pname:layerCount layers are copied to the destination image.
|
|
endif::VK_KHR_maintenance1[]
|
|
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
Copies involving a <<features-formats-requiring-sampler-ycbcr-conversion,
|
|
multi-planar image format>> specify the region to be copied in terms of the
|
|
_plane_ to be copied, not the coordinates of the multi-planar image.
|
|
This means that copies accessing the R/B planes of "`etext:_422`" format
|
|
images must: fit the copied region within half the pname:width of the parent
|
|
image, and that copies accessing the R/B planes of "`etext:_420`" format
|
|
images must: fit the copied region within half the pname:width and
|
|
pname:height of the parent image.
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
.Valid Usage
|
|
****
|
|
ifndef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageCopy-aspectMask-00137]]
|
|
The pname:aspectMask member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageCopy-srcImage-01551]]
|
|
If neither the calling command's pname:srcImage nor the calling
|
|
command's pname:dstImage has a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion, multi-planar
|
|
image format>> then the pname:aspectMask member of pname:srcSubresource
|
|
and pname:dstSubresource must: match
|
|
* [[VUID-VkImageCopy-srcImage-01552]]
|
|
If the calling command's pname:srcImage has a elink:VkFormat with
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,two planes>> then
|
|
the pname:srcSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR or
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR
|
|
* [[VUID-VkImageCopy-srcImage-01553]]
|
|
If the calling command's pname:srcImage has a elink:VkFormat with
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,three planes>>
|
|
then the pname:srcSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR
|
|
* [[VUID-VkImageCopy-dstImage-01554]]
|
|
If the calling command's pname:dstImage has a elink:VkFormat with
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,two planes>> then
|
|
the pname:dstSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR or
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR
|
|
* [[VUID-VkImageCopy-dstImage-01555]]
|
|
If the calling command's pname:dstImage has a elink:VkFormat with
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,three planes>>
|
|
then the pname:dstSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR
|
|
* [[VUID-VkImageCopy-srcImage-01556]]
|
|
If the calling command's pname:srcImage has a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image
|
|
format>> and the pname:dstImage does not have a multi-planar image
|
|
format, the pname:dstSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_COLOR_BIT
|
|
* [[VUID-VkImageCopy-dstImage-01557]]
|
|
If the calling command's pname:dstImage has a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image
|
|
format>> and the pname:srcImage does not have a multi-planar image
|
|
format, the pname:srcSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_COLOR_BIT
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
ifndef::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCopy-layerCount-00138]]
|
|
The pname:layerCount member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
* [[VUID-VkImageCopy-srcImage-00139]]
|
|
If either of the calling command's pname:srcImage or pname:dstImage
|
|
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
|
|
pname:baseArrayLayer and pname:layerCount members of both
|
|
pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
|
|
respectively
|
|
endif::VK_KHR_maintenance1[]
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCopy-extent-00140]]
|
|
The number of slices of the pname:extent (for 3D) or layers of the
|
|
pname:srcSubresource (for non-3D) must: match the number of slices of
|
|
the pname:extent (for 3D) or layers of the pname:dstSubresource (for
|
|
non-3D)
|
|
* [[VUID-VkImageCopy-srcImage-00141]]
|
|
If either of the calling command's pname:srcImage or pname:dstImage
|
|
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
|
|
pname:baseArrayLayer and pname:layerCount members of the corresponding
|
|
subresource must: be `0` and `1`, respectively
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCopy-aspectMask-00142]]
|
|
The pname:aspectMask member of pname:srcSubresource must: specify
|
|
aspects present in the calling command's pname:srcImage
|
|
* [[VUID-VkImageCopy-aspectMask-00143]]
|
|
The pname:aspectMask member of pname:dstSubresource must: specify
|
|
aspects present in the calling command's pname:dstImage
|
|
* [[VUID-VkImageCopy-srcOffset-00144]]
|
|
pname:srcOffset.x and [eq]#(pname:extent.width {plus}
|
|
pname:srcOffset.x)# must: both be greater than or equal to `0` and less
|
|
than or equal to the source image subresource width
|
|
* [[VUID-VkImageCopy-srcOffset-00145]]
|
|
pname:srcOffset.y and [eq]#(pname:extent.height {plus}
|
|
pname:srcOffset.y)# must: both be greater than or equal to `0` and less
|
|
than or equal to the source image subresource height
|
|
* [[VUID-VkImageCopy-srcImage-00146]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.y must: be `0` and
|
|
pname:extent.height must: be `1`.
|
|
* [[VUID-VkImageCopy-srcOffset-00147]]
|
|
pname:srcOffset.z and [eq]#(pname:extent.depth {plus}
|
|
pname:srcOffset.z)# must: both be greater than or equal to `0` and less
|
|
than or equal to the source image subresource depth
|
|
* [[VUID-VkImageCopy-srcImage-00148]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z
|
|
must: be `0` and pname:extent.depth must: be `1`.
|
|
* [[VUID-VkImageCopy-dstOffset-00150]]
|
|
pname:dstOffset.x and [eq]#(pname:extent.width {plus}
|
|
pname:dstOffset.x)# must: both be greater than or equal to `0` and less
|
|
than or equal to the destination image subresource width
|
|
* [[VUID-VkImageCopy-dstOffset-00151]]
|
|
pname:dstOffset.y and [eq]#(pname:extent.height {plus}
|
|
pname:dstOffset.y)# must: both be greater than or equal to `0` and less
|
|
than or equal to the destination image subresource height
|
|
* [[VUID-VkImageCopy-dstImage-00152]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.y must: be `0` and
|
|
pname:extent.height must: be `1`.
|
|
* [[VUID-VkImageCopy-dstOffset-00153]]
|
|
pname:dstOffset.z and [eq]#(pname:extent.depth {plus}
|
|
pname:dstOffset.z)# must: both be greater than or equal to `0` and less
|
|
than or equal to the destination image subresource depth
|
|
* [[VUID-VkImageCopy-dstImage-00154]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z
|
|
must: be `0` and pname:extent.depth must: be `1`.
|
|
* [[VUID-VkImageCopy-srcOffset-00157]]
|
|
If the calling command's pname:srcImage is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
all members of pname:srcOffset must: be a multiple of the corresponding
|
|
dimensions of the compressed texel block
|
|
* [[VUID-VkImageCopy-extent-00158]]
|
|
If the calling command's pname:srcImage is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:extent.width must: be a multiple of the compressed texel block
|
|
width or [eq]#(pname:extent.width {plus} pname:srcOffset.x)# must: equal
|
|
the source image subresource width
|
|
* [[VUID-VkImageCopy-extent-00159]]
|
|
If the calling command's pname:srcImage is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:extent.height must: be a multiple of the compressed texel block
|
|
height or [eq]#(pname:extent.height {plus} pname:srcOffset.y)# must:
|
|
equal the source image subresource height
|
|
* [[VUID-VkImageCopy-extent-00160]]
|
|
If the calling command's pname:srcImage is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:extent.depth must: be a multiple of the compressed texel block
|
|
depth or [eq]#(pname:extent.depth {plus} pname:srcOffset.z)# must: equal
|
|
the source image subresource depth
|
|
* [[VUID-VkImageCopy-dstOffset-00162]]
|
|
If the calling command's pname:dstImage is a compressed format image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
all members of pname:dstOffset must: be a multiple of the corresponding
|
|
dimensions of the compressed texel block
|
|
* [[VUID-VkImageCopy-extent-00163]]
|
|
If the calling command's pname:dstImage is a compressed format image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:extent.width must: be a multiple of the compressed texel block
|
|
width or [eq]#(pname:extent.width {plus} pname:dstOffset.x)# must: equal
|
|
the destination image subresource width
|
|
* [[VUID-VkImageCopy-extent-00164]]
|
|
If the calling command's pname:dstImage is a compressed format image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:extent.height must: be a multiple of the compressed texel block
|
|
height or [eq]#(pname:extent.height {plus} pname:dstOffset.y)# must:
|
|
equal the destination image subresource height
|
|
* [[VUID-VkImageCopy-extent-00165]]
|
|
If the calling command's pname:dstImage is a compressed format image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:extent.depth must: be a multiple of the compressed texel block
|
|
depth or [eq]#(pname:extent.depth {plus} pname:dstOffset.z)# must: equal
|
|
the destination image subresource depth
|
|
* [[VUID-VkImageCopy-srcOffset-00166]]
|
|
pname:srcOffset, pname:dstOffset, and pname:extent must: respect the
|
|
image transfer granularity requirements of the queue family that it will
|
|
be submitted against, as described in
|
|
<<devsandqueues-physical-device-enumeration,Physical Device
|
|
Enumeration>>
|
|
****
|
|
|
|
include::../validity/structs/VkImageCopy.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageSubresourceLayers',desc='Structure specifying a image subresource layers',type='structs']
|
|
--
|
|
|
|
The sname:VkImageSubresourceLayers structure is defined as:
|
|
|
|
include::../api/structs/VkImageSubresourceLayers.txt[]
|
|
|
|
* pname:aspectMask is a combination of elink:VkImageAspectFlagBits,
|
|
selecting the color, depth and/or stencil aspects to be copied.
|
|
* pname:mipLevel is the mipmap level to copy from.
|
|
* pname:baseArrayLayer and pname:layerCount are the starting layer and
|
|
number of layers to copy.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageSubresourceLayers-aspectMask-00167]]
|
|
If pname:aspectMask contains ename:VK_IMAGE_ASPECT_COLOR_BIT, it must:
|
|
not contain either of ename:VK_IMAGE_ASPECT_DEPTH_BIT or
|
|
ename:VK_IMAGE_ASPECT_STENCIL_BIT
|
|
* [[VUID-VkImageSubresourceLayers-aspectMask-00168]]
|
|
pname:aspectMask must: not contain ename:VK_IMAGE_ASPECT_METADATA_BIT
|
|
* pname:layerCount must: be greater than 0
|
|
****
|
|
|
|
include::../validity/structs/VkImageSubresourceLayers.txt[]
|
|
--
|
|
|
|
|
|
[[copies-buffers-images]]
|
|
== Copying Data Between Buffers and Images
|
|
|
|
[open,refpage='vkCmdCopyBufferToImage',desc='Copy data from a buffer into an image',type='protos']
|
|
--
|
|
|
|
To copy data from a buffer object to an image object, call:
|
|
|
|
include::../api/protos/vkCmdCopyBufferToImage.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcBuffer is the source buffer.
|
|
* pname:dstImage is the destination image.
|
|
* pname:dstImageLayout is the layout of the destination image subresources
|
|
for the copy.
|
|
* pname:regionCount is the number of regions to copy.
|
|
* pname:pRegions is a pointer to an array of slink:VkBufferImageCopy
|
|
structures specifying the regions to copy.
|
|
|
|
Each region in pname:pRegions is copied from the specified region of the
|
|
source buffer to the specified region of the destination image.
|
|
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
If the format of pname:dstImage is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image
|
|
format>>), regions of each plane to be a target of a copy must: be specified
|
|
separately using the pname:pRegions member of the slink:VkBufferImageCopy
|
|
structure.
|
|
In this case, the pname:aspectMask of pname:imageSubresource must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR.
|
|
For the purposes of fname:vkCmdCopyBufferToImage, each plane of a
|
|
multi-planar image is treated as having the format listed in
|
|
<<features-formats-compatible-planes>> for the plane identified by the
|
|
pname:aspectMask of the corresponding subresource.
|
|
This applies both to elink:VkFormat and to coordinates used in the copy,
|
|
which correspond to texels in the _plane_ rather than how these texels map
|
|
to coordinates in the image as a whole.
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdCopyBufferToImage-pRegions-00171]]
|
|
The buffer region specified by each element of pname:pRegions must: be a
|
|
region that is contained within pname:srcBuffer
|
|
* [[VUID-vkCmdCopyBufferToImage-pRegions-00172]]
|
|
The image region specified by each element of pname:pRegions must: be a
|
|
region that is contained within pname:dstImage
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
if the pname:dstImage's elink:VkFormat is not a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>, and must: be a region that is contained within the plane being
|
|
copied to if the pname:dstImage's elink:VkFormat is a multi-planar
|
|
format
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyBufferToImage-pRegions-00173]]
|
|
The union of all source regions, and the union of all destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
* [[VUID-vkCmdCopyBufferToImage-srcBuffer-00174]]
|
|
pname:srcBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImage-00175]]
|
|
pname:dstImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyBufferToImage-srcBuffer-00176]]
|
|
If pname:srcBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImage-00177]]
|
|
pname:dstImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImage-00178]]
|
|
If pname:dstImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImage-00179]]
|
|
pname:dstImage must: have a sample count equal to
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImageLayout-00180]]
|
|
pname:dstImageLayout must: specify the layout of the image subresources
|
|
of pname:dstImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImageLayout-00181]]
|
|
pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
|
|
or ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImageLayout-01396]]
|
|
pname:dstImageLayout must: be
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
|
|
ename:VK_IMAGE_LAYOUT_GENERAL, or
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
* The pname:imageSubresource.mipLevel member of each element of
|
|
pname:pRegions must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when pname:dstImage was created
|
|
* The [eq]#pname:imageSubresource.baseArrayLayer {plus}
|
|
pname:imageSubresource.layerCount# of each element of pname:pRegions
|
|
must: be less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when pname:dstImage was created
|
|
****
|
|
|
|
include::../validity/protos/vkCmdCopyBufferToImage.txt[]
|
|
--
|
|
|
|
[open,refpage='vkCmdCopyImageToBuffer',desc='Copy image data into a buffer',type='protos']
|
|
--
|
|
|
|
To copy data from an image object to a buffer object, call:
|
|
|
|
include::../api/protos/vkCmdCopyImageToBuffer.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcImage is the source image.
|
|
* pname:srcImageLayout is the layout of the source image subresources for
|
|
the copy.
|
|
* pname:dstBuffer is the destination buffer.
|
|
* pname:regionCount is the number of regions to copy.
|
|
* pname:pRegions is a pointer to an array of slink:VkBufferImageCopy
|
|
structures specifying the regions to copy.
|
|
|
|
Each region in pname:pRegions is copied from the specified region of the
|
|
source image to the specified region of the destination buffer.
|
|
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
If the elink:VkFormat of pname:srcImage is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar image
|
|
format>>, regions of each plane to be a source of a copy must: be specified
|
|
separately using the pname:pRegions member of the slink:VkBufferImageCopy
|
|
structure.
|
|
In this case, the pname:aspectMask of pname:imageSubresource must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR.
|
|
For the purposes of fname:vkCmdCopyBufferToImage, each plane of a
|
|
multi-planar image is treated as having the format listed in
|
|
<<features-formats-compatible-planes>> for the plane identified by the
|
|
pname:aspectMask of the corresponding subresource.
|
|
This applies both to elink:VkFormat and to coordinates used in the copy,
|
|
which correspond to texels in the _plane_ rather than how these texels map
|
|
to coordinates in the image as a whole.
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdCopyImageToBuffer-pRegions-00182]]
|
|
The image region specified by each element of pname:pRegions must: be a
|
|
region that is contained within pname:srcImage
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
if the pname:srcImage's elink:VkFormat is not a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>, and must: be a region that is contained within the plane being
|
|
copied if the pname:srcImage's elink:VkFormat is a multi-planar format
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-pRegions-00183]]
|
|
The buffer region specified by each element of pname:pRegions must: be a
|
|
region that is contained within pname:dstBuffer
|
|
* [[VUID-vkCmdCopyImageToBuffer-pRegions-00184]]
|
|
The union of all source regions, and the union of all destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImage-00185]]
|
|
pname:srcImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
flink:vkGetPhysicalDeviceFormatProperties
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImage-00186]]
|
|
pname:srcImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImage-00187]]
|
|
If pname:srcImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImage-00188]]
|
|
pname:srcImage must: have a sample count equal to
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-00189]]
|
|
pname:srcImageLayout must: specify the layout of the image subresources
|
|
of pname:srcImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-00190]]
|
|
pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
|
|
or ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-01397]]
|
|
pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00191]]
|
|
pname:dstBuffer must: have been created with
|
|
ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
|
|
* [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00192]]
|
|
If pname:dstBuffer is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* The pname:imageSubresource.mipLevel member of each element of
|
|
pname:pRegions must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when pname:srcImage was created
|
|
* The [eq]#pname:imageSubresource.baseArrayLayer {plus}
|
|
pname:imageSubresource.layerCount# of each element of pname:pRegions
|
|
must: be less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when pname:srcImage was created
|
|
****
|
|
|
|
include::../validity/protos/vkCmdCopyImageToBuffer.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBufferImageCopy',desc='Structure specifying a buffer image copy operation',type='structs']
|
|
--
|
|
|
|
For both flink:vkCmdCopyBufferToImage and flink:vkCmdCopyImageToBuffer, each
|
|
element of pname:pRegions is a structure defined as:
|
|
|
|
include::../api/structs/VkBufferImageCopy.txt[]
|
|
|
|
* pname:bufferOffset is the offset in bytes from the start of the buffer
|
|
object where the image data is copied from or to.
|
|
* pname:bufferRowLength and pname: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 pname:imageExtent.
|
|
* pname:imageSubresource is a slink:VkImageSubresourceLayers used to
|
|
specify the specific image subresources of the image used for the source
|
|
or destination image data.
|
|
* pname:imageOffset selects the initial x, y, z offsets in texels of the
|
|
sub-region of the source or destination image data.
|
|
* pname:imageExtent is the size in texels of the image to copy in
|
|
pname:width, pname:height and pname:depth.
|
|
|
|
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 ename:VK_FORMAT_S8_UINT value per texel.
|
|
* data copied to or from the depth aspect of a ename:VK_FORMAT_D16_UNORM
|
|
or ename:VK_FORMAT_D16_UNORM_S8_UINT format is tightly packed with one
|
|
ename:VK_FORMAT_D16_UNORM value per texel.
|
|
* data copied to or from the depth aspect of a ename:VK_FORMAT_D32_SFLOAT
|
|
or ename:VK_FORMAT_D32_SFLOAT_S8_UINT format is tightly packed with one
|
|
ename:VK_FORMAT_D32_SFLOAT value per texel.
|
|
* data copied to or from the depth aspect of a
|
|
ename:VK_FORMAT_X8_D24_UNORM_PACK32 or ename: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]
|
|
.Note
|
|
====
|
|
To copy both the depth and stencil aspects of a depth/stencil format, two
|
|
entries in pname:pRegions can: be used, where one specifies the depth aspect
|
|
in pname: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 [eq]#[0,1]# or undefined results occur.
|
|
|
|
Copies are done layer by layer starting with image layer
|
|
pname:baseArrayLayer member of pname:imageSubresource.
|
|
pname:layerCount layers are copied from the source image or to the
|
|
destination image.
|
|
|
|
.Valid Usage
|
|
****
|
|
ifndef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-bufferOffset-00193]]
|
|
If the the calling command's sname:VkImage parameter's format is not a
|
|
depth/stencil format, then pname:bufferOffset must: be a multiple of the
|
|
format's element size
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-bufferOffset-01558]]
|
|
If the calling command's sname:VkImage parameter's format is not a
|
|
depth/stencil format or a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>,cthen pname:bufferOffset must: be a multiple of the format's
|
|
element size
|
|
* [[VUID-VkBufferImageCopy-bufferOffset-01559]]
|
|
If the calling command's sname:VkImage parameter's format is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>, then pname:bufferOffset must: be a multiple of the element
|
|
size of the compatible format for the format and the pname:aspectMask of
|
|
the pname:imageSubresource as defined in
|
|
<<features-formats-compatible-planes>>
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-bufferOffset-00194]]
|
|
pname:bufferOffset must: be a multiple of `4`
|
|
* [[VUID-VkBufferImageCopy-bufferRowLength-00195]]
|
|
pname:bufferRowLength must: be `0`, or greater than or equal to the
|
|
pname:width member of pname:imageExtent
|
|
* [[VUID-VkBufferImageCopy-bufferImageHeight-00196]]
|
|
pname:bufferImageHeight must: be `0`, or greater than or equal to the
|
|
pname:height member of pname:imageExtent
|
|
* [[VUID-VkBufferImageCopy-imageOffset-00197]]
|
|
pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus}
|
|
pname:imageOffset.x)# must: both be greater than or equal to `0` and
|
|
less than or equal to the image subresource width
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
where this refers to the width of the _plane_ of the image involved in
|
|
the copy in the case of a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-imageOffset-00198]]
|
|
pname:imageOffset.y and [eq]#(imageExtent.height {plus}
|
|
pname:imageOffset.y)# must: both be greater than or equal to `0` and
|
|
less than or equal to the image subresource height
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
where this refers to the height of the _plane_ of the image involved in
|
|
the copy in the case of a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-srcImage-00199]]
|
|
If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer)
|
|
or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:imageOffset.y must: be `0` and
|
|
pname:imageExtent.height must: be `1`.
|
|
* [[VUID-VkBufferImageCopy-imageOffset-00200]]
|
|
pname:imageOffset.z and [eq]#(imageExtent.depth {plus}
|
|
pname:imageOffset.z)# must: both be greater than or equal to `0` and
|
|
less than or equal to the image subresource depth
|
|
* [[VUID-VkBufferImageCopy-srcImage-00201]]
|
|
If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer)
|
|
or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
|
|
pname:imageOffset.z must: be `0` and pname:imageExtent.depth must: be
|
|
`1`
|
|
* [[VUID-VkBufferImageCopy-bufferRowLength-00203]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:bufferRowLength must: be a multiple of the compressed texel block
|
|
width
|
|
* [[VUID-VkBufferImageCopy-bufferImageHeight-00204]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:bufferImageHeight must: be a multiple of the compressed texel
|
|
block height
|
|
* [[VUID-VkBufferImageCopy-imageOffset-00205]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
all members of pname:imageOffset must: be a multiple of the
|
|
corresponding dimensions of the compressed texel block
|
|
* [[VUID-VkBufferImageCopy-bufferOffset-00206]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:bufferOffset must: be a multiple of the compressed texel block
|
|
size in bytes
|
|
* [[VUID-VkBufferImageCopy-imageExtent-00207]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:imageExtent.width must: be a multiple of the compressed texel
|
|
block width or [eq]#(pname:imageExtent.width {plus}
|
|
pname:imageOffset.x)# must: equal the image subresource width
|
|
* [[VUID-VkBufferImageCopy-imageExtent-00208]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:imageExtent.height must: be a multiple of the compressed texel
|
|
block height or [eq]#(pname:imageExtent.height {plus}
|
|
pname:imageOffset.y)# must: equal the image subresource height
|
|
* [[VUID-VkBufferImageCopy-imageExtent-00209]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:imageExtent.depth must: be a multiple of the compressed texel
|
|
block depth or [eq]#(pname:imageExtent.depth {plus}
|
|
pname:imageOffset.z)# must: equal the image subresource depth
|
|
* [[VUID-VkBufferImageCopy-bufferOffset-00210]]
|
|
pname:bufferOffset, pname:bufferRowLength, pname:bufferImageHeight and
|
|
all members of pname:imageOffset and pname:imageExtent must: respect the
|
|
image transfer granularity requirements of the queue family that it will
|
|
be submitted against, as described in
|
|
<<devsandqueues-physical-device-enumeration,Physical Device
|
|
Enumeration>>
|
|
* [[VUID-VkBufferImageCopy-aspectMask-00211]]
|
|
The pname:aspectMask member of pname:imageSubresource must: specify
|
|
aspects present in the calling command's sname:VkImage parameter
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-aspectMask-01560]]
|
|
If the calling command's sname:VkImage parameter's format is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>>, then the pname:aspectMask member of pname:imageSubresource
|
|
must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR (with
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR valid only for image formats with
|
|
three planes)
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-aspectMask-00212]]
|
|
The pname:aspectMask member of pname:imageSubresource must: only have a
|
|
single bit set
|
|
* [[VUID-VkBufferImageCopy-baseArrayLayer-00213]]
|
|
If the calling command's sname:VkImage parameter is of elink:VkImageType
|
|
ename:VK_IMAGE_TYPE_3D, the pname:baseArrayLayer and pname:layerCount
|
|
members of pname:imageSubresource must: be `0` and `1`, respectively
|
|
* [[VUID-VkBufferImageCopy-None-00214]]
|
|
When copying to the depth aspect of an image subresource, the data in
|
|
the source buffer must: be in the range [eq]#[0,1]#
|
|
****
|
|
|
|
include::../validity/structs/VkBufferImageCopy.txt[]
|
|
--
|
|
|
|
Pseudocode for image/buffer addressing is:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
rowLength = region->bufferRowLength;
|
|
if (rowLength == 0)
|
|
rowLength = region->imageExtent.width;
|
|
|
|
imageHeight = region->bufferImageHeight;
|
|
if (imageHeight == 0)
|
|
imageHeight = region->imageExtent.height;
|
|
|
|
elementSize = <element size of the format of the src/dstImage>;
|
|
|
|
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * elementSize;
|
|
|
|
where x,y,z range from (0,0,0) to region->imageExtent.{width,height,depth}.
|
|
---------------------------------------------------
|
|
|
|
Note that pname:imageOffset does not affect addressing calculations for
|
|
buffer memory.
|
|
Instead, pname:bufferOffset can: be used to select the starting address in
|
|
buffer memory.
|
|
|
|
For block-compression formats, all parameters are still specified in texels
|
|
rather than compressed texel blocks, but the addressing math operates on
|
|
whole compressed texel blocks.
|
|
Pseudocode for compressed copy addressing is:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
rowLength = region->bufferRowLength;
|
|
if (rowLength == 0)
|
|
rowLength = region->imageExtent.width;
|
|
|
|
imageHeight = region->bufferImageHeight;
|
|
if (imageHeight == 0)
|
|
imageHeight = region->imageExtent.height;
|
|
|
|
compressedTexelBlockSizeInBytes = <compressed texel block size taken from the src/dstImage>;
|
|
rowLength /= compressedTexelBlockWidth;
|
|
imageHeight /= compressedTexelBlockHeight;
|
|
|
|
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * compressedTexelBlockSizeInBytes;
|
|
|
|
where x,y,z range from (0,0,0) to region->imageExtent.{width/compressedTexelBlockWidth,height/compressedTexelBlockHeight,depth/compressedTexelBlockDepth}.
|
|
---------------------------------------------------
|
|
|
|
Copying to or from block-compressed images is typically done in multiples of
|
|
the compressed texel block size.
|
|
For this reason the pname:imageExtent must: be a multiple of the compressed
|
|
texel block dimension.
|
|
There is one exception to this rule which is required: to handle compressed
|
|
images created with dimensions that are not a multiple of the compressed
|
|
texel block dimensions:
|
|
|
|
* If pname:imageExtent.width is not a multiple of the compressed texel
|
|
block width, then [eq]#(pname:imageExtent.width {plus}
|
|
pname:imageOffset.x)# must: equal the image subresource width.
|
|
* If pname:imageExtent.height is not a multiple of the compressed texel
|
|
block height, then [eq]#(pname:imageExtent.height {plus}
|
|
pname:imageOffset.y)# must: equal the image subresource height.
|
|
* If pname:imageExtent.depth is not a multiple of the compressed texel
|
|
block depth, then [eq]#(pname:imageExtent.depth {plus}
|
|
pname:imageOffset.z)# must: equal the image subresource depth.
|
|
|
|
This allows the last compressed texel block of the image in each
|
|
non-multiple dimension to be included as a source or destination of the
|
|
copy.
|
|
|
|
|
|
[[copies-imagescaling]]
|
|
== Image Copies with Scaling
|
|
|
|
[open,refpage='vkCmdBlitImage',desc='Copy regions of an image, potentially performing format conversion,',type='protos']
|
|
--
|
|
|
|
To copy regions of a source image into a destination image, potentially
|
|
performing format conversion, arbitrary scaling, and filtering, call:
|
|
|
|
include::../api/protos/vkCmdBlitImage.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcImage is the source image.
|
|
* pname:srcImageLayout is the layout of the source image subresources for
|
|
the blit.
|
|
* pname:dstImage is the destination image.
|
|
* pname:dstImageLayout is the layout of the destination image subresources
|
|
for the blit.
|
|
* pname:regionCount is the number of regions to blit.
|
|
* pname:pRegions is a pointer to an array of slink:VkImageBlit structures
|
|
specifying the regions to blit.
|
|
* pname:filter is a elink:VkFilter specifying the filter to apply if the
|
|
blits require scaling.
|
|
|
|
fname:vkCmdBlitImage must: not be used for multisampled source or
|
|
destination images.
|
|
Use flink:vkCmdResolveImage for this purpose.
|
|
|
|
As the sizes of the source and destination extents can: differ in any
|
|
dimension, texels in the source extent are scaled and filtered to the
|
|
destination extent.
|
|
Scaling occurs via the following operations:
|
|
|
|
* For each destination texel, the integer coordinate of that texel is
|
|
converted to an unnormalized texture coordinate, using the effective
|
|
inverse of the equations described in
|
|
<<textures-unnormalized-to-integer, unnormalized to integer
|
|
conversion>>:
|
|
:: [eq]#u~base~ = i {plus} {onehalf}#
|
|
:: [eq]#v~base~ = j {plus} {onehalf}#
|
|
:: [eq]#w~base~ = k {plus} {onehalf}#
|
|
* These base coordinates are then offset by the first destination
|
|
offset:
|
|
:: [eq]#u~offset~ = u~base~ - x~dst0~#
|
|
:: [eq]#v~offset~ = v~base~ - y~dst0~#
|
|
:: [eq]#w~offset~ = w~base~ - z~dst0~#
|
|
:: [eq]#a~offset~ = a - pname:baseArrayCount~dst~#
|
|
* The scale is determined from the source and destination regions, and
|
|
applied to the offset coordinates:
|
|
:: [eq]#scale_u = (x~src1~ - x~src0~) / (x~dst1~ - x~dst0~)#
|
|
:: [eq]#scale_v = (y~src1~ - y~src0~) / (y~dst1~ - y~dst0~)#
|
|
:: [eq]#scale_w = (z~src1~ - z~src0~) / (z~dst1~ - z~dst0~)#
|
|
:: [eq]#u~scaled~ = u~offset~ * scale~u~#
|
|
:: [eq]#v~scaled~ = v~offset~ * scale~v~#
|
|
:: [eq]#w~scaled~ = w~offset~ * scale~w~#
|
|
* Finally the source offset is added to the scaled coordinates, to
|
|
determine the final unnormalized coordinates used to sample from
|
|
pname:srcImage: +
|
|
:: [eq]#u = u~scaled~ {plus} x~src0~#
|
|
:: [eq]#v = v~scaled~ {plus} y~src0~#
|
|
:: [eq]#w = w~scaled~ {plus} z~src0~#
|
|
:: [eq]#q = pname:mipLevel#
|
|
:: [eq]#a = a~offset~ {plus} pname:baseArrayCount~src~#
|
|
|
|
These coordinates are used to sample from the source image, as described in
|
|
<<textures, Image Operations chapter>>, with the filter mode equal to that
|
|
of pname:filter, a mipmap mode of ename:VK_SAMPLER_MIPMAP_MODE_NEAREST and
|
|
an address mode of ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
|
|
Implementations must: clamp at the edge of the source image, and may:
|
|
additionally clamp to the edge of the source region.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Due to allowable rounding errors in the generation of the source texture
|
|
coordinates, it is not always possible to guarantee exactly which source
|
|
texels will be sampled for a given blit.
|
|
As rounding errors are implementation dependent, the exact results of a
|
|
blitting operation are also implementation dependent.
|
|
====
|
|
|
|
Blits are done layer by layer starting with the pname:baseArrayLayer member
|
|
of pname:srcSubresource for the source and pname:dstSubresource for the
|
|
destination.
|
|
pname:layerCount layers are blitted to the destination image.
|
|
|
|
3D textures are blitted slice by slice.
|
|
Slices in the source region bounded by pname:srcOffsets[0].pname:z and
|
|
pname:srcOffsets[1].pname:z are copied to slices in the destination region
|
|
bounded by pname:dstOffsets[0].pname:z and pname:dstOffsets[1].pname:z.
|
|
For each destination slice, a source z coordinate is linearly interpolated
|
|
between pname:srcOffsets[0].pname:z and pname:srcOffsets[1].pname:z.
|
|
If the pname:filter parameter is ename:VK_FILTER_LINEAR then the value
|
|
sampled from the source image is taken by doing linear filtering using the
|
|
interpolated z coordinate.
|
|
If pname:filter parameter is ename:VK_FILTER_NEAREST then value sampled from
|
|
the source image is taken from the single nearest slice (with undefined
|
|
rounding mode).
|
|
|
|
The following filtering and conversion rules apply:
|
|
|
|
* Integer formats can: only be converted to other integer formats with the
|
|
same signedness.
|
|
* No format conversion is supported between depth/stencil images.
|
|
The formats must: match.
|
|
* Format conversions on unorm, snorm, unscaled and packed float formats of
|
|
the copied aspect of the image are performed by first converting the
|
|
pixels to float values.
|
|
* For sRGB source formats, nonlinear RGB values are converted to linear
|
|
representation prior to filtering.
|
|
* After filtering, the float values are first clamped and then cast to the
|
|
destination image format.
|
|
In case of sRGB destination format, linear RGB values are converted to
|
|
nonlinear representation before writing the pixel to the image.
|
|
|
|
Signed and unsigned integers are converted by first clamping to the
|
|
representable range of the destination format, then casting the value.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdBlitImage-pRegions-00215]]
|
|
The source region specified by each element of pname:pRegions must: be a
|
|
region that is contained within pname:srcImage
|
|
* [[VUID-vkCmdBlitImage-pRegions-00216]]
|
|
The destination region specified by each element of pname:pRegions must:
|
|
be a region that is contained within pname:dstImage
|
|
* [[VUID-vkCmdBlitImage-pRegions-00217]]
|
|
The union of all destination regions, specified by the elements of
|
|
pname:pRegions, must: not overlap in memory with any texel that may: be
|
|
sampled during the blit operation
|
|
* [[VUID-vkCmdBlitImage-srcImage-00218]]
|
|
pname:srcImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdBlitImage-srcImage-01561]]
|
|
pname:srcImage must: not use a format listed in
|
|
<<features-formats-requiring-sampler-ycbcr-conversion>>
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdBlitImage-srcImage-00219]]
|
|
pname:srcImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
|
|
* [[VUID-vkCmdBlitImage-srcImage-00220]]
|
|
If pname:srcImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdBlitImage-srcImageLayout-00221]]
|
|
pname:srcImageLayout must: specify the layout of the image subresources
|
|
of pname:srcImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdBlitImage-srcImageLayout-00222]]
|
|
pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
|
|
or ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdBlitImage-srcImageLayout-01398]]
|
|
pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdBlitImage-dstImage-00223]]
|
|
pname:dstImage must: use a format that supports
|
|
ename:VK_FORMAT_FEATURE_BLIT_DST_BIT, which is indicated by
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
|
|
images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
|
|
optimally tiled images) - as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdBlitImage-dstImage-01562]]
|
|
pname:dstImage must: not use a format listed in
|
|
<<features-formats-requiring-sampler-ycbcr-conversion>>
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdBlitImage-dstImage-00224]]
|
|
pname:dstImage must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
|
|
* [[VUID-vkCmdBlitImage-dstImage-00225]]
|
|
If pname:dstImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdBlitImage-dstImageLayout-00226]]
|
|
pname:dstImageLayout must: specify the layout of the image subresources
|
|
of pname:dstImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdBlitImage-dstImageLayout-00227]]
|
|
pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
|
|
or ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdBlitImage-dstImageLayout-01399]]
|
|
pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdBlitImage-srcImage-00228]]
|
|
The sample count of pname:srcImage and pname:dstImage must: both be
|
|
equal to ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-vkCmdBlitImage-srcImage-00229]]
|
|
If either of pname:srcImage or pname:dstImage was created with a signed
|
|
integer elink:VkFormat, the other must: also have been created with a
|
|
signed integer elink:VkFormat
|
|
* [[VUID-vkCmdBlitImage-srcImage-00230]]
|
|
If either of pname:srcImage or pname:dstImage was created with an
|
|
unsigned integer elink:VkFormat, the other must: also have been created
|
|
with an unsigned integer elink:VkFormat
|
|
* [[VUID-vkCmdBlitImage-srcImage-00231]]
|
|
If either of pname:srcImage or pname:dstImage was created with a
|
|
depth/stencil format, the other must: have exactly the same format
|
|
* [[VUID-vkCmdBlitImage-srcImage-00232]]
|
|
If pname:srcImage was created with a depth/stencil format, pname:filter
|
|
must: be ename:VK_FILTER_NEAREST
|
|
* [[VUID-vkCmdBlitImage-srcImage-00233]]
|
|
pname:srcImage must: have been created with a pname:samples value of
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-vkCmdBlitImage-dstImage-00234]]
|
|
pname:dstImage must: have been created with a pname:samples value of
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-vkCmdBlitImage-filter-00235]]
|
|
If pname:filter is ename:VK_FILTER_LINEAR, pname:srcImage must: be of a
|
|
format which supports linear filtering, as specified by the
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for a linear
|
|
image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an
|
|
optimally tiled image) returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
ifdef::VK_IMG_filter_cubic[]
|
|
* [[VUID-vkCmdBlitImage-filter-00236]]
|
|
If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: be of
|
|
a format which supports cubic filtering, as specified by the
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (for a linear
|
|
image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an
|
|
optimally tiled image) returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
* [[VUID-vkCmdBlitImage-filter-00237]]
|
|
If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: have
|
|
a elink:VkImageType of ename:VK_IMAGE_TYPE_3D
|
|
endif::VK_IMG_filter_cubic[]
|
|
* The pname:srcSubresource.mipLevel member of each element of
|
|
pname:pRegions must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when pname:srcImage was created
|
|
* The pname:dstSubresource.mipLevel member of each element of
|
|
pname:pRegions must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when pname:dstImage was created
|
|
* The [eq]#pname:srcSubresource.baseArrayLayer {plus}
|
|
pname:srcSubresource.layerCount# of each element of pname:pRegions must:
|
|
be less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when pname:srcImage was created
|
|
* The [eq]#pname:dstSubresource.baseArrayLayer {plus}
|
|
pname:dstSubresource.layerCount# of each element of pname:pRegions must:
|
|
be less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when pname:dstImage was created
|
|
****
|
|
|
|
include::../validity/protos/vkCmdBlitImage.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageBlit',desc='Structure specifying an image blit operation',type='structs']
|
|
--
|
|
|
|
The sname:VkImageBlit structure is defined as:
|
|
|
|
include::../api/structs/VkImageBlit.txt[]
|
|
|
|
* pname:srcSubresource is the subresource to blit from.
|
|
* pname:srcOffsets is an array of two slink:VkOffset3D structures
|
|
specifying the bounds of the source region within pname:srcSubresource.
|
|
* pname:dstSubresource is the subresource to blit into.
|
|
* pname:dstOffsets is an array of two slink:VkOffset3D structures
|
|
specifying the bounds of the destination region within
|
|
pname:dstSubresource.
|
|
|
|
For each element of the pname:pRegions array, a blit operation is performed
|
|
the specified source and destination regions.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageBlit-aspectMask-00238]]
|
|
The pname:aspectMask member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
* [[VUID-VkImageBlit-layerCount-00239]]
|
|
The pname:layerCount member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
* [[VUID-VkImageBlit-srcImage-00240]]
|
|
If either of the calling command's pname:srcImage or pname:dstImage
|
|
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
|
|
pname:baseArrayLayer and pname:layerCount members of both
|
|
pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
|
|
respectively
|
|
* [[VUID-VkImageBlit-aspectMask-00241]]
|
|
The pname:aspectMask member of pname:srcSubresource must: specify
|
|
aspects present in the calling command's pname:srcImage
|
|
* [[VUID-VkImageBlit-aspectMask-00242]]
|
|
The pname:aspectMask member of pname:dstSubresource must: specify
|
|
aspects present in the calling command's pname:dstImage
|
|
* [[VUID-VkImageBlit-srcOffset-00243]]
|
|
pname:srcOffset[0].pname:x and pname:srcOffset[1].pname:x must: both be
|
|
greater than or equal to `0` and less than or equal to the source image
|
|
subresource width
|
|
* [[VUID-VkImageBlit-srcOffset-00244]]
|
|
pname:srcOffset[0].pname:y and pname:srcOffset[1].pname:y must: both be
|
|
greater than or equal to `0` and less than or equal to the source image
|
|
subresource height
|
|
* [[VUID-VkImageBlit-srcImage-00245]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:srcOffset[0].y must: be `0` and
|
|
pname:srcOffset[1].y must: be `1`.
|
|
* [[VUID-VkImageBlit-srcOffset-00246]]
|
|
pname:srcOffset[0].pname:z and pname:srcOffset[1].pname:z must: both be
|
|
greater than or equal to `0` and less than or equal to the source image
|
|
subresource depth
|
|
* [[VUID-VkImageBlit-srcImage-00247]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
|
|
pname:srcOffset[0].z must: be `0` and pname:srcOffset[1].z must: be `1`.
|
|
* [[VUID-VkImageBlit-dstOffset-00248]]
|
|
pname:dstOffset[0].pname:x and pname:dstOffset[1].pname:x must: both be
|
|
greater than or equal to `0` and less than or equal to the destination
|
|
image subresource width
|
|
* [[VUID-VkImageBlit-dstOffset-00249]]
|
|
pname:dstOffset[0].pname:y and pname:dstOffset[1].pname:y must: both be
|
|
greater than or equal to `0` and less than or equal to the destination
|
|
image subresource height
|
|
* [[VUID-VkImageBlit-dstImage-00250]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:dstOffset[0].y must: be `0` and
|
|
pname:dstOffset[1].y must: be `1`.
|
|
* [[VUID-VkImageBlit-dstOffset-00251]]
|
|
pname:dstOffset[0].pname:z and pname:dstOffset[1].pname:z must: both be
|
|
greater than or equal to `0` and less than or equal to the destination
|
|
image subresource depth
|
|
* [[VUID-VkImageBlit-dstImage-00252]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
|
|
pname:dstOffset[0].z must: be `0` and pname:dstOffset[1].z must: be `1`.
|
|
****
|
|
|
|
include::../validity/structs/VkImageBlit.txt[]
|
|
--
|
|
|
|
|
|
[[copies-resolve]]
|
|
== Resolving Multisample Images
|
|
|
|
[open,refpage='vkCmdResolveImage',desc='Resolve regions of an image',type='protos']
|
|
--
|
|
|
|
To resolve a multisample image to a non-multisample image, call:
|
|
|
|
include::../api/protos/vkCmdResolveImage.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command will be
|
|
recorded.
|
|
* pname:srcImage is the source image.
|
|
* pname:srcImageLayout is the layout of the source image subresources for
|
|
the resolve.
|
|
* pname:dstImage is the destination image.
|
|
* pname:dstImageLayout is the layout of the destination image subresources
|
|
for the resolve.
|
|
* pname:regionCount is the number of regions to resolve.
|
|
* pname:pRegions is a pointer to an array of slink:VkImageResolve
|
|
structures specifying the regions to resolve.
|
|
|
|
During the resolve the samples corresponding to each pixel location in the
|
|
source are converted to a single sample before being written to the
|
|
destination.
|
|
If the source formats are floating-point or normalized types, the sample
|
|
values for each pixel are resolved in an implementation-dependent manner.
|
|
If the source formats are integer types, a single sample's value is selected
|
|
for each pixel.
|
|
|
|
pname:srcOffset and pname:dstOffset select the initial x, y, and z offsets
|
|
in texels of the sub-regions of the source and destination image data.
|
|
pname:extent is the size in texels of the source image to resolve in
|
|
pname:width, pname:height and pname:depth.
|
|
|
|
Resolves are done layer by layer starting with pname:baseArrayLayer member
|
|
of pname:srcSubresource for the source and pname:dstSubresource for the
|
|
destination.
|
|
pname:layerCount layers are resolved to the destination image.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdResolveImage-pRegions-00253]]
|
|
The source region specified by each element of pname:pRegions must: be a
|
|
region that is contained within pname:srcImage
|
|
* [[VUID-vkCmdResolveImage-pRegions-00254]]
|
|
The destination region specified by each element of pname:pRegions must:
|
|
be a region that is contained within pname:dstImage
|
|
* [[VUID-vkCmdResolveImage-pRegions-00255]]
|
|
The union of all source regions, and the union of all destination
|
|
regions, specified by the elements of pname:pRegions, must: not overlap
|
|
in memory
|
|
* [[VUID-vkCmdResolveImage-srcImage-00256]]
|
|
If pname:srcImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdResolveImage-srcImage-00257]]
|
|
pname:srcImage must: have a sample count equal to any valid sample count
|
|
value other than ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-vkCmdResolveImage-dstImage-00258]]
|
|
If pname:dstImage is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-vkCmdResolveImage-dstImage-00259]]
|
|
pname:dstImage must: have a sample count equal to
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-vkCmdResolveImage-srcImageLayout-00260]]
|
|
pname:srcImageLayout must: specify the layout of the image subresources
|
|
of pname:srcImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdResolveImage-srcImageLayout-00261]]
|
|
pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
|
|
or ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdResolveImage-srcImageLayout-01400]]
|
|
pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdResolveImage-dstImageLayout-00262]]
|
|
pname:dstImageLayout must: specify the layout of the image subresources
|
|
of pname:dstImage specified in pname:pRegions at the time this command
|
|
is executed on a sname:VkDevice
|
|
ifndef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdResolveImage-dstImageLayout-00263]]
|
|
pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
|
|
or ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdResolveImage-dstImageLayout-01401]]
|
|
pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_GENERAL
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
* [[VUID-vkCmdResolveImage-dstImage-00264]]
|
|
If pname:dstImage was created with pname:tiling equal to
|
|
ename:VK_IMAGE_TILING_LINEAR, pname:dstImage must: have been created
|
|
with a pname:format that supports being a color attachment, as specified
|
|
by the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
* [[VUID-vkCmdResolveImage-dstImage-00265]]
|
|
If pname:dstImage was created with pname:tiling equal to
|
|
ename:VK_IMAGE_TILING_OPTIMAL, pname:dstImage must: have been created
|
|
with a pname:format that supports being a color attachment, as specified
|
|
by the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
* [[VUID-vkCmdResolveImage-srcImage-01386]]
|
|
pname:srcImage and pname:dstImage must: have been created with the same
|
|
image format
|
|
* The pname:srcSubresource.mipLevel member of each element of
|
|
pname:pRegions must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when pname:srcImage was created
|
|
* The pname:dstSubresource.mipLevel member of each element of
|
|
pname:pRegions must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when pname:dstImage was created
|
|
* The [eq]#pname:srcSubresource.baseArrayLayer {plus}
|
|
pname:srcSubresource.layerCount# of each element of pname:pRegions must:
|
|
be less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when pname:srcImage was created
|
|
* The [eq]#pname:dstSubresource.baseArrayLayer {plus}
|
|
pname:dstSubresource.layerCount# of each element of pname:pRegions must:
|
|
be less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when pname:dstImage was created
|
|
****
|
|
|
|
include::../validity/protos/vkCmdResolveImage.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageResolve',desc='Structure specifying an image resolve operation',type='structs']
|
|
--
|
|
|
|
The sname:VkImageResolve structure is defined as:
|
|
|
|
include::../api/structs/VkImageResolve.txt[]
|
|
|
|
* pname:srcSubresource and pname:dstSubresource are
|
|
slink:VkImageSubresourceLayers structures specifying the image
|
|
subresources of the images used for the source and destination image
|
|
data, respectively.
|
|
Resolve of depth/stencil images is not supported.
|
|
* pname:srcOffset and pname:dstOffset select the initial x, y, and z
|
|
offsets in texels of the sub-regions of the source and destination image
|
|
data.
|
|
* pname:extent is the size in texels of the source image to resolve in
|
|
pname:width, pname:height and pname:depth.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageResolve-aspectMask-00266]]
|
|
The pname:aspectMask member of pname:srcSubresource and
|
|
pname:dstSubresource must: only contain ename:VK_IMAGE_ASPECT_COLOR_BIT
|
|
* [[VUID-VkImageResolve-layerCount-00267]]
|
|
The pname:layerCount member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
* [[VUID-VkImageResolve-srcImage-00268]]
|
|
If either of the calling command's pname:srcImage or pname:dstImage
|
|
parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
|
|
pname:baseArrayLayer and pname:layerCount members of both
|
|
pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
|
|
respectively
|
|
* [[VUID-VkImageResolve-srcOffset-00269]]
|
|
pname:srcOffset.x and [eq]#(pname:extent.width {plus}
|
|
pname:srcOffset.x)# must: both be greater than or equal to `0` and less
|
|
than or equal to the source image subresource width
|
|
* [[VUID-VkImageResolve-srcOffset-00270]]
|
|
pname:srcOffset.y and [eq]#(pname:extent.height {plus}
|
|
pname:srcOffset.y)# must: both be greater than or equal to `0` and less
|
|
than or equal to the source image subresource height
|
|
* [[VUID-VkImageResolve-srcImage-00271]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.y must: be `0` and
|
|
pname:extent.height must: be `1`.
|
|
* [[VUID-VkImageResolve-srcOffset-00272]]
|
|
pname:srcOffset.z and [eq]#(pname:extent.depth {plus}
|
|
pname:srcOffset.z)# must: both be greater than or equal to `0` and less
|
|
than or equal to the source image subresource depth
|
|
* [[VUID-VkImageResolve-srcImage-00273]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z
|
|
must: be `0` and pname:extent.depth must: be `1`.
|
|
* [[VUID-VkImageResolve-dstOffset-00274]]
|
|
pname:dstOffset.x and [eq]#(pname:extent.width {plus}
|
|
pname:dstOffset.x)# must: both be greater than or equal to `0` and less
|
|
than or equal to the destination image subresource width
|
|
* [[VUID-VkImageResolve-dstOffset-00275]]
|
|
pname:dstOffset.y and [eq]#(pname:extent.height {plus}
|
|
pname:dstOffset.y)# must: both be greater than or equal to `0` and less
|
|
than or equal to the destination image subresource height
|
|
* [[VUID-VkImageResolve-dstImage-00276]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.y must: be `0` and
|
|
pname:extent.height must: be `1`.
|
|
* [[VUID-VkImageResolve-dstOffset-00277]]
|
|
pname:dstOffset.z and [eq]#(pname:extent.depth {plus}
|
|
pname:dstOffset.z)# must: both be greater than or equal to `0` and less
|
|
than or equal to the destination image subresource depth
|
|
* [[VUID-VkImageResolve-dstImage-00278]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z
|
|
must: be `0` and pname:extent.depth must: be `1`.
|
|
****
|
|
|
|
include::../validity/structs/VkImageResolve.txt[]
|
|
--
|
|
|