VKATTACHMENTDESCRIPT(3)

NAME
VkAttachmentDescription - Structure specifying an attachment description

C SPECIFICATION

The VkAttachmentDescription structure is defined as:

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

MEMBERS

    • flags is a bitmask describing additional properties of the attachment. Bits which can be set include:

        typedef enum VkAttachmentDescriptionFlagBits {
            VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT = 0x00000001,
        } VkAttachmentDescriptionFlagBits;

    • format is a VkFormat value specifying the format of the image that will be used for the attachment.

    • samples is the number of samples of the image as defined in VkSampleCountFlagBits.

    • loadOp specifies how the contents of color and depth components of the attachment are treated at the beginning of the subpass where it is first used:

        typedef enum VkAttachmentLoadOp {
            VK_ATTACHMENT_LOAD_OP_LOAD = 0,
            VK_ATTACHMENT_LOAD_OP_CLEAR = 1,
            VK_ATTACHMENT_LOAD_OP_DONT_CARE = 2,
        } VkAttachmentLoadOp;

        • VK_ATTACHMENT_LOAD_OP_LOAD means the contents within the render area will be preserved.

        • VK_ATTACHMENT_LOAD_OP_CLEAR means the contents within the render area will be cleared to a uniform value, which is specified when a render pass instance is begun.

        • VK_ATTACHMENT_LOAD_OP_DONT_CARE means the contents within the area need not be preserved; the contents of the attachment will be undefined inside the render area.

    • storeOp specifies how the contents of color and depth components of the attachment are treated at the end of the subpass where it is last used:

        typedef enum VkAttachmentStoreOp {
            VK_ATTACHMENT_STORE_OP_STORE = 0,
            VK_ATTACHMENT_STORE_OP_DONT_CARE = 1,
        } VkAttachmentStoreOp;

        • VK_ATTACHMENT_STORE_OP_STORE means the contents within the render area are written to memory and will be available for reading after the render pass instance completes once the writes have been synchronized with VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT (for color attachments) or VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT (for depth/stencil attachments).

        • VK_ATTACHMENT_STORE_OP_DONT_CARE means the contents within the render area are not needed after rendering, and may be discarded; the contents of the attachment will be undefined inside the render area.

    • stencilLoadOp specifies how the contents of stencil components of the attachment are treated at the beginning of the subpass where it is first used, and must be one of the same values allowed for loadOp above.

    • stencilStoreOp specifies how the contents of stencil components of the attachment are treated at the end of the last subpass where it is used, and must be one of the same values allowed for storeOp above.

    • initialLayout is the layout the attachment image subresource will be in when a render pass instance begins.

    • finalLayout is the layout the attachment image subresource will be transitioned to when a render pass instance ends. During a render pass instance, an attachment can use a different layout in each subpass, if desired.

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.

During a render pass instance, input/color attachments with color formats that have a component size of 8, 16, or 32 bits must be represented in the attachment’s format throughout the instance. Attachments with other floating- or fixed-point color formats, or with depth components may be represented in a format with a precision higher than the attachment format, but must be represented with the same range. When such a component is loaded via the loadOp, it will be converted into an implementation-dependent format used by the render pass. Such components must be converted from the render pass format, to the format of the attachment, before they are stored or resolved at the end of a render pass instance via storeOp. Conversions occur as described in Numeric Representation and Computation and Fixed-Point Data Conversions.

If flags includes VK_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.

VALID USAGE

    • 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

    • finalLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

SEE ALSO

VkAttachmentDescriptionFlags, VkAttachmentLoadOp, VkAttachmentStoreOp, VkFormat, VkImageLayout, VkRenderPassCreateInfo, VkSampleCountFlagBits

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

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

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.