Vulkan规范：第七章 7.1

7.1. 创建Render Pass

可调用如下函数来创建render pass：

VkResult vkCreateRenderPass(
    VkDevice                                    device,
    const VkRenderPassCreateInfo*               pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkRenderPass*                               pRenderPass);

• device 是创建render pass的逻辑设备。

• pCreateInfo 是一个指向 VkRenderPassCreateInfo实例的指针，描述了render pass的参数。

• pAllocator 控制了主机端内存如何分配，如Memory Allocation一章所述。

• pRenderPass 指向了VkRenderPass handle，是被返回的生成的render pass。

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pCreateInfo must be a pointer to a valid VkRenderPassCreateInfo structure

• If pAllocator is not NULL, pAllocator must be a pointer to a valid VkAllocationCallbacks structure

• pRenderPass must be a pointer to a VkRenderPass handle

Return Codes

Success

• VK_SUCCESS

Failure

• VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

VkRenderPassCreateInfo 数据类型定义如下：

typedef struct VkRenderPassCreateInfo {
    VkStructureType                   sType;
    const void*                       pNext;
    VkRenderPassCreateFlags           flags;
    uint32_t                          attachmentCount;
    const VkAttachmentDescription*    pAttachments;
    uint32_t                          subpassCount;
    const VkSubpassDescription*       pSubpasses;
    uint32_t                          dependencyCount;
    const VkSubpassDependency*        pDependencies;
} VkRenderPassCreateInfo;

• sType 是数据结构的类型。

• pNext 是 NULL 或者一个指向拓展特定的数据结构的指针。

• flags 被保留。

• attachmentCount 是render pass使用的附件的个数，或者为0，表示无附件。附件可以从0开始索引，如 [0,attachmentCount)。

• pAttachments 指向了一个 大小为attachmentCount，元素类型为VkAttachmentDescription 的数组，描述了附件的属性，或当attachmentCount 为0时值为`NULL`。

• subpassCount 是将要为render pass创建的subpass数量。subpass可以从0开始索引，如 [0,subpassCount)。一个render pass必须拥有一个subpass。

• pSubpasses 指向了一个大小为subpassCount，元素类型为VkSubpassDescription 的数组，描述了subpass的属性。

• dependencyCount 是不同对subpass之间依赖的个数，或者为0表示没有依赖。

• pDependencies 指向了一个大小为dependencyCount ，元素类型为 VkSubpassDependency 的数组，描述了不同对subpass之间的依赖关系， 或者当dependencyCount值为0时为 NULL 。

正确使用

• If any two subpasses operate on attachments with overlapping ranges of the same VkDeviceMemory object, and at least one subpass writes to that area of VkDeviceMemory, a subpass dependency must be included (either directly or via some intermediate subpasses) between them

• If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or the attachment indexed by any element of pPreserveAttachments in any given element of pSubpasses is bound to a range of a VkDeviceMemory object that overlaps with any other attachment in any subpass (including the same subpass), the VkAttachmentDescription structures describing them must includeVK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in flags

• If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or any element of pPreserveAttachments in any given element of pSubpasses is not VK_ATTACHMENT_UNUSED, it must be less than attachmentCount

• The value of any element of the pPreserveAttachments member in any given element of pSubpasses must not beVK_ATTACHMENT_UNUSED

• For any member of pAttachments with a loadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL orVK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL.

• For any element of pDependencies, if the srcSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in thesrcStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the source subpass.

• For any element of pDependencies, if the dstSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in thedstStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the source subpass.

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO

• pNext must be NULL

• flags must be 0

• If attachmentCount is not 0, pAttachments must be a pointer to an array of attachmentCount valid VkAttachmentDescription structures

• pSubpasses must be a pointer to an array of subpassCount valid VkSubpassDescription structures

• If dependencyCount is not 0, pDependencies must be a pointer to an array of dependencyCount valid VkSubpassDependency structures

