Vulkan-Docs/doc/specs/vulkan/man/vkCmdBlitImage.txt

116 lines
4.0 KiB
Plaintext

vkCmdBlitImage(3)
=================
Name
----
vkCmdBlitImage - copies regions of an image, potentially performing format conversion,
arbitrary scaling, and filtering (but does not allow MSAA resolve).
C Specification
---------------
include::../protos/vkCmdBlitImage.txt[]
Parameters
----------
pname:commandBuffer::
The command buffer into which the command is to be placed.
pname:srcImage::
The image that is the source of the blit operation.
pname:srcImageLayout::
The layout of the source image at the time of the blit.
pname:dstImage::
The image into which image data is to be copied.
pname:dstImageLayout::
The layout of the destination image at the time of the blit.
pname:regionCount::
The number of regions to blit.
pname:pRegions::
An array of image regions to blit.
pname:filter::
Filtering operation to perform on the image while performing the blit.
Description
-----------
fname:vkCmdBlitImage copies regions of a source image into a destination image, potentially performing
format conversion, arbitrary scaling, and filtering (but does not allow MSAA resolve).
The source and destination images are specified in pname:srcImage and pname:dstImage,
respectively. The layout of the source and destination images must be provided
in pname:srcImageLayout and pname:dstImageLayout, respectively.
The pname:srcImageLayout must be either ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
or ename:VK_IMAGE_LAYOUT_GENERAL. The pname:dstImageLayout must be either
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL.
The pname:srcImage must support the elink:VkFormatFeatureFlags bit
ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT and the pname:dstImage must support
the elink:VkFormatFeatureFlags bit ename:VK_FORMAT_FEATURE_BLIT_DST_BIT.
pname:srcImage and pname:dstImage may reference the same image but results are
undefined if source and destination regions overlap. pname:srcImage or
pname:dstImage may not refer to multi-sampled images. Use fname:vkCmdResolveImage
to resolve multi-sampled images.
pname:pRegions is a pointer to an array of pname:regionCount slink:VkImageBlit
structures, the definition of each is:
include::../structs/VkImageBlit.txt[]
The pname:srcSubresource and pname:dstSubresource members of slink:VkImageBlit
specify the source and destination sub-resources, respectively. Each is
a instance of the slink:VkImageSubresourceLayers structure, the definition of
which is:
include::../structs/VkImageSubresourceLayers.txt[]
The ptext:srcOffset[0] and ptext:srcOffset[1] members of slink:VkImageBlit
define the region of the source image to copy from, and the ptext:dstOffset[0]
and ptext:dstOffset[1] members define the region of the destination image to
copy to. The offset members are instances of the slink:VkOffset3D structure. The
definition of slink:VkOffset3D is:
include::../structs/VkOffset3D.txt[]
The size of the two regions need not match. If they are different, then
the pname:filter parameter determines the filtering mode used to expand or
shrink the source region to fit the destination region. This is a member of
the elink:VkFilter enumeration, the definition of which is:
include::../enums/VkFilter.txt[]
If the format of pname:srcImage is an integer-based format then pname:filter
must be ename:VK_FILTER_NEAREST.
Pixels are copied from the regions bound by srcOffset[0], srcOffset[1] to the
region bound by destOffset[0], destOffset[1], scaling the result if the regions
are different sizes.
fname:vkCmdBlitImage does not perform any implicit barriers. Therefore, if any
region in the array of pname:pRegions a references updates from a prior
region, then results are undefined.
This command may not be used within a renderpass.
include::../validity/protos/vkCmdBlitImage.txt[]
Notes
-----
Although fname:vkCmdBlitImage does not generate errors or return a value, enabled
validation layers may detect possible error conditions or potentially undefined
behavior and report this via some other means.
See Also
--------
flink:vkCmdResolveImage, flink:vkCmdCopyImage
include::footer.txt[]