VKSUBPASSDESCRIPTION(3)

NAME
VkSubpassDescription - Structure specifying a subpass description

C SPECIFICATION

The VkSubpassDescription structure is defined as:

    typedef struct VkSubpassDescription {
        VkSubpassDescriptionFlags       flags;
        VkPipelineBindPoint             pipelineBindPoint;
        uint32_t                        inputAttachmentCount;
        const VkAttachmentReference*    pInputAttachments;
        uint32_t                        colorAttachmentCount;
        const VkAttachmentReference*    pColorAttachments;
        const VkAttachmentReference*    pResolveAttachments;
        const VkAttachmentReference*    pDepthStencilAttachment;
        uint32_t                        preserveAttachmentCount;
        const uint32_t*                 pPreserveAttachments;
    } VkSubpassDescription;

MEMBERS

    • flags is reserved for future use.

    • pipelineBindPoint is a VkPipelineBindPoint value specifying whether this is a compute or graphics subpass. Currently, only graphics subpasses are supported.

    • inputAttachmentCount is the number of input attachments.

    • pInputAttachments is an array of VkAttachmentReference structures (defined below) that lists which of the render pass’s attachments can be read in the shader during the subpass, and what layout each attachment will be in during the subpass. Each element of the array corresponds to an input attachment unit number in the shader, i.e. if the shader declares an input variable layout(input_attachment_index=X, set=Y, binding=Z) then it uses the attachment provided in pInputAttachments[X]. Input attachments must also be bound to the pipeline with a descriptor set, with the input attachment descriptor written in the location (set=Y, binding=Z).

    • colorAttachmentCount is the number of color attachments.

    • pColorAttachments is an array of colorAttachmentCount VkAttachmentReference structures that lists which of the render pass’s attachments will be used as color attachments in the subpass, and what layout each attachment will be in during the subpass. Each element of the array corresponds to a fragment shader output location, i.e. if the shader declared an output variable layout(location=X) then it uses the attachment provided in pColorAttachments[X].

    • pResolveAttachments is NULL or an array of colorAttachmentCount VkAttachmentReference structures that lists which of the render pass’s attachments are resolved to at the end of the subpass, and what layout each attachment will be in during the resolve. If pResolveAttachments is not NULL, each of its elements corresponds to a color attachment (the element in pColorAttachments at the same index). At the end of each subpass, the subpass’s color attachments are resolved to corresponding resolve attachments, unless the resolve attachment index is VK_ATTACHMENT_UNUSED or pResolveAttachments is NULL. If the first use of an attachment in a render pass is as a resolve attachment, then the loadOp is effectively ignored as the resolve is guaranteed to overwrite all pixels in the render area.

    • pDepthStencilAttachment is a pointer to a VkAttachmentReference specifying which attachment will be used for depth/stencil data and the layout it will be in during the subpass. Setting the attachment index to VK_ATTACHMENT_UNUSED or leaving this pointer as NULL indicates that no depth/stencil attachment will be used in the subpass.

    • preserveAttachmentCount is the number of preserved attachments.

    • pPreserveAttachments is an array of preserveAttachmentCount render pass attachment indices describing the attachments that are not used by a subpass, but whose contents must be preserved throughout the subpass.

DESCRIPTION

The contents of an attachment within the render area become undefined at the start of a subpass S if all of the following conditions are true:

    • The attachment is used as a color, depth/stencil, or resolve attachment in any subpass in the render pass.

    • There is a subpass S1 that uses or preserves the attachment, and a subpass dependency from S1 to S.

    • The attachment is not used or preserved in subpass S.

Once the contents of an attachment become undefined in subpass S, they remain undefined for subpasses in subpass dependency chains starting with subpass S until they are written again. However, they remain valid for subpasses in other subpass dependency chains starting with subpass S1 if those subpasses use or preserve the attachment. Valid Usage

    • pipelineBindPoint must be VK_PIPELINE_BIND_POINT_GRAPHICS

    • colorAttachmentCount must be less than or equal to VkPhysicalDeviceLimits::maxColorAttachments

    • 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

    • 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

    • If pResolveAttachments is not NULL, the sample count of each element of pColorAttachments must be anything other than VK_SAMPLE_COUNT_1_BIT

    • Any given element of pResolveAttachments must have a sample count of VK_SAMPLE_COUNT_1_BIT

    • Any given element of pResolveAttachments must have the same VkFormat as its corresponding color attachment

    • All attachments in pColorAttachments and pDepthStencilAttachment that are not VK_ATTACHMENT_UNUSED must have the same sample count

    • If any input attachments are VK_ATTACHMENT_UNUSED, then any pipelines bound during the subpass must not access those input attachments from the fragment shader

    • The attachment member of any element of pPreserveAttachments must not be VK_ATTACHMENT_UNUSED

    • Any given element of pPreserveAttachments must not also be an element of any other member of the subpass description

    • If any attachment is used as both an input attachment and a color or depth/stencil attachment, then each use must use the same layout
Valid Usage (Implicit)

    • flags must be 0

    • pipelineBindPoint must be a valid VkPipelineBindPoint value

    • If inputAttachmentCount is not 0, pInputAttachments must be a pointer to an array of inputAttachmentCount valid VkAttachmentReference structures

    • If colorAttachmentCount is not 0, pColorAttachments must be a pointer to an array of colorAttachmentCount valid VkAttachmentReference structures

    • If colorAttachmentCount is not 0, and pResolveAttachments is not NULL, pResolveAttachments must be a pointer to an array of colorAttachmentCount valid VkAttachmentReference structures

    • If pDepthStencilAttachment is not NULL, pDepthStencilAttachment must be a pointer to a valid VkAttachmentReference structure

    • If preserveAttachmentCount is not 0, pPreserveAttachments must be a pointer to an array of preserveAttachmentCount uint32_t values

SEE ALSO

VkAttachmentReference, VkPipelineBindPoint, VkRenderPassCreateInfo, VkSubpassDescriptionFlags

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkSubpassDescription

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.