• subpassCount must be greater than 0

VkAttachmentDescription数据结构定义如下:

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

• 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 previous contents of the image within the render area will be preserved. For attachments with a depth/stencil format, this uses the access typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT. For attachments with a color format, this uses the access typeVK_ACCESS_COLOR_ATTACHMENT_READ_BIT.

  • 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. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • VK_ATTACHMENT_LOAD_OP_DONT_CARE means the previous contents within the area need not be preserved; the contents of the attachment will be undefined inside the render area. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

• 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 generated during the render pass and within the render area are written to memory. For attachments with a depth/stencil format, this uses the access typeVK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access typeVK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • 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. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

• 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.

如果附件使用了颜色格式，那么loadOp 和 storeOp就被使用了，stencilLoadOp 和 stencilStoreOp被忽略。 如果该格式有深度和/或模板数据，那么loadOp 和storeOp仅用于深度数据，stencilLoadOp 和stencilStoreOp 定义了模板数据如何被处理。 loadOp 和 stencilLoadOp 定义了 load operations ，它作为第一个使用该附件的subpass的一部分被执行。storeOp 和 stencilStoreOp 定义了 store operations，它作为最后一个使用该附件的subpass的一部分被执行。

被subpass使用的附件内每一个值的加载操作，在被记录到subpass的命令读取这个值之前发生。 对于带有深度/模板格式的附件的加载操作发生在VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline阶段。 对于带有颜色格式的附件的加载操作在VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT管线阶段执行。

对于被subpass使用的附件内每一个值的存储操作发生在被记录到subpass的命令向该值写入之后。 对于带有深度/模板格式的附件的存储操作，发生在VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT管线阶段。 对于带有颜色格式的附件的存储操作在VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 管线阶段执行。

如果一个附件没有被subpass使用，那么loadOp, storeOp, stencilStoreOp, and stencilLoadOp 都被忽略，附件的内存内容将不会被render pass的执行所修改。

在一个render pass实例期间内，带有颜色格式（每一个成员大小为8，16或32位）的输入/颜色附件，贯穿于整个实例必须以附件的格式表示。 带有其他浮点或定点颜色格式，或深度成分的附件可能通过比附件格式精度更高的格式所表示，但是必须表示相同的范围。 当这样的component通过loadOp被载入时，它将被转换为被render pass使用的依赖于Vulkan实现的格式。

Such components must be converted from the render pass format, to the format of the attachment, before they are resolved or stored 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.

正确使用

• finalLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

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

editing-note TODO (Jon) - the following text may need to be moved back to combine with vkCreateRenderPass above for automatic ref page generation.

If a render pass uses multiple attachments that alias the same device memory, those attachments must each include theVK_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.

注意 Render passes必须包含任意操作在同一个subpass依赖链的两个subpass之间的subpass依赖（），若这些subpass中至少有一个向这些别名中的一个写入， 这个依赖关系必须包含执行和内存依赖来分离这些别名的使用。 若这些别名是不同图像子资源的不同视图并在内存中有重叠，这些依赖不能包含VK_DEPENDENCY_BY_REGION_BIT。

Multiple attachments that alias the same memory must not be used in a single subpass. A given attachment index mustnot 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. The precise set of valid scenarios is described in more detail below.

If a set of attachments alias each other, then all except the first to be used in the render pass must use an initialLayoutof VK_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.

注意 Once an attachment needs the VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit, there should be no additional cost of introducing additional aliases, and using these additional aliases may allow more efficient clearing of the attachments on multiple uses via VK_ATTACHMENT_LOAD_OP_CLEAR.

VkSubpassDescription 类型数据结构定义如下：

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;

• flags 被保留。

• 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 multisample resolve operation. If pResolveAttachments is not NULL, each of its elements corresponds to a color attachment (the element in pColorAttachments at the same index), and a multisample resolve operation is defined for each attachment. At the end of each subpass, multisample resolve operations read the subpass’s color attachments, and resolve the samples for each pixel to the same pixel location in the corresponding resolve attachments, unless the resolve attachment index is VK_ATTACHMENT_UNUSED. 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.

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.

