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

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

PARAMETERS

commandBuffer
    The command buffer into which the command is to be placed.

srcImage
    The image that is the source of the blit operation.

srcImageLayout
    The layout of the source image at the time of the blit.

dstImage
    The image into which image data is to be copied.

dstImageLayout
    The layout of the destination image at the time of the blit.

regionCount
    The number of regions to blit.

pRegions
    An array of image regions to blit.

filter
    Filtering operation to perform on the image while performing the blit.

DESCRIPTION

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 srcImage and dstImage, respectively. The layout of the source and destination images must be provided in srcImageLayout and dstImageLayout, respectively. The srcImageLayout must be either VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL. The dstImageLayout must be either VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL.

The srcImage must support the VkFormatFeatureFlags bit VK_FORMAT_FEATURE_BLIT_SRC_BIT and the dstImage must support the VkFormatFeatureFlags bit VK_FORMAT_FEATURE_BLIT_DST_BIT. srcImage and dstImage may reference the same image but results are undefined if source and destination regions overlap. srcImage or dstImage may not refer to multi-sampled images. Use vkCmdResolveImage to resolve multi-sampled images.

pRegions is a pointer to an array of regionCount VkImageBlit structures, the definition of each is:

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

The srcSubresource and dstSubresource members of VkImageBlit specify the source and destination sub-resources, respectively. Each is a instance of the VkImageSubresourceLayers structure, the definition of which is:

    typedef struct VkImageSubresourceLayers {
        VkImageAspectFlags    aspectMask;
        uint32_t              mipLevel;
        uint32_t              baseArrayLayer;
        uint32_t              layerCount;
    } VkImageSubresourceLayers;

The srcOffset[0] and srcOffset[1] members of VkImageBlit define the region of the source image to copy from, and the dstOffset[0] and dstOffset[1] members define the region of the destination image to copy to. The offset members are instances of the VkOffset3D structure. The definition of VkOffset3D is:

    typedef struct VkOffset3D {
        int32_t    x;
        int32_t    y;
        int32_t    z;
    } VkOffset3D;

The size of the two regions need not match. If they are different, then the 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 VkFilter enumeration, the definition of which is:

    typedef enum VkFilter {
        VK_FILTER_NEAREST = 0,
        VK_FILTER_LINEAR = 1,
    } VkFilter;

If the format of srcImage is an integer-based format then filter must be 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.

vkCmdBlitImage does not perform any implicit barriers. Therefore, if any region in the array of pRegions a references updates from a prior region, then results are undefined.

This command may not be used within a renderpass.

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 source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

    • 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

    • 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

NOTES

Although 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

vkCmdResolveImage, vkCmdCopyImage

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.