1// Copyright 2022-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5= VK_EXT_subpass_merge_feedback
6:toc: left
7:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/
8:sectnums:
9
10== Problem Statement
11
12The Vulkan render pass mechanism allows the implementation to merge subpasses at render pass
13creation time to improve performance or reduce memory bandwidth usage. However, the criteria
14for merging are implementation-specific and not visible to applications, and the application
15has no way to know which (if any) subpasses were merged.
16
17For performance debugging, applications may want to query whether certain subpasses were
18merged, or why they were not. They may also want to disable subpass merging completely or
19for certain subpasses, in order to determine the impact of subpass merging on performance.
20
21This proposal attempts to provide feedback and control for the subpass merging. It can be used
22for performance debugging or for runtime usage.
23
24== Solution Space
25
26Some new structures can be chained to pNext of VkRenderPassCreateInfo2, then the driver could
27provide subpass merging feedback and control subpass merging at render pass creation time.
28
29If the subpasses cannot be merged, the reason could be returned. The driver could change the
30conditions of subpass merging based on performance result, or being compatible with future new
31extensions, so using a string to store the reason is more flexible than a enumeration.
32
33== Proposal
34
35The following feature is exposed by the VK_EXT_subpass_merge_feedback extension:
36
37[source,c]
38----
39typedef struct VkPhysicalDeviceSubpassMergeFeedbackFeaturesEXT {
40    VkStructureType                sType;
41    void*                          pNext;
42    VkBool32                       subpassMergeFeedback;
43}
44----
45
46`subpassMergeFeedback` is the main feature enabling this extension's functionality and must
47be supported if this extension is supported.
48
49[source,c]
50----
51typedef struct VkRenderPassCreationControlEXT {
52    VkStructureType                sType;
53    const void*                    pNext;
54    VkBool32                       disallowMerging;
55}
56----
57
58The structure can control the subpass merging for both render pass level and subpass level.
59It can be chained to the pNext of VkRenderPassCreateInfo2 or VkSubpassDescription2.
60
61[source,c]
62----
63typedef struct VkRenderPassCreationFeedbackCreateInfoEXT {
64    VkStructureType                             sType;
65    const void*                                 pNext;
66    VkRenderPassCreationFeedbackInfoEXT*        pRenderPassFeedback;
67}
68----
69
70The structure can get the feedback from render pass level at render pass creation time.
71It can be chained to the pNext of VkRenderPassCreateInfo2. The feedback information could
72tell application which subpasses are merged.
73
74[source,c]
75----
76typedef struct VkRenderPassCreationFeedbackInfoEXT {
77    uint32_t                       postMergeSubpassCount;
78}
79----
80
81The structure contains the feedback data from render pass level.
82
83[source,c]
84----
85typedef struct VkRenderPassSubpassFeedbackCreateInfoEXT {
86    VkStructureType                      sType;
87    const void*                          pNext;
88    VkRenderPassSubpassFeedbackInfoEXT*  pSubpassFeedback;
89----
90
91The structure can get the feedback from subpass level at render pass creation time.
92It can be chained to the pNext of VkSubpassDescription2. The feedback information could
93tell application whether a subpass is merged into previous subpass and what is the reason
94if the subpass cannot be merged.
95
96[source,c]
97----
98typedef struct VkRenderPassSubpassFeedbackInfoEXT {
99    VkMergeStatusEXT               mergeStatus;
100    char                           description[VK_MAX_DESCRIPTION_SIZE];
101    uint32_t                       postMergeIndex;
102}
103----
104
105The structure contains the feedback data from the subpass level.
106
107== Issues
108
109=== RESOLVED: Could the reasons of not merging be enum instead of string?
110
111New enums are introduced in addition to the string.
112The enums will cover the main reasons and the string will specify the unspecified reason
113of enum.
114