C Specification

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

// Provided by VK_VERSION_1_0
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. Each element of pRegions must be a region that is contained within its corresponding image.

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
  • VUID-vkCmdResolveImage-commandBuffer-01837
    If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

  • VUID-vkCmdResolveImage-commandBuffer-01838
    If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image

  • VUID-vkCmdResolveImage-commandBuffer-01839
    If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image

  • VUID-vkCmdResolveImage-pRegions-00255
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

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

  • VUID-vkCmdResolveImage-srcImage-00257
    srcImage must have a sample count equal to any valid sample count value other than VK_SAMPLE_COUNT_1_BIT

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

  • VUID-vkCmdResolveImage-dstImage-00259
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

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

  • VUID-vkCmdResolveImage-srcImageLayout-01400
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

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

  • VUID-vkCmdResolveImage-dstImageLayout-01401
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdResolveImage-dstImage-02003
    The format features of dstImage must contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-vkCmdResolveImage-srcImage-01386
    srcImage and dstImage must have been created with the same image format

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

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

  • VUID-vkCmdResolveImage-srcSubresource-01711
    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

  • VUID-vkCmdResolveImage-dstSubresource-01712
    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

  • VUID-vkCmdResolveImage-dstImage-02546
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdResolveImage-srcImage-04446
    If either srcImage or dstImage are of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and srcSubresource.layerCount must be 1

  • VUID-vkCmdResolveImage-srcImage-04447
    If either srcImage or dstImage are of type VK_IMAGE_TYPE_3D, then for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1

  • VUID-vkCmdResolveImage-srcOffset-00269
    For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage

  • VUID-vkCmdResolveImage-srcOffset-00270
    For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage

  • VUID-vkCmdResolveImage-srcImage-00271
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1

  • VUID-vkCmdResolveImage-srcOffset-00272
    For each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage

  • VUID-vkCmdResolveImage-srcImage-00273
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1

  • VUID-vkCmdResolveImage-dstOffset-00274
    For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage

  • VUID-vkCmdResolveImage-dstOffset-00275
    For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage

  • VUID-vkCmdResolveImage-dstImage-00276
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1

  • VUID-vkCmdResolveImage-dstOffset-00277
    For each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

  • VUID-vkCmdResolveImage-dstImage-00278
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1

Valid Usage (Implicit)
  • VUID-vkCmdResolveImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdResolveImage-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-vkCmdResolveImage-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdResolveImage-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-vkCmdResolveImage-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdResolveImage-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageResolve structures

  • VUID-vkCmdResolveImage-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdResolveImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdResolveImage-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdResolveImage-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-vkCmdResolveImage-commonparent
    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

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

Copyright (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0