VKCMDRESOLVEIMAGE(3)

NAME
vkCmdResolveImage - Resolve regions of an image.

C SPECIFICATION

To resolve a multisample image to a non-multisample image, call:

    void vkCmdResolveImage(
        VkCommandBuffer                             commandBuffer,
        VkImage                                     srcImage,
        VkImageLayout                               srcImageLayout,
        VkImage                                     dstImage,
        VkImageLayout                               dstImageLayout,
        uint32_t                                    regionCount,
        const VkImageResolve*                       pRegions);

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

    • dstImage is the destination image.

    • dstImageLayout is the layout of the destination image subresources for the resolve.

    • regionCount is the number of regions to resolve.

    • pRegions is a pointer to an array of VkImageResolve structures specifying the regions to resolve.

DESCRIPTION

During the resolve the samples corresponding to each pixel location in the source are converted to a single sample before being written to the destination. If the source formats are floating-point or normalized types, the sample values for each pixel are resolved in an implementation-dependent manner. If the source formats are integer types, a single sample’s value is selected for each pixel.

srcOffset and dstOffset select the initial x, y, and z offsets in texels of the sub-regions of the source and destination image data. extent is the size in texels of the source image to resolve in width, height and depth. 1D images use only x and width. 2D images use x, y, width and height. 3D images use x, y, z, width, height and depth.

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

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 VkImageResolve structures

    • 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, dstImage, and srcImage 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 have a sample count equal to any valid sample count value other than VK_SAMPLE_COUNT_1_BIT

    • dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

    • 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

    • 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

    • If dstImage was created with tiling equal to VK_IMAGE_TILING_LINEAR, dstImage must have been created with a format that supports being a color attachment, as specified by the VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in VkFormatProperties::linearTilingFeatures returned by vkGetPhysicalDeviceFormatProperties

    • If dstImage was created with tiling equal to VK_IMAGE_TILING_OPTIMAL, dstImage must have been created with a format that supports being a color attachment, as specified by the VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in VkFormatProperties::optimalTilingFeatures 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, VkImage, VkImageLayout, VkImageResolve

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

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

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.