# vkCmdResolveImage(3) Manual Page

## Name

vkCmdResolveImage - Resolve regions of an image

Loading… please wait.

## 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 format is a floating-point or normalized type, the resolve mode is chosen as implementation-dependent behavior. If the resolve mode requires to calculate the result from multiple samples, such as by computing an average or weighted average of the samples, the values for each pixel are resolved with implementation-defined numerical precision.

If the numeric format of `srcImage` uses sRGB encoding and the resolve mode requires the implementation to convert the samples to floating-point to perform the calculations, the implementation should convert samples from nonlinear to linear before resolving the samples as described in the “sRGB EOTF” section of the Khronos Data Format Specification. In this case, the implementation must convert the linear averaged value to nonlinear before writing the resolved result to `dstImage`.

If the source format is an integer type, 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 and `protectedNoFault` is not supported, `srcImage` must not be a protected image

- VUID-vkCmdResolveImage-commandBuffer-01838
  If `commandBuffer` is an unprotected command buffer and `protectedNoFault` is not supported, `dstImage` must not be a protected image

- VUID-vkCmdResolveImage-commandBuffer-01839
  If `commandBuffer` is a protected command buffer and `protectedNoFault` is not supported, `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-linearColorAttachment-06519
  If the `linearColorAttachment` feature is enabled and the image is created with `VK_IMAGE_TILING_LINEAR`, the format features of `dstImage` must contain `VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV`

- 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
  If `srcSubresource.layerCount` is not `VK_REMAINING_ARRAY_LAYERS`, `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
  If `dstSubresource.layerCount` is not `VK_REMAINING_ARRAY_LAYERS`, `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 `dstImage` is of type `VK_IMAGE_TYPE_3D`, then for each element of `pRegions`, `srcSubresource.layerCount` must be `1`

- VUID-vkCmdResolveImage-srcImage-04447
  If `dstImage` is 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`

- VUID-vkCmdResolveImage-srcImage-06762
  `srcImage` must have been created with `VK_IMAGE_USAGE_TRANSFER_SRC_BIT` usage flag

- VUID-vkCmdResolveImage-srcImage-06763
  The format features of `srcImage` must contain `VK_FORMAT_FEATURE_TRANSFER_SRC_BIT`

- VUID-vkCmdResolveImage-dstImage-06764
  `dstImage` must have been created with `VK_IMAGE_USAGE_TRANSFER_DST_BIT` usage flag

- VUID-vkCmdResolveImage-dstImage-06765
  The format features of `dstImage` must contain `VK_FORMAT_FEATURE_TRANSFER_DST_BIT`

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-videocoding
  This command must only be called outside of a video coding scope

- 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 | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Outside | Outside | Graphics | Action

## See Also

VK_VERSION_1_0, VkCommandBuffer, VkImage, VkImageLayout, VkImageResolve

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

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0