Structure specifying an attachment description.

Description

If the attachment uses a color format, then loadOp and storeOp are used, and stencilLoadOp and stencilStoreOp are ignored. If the format has depth and/or stencil components, loadOp and storeOp apply only to the depth data, while stencilLoadOp and stencilStoreOp define how the stencil data is handled. loadOp and stencilLoadOp define the load operations for the attachment. storeOp and stencilStoreOp define the store operations for the attachment. If an attachment is not used by any subpass, loadOp, storeOp, stencilStoreOp, and stencilLoadOp will be ignored for that attachment, and no load or store ops will be performed. However, any transition specified by initialLayout and finalLayout will still be executed.

If flags includes ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then the attachment is treated as if it shares physical memory with another attachment in the same render pass. This information limits the ability of the implementation to reorder certain operations (like layout transitions and the loadOp) such that it is not improperly reordered against other uses of the same physical memory via a different attachment. This is described in more detail below.

If a render pass uses multiple attachments that alias the same device memory, those attachments must each include the ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment description flags. Attachments aliasing the same memory occurs in multiple ways:

• Multiple attachments being assigned the same image view as part of framebuffer creation.
• Attachments using distinct image views that correspond to the same image subresource of an image.
• Attachments using views of distinct image subresources which are bound to overlapping memory ranges.

Multiple attachments that alias the same memory must not be used in a single subpass. A given attachment index must not be used multiple times in a single subpass, with one exception: two subpass attachments can use the same attachment index if at least one use is as an input attachment and neither use is as a resolve or preserve attachment. In other words, the same view can be used simultaneously as an input and color or depth/stencil attachment, but must not be used as multiple color or depth/stencil attachments nor as resolve or preserve attachments.

If a set of attachments alias each other, then all except the first to be used in the render pass must use an initialLayout of IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases make their contents undefined. Once an alias has been used and a different alias has been used after it, the first alias must not be used in any later subpasses. However, an application can assign the same image view to multiple aliasing attachment indices, which allows that image view to be used multiple times even if other aliases are used in between.

Valid Usage

• format must not be FORMAT_UNDEFINED
• If format includes a color or depth component and loadOp is ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be IMAGE_LAYOUT_UNDEFINED
• finalLayout must not be IMAGE_LAYOUT_UNDEFINED or IMAGE_LAYOUT_PREINITIALIZED
• If format is a color format, initialLayout must not be IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
• If format is a depth/stencil format, initialLayout must not be IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
• If format is a color format, finalLayout must not be IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
• If format is a depth/stencil format, finalLayout must not be IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
• If format is a color format, initialLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
• If format is a color format, finalLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
• If the separateDepthStencilLayouts feature is not enabled, initialLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,
• If the separateDepthStencilLayouts feature is not enabled, finalLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,
• If format is a color format, initialLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
• If format is a color format, finalLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
• If format is a depth/stencil format which includes both depth and stencil components, initialLayout must not be IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
• If format is a depth/stencil format which includes both depth and stencil components, finalLayout must not be IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
• If format is a depth/stencil format which includes only the depth component, initialLayout must not be IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
• If format is a depth/stencil format which includes only the depth component, finalLayout must not be IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
• If the synchronization2 feature is not enabled, initialLayout must not be IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
• If the synchronization2 feature is not enabled, finalLayout must not be IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
• If the attachmentFeedbackLoopLayout feature is not enabled, initialLayout must not be IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT
• If the attachmentFeedbackLoopLayout feature is not enabled, finalLayout must not be IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT
• samples must be a bit value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for the given format
• If format includes a stencil component and stencilLoadOp is ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be IMAGE_LAYOUT_UNDEFINED
• If format is a depth/stencil format which includes only the stencil component, initialLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
• If format is a depth/stencil format which includes only the stencil component, finalLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
• If format is a depth/stencil format which includes both depth and stencil components, initialLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
• If format is a depth/stencil format which includes both depth and stencil components, finalLayout must not be IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

Valid Usage (Implicit)

• flags must be a valid combination of VkAttachmentDescriptionFlagBits values
• format must be a valid VkFormat value
• samples must be a valid VkSampleCountFlagBits value
• loadOp must be a valid VkAttachmentLoadOp value
• storeOp must be a valid VkAttachmentStoreOp value
• stencilLoadOp must be a valid VkAttachmentLoadOp value
• stencilStoreOp must be a valid VkAttachmentStoreOp value
• initialLayout must be a valid VkImageLayout value
• finalLayout must be a valid VkImageLayout value

See Also

VkRenderPassCreateInfo

Layout

struct VkAttachmentDescription {
    VkAttachmentDescriptionFlags flags;
    VkFormat format;
    VkSampleCountFlagBits samples;
    VkAttachmentLoadOp loadOp;
    VkAttachmentStoreOp storeOp;
    VkAttachmentLoadOp stencilLoadOp;
    VkAttachmentStoreOp stencilStoreOp;
    VkImageLayout initialLayout;
    VkImageLayout finalLayout;
}