129 lines
5.6 KiB
Plaintext
129 lines
5.6 KiB
Plaintext
// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
vkCmdCopyImage(3)
|
|
=================
|
|
|
|
Name
|
|
----
|
|
vkCmdCopyImage - Copy data between images.
|
|
|
|
C Specification
|
|
---------------
|
|
|
|
// refBegin vkCmdCopyImage Copy data between images.
|
|
|
|
To copy data between image objects, call:
|
|
|
|
include::../protos/vkCmdCopyImage.txt[]
|
|
|
|
|
|
Parameters
|
|
----------
|
|
|
|
* 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.
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
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 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.
|
|
|
|
[[copies-images-format-compatibility]]
|
|
The formats of pname:srcImage and pname:dstImage must: be compatible.
|
|
Formats are considered compatible if their texel size in bytes is the same
|
|
between both formats. For example, ename:VK_FORMAT_R8G8B8A8_UNORM is
|
|
compatible with ename:VK_FORMAT_R32_UINT because both texels are 4
|
|
bytes in size. Depth/stencil formats must: match exactly.
|
|
|
|
fname:vkCmdCopyImage allows copying between size-compatible compressed
|
|
and uncompressed internal formats. Formats are size-compatible if the texel
|
|
size of the uncompressed format is equal to the compressed texel block size in
|
|
bytes 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 4x4 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 4x4 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. 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 and if pname:extent.width is not a
|
|
multiple of the compressed texel block width then (pname:extent.width +
|
|
pname:srcOffset.x) must: equal the image subresource width, if
|
|
pname:extent.height is not a multiple of the compressed texel block height
|
|
then (pname:extent.height + pname:srcOffset.y) must: equal the image
|
|
subresource height and if pname:extent.depth is not a multiple of the
|
|
compressed texel block depth then (pname:extent.depth + pname:srcOffset.z)
|
|
must: equal the image subresource depth. Similarly, if the pname:dstImage is
|
|
compressed and if pname:extent.width is not a multiple of the compressed
|
|
texel block width then (pname:extent.width + pname:dstOffset.x) must: equal
|
|
the image subresource width, if pname:extent.height is not a multiple of the
|
|
compressed texel block height then (pname:extent.height + pname:dstOffset.y)
|
|
must: equal the image subresource height and if pname:extent.depth is not a
|
|
multiple of the compressed texel block depth then (pname:extent.depth +
|
|
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.
|
|
|
|
fname:vkCmdCopyImage can: be used to copy image data between multisample
|
|
images, but both images must: have the same number of samples.
|
|
|
|
include::../validity/protos/vkCmdCopyImage.txt[]
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
slink:VkCommandBuffer, slink:VkImage, slink:VkImageCopy, elink:VkImageLayout
|
|
|
|
|
|
Document Notes
|
|
--------------
|
|
|
|
For more information, see the Vulkan Specification at URL
|
|
|
|
https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdCopyImage
|
|
|
|
This page is extracted from the Vulkan Specification.
|
|
Fixes and changes should be made to the Specification,not directly.
|
|
|
|
include::footer.txt[]
|
|
|