VkSubpassDescription2(3)

# VkSubpassDescription2(3) Manual Page

## Name

VkSubpassDescription2 - Structure specifying a subpass description

Loading… please wait.

## C Specification

The `VkSubpassDescription2` structure is defined as:

    // Provided by VK_VERSION_1_2
    typedef struct VkSubpassDescription2 {
        VkStructureType                  sType;
        const void*                      pNext;
        VkSubpassDescriptionFlags        flags;
        VkPipelineBindPoint              pipelineBindPoint;
        uint32_t                         viewMask;
        uint32_t                         inputAttachmentCount;
        const VkAttachmentReference2*    pInputAttachments;
        uint32_t                         colorAttachmentCount;
        const VkAttachmentReference2*    pColorAttachments;
        const VkAttachmentReference2*    pResolveAttachments;
        const VkAttachmentReference2*    pDepthStencilAttachment;
        uint32_t                         preserveAttachmentCount;
        const uint32_t*                  pPreserveAttachments;
    } VkSubpassDescription2;

or the equivalent

    // Provided by VK_KHR_create_renderpass2
    typedef VkSubpassDescription2 VkSubpassDescription2KHR;

## Members

- `sType` is the type of this structure.

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

- `flags` is a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass.

- `pipelineBindPoint` is a VkPipelineBindPoint value specifying the pipeline type supported for this subpass.

- `viewMask` is a bitfield of view indices describing which views rendering is broadcast to in this subpass, when multiview is enabled.

- `inputAttachmentCount` is the number of input attachments.

- `pInputAttachments` is a pointer to an array of VkAttachmentReference2 structures defining the input attachments for this subpass and their layouts.

- `colorAttachmentCount` is the number of color attachments.

- `pColorAttachments` is a pointer to an array of `colorAttachmentCount` VkAttachmentReference2 structures defining the color attachments for this subpass and their layouts.

- `pResolveAttachments` is `NULL` or a pointer to an array of `colorAttachmentCount` VkAttachmentReference2 structures defining the resolve attachments for this subpass and their layouts.

- `pDepthStencilAttachment` is a pointer to a VkAttachmentReference2 structure specifying the depth/stencil attachment for this subpass and its layout.

- `preserveAttachmentCount` is the number of preserved attachments.

- `pPreserveAttachments` is a pointer to an array of `preserveAttachmentCount` render pass attachment indices identifying attachments that are not used by this subpass, but whose contents must be preserved throughout the subpass.

## Description

Parameters defined by this structure with the same name as those in VkSubpassDescription have the identical effect to those parameters.

`viewMask` has the same effect for the described subpass as VkRenderPassMultiviewCreateInfo::`pViewMasks` has on each corresponding subpass.

If a VkFragmentShadingRateAttachmentInfoKHR structure is included in the `pNext` chain, `pFragmentShadingRateAttachment` is not `NULL`, and its `attachment` member is not `VK_ATTACHMENT_UNUSED`, the identified attachment defines a fragment shading rate attachment for that subpass.

Valid Usage

- VUID-VkSubpassDescription2-pipelineBindPoint-04953
  `pipelineBindPoint` must be `VK_PIPELINE_BIND_POINT_GRAPHICS` or `VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI`

- VUID-VkSubpassDescription2-colorAttachmentCount-03063
  `colorAttachmentCount` must be less than or equal to `VkPhysicalDeviceLimits`::`maxColorAttachments`

- VUID-VkSubpassDescription2-loadOp-03064
  If the first use of an attachment in this render pass is as an input attachment, and the attachment is not also used as a color or depth/stencil attachment in the same subpass, then `loadOp` must not be `VK_ATTACHMENT_LOAD_OP_CLEAR`

- VUID-VkSubpassDescription2-pResolveAttachments-03065
  If `pResolveAttachments` is not `NULL`, for each resolve attachment that does not have the value `VK_ATTACHMENT_UNUSED`, the corresponding color attachment must not have the value `VK_ATTACHMENT_UNUSED`

