vkCmdBlitImage

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.

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 unnormalized to integer conversion:
  • u_base = i + ½
  • v_base = j + ½
  • w_base = k + ½
• These base coordinates are then offset by the first destination offset:
  • u_offset = u_base - x_dst0
  • v_offset = v_base - y_dst0
  • w_offset = w_base - z_dst0
  • a_offset = a - baseArrayCount_dst
• The scale is determined from the source and destination regions, and applied to the offset coordinates:
  • scale_u = (x_src1 - x_src0) / (x_dst1 - x_dst0)
  • scale_v = (y_src1 - y_src0) / (y_dst1 - y_dst0)
  • scale_w = (z_src1 - z_src0) / (z_dst1 - z_dst0)
  • u_scaled = u_offset × scale_u
  • v_scaled = v_offset × scale_v
  • 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 srcImage:
  • u = u_scaled + x_src0
  • v = v_scaled + y_src0
  • w = w_scaled + z_src0
  • q = mipLevel
  • a = a_offset + baseArrayCount_src

These coordinates are used to sample from the source image, as described in Image Operations chapter, with the filter mode equal to that of filter, a mipmap mode of VK_SAMPLER_MIPMAP_MODE_NEAREST and an address mode of 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.

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.

When blitting 3D textures, slices in the destination region bounded by dstOffsets[0].z and dstOffsets[1].z are sampled from slices in the source region bounded by 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 represented by w in the previous equations. If the filter parameter is 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, scaled 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.