正确使用

• 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 musthave 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 inputAttachmentCountvalid VkAttachmentReference structures

• If colorAttachmentCount is not 0, pColorAttachments must be a pointer to an array of colorAttachmentCountvalid 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

VkAttachmentReference 类型数据结构定义如下：

typedef struct VkAttachmentReference {
    uint32_t         attachment;
    VkImageLayout    layout;
} VkAttachmentReference;

• attachment is the index of the attachment of the render pass, and corresponds to the index of the corresponding element in the pAttachments array of the VkRenderPassCreateInfo structure. If any color or depth/stencil attachments are VK_ATTACHMENT_UNUSED, then no writes occur for those attachments.

• layout is a VkImageLayout value specifying the layout the attachment uses during the subpass.

正确使用

• layout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

Valid Usage (Implicit)

• layout must be a valid VkImageLayout value

VkSubpassDependency 类型数据结构定义如下：

typedef struct VkSubpassDependency {
    uint32_t                srcSubpass;
    uint32_t                dstSubpass;
    VkPipelineStageFlags    srcStageMask;
    VkPipelineStageFlags    dstStageMask;
    VkAccessFlags           srcAccessMask;
    VkAccessFlags           dstAccessMask;
    VkDependencyFlags       dependencyFlags;
} VkSubpassDependency;

• srcSubpass is the subpass index of the first subpass in the dependency, or VK_SUBPASS_EXTERNAL.

• dstSubpass is the subpass index of the second subpass in the dependency, or VK_SUBPASS_EXTERNAL.

• srcStageMask defines a source stage mask.

• dstStageMask defines a destination stage mask.

• srcAccessMask defines a source access mask.

• dstAccessMask defines a destination access mask.

• dependencyFlags is a bitmask of VkDependencyFlagBits.

If srcSubpass is equal to dstSubpass then the VkSubpassDependency describes a subpass self-dependency, and only constrains the pipeline barriers allowed within a subpass instance. Otherwise, when a render pass instance which includes a subpass dependency is submitted to a queue, it defines a memory dependency between the subpasses identified by srcSubpass and dstSubpass.

If srcSubpass is equal to VK_SUBPASS_EXTERNAL, the first synchronization scope includes commands submitted to the queue before the render pass instance began. Otherwise, the first set of commands includes all commands submitted as part of the subpass instance identified by srcSubpass and any load, store or multisample resolve operations on attachments used in srcSubpass. In either case, the first synchronization scope is limited to operations on the pipeline stages determined by the source stage mask specified by srcStageMask.

If dstSubpass is equal to VK_SUBPASS_EXTERNAL, the second synchronization scope includes commands submitted after the render pass instance is ended. Otherwise, the second set of commands includes all commands submitted as part of the subpass instance identified by dstSubpass and any load, store or multisample resolve operations on attachments used indstSubpass. In either case, the second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to access in the pipeline stages determined by the source stage mask specified bysrcStageMask. It is also limited to access types in the source access mask specified by srcAccessMask.

The second access scope is limited to access in the pipeline stages determined by the destination stage mask specified by dstStageMask. It is also limited to access types in the destination access mask specified by dstAccessMask.

The availability and visibility operations defined by a subpass dependency affect the execution of image layout transitionswithin the render pass.

正确使用

• If srcSubpass is not VK_SUBPASS_EXTERNAL, srcStageMask must not include VK_PIPELINE_STAGE_HOST_BIT

• If dstSubpass is not VK_SUBPASS_EXTERNAL, dstStageMask must not include VK_PIPELINE_STAGE_HOST_BIT

• If the geometry shaders feature is not enabled, srcStageMask must not containVK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

• If the geometry shaders feature is not enabled, dstStageMask must not containVK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

