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-attachment-06912
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06913
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06914
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06915
    If the attachment member of pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED, ts layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06916
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06917
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06918
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06919
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06920
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06921
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06922
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06923
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06251
    If the attachment member of pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED and its pNext chain includes a VkAttachmentDescriptionStencilLayout structure, the layout member of pDepthStencilAttachment must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • 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-multisampledRenderToSingleSampled-06869
    If none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are enabled, 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-pNext-06870
    If the pNext chain includes a VkMultisampledRenderToSingleSampledInfoEXT structure with multisampledRenderToSingleSampledEnable equal to VK_TRUE, then all attachments in pColorAttachments and pDepthStencilAttachment that are not VK_ATTACHMENT_UNUSED must have a sample count that is either VK_SAMPLE_COUNT_1_BIT or equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

  • VUID-VkSubpassDescription2-pNext-06871
    If the pNext chain includes a VkMultisampledRenderToSingleSampledInfoEXT structure with multisampledRenderToSingleSampledEnable equal to VK_TRUE, and pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a sample count of VK_SAMPLE_COUNT_1_BIT, the pNext chain must also include a VkSubpassDescriptionDepthStencilResolve structure with pDepthStencilResolveAttachment that is either NULL or has the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-multisampledRenderToSingleSampled-06872
    If none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are enabled, all attachments in pDepthStencilAttachment or pColorAttachments that are not VK_ATTACHMENT_UNUSED 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-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, VkMultisampledRenderToSingleSampledInfoEXT, 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-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0