- VUID-VkSubpassDescription2-pResolveAttachments-03066
  If `pResolveAttachments` is not `NULL`, for each resolve attachment that is not `VK_ATTACHMENT_UNUSED`, the corresponding color attachment must not have a sample count of `VK_SAMPLE_COUNT_1_BIT`

- VUID-VkSubpassDescription2-pResolveAttachments-03067
  If `pResolveAttachments` is not `NULL`, each resolve attachment that is not `VK_ATTACHMENT_UNUSED` must have a sample count of `VK_SAMPLE_COUNT_1_BIT`

- VUID-VkSubpassDescription2-pResolveAttachments-03068
  Any given element of `pResolveAttachments` must have the same VkFormat as its corresponding color attachment

- VUID-VkSubpassDescription2-pColorAttachments-03069
  All attachments in `pColorAttachments` that are not `VK_ATTACHMENT_UNUSED` must have the same sample count

- VUID-VkSubpassDescription2-pInputAttachments-02897
  All attachments in `pInputAttachments` that are not `VK_ATTACHMENT_UNUSED` must have image formats whose potential format features contain at least `VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT` or `VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT`

- VUID-VkSubpassDescription2-pColorAttachments-02898
  All attachments in `pColorAttachments` that are not `VK_ATTACHMENT_UNUSED` must have image formats whose potential format features contain `VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT`

- VUID-VkSubpassDescription2-pResolveAttachments-02899
  All attachments in `pResolveAttachments` that are not `VK_ATTACHMENT_UNUSED` must have image formats whose potential format features contain `VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT`

- VUID-VkSubpassDescription2-pDepthStencilAttachment-02900
  If `pDepthStencilAttachment` is not `NULL` and the attachment is not `VK_ATTACHMENT_UNUSED` then it must have an image format whose potential format features contain `VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT`

- VUID-VkSubpassDescription2-linearColorAttachment-06499
  If the `linearColorAttachment` feature is enabled and the image is created with `VK_IMAGE_TILING_LINEAR`, all attachments in `pInputAttachments` that are not `VK_ATTACHMENT_UNUSED` must have image formats whose potential format features must contain `VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV`

- VUID-VkSubpassDescription2-linearColorAttachment-06500
  If the `linearColorAttachment` feature is enabled and the image is created with `VK_IMAGE_TILING_LINEAR`, all attachments in `pColorAttachments` that are not `VK_ATTACHMENT_UNUSED` must have image formats whose potential format features must contain `VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV`

- VUID-VkSubpassDescription2-linearColorAttachment-06501
  If the `linearColorAttachment` feature is enabled and the image is created with `VK_IMAGE_TILING_LINEAR`, all attachments in `pResolveAttachments` that are not `VK_ATTACHMENT_UNUSED` must have image formats whose potential format features must contain `VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV`

- VUID-VkSubpassDescription2-pColorAttachments-03070
  If the `VK_AMD_mixed_attachment_samples` extension is enabled, all attachments in `pColorAttachments` that are not `VK_ATTACHMENT_UNUSED` must have a sample count that is smaller than or equal to the sample count of `pDepthStencilAttachment` if it is not `VK_ATTACHMENT_UNUSED`

- VUID-VkSubpassDescription2-pDepthStencilAttachment-03071
  If neither the `VK_AMD_mixed_attachment_samples` nor the `VK_NV_framebuffer_mixed_samples` extensions are enabled, and if `pDepthStencilAttachment` is not `VK_ATTACHMENT_UNUSED` and any attachments in `pColorAttachments` are not `VK_ATTACHMENT_UNUSED`, they must have the same sample count

- VUID-VkSubpassDescription2-attachment-03073
  Each element of `pPreserveAttachments` must not be `VK_ATTACHMENT_UNUSED`

- VUID-VkSubpassDescription2-pPreserveAttachments-03074
  Any given element of `pPreserveAttachments` must not also be an element of any other member of the subpass description

- VUID-VkSubpassDescription2-layout-02528
  If any attachment is used by more than one VkAttachmentReference2 member, then each use must use the same `layout`

