VkRenderingAttachmentInfo(3)

# VkRenderingAttachmentInfo(3) Manual Page

## Name

VkRenderingAttachmentInfo - Structure specifying attachment information

Loading… please wait.

## C Specification

The `VkRenderingAttachmentInfo` structure is defined as:

    // Provided by VK_VERSION_1_3
    typedef struct VkRenderingAttachmentInfo {
        VkStructureType          sType;
        const void*              pNext;
        VkImageView              imageView;
        VkImageLayout            imageLayout;
        VkResolveModeFlagBits    resolveMode;
        VkImageView              resolveImageView;
        VkImageLayout            resolveImageLayout;
        VkAttachmentLoadOp       loadOp;
        VkAttachmentStoreOp      storeOp;
        VkClearValue             clearValue;
    } VkRenderingAttachmentInfo;

or the equivalent

    // Provided by VK_KHR_dynamic_rendering
    typedef VkRenderingAttachmentInfo VkRenderingAttachmentInfoKHR;

## Members

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `imageView` is the image view that will be used for rendering.

- `imageLayout` is the layout that `imageView` will be in during rendering.

- `resolveMode` is a VkResolveModeFlagBits value defining how data written to `imageView` will be resolved into `resolveImageView`.

- `resolveImageView` is an image view used to write resolved data at the end of rendering.

- `resolveImageLayout` is the layout that `resolveImageView` will be in during rendering.

- `loadOp` is a VkAttachmentLoadOp value defining the load operation for the attachment.

- `storeOp` is a VkAttachmentStoreOp value defining the store operation for the attachment.

- `clearValue` is a VkClearValue structure defining values used to clear `imageView` when `loadOp` is `VK_ATTACHMENT_LOAD_OP_CLEAR`.

## Description

Values in `imageView` are loaded and stored according to the values of `loadOp` and `storeOp`, within the render area for each device specified in VkRenderingInfo. If `imageView` is VK_NULL_HANDLE, and `resolveMode` is not `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`, other members of this structure are ignored; writes to this attachment will be discarded, and no load, store, or multisample resolve operations will be performed.

If `resolveMode` is `VK_RESOLVE_MODE_NONE`, then `resolveImageView` is ignored. If `resolveMode` is not `VK_RESOLVE_MODE_NONE`, and `resolveImageView` is not VK_NULL_HANDLE, a render pass multisample resolve operation is defined for the attachment subresource. If `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`, and the `nullColorAttachmentWithExternalFormatResolve` limit is `VK_TRUE`, values are only undefined once load operations have completed.

| Note The resolve mode and store operation are independent; it is valid to write both resolved and unresolved values, and equally valid to discard the unresolved values while writing the resolved ones.

Store and resolve operations are only performed at the end of a render pass instance that does not specify the `VK_RENDERING_SUSPENDING_BIT_KHR` flag.

Load operations are only performed at the beginning of a render pass instance that does not specify the `VK_RENDERING_RESUMING_BIT_KHR` flag.

Image contents at the end of a suspended render pass instance remain defined for access by a resuming render pass instance.

If the `nullColorAttachmentWithExternalFormatResolve` limit is `VK_TRUE`, and `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`, values in the color attachment will be loaded from the resolve attachment at the start of rendering, and may also be reloaded any time after a resolve occurs or the resolve attachment is written to; if this occurs it must happen-before any writes to the color attachment are performed which happen-after the resolve that triggers this. If any color component in the external format is subsampled, values will be read from the nearest sample in the image when they are loaded.

Valid Usage

- VUID-VkRenderingAttachmentInfo-imageView-06129
  If `imageView` is not VK_NULL_HANDLE and has a non-integer color format, `resolveMode` must be `VK_RESOLVE_MODE_NONE` or `VK_RESOLVE_MODE_AVERAGE_BIT`

- VUID-VkRenderingAttachmentInfo-imageView-06130
  If `imageView` is not VK_NULL_HANDLE and has an integer color format, `resolveMode` must be `VK_RESOLVE_MODE_NONE` or `VK_RESOLVE_MODE_SAMPLE_ZERO_BIT`

