Function Prototype

vkCmdResolveImage

Resolve regions of an image
primary / secondary
outside
graphics
action

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

void vkCmdResolveImage(
    VkCommandBuffer commandBuffer,
    VkImage srcImage,
    VkImageLayout srcImageLayout,
    VkImage dstImage,
    VkImageLayout dstImageLayout,
    uint32_t regionCount,
    const VkImageResolve* pRegions);
  • 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.

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-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 dstImagemust 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-srcImage-parameter

srcImage must be a valid VkImage handle

VUID-vkCmdResolveImage-dstImage-parameter

dstImage must be a valid VkImage handle

VUID-vkCmdResolveImage-pRegions-parameter

pRegions must be a valid pointer to an array of regionCount valid VkImageResolve structures

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