• If the tessellation shaders feature is not enabled, srcStageMask must not containVK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT orVK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

• If the tessellation shaders feature is not enabled, dstStageMask must not containVK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT orVK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

• srcSubpass must be less than or equal to dstSubpass, unless one of them is VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies and ensure a valid execution order

• srcSubpass and dstSubpass must not both be equal to VK_SUBPASS_EXTERNAL

• If srcSubpass is equal to dstSubpass, srcStageMask and dstStageMask must only contain one ofVK_PIPELINE_STAGE_TOP_OF_PIPE_BIT, VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT,VK_PIPELINE_STAGE_VERTEX_INPUT_BIT, VK_PIPELINE_STAGE_VERTEX_SHADER_BIT,VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT,VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT,VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT,VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT, VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT,VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, or VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT

• If srcSubpass is equal to dstSubpass, the logically latest pipeline stage in srcStageMask must be logically earlierthan or equal to the logically earliest pipeline stage in dstStageMask

• Any access flag included in srcAccessMask must be supported by one of the pipeline stages in srcStageMask, as specified in the table of supported access types.

• Any access flag included in dstAccessMask must be supported by one of the pipeline stages in dstStageMask, as specified in the table of supported access types.

Valid Usage (Implicit)

• srcStageMask must be a valid combination of VkPipelineStageFlagBits values

• srcStageMask must not be 0

• dstStageMask must be a valid combination of VkPipelineStageFlagBits values

• dstStageMask must not be 0

• srcAccessMask must be a valid combination of VkAccessFlagBits values

• dstAccessMask must be a valid combination of VkAccessFlagBits values

• dependencyFlags must be a valid combination of VkDependencyFlagBits values

editing-note The following two alleged implicit dependencies are practically no-ops, as the operations they describe are already guaranteed by semaphores and submission order (so they’re almost entirely no-ops on their own). The only reason they exist is because it simplifies reasoning about where automatic layout transitionshappen. Further rewrites of this chapter could potentially remove the need for these.

If there is no subpass dependency from VK_SUBPASS_EXTERNAL to the first subpass that uses an attachment, then an implicit subpass dependency exists from VK_SUBPASS_EXTERNAL to the first subpass it is used in. The subpass dependency operates as if defined with the following parameters:

VkSubpassDependency implicitDependency = {
    .srcSubpass = VK_SUBPASS_EXTERNAL;
    .dstSubpass = firstSubpass; // First subpass attachment is used in
    .srcStageMask = VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT;
    .dstStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT;
    .srcAccessMask = 0;
    .dstAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT |
                     VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
                     VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT |
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT;
    .dependencyFlags = 0;
};

Similarly, if there is no subpass dependency from the last subpass that uses an attachment to VK_SUBPASS_EXTERNAL, then an implicit subpass dependency exists from the last subpass it is used in to VK_SUBPASS_EXTERNAL. The subpass dependency operates as if defined with the following parameters:

VkSubpassDependency implicitDependency = {
    .srcSubpass = lastSubpass; // Last subpass attachment is used in
    .dstSubpass = VK_SUBPASS_EXTERNAL;
    .srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT;
    .dstStageMask = VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT;
    .srcAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT |
                     VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
                     VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT |
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT;
    .dstAccessMask = 0;
    .dependencyFlags = 0;
};

As subpasses may overlap or execute out of order with regards to other subpasses unless a subpass dependency chain describes otherwise, the layout transitions required between subpasses cannot be known to an application. Instead, an application provides the layout that each attachment must be in at the start and end of a renderpass, and the layout it must be in during each subpass it is used in. The implementation then must execute layout transitions between subpasses in order to guarantee that the images are in the layouts required by each subpass, and in the final layout at the end of the render pass.

Automatic layout transitions away from the layout used in a subpass happen-after the availability operations for all dependencies with that subpass as the srcSubpass.

