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.

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
  • The source region specified by each element of pRegions must be a region that is contained within srcImage

  • The destination region specified by each 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

  • If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • srcImage must have a sample count equal to any valid sample count value other than VK_SAMPLE_COUNT_1_BIT

  • If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

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

  • srcImage and dstImage must have been created with the same image format

  • The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • The srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • The dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

Valid Usage (Implicit)
  • 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 valid 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

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Graphics

Transfer

See Also

Document Notes

For more information, see the Vulkan Specification at URL

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

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