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[]