Automatic layout transitions into the layout used in a subpass happen-before the visibility operations for all dependencies with that subpass as the dstSubpass.

Automatic layout transitions away from initialLayout happens-after the availability operations for all dependencies with a srcSubpass equal to VK_SUBPASS_EXTERNAL, where dstSubpass uses the attachment that will be transitioned. For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, automatic layout transitions away from initialLayout happen-after the availability operations for all dependencies with a srcSubpass equal to VK_SUBPASS_EXTERNAL, where dstSubpass uses any aliased attachment.

Automatic layout transitions into finalLayout happens-before the visibility operations for all dependencies with a dstSubpass equal to VK_SUBPASS_EXTERNAL, where srcSubpass uses the attachment that will be transitioned. For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, automatic layout transitions into finalLayout happen-before the visibility operations for all dependencies with a dstSubpass equal toVK_SUBPASS_EXTERNAL, where srcSubpass uses any aliased attachment.

If two subpasses use the same attachment in different layouts, and both layouts are read-only, no subpass dependency needs to be specified between those subpasses. If an implementation treats those layouts separately, it must insert an implicit subpass dependency between those subpasses to separate the uses in each layout. The subpass dependency operates as if defined with the following parameters:

// Used for input attachments
VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
VkAccessFlags inputAttachmentAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT;

// Used for depth/stencil attachments
VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT;
VkAccessFlags depthStencilAttachmentAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT;

VkSubpassDependency implicitDependency = {
    .srcSubpass = firstSubpass;
    .dstSubpass = secondSubpass;
    .srcStageMask = inputAttachmentStages | depthStencilAttachmentStages;
    .dstStageMask = inputAttachmentStages | depthStencilAttachmentStages;
    .srcAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess;
    .dstAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess;
    .dependencyFlags = 0;
};

If a subpass uses the same attachment as both an input attachment and either a color attachment or a depth/stencil attachment, writes via the color or depth/stencil attachment are not automatically made visible to reads via the input attachment, causing a feedback loop, except in any of the following conditions:

• If the color components or depth/stencil components read by the input attachment are mutually exclusive with the components written by the color or depth/stencil attachments, then there is no feedback loop. This requires the graphics pipelines used by the subpass to disable writes to color components that are read as inputs via thecolorWriteMask, and to disable writes to depth/stencil components that are read as inputs via depthWriteEnable orstencilTestEnable.

• If the attachment is used as an input attachment and depth/stencil attachment only, and the depth/stencil attachment is not written to.

• If a memory dependency is inserted between when the attachment is written and when it is subsequently read by later fragments. Pipeline barriers expressing a subpass self-dependency are the only way to achieve this, and one must be inserted every time a fragment will read values at a particular sample (x, y, layer, sample) coordinate, if those values have been written since the most recent pipeline barrier; or the since start of the subpass if there have been no pipeline barriers since the start of the subpass.

An attachment used as both an input attachment and a color attachment must be in the VK_IMAGE_LAYOUT_GENERALlayout. An attachment used as an input attachment and depth/stencil attachment must be in either VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL. An attachment must not be used as both a depth/stencil attachment and a color attachment.

To destroy a render pass, call:

void vkDestroyRenderPass(
    VkDevice                                    device,
    VkRenderPass                                renderPass,
    const VkAllocationCallbacks*                pAllocator);

• device is the logical device that destroys the render pass.

• renderPass is the handle of the render pass to destroy.

• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

正确使用

• All submitted commands that refer to renderPass must have completed execution

• If VkAllocationCallbacks were provided when renderPass was created, a compatible set of callbacks must be provided here

• If no VkAllocationCallbacks were provided when renderPass was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• If renderPass is not VK_NULL_HANDLE, renderPass must be a valid VkRenderPass handle

• If pAllocator is not NULL, pAllocator must be a pointer to a valid VkAllocationCallbacks structure

• If renderPass is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to renderPass must be externally synchronized