## 18.5. Image Copies with Scaling

To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call:

void vkCmdBlitImage(
VkCommandBuffer                             commandBuffer,
VkImage                                     srcImage,
VkImageLayout                               srcImageLayout,
VkImage                                     dstImage,
VkImageLayout                               dstImageLayout,
uint32_t                                    regionCount,
const VkImageBlit*                          pRegions,
VkFilter                                    filter);

• commandBuffer is the command buffer into which the command will be recorded.
• srcImage is the source image.
• srcImageLayout is the layout of the source image subresources for the blit.
• dstImage is the destination image.
• dstImageLayout is the layout of the destination image subresources for the blit.
• regionCount is the number of regions to blit.
• pRegions is a pointer to an array of VkImageBlit structures specifying the regions to blit.
• filter is a VkFilter specifying the filter to apply if the blits require scaling.

vkCmdBlitImage must not be used for multisampled source or destination images. Use vkCmdResolveImage for this purpose.

The VkImageBlit structure is defined as:

typedef struct VkImageBlit {
VkImageSubresourceLayers    srcSubresource;
VkOffset3D                  srcOffsets[2];
VkImageSubresourceLayers    dstSubresource;
VkOffset3D                  dstOffsets[2];
} VkImageBlit;

For each element of the pRegions array, a blit operation is performed between the region of srcSubresource of srcImage (bounded by srcOffsets[0] and srcOffsets[1]) and a region of dstSubresource of dstImage (bounded by dstOffsets[0] and dstOffsets[1]).

If sizes of source and destination extents do not match, scaling is performed by applying the filtering mode specified by filter parameter. VK_FILTER_LINEAR uses bilinear interpolation, and VK_FILTER_NEAREST uses point sampling. When using VK_FILTER_LINEAR, magnifying blits may generate texel coordinates outside of the source region. If those coordinates are outside the bounds of the image level, the coordinates are clamped as in VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE address mode. However, if the coordinates are outside the source region but inside the image level, the implementation may clamp coordinates to the source region.

If source and destination extents are identical, no filtering is performed. Pixels in the axis-aligned region bounded by srcOffsets[0] and srcOffsets[1] will be copied to the destination region bound by dstOffsets[0] and dstOffsets[1]. In the case where dstOffsets[0].x > dstOffsets[1].x the copied pixels are reversed in that direction. Likewise for y and z.

Blits are done layer by layer starting with the baseArrayLayer member of srcSubresource for the source and dstSubresource for the destination. layerCount layers are blitted to the destination image.

3D textures are blitted slice by slice. Slices in the source region bounded by srcOffsets[0].z and srcOffsets[1].z are copied to slices in the destination region bounded by dstOffsets[0].z and dstOffsets[1].z. For each destination slice, a source z coordinate is linearly interpolated between srcOffsets[0].z and srcOffsets[1].z. If the filter parameter is VK_FILTER_LINEAR then the value sampled from the source image is taken by doing linear filtering using the interpolated z coordinate. If filter parameter is VK_FILTER_NEAREST then value sampled from the source image is taken from the single nearest slice (with undefined rounding mode).

The following filtering and conversion rules apply:

• Integer formats can only be converted to other integer formats with the same signedness.
• No format conversion is supported between depth/stencil images - the formats must match.
• Format conversions on unorm, snorm, unscaled and packed float formats of the copied aspect of the image are performed by first converting the pixels to float values.
• In case of sRGB source format, 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.