- VUID-VkSubpassDescription2-None-04439
  Attachments must follow the image layout requirements based on the type of attachment it is being used as

- VUID-VkSubpassDescription2-flags-03076
  If `flags` includes `VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX`, it must also include `VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX`

- VUID-VkSubpassDescription2-attachment-02799
  If the `attachment` member of any element of `pInputAttachments` is not `VK_ATTACHMENT_UNUSED`, then the `aspectMask` member must be a valid combination of VkImageAspectFlagBits

- VUID-VkSubpassDescription2-attachment-02800
  If the `attachment` member of any element of `pInputAttachments` is not `VK_ATTACHMENT_UNUSED`, then the `aspectMask` member must not be `0`

- VUID-VkSubpassDescription2-attachment-02801
  If the `attachment` member of any element of `pInputAttachments` is not `VK_ATTACHMENT_UNUSED`, then the `aspectMask` member must not include `VK_IMAGE_ASPECT_METADATA_BIT`

- VUID-VkSubpassDescription2-attachment-04563
  If the `attachment` member of any element of `pInputAttachments` is not `VK_ATTACHMENT_UNUSED`, then the `aspectMask` member must not include `VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT` for any index i

- VUID-VkSubpassDescription2-pDepthStencilAttachment-04440
  An attachment must not be used in both `pDepthStencilAttachment` and `pColorAttachments`

- VUID-VkSubpassDescription2-multiview-06558
  If the `multiview` feature is not enabled, `viewMask` must be `0`

- VUID-VkSubpassDescription2-viewMask-06706
  The index of the most significant bit in `viewMask` must be less than `maxMultiviewViewCount`

Valid Usage (Implicit)

- VUID-VkSubpassDescription2-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2`

- VUID-VkSubpassDescription2-pNext-pNext
  Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkFragmentShadingRateAttachmentInfoKHR, VkRenderPassCreationControlEXT, VkRenderPassSubpassFeedbackCreateInfoEXT, or VkSubpassDescriptionDepthStencilResolve

- VUID-VkSubpassDescription2-sType-unique
  The `sType` value of each struct in the `pNext` chain must be unique

- VUID-VkSubpassDescription2-flags-parameter
  `flags` must be a valid combination of VkSubpassDescriptionFlagBits values

- VUID-VkSubpassDescription2-pipelineBindPoint-parameter
  `pipelineBindPoint` must be a valid VkPipelineBindPoint value

- VUID-VkSubpassDescription2-pInputAttachments-parameter
  If `inputAttachmentCount` is not `0`, `pInputAttachments` must be a valid pointer to an array of `inputAttachmentCount` valid VkAttachmentReference2 structures

- VUID-VkSubpassDescription2-pColorAttachments-parameter
  If `colorAttachmentCount` is not `0`, `pColorAttachments` must be a valid pointer to an array of `colorAttachmentCount` valid VkAttachmentReference2 structures

- VUID-VkSubpassDescription2-pResolveAttachments-parameter
  If `colorAttachmentCount` is not `0`, and `pResolveAttachments` is not `NULL`, `pResolveAttachments` must be a valid pointer to an array of `colorAttachmentCount` valid VkAttachmentReference2 structures

- VUID-VkSubpassDescription2-pDepthStencilAttachment-parameter
  If `pDepthStencilAttachment` is not `NULL`, `pDepthStencilAttachment` must be a valid pointer to a valid VkAttachmentReference2 structure

- VUID-VkSubpassDescription2-pPreserveAttachments-parameter
  If `preserveAttachmentCount` is not `0`, `pPreserveAttachments` must be a valid pointer to an array of `preserveAttachmentCount` `uint32_t` values

## See Also

VK_KHR_create_renderpass2, VK_VERSION_1_2, VkAttachmentReference2, VkPipelineBindPoint, VkRenderPassCreateInfo2, VkStructureType, VkSubpassDescriptionFlags

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

SPDX-License-Identifier: CC-BY-4.0