- VUID-VkRenderingAttachmentInfo-imageView-06861
  `imageView` must not have a sample count of `VK_SAMPLE_COUNT_1_BIT` if all of the following hold:

  - `imageView` is not VK_NULL_HANDLE

  - `resolveMode` is not `VK_RESOLVE_MODE_NONE`

  - the `pNext` chain of VkRenderingInfo does not include a VkMultisampledRenderToSingleSampledInfoEXT structure with the `multisampledRenderToSingleSampledEnable` field equal to `VK_TRUE`

- VUID-VkRenderingAttachmentInfo-imageView-06862
  `resolveImageView` must not be VK_NULL_HANDLE if all of the following hold:

  - `imageView` is not VK_NULL_HANDLE

  - `resolveMode` is not `VK_RESOLVE_MODE_NONE`

  - the `pNext` chain of VkRenderingInfo does not include a VkMultisampledRenderToSingleSampledInfoEXT structure with the `multisampledRenderToSingleSampledEnable` field equal to `VK_TRUE`

- VUID-VkRenderingAttachmentInfo-imageView-06863
  If `imageView` is not VK_NULL_HANDLE, `resolveMode` is not `VK_RESOLVE_MODE_NONE`, the `pNext` chain of VkRenderingInfo includes a VkMultisampledRenderToSingleSampledInfoEXT structure with the `multisampledRenderToSingleSampledEnable` field equal to `VK_TRUE`, and `imageView` has a sample count of `VK_SAMPLE_COUNT_1_BIT`, `resolveImageView` must be VK_NULL_HANDLE

- VUID-VkRenderingAttachmentInfo-imageView-06864
  If `imageView` is not VK_NULL_HANDLE, `resolveImageView` is not VK_NULL_HANDLE, and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `resolveImageView` must have a sample count of `VK_SAMPLE_COUNT_1_BIT`

- VUID-VkRenderingAttachmentInfo-imageView-06865
  If `imageView` is not VK_NULL_HANDLE, `resolveImageView` is not VK_NULL_HANDLE, and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `imageView` and `resolveImageView` must have the same VkFormat

- VUID-VkRenderingAttachmentInfo-imageView-06135
  If `imageView` is not VK_NULL_HANDLE, `imageLayout` must not be `VK_IMAGE_LAYOUT_UNDEFINED`, `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL`, `VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL`, `VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL`, or `VK_IMAGE_LAYOUT_PREINITIALIZED`

- VUID-VkRenderingAttachmentInfo-imageView-06136
  If `imageView` is not VK_NULL_HANDLE and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `resolveImageLayout` must not be `VK_IMAGE_LAYOUT_UNDEFINED`, `VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL`, `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL`, `VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL`, `VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL`, or `VK_IMAGE_LAYOUT_PREINITIALIZED`

- VUID-VkRenderingAttachmentInfo-imageView-06137
  If `imageView` is not VK_NULL_HANDLE and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `resolveImageLayout` must not be `VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL` or `VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL`

- VUID-VkRenderingAttachmentInfo-imageView-06138
  If `imageView` is not VK_NULL_HANDLE, `imageLayout` must not be `VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV`

- VUID-VkRenderingAttachmentInfo-imageView-06139
  If `imageView` is not VK_NULL_HANDLE and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `resolveImageLayout` must not be `VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV`

- VUID-VkRenderingAttachmentInfo-imageView-06140
  If `imageView` is not VK_NULL_HANDLE, `imageLayout` must not be `VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT`

- VUID-VkRenderingAttachmentInfo-imageView-06141
  If `imageView` is not VK_NULL_HANDLE and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `resolveImageLayout` must not be `VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT`

- VUID-VkRenderingAttachmentInfo-imageView-06142
  If `imageView` is not VK_NULL_HANDLE and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `resolveImageLayout` must not be `VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR`

- VUID-VkRenderingAttachmentInfo-imageView-06143
  If `imageView` is not VK_NULL_HANDLE, `imageLayout` must not be `VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR`

- VUID-VkRenderingAttachmentInfo-imageView-06144
  If `imageView` is not VK_NULL_HANDLE and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `resolveImageLayout` must not be `VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR`

