mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-18 18:31:46 +00:00
5abf83f95d
* Update release number to 107.
Public Issues:
* Fix revision date for the `<<VK_AMD_gpu_shader_half_float>>` appendix
(public issue 617).
* Make <<synchronization-pipeline-barriers-subpass-self-dependencies,
subpass self-dependencies>> less restrictive (public issue 777).
* Fix the `<<VK_EXT_full_screen_exclusive>>` dependency on
`<<VK_KHR_win32_surface>>` in `vk.xml` (public pull request 849).
* Remove single-page (`apispec.html`) refpage sub-targets from the
Makefile `allman` target and the build instructions. The target is still
present in the Makefile, but we have not been actively maintaining the
single-page document and do not promise it will work. The full
Specification and the individual API reference pages are what we support
and publish at present (public issue 949).
Internal Issues:
* De-duplicate common valid usage statements shared by multiple commands
or structures by using asciidoctor includes and dynamically assigning
part of the valid usage ID based on which command or structure they're
being applied to (internal issue 779).
* Add reference pages for constructs not part of the formal API, such as
platform calling convention macros, and script changes supporting them
This required suppressing some check_spec_links warning classes in order
to pass CI, until a more sophisticated fix can be done (internal issue
888).
* Change math notation for the elink:VkPrimitiveTopology descriptions to
use short forms `v` and `p` instead of `vertex` and `primitive`,
increasing legibility (internal issue 1611).
* Rewrite generated file includes relative to a globally specified path,
fixing some issues with refpage generation (internal issue 1630).
* Update contributor list for `<<VK_EXT_calibrated_timestamps>>`.
* Fix use of pathlin in `scripts/generator.py` so the script will work on
Windows under Python 3.5 (internal merge request 3107).
* Add missing conditionals around the
<<descriptorsets-accelerationstructure, Acceleration Structure>>
section (internal merge request 3108).
* More script synchronization with OpenXR spec repository (internal merge
request 3109).
* Mark the `<<VK_AMD_gpu_shader_half_float>>` and
`<<VK_AMD_gpu_shader_int16>>` extensions as deprecated in `vk.xml` and
the corresponding extension appendices (internal merge request 3112).
New Extensions:
* `<<VK_EXT_headless_surface>>`
1996 lines
98 KiB
Plaintext
1996 lines
98 KiB
Plaintext
// Copyright (c) 2015-2019 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
|
|
|
|
The following valid usage rules apply to all copy commands:
|
|
|
|
* Copy commands must: be recorded outside of a render pass instance.
|
|
* The set of all bytes bound to all the source regions must: not overlap
|
|
the set of all bytes bound to the destination regions.
|
|
* The set of all bytes bound to each destination region must: not overlap
|
|
the set of all bytes bound to another destination region.
|
|
* 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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* Source images must: have ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT in
|
|
their <<resources-image-format-features,format features>>.
|
|
* Destination images must: have ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT
|
|
in their <<resources-image-format-features,format features>>.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* 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.
|
|
ifndef::VK_EXT_separate_stencil_usage[]
|
|
* Source images must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in
|
|
slink:VkImageCreateInfo::pname:usage
|
|
* Destination images must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in
|
|
slink:VkImageCreateInfo::pname:usage
|
|
endif::VK_EXT_separate_stencil_usage[]
|
|
ifdef::VK_EXT_separate_stencil_usage[]
|
|
* If the stencil aspect of source image is accessed, and the source image
|
|
was not created with <<VkImageStencilUsageCreateInfoEXT,separate stencil
|
|
usage>>, the source image must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in
|
|
slink:VkImageCreateInfo::pname:usage
|
|
* If the stencil aspect of destination image is accessed, and the
|
|
destination image was not created with
|
|
<<VkImageStencilUsageCreateInfoEXT,separate stencil usage>>, the
|
|
destination image must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in
|
|
slink:VkImageCreateInfo::pname:usage
|
|
* If the stencil aspect of source image is accessed, and the source image
|
|
was created with <<VkImageStencilUsageCreateInfoEXT,separate stencil
|
|
usage>>, the source image must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in
|
|
slink:VkImageStencilUsageCreateInfoEXT::pname:stencilUsage
|
|
* If the stencil aspect of destination image is accessed, and the
|
|
destination image was created with
|
|
<<VkImageStencilUsageCreateInfoEXT,separate stencil usage>>, the
|
|
destination image must: have been created with
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in
|
|
slink:VkImageStencilUsageCreateInfoEXT::pname:stencilUsage
|
|
* If non-stencil aspects of a source image are accessed, the source image
|
|
must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set
|
|
in slink:VkImageCreateInfo::pname:usage
|
|
* If non-stencil aspects of a source image are accessed, the source image
|
|
must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set
|
|
in slink:VkImageCreateInfo::pname:usage
|
|
endif::VK_EXT_separate_stencil_usage[]
|
|
|
|
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::{generated}/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 resulting values are undefined: if the copy regions
|
|
overlap in memory.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[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
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdCopyBuffer-commandBuffer-01822]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:srcBuffer must: not be a protected buffer
|
|
* [[VUID-vkCmdCopyBuffer-commandBuffer-01823]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:dstBuffer must: not be a protected buffer
|
|
* [[VUID-vkCmdCopyBuffer-commandBuffer-01824]]
|
|
If pname:commandBuffer is a protected command buffer, then
|
|
pname:dstBuffer must: not be an unprotected buffer
|
|
endif::VK_VERSION_1_1[]
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkCmdCopyBuffer.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBufferCopy',desc='Structure specifying a buffer copy operation',type='structs']
|
|
--
|
|
|
|
The sname:VkBufferCopy structure is defined as:
|
|
|
|
include::{generated}/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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBufferCopy-size-01988]]
|
|
The pname:size must: be greater than `0`
|
|
****
|
|
|
|
include::{generated}/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::{generated}/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 compatible if they share the same class, as shown in the
|
|
<<formats-compatibility,Compatible Formats>> table.
|
|
Depth/stencil formats must: match exactly.
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
If the format of pname:srcImage or pname:dstImage is a
|
|
<<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, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
|
|
For the purposes of fname:vkCmdCopyImage, each plane of a multi-planar image
|
|
is treated as having the format listed in <<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 plane of a
|
|
ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM 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 plane of an image of format
|
|
ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16, as each texel is
|
|
2 bytes in size.
|
|
====
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
[[copies-images-format-size-compatibility]]
|
|
fname:vkCmdCopyImage allows copying between _size-compatible_ compressed and
|
|
uncompressed internal formats.
|
|
Formats are size-compatible if the texel block size of the uncompressed
|
|
format is equal to the 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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
"`etext:_422`" image formats that are not
|
|
<<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_VERSION_1_1,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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
if the pname:srcImage's elink:VkFormat is not a
|
|
<<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_VERSION_1_1,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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
if the pname:dstImage's elink:VkFormat is not a
|
|
<<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_VERSION_1_1,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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-01995]]
|
|
The <<resources-image-format-features,format features>> of
|
|
pname:srcImage must: contain ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT.
|
|
endif::VK_VERSION_1_1,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_VERSION_1_1,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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,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_VERSION_1_1,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-01917]]
|
|
pname:srcImageLayout must: be
|
|
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
|
|
ename:VK_IMAGE_LAYOUT_GENERAL, or
|
|
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImage-dstImage-01996]]
|
|
The <<resources-image-format-features,format features>> of
|
|
pname:dstImage must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT.
|
|
endif::VK_VERSION_1_1,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_VERSION_1_1,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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,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_VERSION_1_1,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_VERSION_1_1,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, above>>
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-01548]]
|
|
If the elink:VkFormat of each of pname:srcImage and pname:dstImage is
|
|
not a <<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, above>>
|
|
* [[VUID-vkCmdCopyImage-None-01549]]
|
|
In a copy to or from a plane of a
|
|
<<formats-requiring-sampler-ycbcr-conversion,multi-planar image>>, the
|
|
elink:VkFormat of the image and plane must: be compatible according to
|
|
<<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
|
|
<<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, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT (with
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT valid only for a elink:VkFormat with
|
|
three planes)
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImage-srcImage-00136]]
|
|
The sample count of pname:srcImage and pname:dstImage must: match
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdCopyImage-commandBuffer-01825]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:srcImage must: not be a protected image
|
|
* [[VUID-vkCmdCopyImage-commandBuffer-01826]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:dstImage must: not be a protected image
|
|
* [[VUID-vkCmdCopyImage-commandBuffer-01827]]
|
|
If pname:commandBuffer is a protected command buffer, then
|
|
pname:dstImage must: not be an unprotected image
|
|
endif::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdCopyImage-srcSubresource-01696]]
|
|
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
|
|
* [[VUID-vkCmdCopyImage-dstSubresource-01697]]
|
|
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
|
|
* [[VUID-vkCmdCopyImage-srcSubresource-01698]]
|
|
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
|
|
* [[VUID-vkCmdCopyImage-dstSubresource-01699]]
|
|
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
|
|
* [[VUID-vkCmdCopyImage-srcOffset-01783]]
|
|
The pname:srcOffset and pname:extent members of each element of
|
|
pname:pRegions must: respect the image transfer granularity requirements
|
|
of pname:commandBuffer's command pool's queue family, as described in
|
|
slink:VkQueueFamilyProperties
|
|
* [[VUID-vkCmdCopyImage-dstOffset-01784]]
|
|
The pname:dstOffset and pname:extent members of each element of
|
|
pname:pRegions must: respect the image transfer granularity requirements
|
|
of pname:commandBuffer's command pool's queue family, as described in
|
|
slink:VkQueueFamilyProperties
|
|
ifdef::VK_EXT_fragment_density_map[]
|
|
* [[VUID-vkCmdCopyImage-dstImage-02542]]
|
|
pname:dstImage and pname:srcImage must: not have been created with
|
|
pname:flags containing ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
|
|
endif::VK_EXT_fragment_density_map[]
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkCmdCopyImage.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageCopy',desc='Structure specifying an image copy operation',type='structs']
|
|
--
|
|
|
|
The sname:VkImageCopy structure is defined as:
|
|
|
|
include::{generated}/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 pname:x, pname:y,
|
|
and pname:z offsets in texels of the sub-regions of the source and
|
|
destination image data.
|
|
* pname:extent is the size in texels of the image to copy in pname:width,
|
|
pname:height and pname:depth.
|
|
|
|
ifdef::VK_VERSION_1_1,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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
ifndef::VK_VERSION_1_1,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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
Copies involving a <<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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
.Valid Usage
|
|
****
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageCopy-aspectMask-00137]]
|
|
The pname:aspectMask member of pname:srcSubresource and
|
|
pname:dstSubresource must: match
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,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
|
|
<<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
|
|
<<formats-requiring-sampler-ycbcr-conversion,two planes>> then the
|
|
pname:srcSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT
|
|
* [[VUID-VkImageCopy-srcImage-01553]]
|
|
If the calling command's pname:srcImage has a elink:VkFormat with
|
|
<<formats-requiring-sampler-ycbcr-conversion,three planes>> then the
|
|
pname:srcSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT
|
|
* [[VUID-VkImageCopy-dstImage-01554]]
|
|
If the calling command's pname:dstImage has a elink:VkFormat with
|
|
<<formats-requiring-sampler-ycbcr-conversion,two planes>> then the
|
|
pname:dstSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT
|
|
* [[VUID-VkImageCopy-dstImage-01555]]
|
|
If the calling command's pname:dstImage has a elink:VkFormat with
|
|
<<formats-requiring-sampler-ycbcr-conversion,three planes>> then the
|
|
pname:dstSubresource pname:aspectMask must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT
|
|
* [[VUID-VkImageCopy-srcImage-01556]]
|
|
If the calling command's pname:srcImage has a
|
|
<<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
|
|
<<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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifndef::VK_VERSION_1_1,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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
ifdef::VK_VERSION_1_1,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_VERSION_1_1,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-01785]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.z must: be `0` and
|
|
pname:extent.depth must: be `1`.
|
|
* [[VUID-VkImageCopy-dstImage-01786]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.z must: be `0` and
|
|
pname:extent.depth must: be `1`.
|
|
* [[VUID-VkImageCopy-srcImage-01787]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z must: be `0`.
|
|
* [[VUID-VkImageCopy-dstImage-01788]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z must: be `0`.
|
|
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCopy-srcImage-01789]]
|
|
If the calling command's pname:srcImage or pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_2D, then pname:extent.depth must: be `1`.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCopy-srcImage-01790]]
|
|
If both pname:srcImage and pname:dstImage are of type
|
|
ename:VK_IMAGE_TYPE_2D then pname:extent.depth must: be `1`.
|
|
* [[VUID-VkImageCopy-srcImage-01791]]
|
|
If the calling command's pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_2D, and the pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_3D, then pname:extent.depth must: equal to the
|
|
pname:layerCount member of pname:srcSubresource.
|
|
* [[VUID-VkImageCopy-dstImage-01792]]
|
|
If the calling command's pname:dstImage is of type
|
|
ename:VK_IMAGE_TYPE_2D, and the pname:srcImage is of type
|
|
ename:VK_IMAGE_TYPE_3D, then pname:extent.depth must: equal to the
|
|
pname:layerCount member of pname:dstSubresource.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[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
|
|
// The block of VU below come in alternate versions when the extension is
|
|
// enabled.
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageCopy-srcOffset-00157]]
|
|
If the calling command's pname:srcImage is a compressed image, 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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
// The nested ifdefs are there in anticipation of the hoped-for day when the
|
|
// VU extractor and validation layers can handle VU with imbedded
|
|
// conditionals. They are commented out until then.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageCopy-srcImage-01727]]
|
|
If the calling command's pname:srcImage is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-srcImage-01728]]
|
|
If the calling command's pname:srcImage is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-srcImage-01729]]
|
|
If the calling command's pname:srcImage is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-srcImage-01730]]
|
|
If the calling command's pname:srcImage is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-dstImage-01731]]
|
|
If the calling command's pname:dstImage is a compressed format image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-dstImage-01732]]
|
|
If the calling command's pname:dstImage is a compressed format image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-dstImage-01733]]
|
|
If the calling command's pname:dstImage is a compressed format image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-dstImage-01734]]
|
|
If the calling command's pname:dstImage is a compressed format image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
****
|
|
|
|
include::{generated}/validity/structs/VkImageCopy.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageSubresourceLayers',desc='Structure specifying an image subresource layers',type='structs']
|
|
--
|
|
|
|
The sname:VkImageSubresourceLayers structure is defined as:
|
|
|
|
include::{generated}/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
|
|
ifdef::VK_EXT_image_drm_format_modifier[]
|
|
* [[VUID-VkImageSubresourceLayers-aspectMask-02247]]
|
|
pname:aspectMask must: not include
|
|
etext:VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index etext:i.
|
|
endif::VK_EXT_image_drm_format_modifier[]
|
|
* [[VUID-VkImageSubresourceLayers-layerCount-01700]]
|
|
pname:layerCount must: be greater than 0
|
|
****
|
|
|
|
include::{generated}/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::{generated}/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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
If the format of pname:dstImage is a
|
|
<<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, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
|
|
For the purposes of fname:vkCmdCopyBufferToImage, each plane of a
|
|
multi-planar image is treated as having the format listed in
|
|
<<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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdCopyBufferToImage-pRegions-00171]]
|
|
pname:srcBuffer must: be large enough to contain all buffer locations
|
|
that are accessed according to <<copies-buffers-images-addressing,Buffer
|
|
and Image Addressing>>, for each element of pname:pRegions
|
|
* [[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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
if the pname:dstImage's elink:VkFormat is not a
|
|
<<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_VERSION_1_1,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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImage-01997]]
|
|
The <<resources-image-format-features,format features>> of
|
|
pname:dstImage must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT.
|
|
endif::VK_VERSION_1_1,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[]
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdCopyBufferToImage-commandBuffer-01828]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:srcBuffer must: not be a protected buffer
|
|
* [[VUID-vkCmdCopyBufferToImage-commandBuffer-01829]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:dstImage must: not be a protected image
|
|
* [[VUID-vkCmdCopyBufferToImage-commandBuffer-01830]]
|
|
If pname:commandBuffer is a protected command buffer, then
|
|
pname:dstImage must: not be an unprotected image
|
|
endif::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdCopyBufferToImage-imageSubresource-01701]]
|
|
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
|
|
* [[VUID-vkCmdCopyBufferToImage-imageSubresource-01702]]
|
|
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
|
|
* [[VUID-vkCmdCopyBufferToImage-imageOffset-01793]]
|
|
The pname:imageOffset and pname:imageExtent members of each element of
|
|
pname:pRegions must: respect the image transfer granularity requirements
|
|
of pname:commandBuffer's command pool's queue family, as described in
|
|
slink:VkQueueFamilyProperties
|
|
ifdef::VK_EXT_fragment_density_map[]
|
|
* [[VUID-vkCmdCopyBufferToImage-dstImage-02543]]
|
|
pname:dstImage must: not have been created with pname:flags containing
|
|
ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
|
|
endif::VK_EXT_fragment_density_map[]
|
|
****
|
|
|
|
include::{generated}/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::{generated}/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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
If the elink:VkFormat of pname:srcImage is a
|
|
<<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, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
|
|
For the purposes of fname:vkCmdCopyBufferToImage, each plane of a
|
|
multi-planar image is treated as having the format listed in
|
|
<<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_VERSION_1_1,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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
if the pname:srcImage's elink:VkFormat is not a
|
|
<<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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-pRegions-00183]]
|
|
pname:dstBuffer must: be large enough to contain all buffer locations
|
|
that are accessed according to <<copies-buffers-images-addressing,Buffer
|
|
and Image Addressing>>, for each element of pname:pRegions
|
|
* [[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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImage-01998]]
|
|
The <<resources-image-format-features,format features>> of
|
|
pname:srcImage must: contain ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT.
|
|
endif::VK_VERSION_1_1,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
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-commandBuffer-01831]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:srcImage must: not be a protected image
|
|
* [[VUID-vkCmdCopyImageToBuffer-commandBuffer-01832]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:dstBuffer must: not be a protected buffer
|
|
* [[VUID-vkCmdCopyImageToBuffer-commandBuffer-01833]]
|
|
If pname:commandBuffer is a protected command buffer, then
|
|
pname:dstBuffer must: not be an unprotected buffer
|
|
endif::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-imageSubresource-01703]]
|
|
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
|
|
* [[VUID-vkCmdCopyImageToBuffer-imageSubresource-01704]]
|
|
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
|
|
* [[VUID-vkCmdCopyImageToBuffer-imageOffset-01794]]
|
|
The pname:imageOffset and pname:imageExtent members of each element of
|
|
pname:pRegions must: respect the image transfer granularity requirements
|
|
of pname:commandBuffer's command pool's queue family, as described in
|
|
slink:VkQueueFamilyProperties
|
|
ifdef::VK_EXT_fragment_density_map[]
|
|
* [[VUID-vkCmdCopyImageToBuffer-srcImage-02544]]
|
|
pname:srcImage must: not have been created with pname:flags containing
|
|
ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
|
|
endif::VK_EXT_fragment_density_map[]
|
|
****
|
|
|
|
include::{generated}/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::{generated}/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 in texels a
|
|
subregion of a larger two- or three-dimensional image in buffer memory,
|
|
and control the addressing calculations.
|
|
If either of these values is zero, that aspect of the buffer memory is
|
|
considered to be tightly packed according to the 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 pname:x, pname:y, pname: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.
|
|
|
|
ifndef::VK_EXT_depth_range_unrestricted[]
|
|
When copying to a depth aspect, the data in buffer memory must: be in the
|
|
range [eq]#[0,1]#, or the resulting values are undefined:.
|
|
endif::VK_EXT_depth_range_unrestricted[]
|
|
|
|
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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-bufferOffset-00193]]
|
|
If 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 texel block size.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,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
|
|
<<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>, then
|
|
pname:bufferOffset must: be a multiple of the format's texel block size.
|
|
* [[VUID-VkBufferImageCopy-bufferOffset-01559]]
|
|
If the calling command's sname:VkImage parameter's format is a
|
|
<<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 <<formats-compatible-planes>>
|
|
endif::VK_VERSION_1_1,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_VERSION_1_1,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
|
|
<<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>
|
|
endif::VK_VERSION_1_1,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_VERSION_1_1,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
|
|
<<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>
|
|
endif::VK_VERSION_1_1,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`
|
|
// The block of VU below come in alternate versions when the extension is
|
|
// enabled.
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-bufferRowLength-00203]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
// The nested ifdefs are there in anticipation of the hoped-for day when the
|
|
// VU extractor and validation layers can handle VU with imbedded
|
|
// conditionals. They are commented out until then.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-None-01735]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:bufferRowLength must: be a multiple of the compressed texel block
|
|
width
|
|
* [[VUID-VkBufferImageCopy-None-01736]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:bufferImageHeight must: be a multiple of the compressed texel
|
|
block height
|
|
* [[VUID-VkBufferImageCopy-None-01737]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-None-01738]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:bufferOffset must: be a multiple of the compressed texel block
|
|
size in bytes
|
|
* [[VUID-VkBufferImageCopy-None-01739]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-None-01740]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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-None-01741]]
|
|
If the calling command's sname:VkImage parameter is a compressed image,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or a _single-plane_, "`etext:_422`" image format,
|
|
// endif::VK_VERSION_1_1,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
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBufferImageCopy-aspectMask-01560]]
|
|
If the calling command's sname:VkImage parameter's format is a
|
|
<<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, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT (with
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with
|
|
three planes)
|
|
endif::VK_VERSION_1_1,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
|
|
ifndef::VK_EXT_depth_range_unrestricted[]
|
|
* [[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]#
|
|
endif::VK_EXT_depth_range_unrestricted[]
|
|
****
|
|
|
|
include::{generated}/validity/structs/VkBufferImageCopy.txt[]
|
|
--
|
|
|
|
[[copies-buffers-images-addressing]]
|
|
=== Buffer and Image Addressing
|
|
|
|
Pseudocode for image/buffer addressing of uncompressed formats is:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
rowLength = region->bufferRowLength;
|
|
if (rowLength == 0)
|
|
rowLength = region->imageExtent.width;
|
|
|
|
imageHeight = region->bufferImageHeight;
|
|
if (imageHeight == 0)
|
|
imageHeight = region->imageExtent.height;
|
|
|
|
texelBlockSize = <texel block size of the format of the src/dstImage>;
|
|
|
|
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize;
|
|
|
|
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-compressed 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::{generated}/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 the value sampled
|
|
from the source image is taken from the single nearest slice, with an
|
|
implementation-dependent arithmetic 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-01999]]
|
|
The <<resources-image-format-features,format features>> of
|
|
pname:srcImage must: contain ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdBlitImage-srcImage-01561]]
|
|
pname:srcImage must: not use a format listed in
|
|
<<formats-requiring-sampler-ycbcr-conversion>>
|
|
endif::VK_VERSION_1_1,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-02000]]
|
|
The <<resources-image-format-features,format features>> of
|
|
pname:dstImage must: contain ename:VK_FORMAT_FEATURE_BLIT_DST_BIT.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkCmdBlitImage-dstImage-01562]]
|
|
pname:dstImage must: not use a format listed in
|
|
<<formats-requiring-sampler-ycbcr-conversion>>
|
|
endif::VK_VERSION_1_1,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-02001]]
|
|
If pname:filter is ename:VK_FILTER_LINEAR, then the
|
|
<<resources-image-format-features,format features>> of pname:srcImage
|
|
must: contain ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT.
|
|
ifdef::VK_IMG_filter_cubic,VK_EXT_filter_cubic[]
|
|
* [[VUID-vkCmdBlitImage-filter-02002]]
|
|
If pname:filter is ename:VK_FILTER_CUBIC_EXT, then the
|
|
<<resources-image-format-features,format features>> of pname:srcImage
|
|
must: contain
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT.
|
|
* [[VUID-vkCmdBlitImage-filter-00237]]
|
|
If pname:filter is ename:VK_FILTER_CUBIC_EXT, pname:srcImage must: have
|
|
a elink:VkImageType of ename:VK_IMAGE_TYPE_2D
|
|
endif::VK_IMG_filter_cubic,VK_EXT_filter_cubic[]
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdBlitImage-commandBuffer-01834]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:srcImage must: not be a protected image
|
|
* [[VUID-vkCmdBlitImage-commandBuffer-01835]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:dstImage must: not be a protected image
|
|
* [[VUID-vkCmdBlitImage-commandBuffer-01836]]
|
|
If pname:commandBuffer is a protected command buffer, then
|
|
pname:dstImage must: not be an unprotected image
|
|
endif::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdBlitImage-srcSubresource-01705]]
|
|
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
|
|
* [[VUID-vkCmdBlitImage-dstSubresource-01706]]
|
|
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
|
|
* [[VUID-vkCmdBlitImage-srcSubresource-01707]]
|
|
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
|
|
* [[VUID-vkCmdBlitImage-dstSubresource-01708]]
|
|
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
|
|
ifdef::VK_EXT_fragment_density_map[]
|
|
* [[VUID-vkCmdBlitImage-dstImage-02545]]
|
|
pname:dstImage and pname:srcImage must: not have been created with
|
|
pname:flags containing ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
|
|
endif::VK_EXT_fragment_density_map[]
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkCmdBlitImage.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageBlit',desc='Structure specifying an image blit operation',type='structs']
|
|
--
|
|
|
|
The sname:VkImageBlit structure is defined as:
|
|
|
|
include::{generated}/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::{generated}/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::{generated}/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 pname:x, pname:y, and
|
|
pname: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-02003]]
|
|
The <<resources-image-format-features,format features>> of
|
|
pname:dstImage must: contain
|
|
ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT.
|
|
* [[VUID-vkCmdResolveImage-srcImage-01386]]
|
|
pname:srcImage and pname:dstImage must: have been created with the same
|
|
image format
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdResolveImage-commandBuffer-01837]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:srcImage must: not be a protected image
|
|
* [[VUID-vkCmdResolveImage-commandBuffer-01838]]
|
|
If pname:commandBuffer is an unprotected command buffer, then
|
|
pname:dstImage must: not be a protected image
|
|
* [[VUID-vkCmdResolveImage-commandBuffer-01839]]
|
|
If pname:commandBuffer is a protected command buffer, then
|
|
pname:dstImage must: not be an unprotected image
|
|
endif::VK_VERSION_1_1[]
|
|
* [[VUID-vkCmdResolveImage-srcSubresource-01709]]
|
|
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
|
|
* [[VUID-vkCmdResolveImage-dstSubresource-01710]]
|
|
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
|
|
* [[VUID-vkCmdResolveImage-srcSubresource-01711]]
|
|
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
|
|
* [[VUID-vkCmdResolveImage-dstSubresource-01712]]
|
|
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
|
|
ifdef::VK_EXT_fragment_density_map[]
|
|
* [[VUID-vkCmdResolveImage-dstImage-02546]]
|
|
pname:dstImage and pname:srcImage must: not have been created with
|
|
pname:flags containing ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
|
|
endif::VK_EXT_fragment_density_map[]
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkCmdResolveImage.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageResolve',desc='Structure specifying an image resolve operation',type='structs']
|
|
--
|
|
|
|
The sname:VkImageResolve structure is defined as:
|
|
|
|
include::{generated}/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 pname:x, pname:y,
|
|
and pname: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::{generated}/validity/structs/VkImageResolve.txt[]
|
|
--
|
|
|
|
ifdef::VK_AMD_buffer_marker[]
|
|
include::VK_AMD_buffer_marker/copies.txt[]
|
|
endif::VK_AMD_buffer_marker[]
|