VKCMDBLITIMAGE(3)

NAME
vkCmdBlitImage - Copy regions of an image, potentially performing format conversion,

C SPECIFICATION

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);

PARAMETERS

    • 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.

DESCRIPTION

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:

    \begin{align*} u_{base} & = i + \frac{1}{2}\\ v_{base} & = j + \frac{1}{2}\\ w_{base} & = k + \frac{1}{2}\\ \end{align*}

    • These base coordinates are then offset by the first destination offset:

    \begin{align*} u_{offset} & = u_{base} - x_{dst_0}\\ v_{offset} & = v_{base} - y_{dst_0}\\ w_{offset} & = w_{base} - z_{dst_0}\\ a_{offset} & = a - baseArrayCount_{dst} \end{align*}

    • The scale is determined from the source and destination regions, and applied to the offset coordinates:

    \begin{align*} scale_u & = \frac{x_{src_1} - x_{src_0}}{x_{dst_1} - x_{dst_0}}\\ scale_v & = \frac{y_{src_1} - y_{src_0}}{y_{dst_1} - y_{dst_0}}\\ scale_w & = \frac{z_{src_1} - z_{src_0}}{z_{dst_1} - z_{dst_0}}\\ \\ u_{scaled} & = u_{offset} * scale_u\\ v_{scaled} & = v_{offset} * scale_v\\ w_{scaled} & = w_{offset} * scale_w \end{align*}

    • Finally the source offset is added to the scaled coordinates, to determine the final unnormalized coordinates used to sample from srcImage:

    \begin{align*} u & = u_{scaled} + x_{src_0}\\ v & = v_{scaled} + y_{src_0}\\ w & = w_{scaled} + z_{src_0}\\ q & = mipLevel\\ a & = a_{offset} + baseArrayCount_{src} \end{align*}

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.

    Note

    Due to allowable rounding errors in the generation of the source texture coordinates, it is not always possible to guarantee exactly which source texels will be sampled for a given blit. As rounding errors are implementation dependent, the exact results of a blitting operation are also implementation dependent.

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.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • srcImage must be a valid VkImage handle

    • srcImageLayout must be a valid VkImageLayout value

    • dstImage must be a valid VkImage handle

    • dstImageLayout must be a valid VkImageLayout value

    • pRegions must be a pointer to an array of regionCount valid VkImageBlit structures

    • filter must be a valid VkFilter value

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support graphics operations

    • This command must only be called outside of a render pass instance

    • regionCount must be greater than 0

    • Each of commandBuffer, srcImage and dstImage must have been created, allocated or retrieved from the same VkDevice

    • The source region specified by a given element of pRegions must be a region that is contained within srcImage

    • The destination region specified by a given element of pRegions must be a region that is contained within dstImage

    • The union of all destination regions, specified by the elements of pRegions, must not overlap in memory with any texel that may be sampled during the blit operation

    • srcImage must use a format that supports VK_FORMAT_FEATURE_BLIT_SRC_BIT, which is indicated by VkFormatProperties::linearTilingFeatures (for linear tiled images) or VkFormatProperties::optimalTilingFeatures (for optimally tiled images) - as returned by vkGetPhysicalDeviceFormatProperties

    • srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

    • srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

    • srcImageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

    • dstImage must use a format that supports VK_FORMAT_FEATURE_BLIT_DST_BIT, which is indicated by VkFormatProperties::linearTilingFeatures (for linear tiled images) or VkFormatProperties::optimalTilingFeatures (for optimally tiled images) - as returned by vkGetPhysicalDeviceFormatProperties

    • dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

    • dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

    • dstImageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

    • The sample count of srcImage and dstImage must both be equal to VK_SAMPLE_COUNT_1_BIT

    • If either of srcImage or dstImage was created with a signed integer VkFormat, the other must also have been created with a signed integer VkFormat

    • If either of srcImage or dstImage was created with an unsigned integer VkFormat, the other must also have been created with an unsigned integer VkFormat

    • If either of srcImage or dstImage was created with a depth/stencil format, the other must have exactly the same format

    • If srcImage was created with a depth/stencil format, filter must be VK_FILTER_NEAREST

    • srcImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

    • dstImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

    • If filter is VK_FILTER_LINEAR, srcImage must be of a format which supports linear filtering, as specified by the VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in VkFormatProperties::linearTilingFeatures (for a linear image) or VkFormatProperties::optimalTilingFeatures(for an optimally tiled image) returned by vkGetPhysicalDeviceFormatProperties

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Outside | GRAPHICS

SEE ALSO

VkCommandBuffer, VkFilter, VkImage, VkImageBlit, VkImageLayout

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdBlitImage

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.