- VUID-VkRenderingAttachmentInfo-imageView-06145
  If `imageView` is not VK_NULL_HANDLE, `imageLayout` must not be `VK_IMAGE_LAYOUT_PRESENT_SRC_KHR`

- VUID-VkRenderingAttachmentInfo-imageView-06146
  If `imageView` is not VK_NULL_HANDLE and `resolveMode` is not `VK_RESOLVE_MODE_NONE`, `resolveImageLayout` must not be `VK_IMAGE_LAYOUT_PRESENT_SRC_KHR`

- VUID-VkRenderingAttachmentInfo-externalFormatResolve-09323
  If `externalFormatResolve` is not enabled, `resolveMode` must not be `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`

- VUID-VkRenderingAttachmentInfo-resolveMode-09324
  If `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`, `resolveImageView` must be a valid image view

- VUID-VkRenderingAttachmentInfo-nullColorAttachmentWithExternalFormatResolve-09325
  If the `nullColorAttachmentWithExternalFormatResolve` property is `VK_TRUE` and `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`, `resolveImageView` must have been created with an image with a `samples` value of `VK_SAMPLE_COUNT_1_BIT`

- VUID-VkRenderingAttachmentInfo-resolveMode-09326
  If `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`, `resolveImageView` must have been created with an external format specified by VkExternalFormatANDROID

- VUID-VkRenderingAttachmentInfo-resolveMode-09327
  If `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`, `resolveImageView` must have been created with a `subresourceRange.layerCount` of `1`

- VUID-VkRenderingAttachmentInfo-resolveMode-09328
  If `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID` and `nullColorAttachmentWithExternalFormatResolve` is `VK_TRUE`, `imageView` must be VK_NULL_HANDLE

- VUID-VkRenderingAttachmentInfo-resolveMode-09329
  If `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID` and `nullColorAttachmentWithExternalFormatResolve` is `VK_FALSE`, `imageView` must be a valid VkImageView

- VUID-VkRenderingAttachmentInfo-resolveMode-09330
  If `resolveMode` is `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID` and `nullColorAttachmentWithExternalFormatResolve` is `VK_FALSE`, `imageView` must have a format equal to the value of VkAndroidHardwareBufferFormatResolvePropertiesANDROID::`colorAttachmentFormat` as returned by a call to vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer that was used to create `resolveImageView`

Valid Usage (Implicit)

- VUID-VkRenderingAttachmentInfo-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO`

- VUID-VkRenderingAttachmentInfo-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkRenderingAttachmentInfo-imageView-parameter
  If `imageView` is not VK_NULL_HANDLE, `imageView` must be a valid VkImageView handle

- VUID-VkRenderingAttachmentInfo-imageLayout-parameter
  `imageLayout` must be a valid VkImageLayout value

- VUID-VkRenderingAttachmentInfo-resolveMode-parameter
  If `resolveMode` is not `0`, `resolveMode` must be a valid VkResolveModeFlagBits value

- VUID-VkRenderingAttachmentInfo-resolveImageView-parameter
  If `resolveImageView` is not VK_NULL_HANDLE, `resolveImageView` must be a valid VkImageView handle

- VUID-VkRenderingAttachmentInfo-resolveImageLayout-parameter
  `resolveImageLayout` must be a valid VkImageLayout value

- VUID-VkRenderingAttachmentInfo-loadOp-parameter
  `loadOp` must be a valid VkAttachmentLoadOp value

- VUID-VkRenderingAttachmentInfo-storeOp-parameter
  `storeOp` must be a valid VkAttachmentStoreOp value

- VUID-VkRenderingAttachmentInfo-clearValue-parameter
  `clearValue` must be a valid VkClearValue union

- VUID-VkRenderingAttachmentInfo-commonparent
  Both of `imageView`, and `resolveImageView` that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

## See Also

VK_KHR_dynamic_rendering, VK_VERSION_1_3, VkAttachmentLoadOp, VkAttachmentStoreOp, VkClearValue, VkImageLayout, VkImageView, VkRenderingInfo, VkResolveModeFlagBits, VkStructureType

## 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-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0