1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[[renderpass]] 6= Render Pass 7 8[open,refpage='VkRenderPass',desc='Opaque handle to a render pass object',type='handles'] 9-- 10 11A _render pass_ represents a collection of attachments, subpasses, and 12dependencies between the subpasses, and describes how the attachments are 13used over the course of the subpasses. 14The use of a render pass in a command buffer is a _render pass instance_. 15 16Render passes are represented by sname:VkRenderPass handles: 17 18include::../api/handles/VkRenderPass.txt[] 19 20-- 21 22An _attachment description_ describes the properties of an attachment 23including its format, sample count, and how its contents are treated at the 24beginning and end of each render pass instance. 25 26[[renderpass-subpass]] 27A _subpass_ represents a phase of rendering that reads and writes a subset 28of the attachments in a render pass. 29Rendering commands are recorded into a particular subpass of a render pass 30instance. 31 32A _subpass description_ describes the subset of attachments that is involved 33in the execution of a subpass. 34Each subpass can: read from some attachments as _input attachments_, write 35to some as _color attachments_ or _depth/stencil attachments_, and perform 36_multisample resolve operations_ to _resolve attachments_. 37A subpass description can: also include a set of _preserve attachments_, 38which are attachments that are not read or written by the subpass but whose 39contents must: be preserved throughout the subpass. 40 41A subpass _uses an attachment_ if the attachment is a color, depth/stencil, 42resolve, or input attachment for that subpass (as determined by the 43pname:pColorAttachments, pname:pDepthStencilAttachment, 44pname:pResolveAttachments, and pname:pInputAttachments members of 45slink:VkSubpassDescription, respectively). 46A subpass does not use an attachment if that attachment is preserved by the 47subpass. 48The _first use of an attachment_ is in the lowest numbered subpass that uses 49that attachment. 50Similarly, the _last use of an attachment_ is in the highest numbered 51subpass that uses that attachment. 52 53The subpasses in a render pass all render to the same dimensions, and 54fragments for pixel (x,y,layer) in one subpass can: only read attachment 55contents written by previous subpasses at that same (x,y,layer) location. 56 57[NOTE] 58.Note 59==== 60By describing a complete set of subpasses in advance, render passes provide 61the implementation an opportunity to optimize the storage and transfer of 62attachment data between subpasses. 63 64In practice, this means that subpasses with a simple framebuffer-space 65dependency may: be merged into a single tiled rendering pass, keeping the 66attachment data on-chip for the duration of a render pass instance. 67However, it is also quite common for a render pass to only contain a single 68subpass. 69==== 70 71_Subpass dependencies_ describe <<synchronization-dependencies, execution 72and memory dependencies>> between subpasses. 73 74A _subpass dependency chain_ is a sequence of subpass dependencies in a 75render pass, where the source subpass of each subpass dependency (after the 76first) equals the destination subpass of the previous dependency. 77 78Execution of subpasses may: overlap or execute out of order with regards to 79other subpasses, unless otherwise enforced by an execution dependency. 80Each subpass only respects <<synchronization-submission-order, submission 81order>> for commands recorded in the same subpass, and the 82flink:vkCmdBeginRenderPass and flink:vkCmdEndRenderPass commands that 83delimit the render pass - commands within other subpasses are not included. 84This affects most other <<synchronization-implicit, implicit ordering 85guarantees>>. 86 87A render pass describes the structure of subpasses and attachments 88independent of any specific image views for the attachments. 89The specific image views that will be used for the attachments, and their 90dimensions, are specified in sname:VkFramebuffer objects. 91Framebuffers are created with respect to a specific render pass that the 92framebuffer is compatible with (see <<renderpass-compatibility,Render Pass 93Compatibility>>). 94Collectively, a render pass and a framebuffer define the complete render 95target state for one or more subpasses as well as the algorithmic 96dependencies between the subpasses. 97 98The various pipeline stages of the drawing commands for a given subpass may: 99execute concurrently and/or out of order, both within and across drawing 100commands, whilst still respecting <<synchronization-pipeline-stages-order, 101pipeline order>>. 102However for a given (x,y,layer,sample) sample location, certain per-sample 103operations are performed in <<primrast-order,rasterization order>>. 104 105 106[[renderpass-creation]] 107== Render Pass Creation 108 109[open,refpage='vkCreateRenderPass',desc='Create a new render pass object',type='protos'] 110-- 111 112To create a render pass, call: 113 114include::../api/protos/vkCreateRenderPass.txt[] 115 116 * pname:device is the logical device that creates the render pass. 117 * pname:pCreateInfo is a pointer to an instance of the 118 slink:VkRenderPassCreateInfo structure that describes the parameters of 119 the render pass. 120 * pname:pAllocator controls host memory allocation as described in the 121 <<memory-allocation, Memory Allocation>> chapter. 122 * pname:pRenderPass points to a slink:VkRenderPass handle in which the 123 resulting render pass object is returned. 124 125include::../validity/protos/vkCreateRenderPass.txt[] 126-- 127 128[open,refpage='VkRenderPassCreateInfo',desc='Structure specifying parameters of a newly created render pass',type='structs'] 129-- 130 131The sname:VkRenderPassCreateInfo structure is defined as: 132 133include::../api/structs/VkRenderPassCreateInfo.txt[] 134 135 * pname:sType is the type of this structure. 136 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 137 * pname:flags is reserved for future use. 138 * pname:attachmentCount is the number of attachments used by this render 139 pass, or zero indicating no attachments. 140 Attachments are referred to by zero-based indices in the range 141 [0,pname:attachmentCount). 142 * pname:pAttachments points to an array of pname:attachmentCount number of 143 slink:VkAttachmentDescription structures describing properties of the 144 attachments, or `NULL` if pname:attachmentCount is zero. 145 * pname:subpassCount is the number of subpasses to create for this render 146 pass. 147 Subpasses are referred to by zero-based indices in the range 148 [0,pname:subpassCount). 149 A render pass must: have at least one subpass. 150 * pname:pSubpasses points to an array of pname:subpassCount number of 151 slink:VkSubpassDescription structures describing properties of the 152 subpasses. 153 * pname:dependencyCount is the number of dependencies between pairs of 154 subpasses, or zero indicating no dependencies. 155 * pname:pDependencies points to an array of pname:dependencyCount number 156 of slink:VkSubpassDependency structures describing dependencies between 157 pairs of subpasses, or `NULL` if pname:dependencyCount is zero. 158 159.Valid Usage 160**** 161 * [[VUID-VkRenderPassCreateInfo-None-00832]] 162 If any two subpasses operate on attachments with overlapping ranges of 163 the same sname:VkDeviceMemory object, and at least one subpass writes to 164 that area of sname:VkDeviceMemory, a subpass dependency must: be 165 included (either directly or via some intermediate subpasses) between 166 them 167 * [[VUID-VkRenderPassCreateInfo-attachment-00833]] 168 If the pname:attachment member of any element of 169 pname:pInputAttachments, pname:pColorAttachments, 170 pname:pResolveAttachments or pname:pDepthStencilAttachment, or the 171 attachment indexed by any element of pname:pPreserveAttachments in any 172 element of pname:pSubpasses is bound to a range of a 173 sname:VkDeviceMemory object that overlaps with any other attachment in 174 any subpass (including the same subpass), the 175 sname:VkAttachmentDescription structures describing them must: include 176 ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in pname:flags 177 * [[VUID-VkRenderPassCreateInfo-attachment-00834]] 178 If the pname:attachment member of any element of 179 pname:pInputAttachments, pname:pColorAttachments, 180 pname:pResolveAttachments or pname:pDepthStencilAttachment, or any 181 element of pname:pPreserveAttachments in any element of pname:pSubpasses 182 is not ename:VK_ATTACHMENT_UNUSED, it must: be less than 183 pname:attachmentCount 184 * [[VUID-VkRenderPassCreateInfo-pPreserveAttachments-00835]] 185 The value of each element of the pname:pPreserveAttachments member in 186 each element of pname:pSubpasses must: not be ename:VK_ATTACHMENT_UNUSED 187 * [[VUID-VkRenderPassCreateInfo-pAttachments-00836]] 188 For any member of pname:pAttachments with a pname:loadOp equal to 189 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 190 must: not specify a pname:layout equal to 191 pname:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or 192 pname:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL. 193ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 194 * [[VUID-VkRenderPassCreateInfo-pAttachments-01566]] 195 For any member of pname:pAttachments with a pname:loadOp equal to 196 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 197 must: not specify a pname:layout equal to 198 pname:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL. 199 * [[VUID-VkRenderPassCreateInfo-pAttachments-01567]] 200 For any member of pname:pAttachments with a pname:stencilLoadOp equal to 201 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 202 must: not specify a pname:layout equal to 203 pname:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL. 204 * [[VUID-VkRenderPassCreateInfo-pNext-01926]] 205 If the pname:pNext chain includes an instance of 206 slink:VkRenderPassInputAttachmentAspectCreateInfo, the pname:subpass 207 member of each element of its pname:pAspectReferences member must: be 208 less than pname:subpassCount 209 * [[VUID-VkRenderPassCreateInfo-pNext-01927]] 210 If the pname:pNext chain includes an instance of 211 slink:VkRenderPassInputAttachmentAspectCreateInfo, the 212 pname:inputAttachmentIndex member of each element of its 213 pname:pAspectReferences member must: be less than the value of 214 pname:inputAttachmentCount in the member of pname:pSubpasses identified 215 by its pname:subpass member 216 * [[VUID-VkRenderPassCreateInfo-pNext-01963]] 217 If the pname:pNext chain includes an instance of 218 slink:VkRenderPassInputAttachmentAspectCreateInfo, the pname:aspectMask 219 member of any element of pname:pAspectReferences must: only include 220 aspects that are present in images of the pname:format of the input 221 attachment specified by the pname:subpass and pname:inputAttachment of 222 the same element of pname:pAspectReferences 223endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 224ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 225 * [[VUID-VkRenderPassCreateInfo-pNext-01928]] 226 If the pname:pNext chain includes an instance of 227 slink:VkRenderPassMultiviewCreateInfo, and its pname:subpassCount member 228 is not zero, that member must: be equal to the value of 229 pname:subpassCount 230 * [[VUID-VkRenderPassCreateInfo-pNext-01929]] 231 If the pname:pNext chain includes an instance of 232 slink:VkRenderPassMultiviewCreateInfo, if its pname:dependencyCount 233 member is not zero, it must: be equal to pname:dependencyCount 234 * [[VUID-VkRenderPassCreateInfo-pNext-01930]] 235 If the pname:pNext chain includes an instance of 236 slink:VkRenderPassMultiviewCreateInfo, for each non-zero element of 237 pname:pViewOffsets, the pname:srcSubpass and pname:dstSubpass members of 238 pname:pDependencies at the same index must: not be equal 239endif::VK_VERSION_1_1,VK_KHR_multiview[] 240 * [[VUID-VkRenderPassCreateInfo-pDependencies-00837]] 241 For any element of pname:pDependencies, if the pname:srcSubpass is not 242 ename:VK_SUBPASS_EXTERNAL, all stage flags included in the 243 pname:srcStageMask member of that dependency must: be a pipeline stage 244 supported by the <<synchronization-pipeline-stages-types, pipeline>> 245 identified by the pname:pipelineBindPoint member of the source subpass. 246 * [[VUID-VkRenderPassCreateInfo-pDependencies-00838]] 247 For any element of pname:pDependencies, if the pname:dstSubpass is not 248 ename:VK_SUBPASS_EXTERNAL, all stage flags included in the 249 pname:dstStageMask member of that dependency must: be a pipeline stage 250 supported by the <<synchronization-pipeline-stages-types, pipeline>> 251 identified by the pname:pipelineBindPoint member of the source subpass. 252**** 253 254include::../validity/structs/VkRenderPassCreateInfo.txt[] 255-- 256 257[open,refpage='VkRenderPassCreateFlags',desc='Reserved for future use',type='enums'] 258-- 259include::../api/flags/VkRenderPassCreateFlags.txt[] 260 261sname:VkRenderPassCreateFlags is a bitmask type for setting a mask, but is 262currently reserved for future use. 263-- 264 265ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 266 267[[renderpass-multiview]] 268[open,refpage='VkRenderPassMultiviewCreateInfo',desc='Structure containing multiview info for all subpasses',type='structs'] 269-- 270 271If the sname:VkRenderPassCreateInfo::pname:pNext chain includes a 272sname:VkRenderPassMultiviewCreateInfo structure, then that structure 273includes an array of view masks, view offsets, and correlation masks for the 274render pass. 275 276The sname:VkRenderPassMultiviewCreateInfo structure is defined as: 277 278include::../api/structs/VkRenderPassMultiviewCreateInfo.txt[] 279 280ifdef::VK_KHR_multiview[] 281or the equivalent 282 283include::../api/structs/VkRenderPassMultiviewCreateInfoKHR.txt[] 284endif::VK_KHR_multiview[] 285 286 * pname:sType is the type of this structure. 287 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 288 * pname:subpassCount is zero or is the number of subpasses in the render 289 pass. 290 * pname:pViewMasks points to an array of pname:subpassCount number of view 291 masks, where each mask is a bitfield of view indices describing which 292 views rendering is broadcast to in each subpass, when multiview is 293 enabled. 294 If pname:subpassCount is zero, each view mask is treated as zero. 295 * pname:dependencyCount is zero or the number of dependencies in the 296 render pass. 297 * pname:pViewOffsets points to an array of pname:dependencyCount view 298 offsets, one for each dependency. 299 If pname:dependencyCount is zero, each dependency's view offset is 300 treated as zero. 301 Each view offset controls which views in the source subpass the views in 302 the destination subpass depend on. 303 * pname:correlationMaskCount is zero or a number of correlation masks. 304 * pname:pCorrelationMasks is an array of view masks indicating sets of 305 views that may: be more efficient to render concurrently. 306 307When a subpass uses a non-zero view mask, _multiview_ functionality is 308considered to be enabled. 309Multiview is all-or-nothing for a render pass - that is, either all 310subpasses must: have a non-zero view mask (though some subpasses may: have 311only one view) or all must: be zero. 312Multiview causes all drawing and clear commands in the subpass to behave as 313if they were broadcast to each view, where a view is represented by one 314layer of the framebuffer attachments. 315All draws and clears are broadcast to each _view index_ whose bit is set in 316the view mask. 317The view index is provided in the code:ViewIndex shader input variable, and 318color, depth/stencil, and input attachments all read/write the layer of the 319framebuffer corresponding to the view index. 320 321If the view mask is zero for all subpasses, multiview is considered to be 322disabled and all drawing commands execute normally, without this additional 323broadcasting. 324 325Some implementations may: not support multiview in conjunction with 326<<features-features-multiview-gs,geometry shaders>> or 327<<features-features-multiview-tess,tessellation shaders>>. 328 329[[renderpass-multiview-view-local]] 330When multiview is enabled, the ename:VK_DEPENDENCY_VIEW_LOCAL_BIT bit in a 331dependency can: be used to express a view-local dependency, meaning that 332each view in the destination subpass depends on a single view in the source 333subpass. 334Unlike pipeline barriers, a subpass dependency can: potentially have a 335different view mask in the source subpass and the destination subpass. 336If the dependency is view-local, then each view ([eq]#dstView#) in the 337destination subpass depends on the view [eq]#dstView {plus} 338pViewOffsets[dependency]# in the source subpass. 339If there is not such a view in the source subpass, then this dependency does 340not affect that view in the destination subpass. 341If the dependency is not view-local, then all views in the destination 342subpass depend on all views in the source subpass, and the view offset is 343ignored. 344A non-zero view offset is not allowed in a self-dependency. 345 346The elements of pname:pCorrelationMasks are a set of masks of views 347indicating that views in the same mask may: exhibit spatial coherency 348between the views, making it more efficient to render them concurrently. 349Correlation masks must: not have a functional effect on the results of the 350multiview rendering. 351 352When multiview is enabled, at the beginning of each subpass all non-render 353pass state is undefined. 354In particular, each time flink:vkCmdBeginRenderPass or 355flink:vkCmdNextSubpass is called the graphics pipeline must: be bound, any 356relevant descriptor sets or vertex/index buffers must: be bound, and any 357relevant dynamic state or push constants must: be set before they are used. 358 359ifdef::VK_NVX_multiview_per_view_attributes[] 360 361A multiview subpass can: declare that its shaders will write per-view 362attributes for all views in a single invocation, by setting the 363ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit in the subpass 364description. 365The only supported per-view attributes are position and viewport mask, and 366per-view position and viewport masks are written to output array variables 367decorated with code:PositionPerViewNV and code:ViewportMaskPerViewNV, 368respectively. 369If `<<VK_NV_viewport_array2>>` is not supported and enabled, 370code:ViewportMaskPerViewNV must: not be used. 371Values written to elements of code:PositionPerViewNV and 372code:ViewportMaskPerViewNV must: not depend on the code:ViewIndex. 373The shader must: also write to an output variable decorated with 374code:Position, and the value written to code:Position must: equal the value 375written to code:PositionPerViewNV[code:ViewIndex]. 376Similarly, if code:ViewportMaskPerViewNV is written to then the shader must: 377also write to an output variable decorated with code:ViewportMaskNV, and the 378value written to code:ViewportMaskNV must: equal the value written to 379code:ViewportMaskPerViewNV[code:ViewIndex]. 380Implementations will either use values taken from code:Position and 381code:ViewportMaskNV and invoke the shader once for each view, or will use 382values taken from code:PositionPerViewNV and code:ViewportMaskPerViewNV and 383invoke the shader fewer times. 384The values written to code:Position and code:ViewportMaskNV must: not depend 385on the values written to code:PositionPerViewNV and 386code:ViewportMaskPerViewNV, or vice versa (to allow compilers to eliminate 387the unused outputs). 388All attributes that do not have `*PerViewNV` counterparts must: not depend 389on code:ViewIndex. 390 391Per-view attributes are all-or-nothing for a subpass. 392That is, all pipelines compiled against a subpass that includes the 393ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit must: write 394per-view attributes to the `*PerViewNV[]` shader outputs, in addition to the 395non-per-view (e.g. code:Position) outputs. 396Pipelines compiled against a subpass that does not include this bit must: 397not include the `*PerViewNV[]` outputs in their interfaces. 398 399endif::VK_NVX_multiview_per_view_attributes[] 400 401.Valid Usage 402**** 403 * [[VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-00841]] 404 Each view index must: not be set in more than one element of 405 pname:pCorrelationMasks 406**** 407 408include::../validity/structs/VkRenderPassMultiviewCreateInfo.txt[] 409-- 410 411endif::VK_VERSION_1_1,VK_KHR_multiview[] 412 413[open,refpage='VkAttachmentDescription',desc='Structure specifying an attachment description',type='structs'] 414-- 415 416The sname:VkAttachmentDescription structure is defined as: 417 418include::../api/structs/VkAttachmentDescription.txt[] 419 420 * pname:flags is a bitmask of elink:VkAttachmentDescriptionFlagBits 421 specifying additional properties of the attachment. 422 * pname:format is a elink:VkFormat value specifying the format of the 423 image view that will be used for the attachment. 424 * pname:samples is the number of samples of the image as defined in 425 elink:VkSampleCountFlagBits. 426 * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the 427 contents of color and depth components of the attachment are treated at 428 the beginning of the subpass where it is first used. 429 * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the 430 contents of color and depth components of the attachment are treated at 431 the end of the subpass where it is last used. 432 * pname:stencilLoadOp is a elink:VkAttachmentLoadOp value specifying how 433 the contents of stencil components of the attachment are treated at the 434 beginning of the subpass where it is first used. 435 * pname:stencilStoreOp is a elink:VkAttachmentStoreOp value specifying how 436 the contents of stencil components of the attachment are treated at the 437 end of the last subpass where it is used. 438 * pname:initialLayout is the layout the attachment image subresource will 439 be in when a render pass instance begins. 440 * pname:finalLayout is the layout the attachment image subresource will be 441 transitioned to when a render pass instance ends. 442 During a render pass instance, an attachment can: use a different layout 443 in each subpass, if desired. 444 445[[renderpass-load-store-ops]] 446If the attachment uses a color format, then pname:loadOp and pname:storeOp 447are used, and pname:stencilLoadOp and pname:stencilStoreOp are ignored. 448If the format has depth and/or stencil components, pname:loadOp and 449pname:storeOp apply only to the depth data, while pname:stencilLoadOp and 450pname:stencilStoreOp define how the stencil data is handled. 451pname:loadOp and pname:stencilLoadOp define the _load operations_ that 452execute as part of the first subpass that uses the attachment. 453pname:storeOp and pname:stencilStoreOp define the _store operations_ that 454execute as part of the last subpass that uses the attachment. 455 456The load operation for each sample in an attachment happens-before any 457recorded command which accesses the sample in the first subpass where the 458attachment is used. 459Load operations for attachments with a depth/stencil format execute in the 460ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage. 461Load operations for attachments with a color format execute in the 462ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 463 464The store operation for each sample in an attachment happens-after any 465recorded command which accesses the sample in the last subpass where the 466attachment is used. 467Store operations for attachments with a depth/stencil format execute in the 468ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage. 469Store operations for attachments with a color format execute in the 470ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 471 472If an attachment is not used by any subpass, then pname:loadOp, 473pname:storeOp, pname:stencilStoreOp, and pname:stencilLoadOp are ignored, 474and the attachment's memory contents will not be modified by execution of a 475render pass instance. 476 477ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 478 479The load and store operations apply on the first and last use of each view 480in the render pass, respectively. 481If a view index of an attachment is not included in the view mask in any 482subpass that uses it, then the load and store operations are ignored, and 483the attachment's memory contents will not be modified by execution of a 484render pass instance. 485 486endif::VK_VERSION_1_1,VK_KHR_multiview[] 487 488[[renderpass-precision]] 489During a render pass instance, input/color attachments with color formats 490that have a component size of 8, 16, or 32 bits must: be represented in the 491attachment's format throughout the instance. 492Attachments with other floating- or fixed-point color formats, or with depth 493components may: be represented in a format with a precision higher than the 494attachment format, but must: be represented with the same range. 495When such a component is loaded via the pname:loadOp, it will be converted 496into an implementation-dependent format used by the render pass. 497Such components must: be converted from the render pass format, to the 498format of the attachment, before they are resolved or stored at the end of a 499render pass instance via pname:storeOp. 500Conversions occur as described in <<fundamentals-numerics,Numeric 501Representation and Computation>> and <<fundamentals-fixedconv, Fixed-Point 502Data Conversions>>. 503 504[[renderpass-aliasing]] 505If pname:flags includes ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then 506the attachment is treated as if it shares physical memory with another 507attachment in the same render pass. 508This information limits the ability of the implementation to reorder certain 509operations (like layout transitions and the pname:loadOp) such that it is 510not improperly reordered against other uses of the same physical memory via 511a different attachment. 512This is described in more detail below. 513 514.Valid Usage 515**** 516 * [[VUID-VkAttachmentDescription-finalLayout-00843]] 517 pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or 518 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 519**** 520 521include::../validity/structs/VkAttachmentDescription.txt[] 522-- 523 524ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 525 526[open,refpage='VkRenderPassInputAttachmentAspectCreateInfo',desc='Structure specifying, for a given subpass/input attachment pair, which aspect can: be read.',type='structs'] 527-- 528 529To specify which aspects of an input attachment can: be read add a 530slink:VkRenderPassInputAttachmentAspectCreateInfo structure to the 531pname:pNext chain of the slink:VkRenderPassCreateInfo structure: 532 533The sname:VkRenderPassInputAttachmentAspectCreateInfo structure is defined 534as: 535 536include::../api/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[] 537 538ifdef::VK_KHR_maintenance2[] 539or the equivalent 540 541include::../api/structs/VkRenderPassInputAttachmentAspectCreateInfoKHR.txt[] 542endif::VK_KHR_maintenance2[] 543 544 * pname:sType is the type of this structure. 545 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 546 * pname:aspectReferenceCount is the number of elements in the 547 pAspectReferences array. 548 * pname:pAspectReferences points to an array of pname:aspectReferenceCount 549 number of slink:VkInputAttachmentAspectReference structures describing 550 which aspect(s) can: be accessed for a given input attachment within a 551 given subpass. 552 553include::../validity/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[] 554-- 555 556[open,refpage='VkInputAttachmentAspectReference',desc='Structure specifying a subpass/input attachment pair and an aspect mask that can: be read.',type='structs'] 557-- 558 559The sname:VkInputAttachmentAspectReference structure specifies an aspect 560mask for a specific input attachment of a specific subpass in the render 561pass. 562 563pname:subpass and pname:inputAttachmentIndex index into the render pass as: 564 565pname:pCreateInfo::pname:pSubpasses[pname:subpass].pname:pInputAttachments[pname:inputAttachmentIndex] 566 567include::../api/structs/VkInputAttachmentAspectReference.txt[] 568 569ifdef::VK_KHR_maintenance2[] 570or the equivalent 571 572include::../api/structs/VkInputAttachmentAspectReferenceKHR.txt[] 573endif::VK_KHR_maintenance2[] 574 575 * pname:subpass is an index into the pname:pSubpasses array of the parent 576 sname:VkRenderPassCreateInfo structure. 577 * pname:inputAttachmentIndex is an index into the pname:pInputAttachments 578 of the specified subpass. 579 * pname:aspectMask is a mask of which aspect(s) can: be accessed within 580 the specified subpass. 581 582.Valid Usage 583**** 584 * [[VUID-VkInputAttachmentAspectReference-aspectMask-01964]] 585 pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT 586**** 587 588include::../validity/structs/VkInputAttachmentAspectReference.txt[] 589-- 590 591ifdef::editing-notes[] 592[NOTE] 593.editing-note 594==== 595TODO (Jon) - it's unclear whether the following two paragraphs are intended 596to apply to slink:VkAttachmentDescription, one of the extension structures 597described immediately above, or something else. 598The following description of elink:VkAttachmentDescriptionFlagBits should: 599probably be moved up to near slink:VkAttachmentDescription. 600==== 601endif::editing-notes[] 602 603An application must: only access the specified aspect(s). 604 605An application can: access any aspect of an input attachment that does not 606have a specified aspect mask. 607 608endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 609 610[open,refpage='VkAttachmentDescriptionFlagBits',desc='Bitmask specifying additional properties of an attachment',type='enums'] 611-- 612 613Bits which can: be set in slink:VkAttachmentDescription::pname:flags 614describing additional properties of the attachment are: 615 616include::../api/enums/VkAttachmentDescriptionFlagBits.txt[] 617 618 * ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT specifies that the 619 attachment aliases the same device memory as other attachments. 620 621-- 622 623[open,refpage='VkAttachmentDescriptionFlags',desc='Bitmask of VkAttachmentDescriptionFlagBits',type='enums'] 624-- 625include::../api/flags/VkAttachmentDescriptionFlags.txt[] 626 627sname:VkAttachmentDescriptionFlags is a bitmask type for setting a mask of 628zero or more slink:VkAttachmentDescriptionFlagBits. 629-- 630 631[open,refpage='VkAttachmentLoadOp',desc='Specify how contents of an attachment are treated at the beginning of a subpass',type='enums'] 632-- 633 634Possible values of slink:VkAttachmentDescription::pname:loadOp and 635pname:stencilLoadOp, specifying how the contents of the attachment are 636treated, are: 637 638include::../api/enums/VkAttachmentLoadOp.txt[] 639 640 * ename:VK_ATTACHMENT_LOAD_OP_LOAD specifies that the previous contents of 641 the image within the render area will be preserved. 642 For attachments with a depth/stencil format, this uses the access type 643 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT. 644 For attachments with a color format, this uses the access type 645 ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT. 646 * ename:VK_ATTACHMENT_LOAD_OP_CLEAR specifies that the contents within the 647 render area will be cleared to a uniform value, which is specified when 648 a render pass instance is begun. 649 For attachments with a depth/stencil format, this uses the access type 650 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 651 For attachments with a color format, this uses the access type 652 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 653 * ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE specifies that the previous 654 contents within the area need not be preserved; the contents of the 655 attachment will be undefined inside the render area. 656 For attachments with a depth/stencil format, this uses the access type 657 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 658 For attachments with a color format, this uses the access type 659 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 660 661-- 662 663[open,refpage='VkAttachmentStoreOp',desc='Specify how contents of an attachment are treated at the end of a subpass',type='enums'] 664-- 665 666Possible values of slink:VkAttachmentDescription::pname:storeOp and 667pname:stencilStoreOp, specifying how the contents of the attachment are 668treated, are: 669 670include::../api/enums/VkAttachmentStoreOp.txt[] 671 672 * ename:VK_ATTACHMENT_STORE_OP_STORE specifies the contents generated 673 during the render pass and within the render area are written to memory. 674 For attachments with a depth/stencil format, this uses the access type 675 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 676 For attachments with a color format, this uses the access type 677 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 678 * ename:VK_ATTACHMENT_STORE_OP_DONT_CARE specifies the contents within the 679 render area are not needed after rendering, and may: be discarded; the 680 contents of the attachment will be undefined inside the render area. 681 For attachments with a depth/stencil format, this uses the access type 682 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 683 For attachments with a color format, this uses the access type 684 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 685 686-- 687 688ifdef::editing-notes[] 689[NOTE] 690.editing-note 691==== 692TODO (Jon) - the following text may need to be moved back to combine with 693flink:vkCreateRenderPass above for automatic ref page generation. 694==== 695endif::editing-notes[] 696 697If a render pass uses multiple attachments that alias the same device 698memory, those attachments must: each include the 699ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment 700description flags. 701Attachments aliasing the same memory occurs in multiple ways: 702 703 * Multiple attachments being assigned the same image view as part of 704 framebuffer creation. 705 * Attachments using distinct image views that correspond to the same image 706 subresource of an image. 707 * Attachments using views of distinct image subresources which are bound 708 to overlapping memory ranges. 709 710[NOTE] 711.Note 712==== 713Render passes must: include subpass dependencies (either directly or via a 714subpass dependency chain) between any two subpasses that operate on the same 715attachment or aliasing attachments and those subpass dependencies must: 716include execution and memory dependencies separating uses of the aliases, if 717at least one of those subpasses writes to one of the aliases. 718These dependencies must: not include the ename:VK_DEPENDENCY_BY_REGION_BIT 719if the aliases are views of distinct image subresources which overlap in 720memory. 721==== 722 723Multiple attachments that alias the same memory must: not be used in a 724single subpass. 725A given attachment index must: not be used multiple times in a single 726subpass, with one exception: two subpass attachments can: use the same 727attachment index if at least one use is as an input attachment and neither 728use is as a resolve or preserve attachment. 729In other words, the same view can: be used simultaneously as an input and 730color or depth/stencil attachment, but must: not be used as multiple color 731or depth/stencil attachments nor as resolve or preserve attachments. 732The precise set of valid scenarios is described in more detail 733<<renderpass-feedbackloop, below>>. 734 735If a set of attachments alias each other, then all except the first to be 736used in the render pass must: use an pname:initialLayout of 737ename:VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases 738make their contents undefined. 739Once an alias has been used and a different alias has been used after it, 740the first alias must: not be used in any later subpasses. 741However, an application can: assign the same image view to multiple aliasing 742attachment indices, which allows that image view to be used multiple times 743even if other aliases are used in between. 744 745[NOTE] 746.Note 747==== 748Once an attachment needs the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT 749bit, there should: be no additional cost of introducing additional aliases, 750and using these additional aliases may: allow more efficient clearing of the 751attachments on multiple uses via ename:VK_ATTACHMENT_LOAD_OP_CLEAR. 752==== 753 754[open,refpage='VkSubpassDescription',desc='Structure specifying a subpass description',type='structs'] 755-- 756 757The sname:VkSubpassDescription structure is defined as: 758 759include::../api/structs/VkSubpassDescription.txt[] 760 761 * pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits 762 specifying usage of the subpass. 763 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying 764 whether this is a compute or graphics subpass. 765 Currently, only graphics subpasses are supported. 766 * pname:inputAttachmentCount is the number of input attachments. 767 * pname:pInputAttachments is an array of slink:VkAttachmentReference 768 structures (defined below) that lists which of the render pass's 769 attachments can: be read in the fragment shader stage during the 770 subpass, and what layout each attachment will be in during the subpass. 771 Each element of the array corresponds to an input attachment unit number 772 in the shader, i.e. if the shader declares an input variable 773 `layout(input_attachment_index=X, set=Y, binding=Z)` then it uses the 774 attachment provided in pname:pInputAttachments[X]. 775 Input attachments must: also be bound to the pipeline with a descriptor 776 set, with the input attachment descriptor written in the location 777 (set=Y, binding=Z). 778 Fragment shaders can: use subpass input variables to access the contents 779 of an input attachment at the fragment's (x, y, layer) framebuffer 780 coordinates. 781 * pname:colorAttachmentCount is the number of color attachments. 782 * pname:pColorAttachments is an array of pname:colorAttachmentCount 783 slink:VkAttachmentReference structures that lists which of the render 784 pass's attachments will be used as color attachments in the subpass, and 785 what layout each attachment will be in during the subpass. 786 Each element of the array corresponds to a fragment shader output 787 location, i.e. if the shader declared an output variable 788 `layout(location=X)` then it uses the attachment provided in 789 pname:pColorAttachments[X]. 790 * pname:pResolveAttachments is `NULL` or an array of 791 pname:colorAttachmentCount slink:VkAttachmentReference structures that 792 lists which of the render pass's attachments are resolved to at the end 793 of the subpass, and what layout each attachment will be in during the 794 multisample resolve operation. 795 If pname:pResolveAttachments is not `NULL`, each of its elements 796 corresponds to a color attachment (the element in 797 pname:pColorAttachments at the same index), and a multisample resolve 798 operation is defined for each attachment. 799 At the end of each subpass, multisample resolve operations read the 800 subpass's color attachments, and resolve the samples for each pixel to 801 the same pixel location in the corresponding resolve attachments, unless 802 the resolve attachment index is ename:VK_ATTACHMENT_UNUSED. 803 If the first use of an attachment in a render pass is as a resolve 804 attachment, then the pname:loadOp is effectively ignored as the resolve 805 is guaranteed to overwrite all pixels in the render area. 806 * pname:pDepthStencilAttachment is a pointer to a 807 slink:VkAttachmentReference specifying which attachment will be used for 808 depth/stencil data and the layout it will be in during the subpass. 809 Setting the attachment index to ename:VK_ATTACHMENT_UNUSED or leaving 810 this pointer as `NULL` indicates that no depth/stencil attachment will 811 be used in the subpass. 812 * pname:preserveAttachmentCount is the number of preserved attachments. 813 * pname:pPreserveAttachments is an array of pname:preserveAttachmentCount 814 render pass attachment indices describing the attachments that are not 815 used by a subpass, but whose contents must: be preserved throughout the 816 subpass. 817 818The contents of an attachment within the render area become undefined at the 819start of a subpass *S* if all of the following conditions are true: 820 821 * The attachment is used as a color, depth/stencil, or resolve attachment 822 in any subpass in the render pass. 823 * There is a subpass *S~1~* that uses or preserves the attachment, and a 824 subpass dependency from *S~1~* to *S*. 825 * The attachment is not used or preserved in subpass *S*. 826 827Once the contents of an attachment become undefined in subpass *S*, they 828remain undefined for subpasses in subpass dependency chains starting with 829subpass *S* until they are written again. 830However, they remain valid for subpasses in other subpass dependency chains 831starting with subpass *S~1~* if those subpasses use or preserve the 832attachment. 833 834.Valid Usage 835**** 836 * [[VUID-VkSubpassDescription-pipelineBindPoint-00844]] 837 pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS 838 * [[VUID-VkSubpassDescription-colorAttachmentCount-00845]] 839 pname:colorAttachmentCount must: be less than or equal to 840 sname:VkPhysicalDeviceLimits::pname:maxColorAttachments 841 * [[VUID-VkSubpassDescription-loadOp-00846]] 842 If the first use of an attachment in this render pass is as an input 843 attachment, and the attachment is not also used as a color or 844 depth/stencil attachment in the same subpass, then pname:loadOp must: 845 not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR 846 * [[VUID-VkSubpassDescription-pResolveAttachments-00847]] 847 If pname:pResolveAttachments is not `NULL`, for each resolve attachment 848 that does not have the value ename:VK_ATTACHMENT_UNUSED, the 849 corresponding color attachment must: not have the value 850 ename:VK_ATTACHMENT_UNUSED 851 * [[VUID-VkSubpassDescription-pResolveAttachments-00848]] 852 If pname:pResolveAttachments is not `NULL`, the sample count of each 853 element of pname:pColorAttachments must: be anything other than 854 ename:VK_SAMPLE_COUNT_1_BIT 855 * [[VUID-VkSubpassDescription-pResolveAttachments-00849]] 856 Each element of pname:pResolveAttachments must: have a sample count of 857 ename:VK_SAMPLE_COUNT_1_BIT 858 * [[VUID-VkSubpassDescription-pResolveAttachments-00850]] 859 Each element of pname:pResolveAttachments must: have the same 860 elink:VkFormat as its corresponding color attachment 861 * [[VUID-VkSubpassDescription-pColorAttachments-01417]] 862 All attachments in pname:pColorAttachments that are not 863 ename:VK_ATTACHMENT_UNUSED must: have the same sample count 864ifdef::VK_AMD_mixed_attachment_samples[] 865 * [[VUID-VkSubpassDescription-pColorAttachments-01506]] 866 All attachments in pname:pColorAttachments that are not 867 ename:VK_ATTACHMENT_UNUSED must: have a sample count that is smaller 868 than or equal to the sample count of pname:pDepthStencilAttachment if it 869 is not ename:VK_ATTACHMENT_UNUSED 870endif::VK_AMD_mixed_attachment_samples[] 871ifndef::VK_AMD_mixed_attachment_samples[] 872ifndef::VK_NV_framebuffer_mixed_samples[] 873 * [[VUID-VkSubpassDescription-pDepthStencilAttachment-01418]] 874 If pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and 875 any attachments in pname:pColorAttachments are not 876 ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count 877endif::VK_NV_framebuffer_mixed_samples[] 878endif::VK_AMD_mixed_attachment_samples[] 879 * [[VUID-VkSubpassDescription-None-00852]] 880 If any input attachments are ename:VK_ATTACHMENT_UNUSED, then any 881 pipelines bound during the subpass must: not access those input 882 attachments from the fragment shader 883 * [[VUID-VkSubpassDescription-attachment-00853]] 884 The pname:attachment member of each element of 885 pname:pPreserveAttachments must: not be ename:VK_ATTACHMENT_UNUSED 886 * [[VUID-VkSubpassDescription-pPreserveAttachments-00854]] 887 Each element of pname:pPreserveAttachments must: not also be an element 888 of any other member of the subpass description 889 * [[VUID-VkSubpassDescription-layout-00855]] 890 If any attachment is used as both an input attachment and a color or 891 depth/stencil attachment, then each use must: use the same pname:layout 892ifdef::VK_NVX_multiview_per_view_attributes[] 893 * [[VUID-VkSubpassDescription-flags-00856]] 894 If pname:flags includes 895 ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must: 896 also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX. 897endif::VK_NVX_multiview_per_view_attributes[] 898**** 899 900include::../validity/structs/VkSubpassDescription.txt[] 901-- 902 903[open,refpage='VkSubpassDescriptionFlagBits',desc='Bitmask specifying usage of a subpass',type='enums'] 904-- 905 906Bits which can: be set in slink:VkSubpassDescription::pname:flags, 907specifying usage of the subpass, are: 908 909include::../api/enums/VkSubpassDescriptionFlagBits.txt[] 910 911ifdef::VK_NVX_multiview_per_view_attributes[] 912 * ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX specifies that 913 shaders compiled for this subpass write the attributes for all views in 914 a single invocation of each vertex processing stage. 915 All pipelines compiled against a subpass that includes this bit must: 916 write per-view attributes to the `*PerViewNV[]` shader outputs, in 917 addition to the non-per-view (e.g. code:Position) outputs. 918 * ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX specifies 919 that shaders compiled for this subpass use per-view positions which only 920 differ in value in the x component. 921 Per-view viewport mask can: also be used. 922endif::VK_NVX_multiview_per_view_attributes[] 923 924ifndef::VK_NVX_multiview_per_view_attributes[] 925[NOTE] 926.Note 927==== 928All bits for this type are defined by extensions, and none of those 929extensions are enabled in this build of the specification. 930==== 931endif::VK_NVX_multiview_per_view_attributes[] 932-- 933 934[open,refpage='VkSubpassDescriptionFlags',desc='Bitmask of VkSubpassDescriptionFlagBits',type='enums'] 935-- 936include::../api/flags/VkSubpassDescriptionFlags.txt[] 937 938sname:VkSubpassDescriptionFlags is a bitmask type for setting a mask of zero 939or more slink:VkSubpassDescriptionFlagBits. 940-- 941 942[open,refpage='VkAttachmentReference',desc='Structure specifying an attachment reference',type='structs'] 943-- 944 945The sname:VkAttachmentReference structure is defined as: 946 947include::../api/structs/VkAttachmentReference.txt[] 948 949 * pname:attachment is the index of the attachment of the render pass, and 950 corresponds to the index of the corresponding element in the 951 pname:pAttachments array of the sname:VkRenderPassCreateInfo structure. 952 If any color or depth/stencil attachments are 953 ename:VK_ATTACHMENT_UNUSED, then no writes occur for those attachments. 954 * pname:layout is a elink:VkImageLayout value specifying the layout the 955 attachment uses during the subpass. 956 957.Valid Usage 958**** 959 * [[VUID-VkAttachmentReference-layout-00857]] 960 pname:layout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or 961 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 962**** 963 964include::../validity/structs/VkAttachmentReference.txt[] 965-- 966 967[open,refpage='VkSubpassDependency',desc='Structure specifying a subpass dependency',type='structs'] 968-- 969 970The sname:VkSubpassDependency structure is defined as: 971 972include::../api/structs/VkSubpassDependency.txt[] 973 974 * pname:srcSubpass is the subpass index of the first subpass in the 975 dependency, or ename:VK_SUBPASS_EXTERNAL. 976 * pname:dstSubpass is the subpass index of the second subpass in the 977 dependency, or ename:VK_SUBPASS_EXTERNAL. 978 * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits 979 specifying the <<synchronization-pipeline-stages-masks, source stage 980 mask>>. 981 * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits 982 specifying the <<synchronization-pipeline-stages-masks, destination 983 stage mask>> 984 * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 985 <<synchronization-access-masks, source access mask>>. 986 * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 987 <<synchronization-access-masks, destination access mask>>. 988 * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits. 989 990If pname:srcSubpass is equal to pname:dstSubpass then the 991slink:VkSubpassDependency describes a 992<<synchronization-pipeline-barriers-subpass-self-dependencies, subpass 993self-dependency>>, and only constrains the pipeline barriers allowed within 994a subpass instance. 995Otherwise, when a render pass instance which includes a subpass dependency 996is submitted to a queue, it defines a memory dependency between the 997subpasses identified by pname:srcSubpass and pname:dstSubpass. 998 999If pname:srcSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the first 1000<<synchronization-dependencies-scopes, synchronization scope>> includes 1001commands that occur earlier in <<synchronization-submission-order,submission 1002order>> than the flink:vkCmdBeginRenderPass used to begin the render pass 1003instance. 1004Otherwise, the first set of commands includes all commands submitted as part 1005of the subpass instance identified by pname:srcSubpass and any load, store 1006or multisample resolve operations on attachments used in pname:srcSubpass. 1007In either case, the first synchronization scope is limited to operations on 1008the pipeline stages determined by the 1009<<synchronization-pipeline-stages-masks, source stage mask>> specified by 1010pname:srcStageMask. 1011 1012If pname:dstSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the second 1013<<synchronization-dependencies-scopes, synchronization scope>> includes 1014commands that occur later in <<synchronization-submission-order,submission 1015order>> than the flink:vkCmdEndRenderPass used to end the render pass 1016instance. 1017Otherwise, the second set of commands includes all commands submitted as 1018part of the subpass instance identified by pname:dstSubpass and any load, 1019store or multisample resolve operations on attachments used in 1020pname:dstSubpass. 1021In either case, the second synchronization scope is limited to operations on 1022the pipeline stages determined by the 1023<<synchronization-pipeline-stages-masks, destination stage mask>> specified 1024by pname:dstStageMask. 1025 1026The first <<synchronization-dependencies-access-scopes, access scope>> is 1027limited to access in the pipeline stages determined by the 1028<<synchronization-pipeline-stages-masks, source stage mask>> specified by 1029pname:srcStageMask. 1030It is also limited to access types in the <<synchronization-access-masks, 1031source access mask>> specified by pname:srcAccessMask. 1032 1033The second <<synchronization-dependencies-access-scopes, access scope>> is 1034limited to access in the pipeline stages determined by the 1035<<synchronization-pipeline-stages-masks, destination stage mask>> specified 1036by pname:dstStageMask. 1037It is also limited to access types in the <<synchronization-access-masks, 1038destination access mask>> specified by pname:dstAccessMask. 1039 1040The <<synchronization-dependencies-available-and-visible, availability and 1041visibility operations>> defined by a subpass dependency affect the execution 1042of <<renderpass-layout-transitions, image layout transitions>> within the 1043render pass. 1044 1045[NOTE] 1046.Note 1047==== 1048For non-attachment resources, the memory dependency expressed by subpass 1049dependency is nearly identical to that of a slink:VkMemoryBarrier (with 1050matching pname:srcAccessMask/pname:dstAccessMask parameters) submitted as a 1051part of a flink:vkCmdPipelineBarrier (with matching 1052pname:srcStageMask/pname:dstStageMask parameters). 1053The only difference being that its scopes are limited to the identified 1054subpasses rather than potentially affecting everything before and after. 1055 1056For attachments however, subpass dependencies work more like a 1057slink:VkImageMemoryBarrier defined similarly to the slink:VkMemoryBarrier 1058above, the queue family indices set to ename:VK_QUEUE_FAMILY_IGNORED, and 1059layouts as follows: 1060 1061 * The equivalent to pname:oldLayout is the attachment's layout according 1062 to the subpass description for pname:srcSubpass. 1063 * The equivalent to pname:newLayout is the attachment's layout according 1064 to the subpass description for pname:dstSubpass. 1065==== 1066 1067.Valid Usage 1068**** 1069 * [[VUID-VkSubpassDependency-srcSubpass-00858]] 1070 If pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:srcStageMask 1071 must: not include ename:VK_PIPELINE_STAGE_HOST_BIT 1072 * [[VUID-VkSubpassDependency-dstSubpass-00859]] 1073 If pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:dstStageMask 1074 must: not include ename:VK_PIPELINE_STAGE_HOST_BIT 1075 * [[VUID-VkSubpassDependency-srcStageMask-00860]] 1076 If the <<features-features-geometryShader,geometry shaders>> feature is 1077 not enabled, pname:srcStageMask must: not contain 1078 ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 1079 * [[VUID-VkSubpassDependency-dstStageMask-00861]] 1080 If the <<features-features-geometryShader,geometry shaders>> feature is 1081 not enabled, pname:dstStageMask must: not contain 1082 ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 1083 * [[VUID-VkSubpassDependency-srcStageMask-00862]] 1084 If the <<features-features-tessellationShader,tessellation shaders>> 1085 feature is not enabled, pname:srcStageMask must: not contain 1086 ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or 1087 ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT 1088 * [[VUID-VkSubpassDependency-dstStageMask-00863]] 1089 If the <<features-features-tessellationShader,tessellation shaders>> 1090 feature is not enabled, pname:dstStageMask must: not contain 1091 ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or 1092 ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT 1093 * [[VUID-VkSubpassDependency-srcSubpass-00864]] 1094 pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless 1095 one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies 1096 and ensure a valid execution order 1097 * [[VUID-VkSubpassDependency-srcSubpass-00865]] 1098 pname:srcSubpass and pname:dstSubpass must: not both be equal to 1099 ename:VK_SUBPASS_EXTERNAL 1100 * [[VUID-VkSubpassDependency-srcSubpass-01989]] 1101 If pname:srcSubpass is equal to pname:dstSubpass, pname:srcStageMask and 1102 pname:dstStageMask must: not set any bits that are not 1103 ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT, or not one of the 1104 <<synchronization-pipeline-stages-types,graphics pipeline stages>> 1105 * [[VUID-VkSubpassDependency-srcSubpass-00867]] 1106 If pname:srcSubpass is equal to pname:dstSubpass and not all of the 1107 stages in pname:srcStageMask and pname:dstStageMask are 1108 <<synchronization-framebuffer-regions,framebuffer-space stages>>, the 1109 <<synchronization-pipeline-stages-order, logically latest>> pipeline 1110 stage in pname:srcStageMask must: be 1111 <<synchronization-pipeline-stages-order, logically earlier>> than or 1112 equal to the <<synchronization-pipeline-stages-order, logically 1113 earliest>> pipeline stage in pname:dstStageMask 1114 * [[VUID-VkSubpassDependency-srcAccessMask-00868]] 1115 Any access flag included in pname:srcAccessMask must: be supported by 1116 one of the pipeline stages in pname:srcStageMask, as specified in the 1117 <<synchronization-access-types-supported, table of supported access 1118 types>>. 1119 * [[VUID-VkSubpassDependency-dstAccessMask-00869]] 1120 Any access flag included in pname:dstAccessMask must: be supported by 1121 one of the pipeline stages in pname:dstStageMask, as specified in the 1122 <<synchronization-access-types-supported, table of supported access 1123 types>>. 1124ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1125 * [[VUID-VkSubpassDependency-dependencyFlags-00870]] 1126 If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, 1127 then both pname:srcSubpass and pname:dstSubpass must: not equal 1128 ename:VK_SUBPASS_EXTERNAL 1129 * [[VUID-VkSubpassDependency-dependencyFlags-00871]] 1130 If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, 1131 then the render pass must: have multiview enabled 1132 * [[VUID-VkSubpassDependency-srcSubpass-00872]] 1133 If pname:srcSubpass equals pname:dstSubpass and that subpass has more 1134 than one bit set in the view mask, then pname:dependencyFlags must: 1135 include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT 1136endif::VK_VERSION_1_1,VK_KHR_multiview[] 1137**** 1138 1139include::../validity/structs/VkSubpassDependency.txt[] 1140-- 1141 1142ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1143 1144When multiview is enabled, the execution of the multiple views of one 1145subpass may: not occur simultaneously or even back-to-back, and rather may: 1146be interleaved with the execution of other subpasses. 1147The load and store operations apply to attachments on a per-view basis. 1148For example, an attachment using ename:VK_ATTACHMENT_LOAD_OP_CLEAR will have 1149each view cleared on first use, but the first use of one view may be 1150temporally distant from the first use of another view. 1151 1152[NOTE] 1153.Note 1154==== 1155A good mental model for multiview is to think of a multiview subpass as if 1156it were a collection of individual (per-view) subpasses that are logically 1157grouped together and described as a single multiview subpass in the API. 1158Similarly, a multiview attachment can be thought of like several individual 1159attachments that happen to be layers in a single image. 1160A view-local dependency between two multiview subpasses acts like a set of 1161one-to-one dependencies between corresponding pairs of per-view subpasses. 1162A view-global dependency between two multiview subpasses acts like a set of 1163[eq]#N {times} M# dependencies between all pairs of per-view subpasses in 1164the source and destination. 1165Thus, it is a more compact representation which also makes clear the 1166commonality and reuse that is present between views in a subpass. 1167This interpretation motivates the answers to questions like "`when does the 1168load op apply`" - it is on the first use of each view of an attachment, as 1169if each view were a separate attachment. 1170==== 1171 1172endif::VK_VERSION_1_1,VK_KHR_multiview[] 1173 1174ifdef::editing-notes[] 1175[NOTE] 1176.editing-note 1177==== 1178The following two alleged implicit dependencies are practically no-ops, as 1179the operations they describe are already guaranteed by semaphores and 1180submission order (so they're almost entirely no-ops on their own). 1181The *only* reason they exist is because it simplifies reasoning about where 1182<<renderpass-layout-transitions, automatic layout transitions>> happen. 1183Further rewrites of this chapter could potentially remove the need for 1184these. 1185==== 1186endif::editing-notes[] 1187 1188If there is no subpass dependency from ename:VK_SUBPASS_EXTERNAL to the 1189first subpass that uses an attachment, then an implicit subpass dependency 1190exists from ename:VK_SUBPASS_EXTERNAL to the first subpass it is used in. 1191The subpass dependency operates as if defined with the following parameters: 1192 1193[source,c] 1194--------------------------------------------------- 1195VkSubpassDependency implicitDependency = { 1196 .srcSubpass = VK_SUBPASS_EXTERNAL; 1197 .dstSubpass = firstSubpass; // First subpass attachment is used in 1198 .srcStageMask = VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT; 1199 .dstStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT; 1200 .srcAccessMask = 0; 1201 .dstAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT | 1202 VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | 1203 VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | 1204 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT | 1205 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT; 1206 .dependencyFlags = 0; 1207}; 1208--------------------------------------------------- 1209 1210Similarly, if there is no subpass dependency from the last subpass that uses 1211an attachment to ename:VK_SUBPASS_EXTERNAL, then an implicit subpass 1212dependency exists from the last subpass it is used in to 1213ename:VK_SUBPASS_EXTERNAL. 1214The subpass dependency operates as if defined with the following parameters: 1215 1216[source,c] 1217--------------------------------------------------- 1218VkSubpassDependency implicitDependency = { 1219 .srcSubpass = lastSubpass; // Last subpass attachment is used in 1220 .dstSubpass = VK_SUBPASS_EXTERNAL; 1221 .srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT; 1222 .dstStageMask = VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT; 1223 .srcAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT | 1224 VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | 1225 VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | 1226 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT | 1227 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT; 1228 .dstAccessMask = 0; 1229 .dependencyFlags = 0; 1230}; 1231--------------------------------------------------- 1232 1233[[renderpass-layout-transitions]] 1234As subpasses may: overlap or execute out of order with regards to other 1235subpasses unless a subpass dependency chain describes otherwise, the layout 1236transitions required between subpasses cannot: be known to an application. 1237Instead, an application provides the layout that each attachment must: be in 1238at the start and end of a render pass, and the layout it must: be in during 1239each subpass it is used in. 1240The implementation then must: execute layout transitions between subpasses 1241in order to guarantee that the images are in the layouts required by each 1242subpass, and in the final layout at the end of the render pass. 1243 1244Automatic layout transitions apply to the entire image subresource attached 1245to the framebuffer. 1246ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1247If the attachment view is a 2D or 2D array view of a 3D image, even if the 1248attachment view only refers to a subset of the slices of the selected mip 1249level of the 3D image, automatic layout transitions apply to the entire 1250subresource referenced which is the entire mip level in this case. 1251endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1252 1253Automatic layout transitions away from the layout used in a subpass 1254happen-after the availability operations for all dependencies with that 1255subpass as the pname:srcSubpass. 1256 1257Automatic layout transitions into the layout used in a subpass happen-before 1258the visibility operations for all dependencies with that subpass as the 1259pname:dstSubpass. 1260 1261Automatic layout transitions away from pname:initialLayout happens-after the 1262availability operations for all dependencies with a pname:srcSubpass equal 1263to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses the attachment 1264that will be transitioned. 1265For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, 1266automatic layout transitions away from pname:initialLayout happen-after the 1267availability operations for all dependencies with a pname:srcSubpass equal 1268to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses any aliased 1269attachment. 1270 1271Automatic layout transitions into pname:finalLayout happens-before the 1272visibility operations for all dependencies with a pname:dstSubpass equal to 1273ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses the attachment that 1274will be transitioned. 1275For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, 1276automatic layout transitions into pname:finalLayout happen-before the 1277visibility operations for all dependencies with a pname:dstSubpass equal to 1278ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses any aliased 1279attachment. 1280 1281ifdef::VK_EXT_sample_locations[] 1282 1283The image layout of the depth aspect of a depth/stencil attachment referring 1284to an image created with 1285ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent 1286on the last sample locations used to render to the attachment, thus 1287automatic layout transitions use the sample locations state specified in 1288slink:VkRenderPassSampleLocationsBeginInfoEXT. 1289 1290Automatic layout transitions of an attachment referring to a depth/stencil 1291image created with 1292ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT use the 1293sample locations the image subresource range referenced by the attachment 1294was last rendered with. 1295If the current render pass does not use the attachment as a depth/stencil 1296attachment in any subpass that happens-before, the automatic layout 1297transition uses the sample locations state specified in the 1298pname:sampleLocationsInfo member of the element of the 1299sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pAttachmentInitialSampleLocations 1300array for which the pname:attachmentIndex member equals the attachment index 1301of the attachment, if one is specified. 1302Otherwise, the automatic layout transition uses the sample locations state 1303specified in the pname:sampleLocationsInfo member of the element of the 1304sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pPostSubpassSampleLocations 1305array for which the pname:subpassIndex member equals the index of the 1306subpass that last used the attachment as a depth/stencil attachment, if one 1307is specified. 1308 1309If no sample locations state has been specified for an automatic layout 1310transition performed on an attachment referring to a depth/stencil image 1311created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT 1312the contents of the depth aspect of the depth/stencil attachment become 1313undefined as if the layout of the attachment was transitioned from the 1314ename:VK_IMAGE_LAYOUT_UNDEFINED layout. 1315 1316endif::VK_EXT_sample_locations[] 1317 1318If two subpasses use the same attachment in different layouts, and both 1319layouts are read-only, no subpass dependency needs to be specified between 1320those subpasses. 1321If an implementation treats those layouts separately, it must: insert an 1322implicit subpass dependency between those subpasses to separate the uses in 1323each layout. 1324The subpass dependency operates as if defined with the following parameters: 1325 1326[source,c] 1327--------------------------------------------------- 1328// Used for input attachments 1329VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT; 1330VkAccessFlags inputAttachmentAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT; 1331 1332// Used for depth/stencil attachments 1333VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT; 1334VkAccessFlags depthStencilAttachmentAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT; 1335 1336VkSubpassDependency implicitDependency = { 1337 .srcSubpass = firstSubpass; 1338 .dstSubpass = secondSubpass; 1339 .srcStageMask = inputAttachmentStages | depthStencilAttachmentStages; 1340 .dstStageMask = inputAttachmentStages | depthStencilAttachmentStages; 1341 .srcAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess; 1342 .dstAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess; 1343 .dependencyFlags = 0; 1344}; 1345--------------------------------------------------- 1346 1347[[renderpass-feedbackloop]] 1348If a subpass uses the same attachment as both an input attachment and either 1349a color attachment or a depth/stencil attachment, writes via the color or 1350depth/stencil attachment are not automatically made visible to reads via the 1351input attachment, causing a _feedback loop_, except in any of the following 1352conditions: 1353 1354 * If the color components or depth/stencil components read by the input 1355 attachment are mutually exclusive with the components written by the 1356 color or depth/stencil attachments, then there is no feedback loop. 1357 This requires the graphics pipelines used by the subpass to disable 1358 writes to color components that are read as inputs via the 1359 pname:colorWriteMask, and to disable writes to depth/stencil components 1360 that are read as inputs via pname:depthWriteEnable or 1361 pname:stencilTestEnable. 1362 * If the attachment is used as an input attachment and depth/stencil 1363 attachment only, and the depth/stencil attachment is not written to. 1364 * If a memory dependency is inserted between when the attachment is 1365 written and when it is subsequently read by later fragments. 1366 <<synchronization-pipeline-barriers, Pipeline barriers>> expressing a 1367 <<synchronization-pipeline-barriers-subpass-self-dependencies, subpass 1368 self-dependency>> are the only way to achieve this, and one must: be 1369 inserted every time a fragment will read values at a particular sample 1370 (x, y, layer, sample) coordinate, if those values have been written 1371 since the most recent pipeline barrier; or the since start of the 1372 subpass if there have been no pipeline barriers since the start of the 1373 subpass. 1374 1375An attachment used as both an input attachment and a color attachment must: 1376be in the 1377ifdef::VK_KHR_shared_presentable_image[] 1378ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or 1379endif::VK_KHR_shared_presentable_image[] 1380ename:VK_IMAGE_LAYOUT_GENERAL layout. 1381An attachment used as an input attachment and depth/stencil attachment must: 1382be in the 1383ifdef::VK_KHR_shared_presentable_image[] 1384ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 1385endif::VK_KHR_shared_presentable_image[] 1386ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 1387ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 1388ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 1389endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 1390ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or 1391ename:VK_IMAGE_LAYOUT_GENERAL layout. 1392An attachment must: not be used as both a depth/stencil attachment and a 1393color attachment. 1394 1395ifdef::VK_KHR_create_renderpass2[] 1396 1397A more extensible version of render pass creation is also defined below. 1398 1399[open,refpage='vkCreateRenderPass2KHR',desc='Create a new render pass object',type='protos'] 1400-- 1401 1402To create a render pass, call: 1403 1404include::../api/protos/vkCreateRenderPass2KHR.txt[] 1405 1406 * pname:device is the logical device that creates the render pass. 1407 * pname:pCreateInfo is a pointer to an instance of the 1408 slink:VkRenderPassCreateInfo2KHR structure that describes the parameters 1409 of the render pass. 1410 * pname:pAllocator controls host memory allocation as described in the 1411 <<memory-allocation, Memory Allocation>> chapter. 1412 * pname:pRenderPass points to a sname:VkRenderPass handle in which the 1413 resulting render pass object is returned. 1414 1415This command is functionally identical to flink:vkCreateRenderPass, but 1416includes extensible sub-structures that include pname:sType and pname:pNext 1417parameters, allowing them to be more easily extended. 1418 1419include::../validity/protos/vkCreateRenderPass2KHR.txt[] 1420-- 1421 1422[open,refpage='VkRenderPassCreateInfo2KHR',desc='Structure specifying parameters of a newly created render pass',type='structs'] 1423-- 1424 1425The sname:VkRenderPassCreateInfo2KHR structure is defined as: 1426 1427include::../api/structs/VkRenderPassCreateInfo2KHR.txt[] 1428 1429 * pname:sType is the type of this structure. 1430 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1431 * pname:flags is reserved for future use. 1432 * pname:attachmentCount is the number of attachments used by this render 1433 pass. 1434 * pname:pAttachments points to an array of pname:attachmentCount 1435 slink:VkAttachmentDescription2KHR structures describing the attachments 1436 used by the render pass. 1437 * pname:subpassCount is the number of subpasses to create. 1438 * pname:pSubpasses points to an array of pname:subpassCount 1439 slink:VkSubpassDescription2KHR structures describing each subpass. 1440 * pname:dependencyCount is the number of dependencies between pairs of 1441 subpasses. 1442 * pname:pDependencies points to an array of pname:dependencyCount 1443 slink:VkSubpassDependency2KHR structures describing dependencies between 1444 pairs of subpasses. 1445 * pname:correlatedViewMaskCount is the number of correlation masks. 1446 * pname:pCorrelatedViewMasks is an array of view masks indicating sets of 1447 views that may: be more efficient to render concurrently. 1448 1449Parameters defined by this structure with the same name as those in 1450slink:VkRenderPassCreateInfo have the identical effect to those parameters; 1451the child structures are variants of those used in 1452slink:VkRenderPassCreateInfo which include pname:sType and pname:pNext 1453parameters, allowing them to be extended. 1454 1455If the slink:VkSubpassDescription2KHR::pname:viewMask member of any element 1456of pname:pSubpasses is not zero, _multiview_ functionality is considered to 1457be enabled for this render pass. 1458 1459pname:correlatedViewMaskCount and pname:pCorrelatedViewMasks have the same 1460effect as slink:VkRenderPassMultiviewCreateInfo::pname:correlationMaskCount 1461and slink:VkRenderPassMultiviewCreateInfo::pname:pCorrelationMasks, 1462respectively. 1463 1464.Valid Usage 1465**** 1466 * [[VUID-VkRenderPassCreateInfo2KHR-None-03049]] 1467 If any two subpasses operate on attachments with overlapping ranges of 1468 the same sname:VkDeviceMemory object, and at least one subpass writes to 1469 that area of sname:VkDeviceMemory, a subpass dependency must: be 1470 included (either directly or via some intermediate subpasses) between 1471 them 1472 * [[VUID-VkRenderPassCreateInfo2KHR-attachment-03050]] 1473 If the pname:attachment member of any element of 1474 pname:pInputAttachments, pname:pColorAttachments, 1475 pname:pResolveAttachments or pname:pDepthStencilAttachment, or the 1476 attachment indexed by any element of pname:pPreserveAttachments in any 1477 given element of pname:pSubpasses is bound to a range of a 1478 sname:VkDeviceMemory object that overlaps with any other attachment in 1479 any subpass (including the same subpass), the 1480 sname:VkAttachmentDescription2KHR structures describing them must: 1481 include ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in pname:flags 1482 * [[VUID-VkRenderPassCreateInfo2KHR-attachment-03051]] 1483 If the pname:attachment member of any element of 1484 pname:pInputAttachments, pname:pColorAttachments, 1485 pname:pResolveAttachments or pname:pDepthStencilAttachment, or any 1486 element of pname:pPreserveAttachments in any given element of 1487 pname:pSubpasses is not ename:VK_ATTACHMENT_UNUSED, it must: be less 1488 than pname:attachmentCount 1489 * [[VUID-VkRenderPassCreateInfo2KHR-pPreserveAttachments-03052]] 1490 The value of any element of the pname:pPreserveAttachments member in any 1491 given element of pname:pSubpasses must: not be 1492 ename:VK_ATTACHMENT_UNUSED 1493 * [[VUID-VkRenderPassCreateInfo2KHR-pAttachments-03053]] 1494 For any member of pname:pAttachments with a pname:loadOp equal to 1495 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 1496 must: not specify a pname:layout equal to 1497 pname:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or 1498 pname:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL. 1499 * [[VUID-VkRenderPassCreateInfo2KHR-pDependencies-03054]] 1500 For any element of pname:pDependencies, if the pname:srcSubpass is not 1501 ename:VK_SUBPASS_EXTERNAL, all stage flags included in the 1502 pname:srcStageMask member of that dependency must: be a pipeline stage 1503 supported by the <<synchronization-pipeline-stages-types, pipeline>> 1504 identified by the pname:pipelineBindPoint member of the source subpass. 1505 * [[VUID-VkRenderPassCreateInfo2KHR-pDependencies-03055]] 1506 For any element of pname:pDependencies, if the pname:dstSubpass is not 1507 ename:VK_SUBPASS_EXTERNAL, all stage flags included in the 1508 pname:dstStageMask member of that dependency must: be a pipeline stage 1509 supported by the <<synchronization-pipeline-stages-types, pipeline>> 1510 identified by the pname:pipelineBindPoint member of the source subpass. 1511 * [[VUID-VkRenderPassCreateInfo2KHR-pCorrelatedViewMasks-03056]] 1512 The set of bits included in any element of pname:pCorrelatedViewMasks 1513 must: not overlap with the set of bits included in any other element of 1514 pname:pCorrelatedViewMasks 1515 * [[VUID-VkRenderPassCreateInfo2KHR-viewMask-03057]] 1516 If the slink:VkSubpassDescription2KHR::pname:viewMask member of all 1517 elements of pname:pSubpasses is `0`, pname:correlatedViewMaskCount must: 1518 be `0` 1519 * [[VUID-VkRenderPassCreateInfo2KHR-viewMask-03058]] 1520 The slink:VkSubpassDescription2KHR::pname:viewMask member of all 1521 elements of pname:pSubpasses must: either all be `0`, or all not be `0` 1522 * [[VUID-VkRenderPassCreateInfo2KHR-viewMask-03059]] 1523 If the slink:VkSubpassDescription2KHR::pname:viewMask member of all 1524 elements of pname:pSubpasses is `0`, the pname:dependencyFlags member of 1525 any element of pname:pDependencies must: not include 1526 ename:VK_DEPENDENCY_VIEW_LOCAL_BIT 1527 * [[VUID-VkRenderPassCreateInfo2KHR-pDependencies-03060]] 1528 For any element of pname:pDependencies where its pname:srcSubpass member 1529 equals its pname:dstSubpass member, if the pname:viewMask member of the 1530 corresponding element of pname:pSubpasses includes more than one bit, 1531 its pname:dependencyFlags member must: include 1532 ename:VK_DEPENDENCY_VIEW_LOCAL_BIT 1533**** 1534 1535include::../validity/structs/VkRenderPassCreateInfo2KHR.txt[] 1536-- 1537 1538[open,refpage='VkAttachmentDescription2KHR',desc='Structure specifying an attachment description',type='structs'] 1539-- 1540 1541The sname:VkAttachmentDescription2KHR structure is defined as: 1542 1543include::../api/structs/VkAttachmentDescription2KHR.txt[] 1544 1545 * pname:sType is the type of this structure. 1546 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1547 * pname:flags is a bitmask of elink:VkAttachmentDescription2KHRFlagBits 1548 specifying additional properties of the attachment. 1549 * pname:format is a elink:VkFormat value specifying the format of the 1550 image that will be used for the attachment. 1551 * pname:samples is the number of samples of the image as defined in 1552 elink:VkSampleCountFlagBits. 1553 * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the 1554 contents of color and depth components of the attachment are treated at 1555 the beginning of the subpass where it is first used. 1556 * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the 1557 contents of color and depth components of the attachment are treated at 1558 the end of the subpass where it is last used. 1559 * pname:stencilLoadOp is a elink:VkAttachmentLoadOp value specifying how 1560 the contents of stencil components of the attachment are treated at the 1561 beginning of the subpass where it is first used. 1562 * pname:stencilStoreOp is a elink:VkAttachmentStoreOp value specifying how 1563 the contents of stencil components of the attachment are treated at the 1564 end of the last subpass where it is used. 1565 * pname:initialLayout is the layout the attachment image subresource will 1566 be in when a render pass instance begins. 1567 * pname:finalLayout is the layout the attachment image subresource will be 1568 transitioned to when a render pass instance ends. 1569 1570Parameters defined by this structure with the same name as those in 1571slink:VkAttachmentDescription have the identical effect to those parameters. 1572 1573.Valid Usage 1574**** 1575 * [[VUID-VkAttachmentDescription2KHR-finalLayout-03061]] 1576 pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or 1577 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 1578**** 1579 1580include::../validity/structs/VkAttachmentDescription2KHR.txt[] 1581-- 1582 1583[open,refpage='VkSubpassDescription2KHR',desc='Structure specifying a subpass description',type='structs'] 1584-- 1585 1586The sname:VkSubpassDescription2KHR structure is defined as: 1587 1588include::../api/structs/VkSubpassDescription2KHR.txt[] 1589 1590 * pname:sType is the type of this structure. 1591 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1592 * pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits 1593 specifying usage of the subpass. 1594 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying 1595 the pipeline type supported for this subpass. 1596 * pname:viewMask is a bitfield of view indices describing which views 1597 rendering is broadcast to in this subpass, when multiview is enabled. 1598 * pname:inputAttachmentCount is the number of input attachments. 1599 * pname:pInputAttachments is an array of slink:VkAttachmentReference 1600 structures defining the input attachments for this subpass and their 1601 layouts. 1602 * pname:colorAttachmentCount is the number of color attachments. 1603 * pname:pColorAttachments is an array of slink:VkAttachmentReference 1604 structures defining the color attachments for this subpass and their 1605 layouts. 1606 * pname:pResolveAttachments is an optional array of 1607 pname:colorAttachmentCount slink:VkAttachmentReference structures 1608 defining the resolve attachments for this subpass and their layouts. 1609 * pname:pDepthStencilAttachment is a pointer to a 1610 slink:VkAttachmentReference specifying the depth/stencil attachment for 1611 this subpass and its layout. 1612 * pname:preserveAttachmentCount is the number of preserved attachments. 1613 * pname:pPreserveAttachments is an array of pname:preserveAttachmentCount 1614 render pass attachment indices identifying attachments that are not used 1615 by this subpass, but whose contents must: be preserved throughout the 1616 subpass. 1617 1618Parameters defined by this structure with the same name as those in 1619slink:VkSubpassDescription have the identical effect to those parameters. 1620 1621pname:viewMask has the same effect for the described subpass as 1622slink:VkRenderPassMultiviewCreateInfo::pname:pViewMasks has on each 1623corresponding subpass. 1624 1625.Valid Usage 1626**** 1627 * [[VUID-VkSubpassDescription2KHR-pipelineBindPoint-03062]] 1628 pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS 1629 * [[VUID-VkSubpassDescription2KHR-colorAttachmentCount-03063]] 1630 pname:colorAttachmentCount must: be less than or equal to 1631 sname:VkPhysicalDeviceLimits::pname:maxColorAttachments 1632 * [[VUID-VkSubpassDescription2KHR-loadOp-03064]] 1633 If the first use of an attachment in this render pass is as an input 1634 attachment, and the attachment is not also used as a color or 1635 depth/stencil attachment in the same subpass, then pname:loadOp must: 1636 not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR 1637 * [[VUID-VkSubpassDescription2KHR-pResolveAttachments-03065]] 1638 If pname:pResolveAttachments is not `NULL`, for each resolve attachment 1639 that does not have the value ename:VK_ATTACHMENT_UNUSED, the 1640 corresponding color attachment must: not have the value 1641 ename:VK_ATTACHMENT_UNUSED 1642 * [[VUID-VkSubpassDescription2KHR-pResolveAttachments-03066]] 1643 If pname:pResolveAttachments is not `NULL`, the sample count of each 1644 element of pname:pColorAttachments must: be anything other than 1645 ename:VK_SAMPLE_COUNT_1_BIT 1646 * [[VUID-VkSubpassDescription2KHR-pResolveAttachments-03067]] 1647 Any given element of pname:pResolveAttachments must: have a sample count 1648 of ename:VK_SAMPLE_COUNT_1_BIT 1649 * [[VUID-VkSubpassDescription2KHR-pResolveAttachments-03068]] 1650 Any given element of pname:pResolveAttachments must: have the same 1651 elink:VkFormat as its corresponding color attachment 1652 * [[VUID-VkSubpassDescription2KHR-pColorAttachments-03069]] 1653 All attachments in pname:pColorAttachments that are not 1654 ename:VK_ATTACHMENT_UNUSED must: have the same sample count 1655ifdef::VK_AMD_mixed_attachment_samples[] 1656 * [[VUID-VkSubpassDescription2KHR-pColorAttachments-03070]] 1657 All attachments in pname:pColorAttachments that are not 1658 ename:VK_ATTACHMENT_UNUSED must: have a sample count that is smaller 1659 than or equal to the sample count of pname:pDepthStencilAttachment if it 1660 is not ename:VK_ATTACHMENT_UNUSED 1661endif::VK_AMD_mixed_attachment_samples[] 1662ifndef::VK_AMD_mixed_attachment_samples[] 1663ifndef::VK_NV_framebuffer_mixed_samples[] 1664 * [[VUID-VkSubpassDescription2KHR-pDepthStencilAttachment-03071]] 1665 If pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and 1666 any attachments in pname:pColorAttachments are not 1667 ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count 1668endif::VK_NV_framebuffer_mixed_samples[] 1669endif::VK_AMD_mixed_attachment_samples[] 1670 * [[VUID-VkSubpassDescription2KHR-None-03072]] 1671 If any input attachments are ename:VK_ATTACHMENT_UNUSED, then any 1672 pipelines bound during the subpass must: not access those input 1673 attachments from the fragment shader 1674 * [[VUID-VkSubpassDescription2KHR-attachment-03073]] 1675 The pname:attachment member of any element of pname:pPreserveAttachments 1676 must: not be ename:VK_ATTACHMENT_UNUSED 1677 * [[VUID-VkSubpassDescription2KHR-pPreserveAttachments-03074]] 1678 Any given element of pname:pPreserveAttachments must: not also be an 1679 element of any other member of the subpass description 1680 * [[VUID-VkSubpassDescription2KHR-layout-03075]] 1681 If any attachment is used as both an input attachment and a color or 1682 depth/stencil attachment, then each use must: use the same pname:layout 1683ifdef::VK_NVX_multiview_per_view_attributes[] 1684 * [[VUID-VkSubpassDescription2KHR-flags-03076]] 1685 If pname:flags includes 1686 ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must: 1687 also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX. 1688endif::VK_NVX_multiview_per_view_attributes[] 1689 * [[VUID-VkSubpassDescription2KHR-aspectMask-03175]] 1690 The pname:aspectMask member of any element of pname:pInputAttachments 1691 must: be a valid combination of elink:VkImageAspectFlagBits 1692 * [[VUID-VkSubpassDescription2KHR-aspectMask-03176]] 1693 The pname:aspectMask member of any element of pname:pInputAttachments 1694 must: not be `0` 1695**** 1696 1697include::../validity/structs/VkSubpassDescription2KHR.txt[] 1698-- 1699 1700 1701[open,refpage='VkAttachmentReference2KHR',desc='Structure specifying an attachment reference',type='structs'] 1702-- 1703 1704The sname:VkAttachmentReference2KHR structure is defined as: 1705 1706include::../api/structs/VkAttachmentReference2KHR.txt[] 1707 1708 * pname:sType is the type of this structure. 1709 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1710 * pname:attachment is either an integer value identifying an attachment at 1711 the corresponding index in 1712 slink:VkRenderPassCreateInfo::pname:pAttachments, or 1713 ename:VK_ATTACHMENT_UNUSED to signify that this attachment is not used. 1714 * pname:layout is a elink:VkImageLayout value specifying the layout the 1715 attachment uses during the subpass. 1716 * pname:aspectMask is a mask of which aspect(s) can: be accessed within 1717 the specified subpass as an input attachment. 1718 1719Parameters defined by this structure with the same name as those in 1720slink:VkAttachmentReference have the identical effect to those parameters. 1721 1722pname:aspectMask has the same effect for the described attachment as 1723slink:VkInputAttachmentAspectReference::pname:aspectMask has on each 1724corresponding attachment. 1725It is ignored when this structure is used to describe anything other than an 1726input attachment reference. 1727 1728.Valid Usage 1729**** 1730 * [[VUID-VkAttachmentReference2KHR-layout-03077]] 1731 pname:layout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or 1732 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 1733**** 1734 1735include::../validity/structs/VkAttachmentReference2KHR.txt[] 1736-- 1737 1738[open,refpage='VkSubpassDependency2KHR',desc='Structure specifying a subpass dependency',type='structs'] 1739-- 1740 1741The sname:VkSubpassDependency2KHR structure is defined as: 1742 1743include::../api/structs/VkSubpassDependency2KHR.txt[] 1744 1745 * pname:sType is the type of this structure. 1746 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1747 * pname:srcSubpass is the subpass index of the first subpass in the 1748 dependency, or ename:VK_SUBPASS_EXTERNAL. 1749 * pname:dstSubpass is the subpass index of the second subpass in the 1750 dependency, or ename:VK_SUBPASS_EXTERNAL. 1751 * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits 1752 specifying the <<synchronization-pipeline-stages-masks, source stage 1753 mask>>. 1754 * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits 1755 specifying the <<synchronization-pipeline-stages-masks, destination 1756 stage mask>> 1757 * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 1758 <<synchronization-access-masks, source access mask>>. 1759 * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 1760 <<synchronization-access-masks, destination access mask>>. 1761 * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits. 1762 * pname:viewOffset controls which views in the source subpass the views in 1763 the destination subpass depend on. 1764 1765Parameters defined by this structure with the same name as those in 1766slink:VkSubpassDependency have the identical effect to those parameters. 1767 1768pname:viewOffset has the same effect for the described subpass dependency as 1769slink:VkRenderPassMultiviewCreateInfo::pname:pViewOffsets has on each 1770corresponding subpass dependency. 1771 1772.Valid Usage 1773**** 1774 * [[VUID-VkSubpassDependency2KHR-srcSubpass-03078]] 1775 If pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:srcStageMask 1776 must: not include ename:VK_PIPELINE_STAGE_HOST_BIT 1777 * [[VUID-VkSubpassDependency2KHR-dstSubpass-03079]] 1778 If pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:dstStageMask 1779 must: not include ename:VK_PIPELINE_STAGE_HOST_BIT 1780 * [[VUID-VkSubpassDependency2KHR-srcStageMask-03080]] 1781 If the <<features-features-geometryShader,geometry shaders>> feature is 1782 not enabled, pname:srcStageMask must: not contain 1783 ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 1784 * [[VUID-VkSubpassDependency2KHR-dstStageMask-03081]] 1785 If the <<features-features-geometryShader,geometry shaders>> feature is 1786 not enabled, pname:dstStageMask must: not contain 1787 ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 1788 * [[VUID-VkSubpassDependency2KHR-srcStageMask-03082]] 1789 If the <<features-features-tessellationShader,tessellation shaders>> 1790 feature is not enabled, pname:srcStageMask must: not contain 1791 ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or 1792 ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT 1793 * [[VUID-VkSubpassDependency2KHR-dstStageMask-03083]] 1794 If the <<features-features-tessellationShader,tessellation shaders>> 1795 feature is not enabled, pname:dstStageMask must: not contain 1796 ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or 1797 ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT 1798 * [[VUID-VkSubpassDependency2KHR-srcSubpass-03084]] 1799 pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless 1800 one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies 1801 and ensure a valid execution order 1802 * [[VUID-VkSubpassDependency2KHR-srcSubpass-03085]] 1803 pname:srcSubpass and pname:dstSubpass must: not both be equal to 1804 ename:VK_SUBPASS_EXTERNAL 1805 * [[VUID-VkSubpassDependency2KHR-srcSubpass-03086]] 1806 If pname:srcSubpass is equal to pname:dstSubpass, pname:srcStageMask and 1807 pname:dstStageMask must: only contain one of 1808 ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT, 1809 ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT, 1810 ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT, 1811 ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, 1812 ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, 1813 ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, 1814 ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, 1815 ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, 1816 ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT, 1817 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT, 1818 ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT, 1819 ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, or 1820 ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT 1821 * [[VUID-VkSubpassDependency2KHR-srcSubpass-03087]] 1822 If pname:srcSubpass is equal to pname:dstSubpass and not all of the 1823 stages in pname:srcStageMask and pname:dstStageMask are 1824 <<synchronization-framebuffer-regions,framebuffer-space stages>>, the 1825 <<synchronization-pipeline-stages-order, logically latest>> pipeline 1826 stage in pname:srcStageMask must: be 1827 <<synchronization-pipeline-stages-order, logically earlier>> than or 1828 equal to the <<synchronization-pipeline-stages-order, logically 1829 earliest>> pipeline stage in pname:dstStageMask 1830 * [[VUID-VkSubpassDependency2KHR-srcAccessMask-03088]] 1831 Any access flag included in pname:srcAccessMask must: be supported by 1832 one of the pipeline stages in pname:srcStageMask, as specified in the 1833 <<synchronization-access-types-supported, table of supported access 1834 types>> 1835 * [[VUID-VkSubpassDependency2KHR-dstAccessMask-03089]] 1836 Any access flag included in pname:dstAccessMask must: be supported by 1837 one of the pipeline stages in pname:dstStageMask, as specified in the 1838 <<synchronization-access-types-supported, table of supported access 1839 types>> 1840 * [[VUID-VkSubpassDependency2KHR-dependencyFlags-03090]] 1841 If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, 1842 pname:srcSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL 1843 * [[VUID-VkSubpassDependency2KHR-dependencyFlags-03091]] 1844 If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, 1845 pname:dstSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL 1846 * [[VUID-VkSubpassDependency2KHR-dependencyFlags-03092]] 1847 If pname:dependencyFlags does not include 1848 ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, pname:viewOffset must: be `0` 1849 * [[VUID-VkSubpassDependency2KHR-viewOffset-03093]] 1850 If pname:viewOffset is not `0`, pname:srcSubpass must: not be equal to 1851 pname:dstSubpass. 1852**** 1853 1854include::../validity/structs/VkSubpassDependency2KHR.txt[] 1855-- 1856 1857 1858endif::VK_KHR_create_renderpass2[] 1859 1860 1861[open,refpage='vkDestroyRenderPass',desc='Destroy a render pass object',type='protos'] 1862-- 1863 1864To destroy a render pass, call: 1865 1866include::../api/protos/vkDestroyRenderPass.txt[] 1867 1868 * pname:device is the logical device that destroys the render pass. 1869 * pname:renderPass is the handle of the render pass to destroy. 1870 * pname:pAllocator controls host memory allocation as described in the 1871 <<memory-allocation, Memory Allocation>> chapter. 1872 1873.Valid Usage 1874**** 1875 * [[VUID-vkDestroyRenderPass-renderPass-00873]] 1876 All submitted commands that refer to pname:renderPass must: have 1877 completed execution 1878 * [[VUID-vkDestroyRenderPass-renderPass-00874]] 1879 If sname:VkAllocationCallbacks were provided when pname:renderPass was 1880 created, a compatible set of callbacks must: be provided here 1881 * [[VUID-vkDestroyRenderPass-renderPass-00875]] 1882 If no sname:VkAllocationCallbacks were provided when pname:renderPass 1883 was created, pname:pAllocator must: be `NULL` 1884**** 1885 1886include::../validity/protos/vkDestroyRenderPass.txt[] 1887-- 1888 1889 1890[[renderpass-compatibility]] 1891== Render Pass Compatibility 1892 1893Framebuffers and graphics pipelines are created based on a specific render 1894pass object. 1895They must: only be used with that render pass object, or one compatible with 1896it. 1897 1898Two attachment references are compatible if they have matching format and 1899sample count, or are both ename:VK_ATTACHMENT_UNUSED or the pointer that 1900would contain the reference is `NULL`. 1901 1902Two arrays of attachment references are compatible if all corresponding 1903pairs of attachments are compatible. 1904If the arrays are of different lengths, attachment references not present in 1905the smaller array are treated as ename:VK_ATTACHMENT_UNUSED. 1906 1907Two render passes are compatible if their corresponding color, input, 1908resolve, and depth/stencil attachment references are compatible and if they 1909are otherwise identical except for: 1910 1911 * Initial and final image layout in attachment descriptions 1912 * Load and store operations in attachment descriptions 1913 * Image layout in attachment references 1914 1915A framebuffer is compatible with a render pass if it was created using the 1916same render pass or a compatible render pass. 1917 1918 1919== Framebuffers 1920 1921[open,refpage='VkFramebuffer',desc='Opaque handle to a framebuffer object',type='handles'] 1922-- 1923 1924Render passes operate in conjunction with _framebuffers_. 1925Framebuffers represent a collection of specific memory attachments that a 1926render pass instance uses. 1927 1928Framebuffers are represented by sname:VkFramebuffer handles: 1929 1930include::../api/handles/VkFramebuffer.txt[] 1931 1932-- 1933 1934[open,refpage='vkCreateFramebuffer',desc='Create a new framebuffer object',type='protos'] 1935-- 1936 1937To create a framebuffer, call: 1938 1939include::../api/protos/vkCreateFramebuffer.txt[] 1940 1941 * pname:device is the logical device that creates the framebuffer. 1942 * pname:pCreateInfo points to a slink:VkFramebufferCreateInfo structure 1943 which describes additional information about framebuffer creation. 1944 * pname:pAllocator controls host memory allocation as described in the 1945 <<memory-allocation, Memory Allocation>> chapter. 1946 * pname:pFramebuffer points to a slink:VkFramebuffer handle in which the 1947 resulting framebuffer object is returned. 1948 1949include::../validity/protos/vkCreateFramebuffer.txt[] 1950-- 1951 1952[open,refpage='VkFramebufferCreateInfo',desc='Structure specifying parameters of a newly created framebuffer',type='structs'] 1953-- 1954 1955The sname:VkFramebufferCreateInfo structure is defined as: 1956 1957include::../api/structs/VkFramebufferCreateInfo.txt[] 1958 1959 * pname:sType is the type of this structure. 1960 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1961 * pname:flags is reserved for future use. 1962 * pname:renderPass is a render pass that defines what render passes the 1963 framebuffer will be compatible with. 1964 See <<renderpass-compatibility,Render Pass Compatibility>> for details. 1965 * pname:attachmentCount is the number of attachments. 1966 * pname:pAttachments is an array of slink:VkImageView handles, each of 1967 which will be used as the corresponding attachment in a render pass 1968 instance. 1969 * pname:width, pname:height and pname:layers define the dimensions of the 1970 framebuffer. 1971ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1972 If the render pass uses multiview, then pname:layers must: be one and 1973 each attachment requires a number of layers that is greater than the 1974 maximum bit index set in the view mask in the subpasses in which it is 1975 used. 1976endif::VK_VERSION_1_1,VK_KHR_multiview[] 1977 1978Applications must: ensure that all accesses to memory that backs image 1979subresources used as attachments in a given renderpass instance either 1980happen-before the <<renderpass-load-store-ops, load operations>> for those 1981attachments, or happen-after the <<renderpass-load-store-ops, store 1982operations>> for those attachments. 1983 1984ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 1985For depth/stencil attachments, each aspect can: be used separately as 1986attachments and non-attachments as long as the non-attachment accesses are 1987also via an image subresource in either the 1988ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL layout or 1989the ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL layout, 1990and the attachment resource uses whichever of those two layouts the image 1991accesses do not. 1992Use of non-attachment aspects in this case is only well defined if the 1993attachment is used in the subpass where the non-attachment access is being 1994made, or the layout of the image subresource is constant throughout the 1995entire render pass instance, including the pname:initialLayout and 1996pname:finalLayout. 1997endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 1998 1999[NOTE] 2000.Note 2001==== 2002ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2003This restriction means 2004endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2005ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2006These restrictions mean 2007endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2008that the render pass has full knowledge of all uses of all of the 2009attachments, so that the implementation is able to make correct decisions 2010about when and how to perform layout transitions, when to overlap execution 2011of subpasses, etc. 2012==== 2013 2014 2015[[renderpass-noattachments]] 2016It is legal for a subpass to use no color or depth/stencil attachments, and 2017rather use shader side effects such as image stores and atomics to produce 2018an output. 2019In this case, the subpass continues to use the pname:width, pname:height, 2020and pname:layers of the framebuffer to define the dimensions of the 2021rendering area, and the pname:rasterizationSamples from each pipeline's 2022slink:VkPipelineMultisampleStateCreateInfo to define the number of samples 2023used in rasterization; however, if 2024slink:VkPhysicalDeviceFeatures::pname:variableMultisampleRate is 2025code:VK_FALSE, then all pipelines to be bound with a given zero-attachment 2026subpass must: have the same value for 2027slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples. 2028 2029.Valid Usage 2030**** 2031 * [[VUID-VkFramebufferCreateInfo-attachmentCount-00876]] 2032 pname:attachmentCount must: be equal to the attachment count specified 2033 in pname:renderPass 2034 * [[VUID-VkFramebufferCreateInfo-pAttachments-00877]] 2035 Each element of pname:pAttachments that is used as a color attachment or 2036 resolve attachment by pname:renderPass must: have been created with a 2037 pname:usage value including ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 2038 * [[VUID-VkFramebufferCreateInfo-pAttachments-00878]] 2039 Each element of pname:pAttachments that is used as a depth/stencil 2040 attachment by pname:renderPass must: have been created with a 2041 pname:usage value including 2042 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 2043 * [[VUID-VkFramebufferCreateInfo-pAttachments-00879]] 2044 Each element of pname:pAttachments that is used as an input attachment 2045 by pname:renderPass must: have been created with a pname:usage value 2046 including ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 2047 * [[VUID-VkFramebufferCreateInfo-pAttachments-00880]] 2048 Each element of pname:pAttachments must: have been created with an 2049 elink:VkFormat value that matches the elink:VkFormat specified by the 2050 corresponding sname:VkAttachmentDescription in pname:renderPass 2051 * [[VUID-VkFramebufferCreateInfo-pAttachments-00881]] 2052 Each element of pname:pAttachments must: have been created with a 2053 pname:samples value that matches the pname:samples value specified by 2054 the corresponding sname:VkAttachmentDescription in pname:renderPass 2055 * [[VUID-VkFramebufferCreateInfo-pAttachments-00882]] 2056 Each element of pname:pAttachments must: have dimensions at least as 2057 large as the corresponding framebuffer dimension 2058 * [[VUID-VkFramebufferCreateInfo-pAttachments-00883]] 2059 Each element of pname:pAttachments must: only specify a single mip level 2060 * [[VUID-VkFramebufferCreateInfo-pAttachments-00884]] 2061 Each element of pname:pAttachments must: have been created with the 2062 identity swizzle 2063 * [[VUID-VkFramebufferCreateInfo-width-00885]] 2064 pname:width must: be greater than `0`. 2065 * [[VUID-VkFramebufferCreateInfo-width-00886]] 2066 pname:width must: be less than or equal to 2067 sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth 2068 * [[VUID-VkFramebufferCreateInfo-height-00887]] 2069 pname:height must: be greater than `0`. 2070 * [[VUID-VkFramebufferCreateInfo-height-00888]] 2071 pname:height must: be less than or equal to 2072 sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight 2073 * [[VUID-VkFramebufferCreateInfo-layers-00889]] 2074 pname:layers must: be greater than `0`. 2075 * [[VUID-VkFramebufferCreateInfo-layers-00890]] 2076 pname:layers must: be less than or equal to 2077 sname:VkPhysicalDeviceLimits::pname:maxFramebufferLayers 2078ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2079 * [[VUID-VkFramebufferCreateInfo-pAttachments-00891]] 2080 Each element of pname:pAttachments that is a 2D or 2D array image view 2081 taken from a 3D image must: not be a depth/stencil format 2082endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2083**** 2084 2085include::../validity/structs/VkFramebufferCreateInfo.txt[] 2086-- 2087 2088[open,refpage='VkFramebufferCreateFlags',desc='Reserved for future use',type='enums'] 2089-- 2090include::../api/flags/VkFramebufferCreateFlags.txt[] 2091 2092sname:VkFramebufferCreateFlags is a bitmask type for setting a mask, but is 2093currently reserved for future use. 2094-- 2095 2096[open,refpage='vkDestroyFramebuffer',desc='Destroy a framebuffer object',type='protos'] 2097-- 2098 2099To destroy a framebuffer, call: 2100 2101include::../api/protos/vkDestroyFramebuffer.txt[] 2102 2103 * pname:device is the logical device that destroys the framebuffer. 2104 * pname:framebuffer is the handle of the framebuffer to destroy. 2105 * pname:pAllocator controls host memory allocation as described in the 2106 <<memory-allocation, Memory Allocation>> chapter. 2107 2108.Valid Usage 2109**** 2110 * [[VUID-vkDestroyFramebuffer-framebuffer-00892]] 2111 All submitted commands that refer to pname:framebuffer must: have 2112 completed execution 2113 * [[VUID-vkDestroyFramebuffer-framebuffer-00893]] 2114 If sname:VkAllocationCallbacks were provided when pname:framebuffer was 2115 created, a compatible set of callbacks must: be provided here 2116 * [[VUID-vkDestroyFramebuffer-framebuffer-00894]] 2117 If no sname:VkAllocationCallbacks were provided when pname:framebuffer 2118 was created, pname:pAllocator must: be `NULL` 2119**** 2120 2121include::../validity/protos/vkDestroyFramebuffer.txt[] 2122-- 2123 2124 2125[[renderpass-commands]] 2126== Render Pass Commands 2127 2128An application records the commands for a render pass instance one subpass 2129at a time, by beginning a render pass instance, iterating over the subpasses 2130to record commands for that subpass, and then ending the render pass 2131instance. 2132 2133[open,refpage='vkCmdBeginRenderPass',desc='Begin a new render pass',type='protos'] 2134-- 2135 2136To begin a render pass instance, call: 2137 2138include::../api/protos/vkCmdBeginRenderPass.txt[] 2139 2140 * pname:commandBuffer is the command buffer in which to record the 2141 command. 2142 * pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo 2143 structure (defined below) which specifies the render pass to begin an 2144 instance of, and the framebuffer the instance uses. 2145 * pname:contents is a elink:VkSubpassContents value specifying how the 2146 commands in the first subpass will be provided. 2147 2148After beginning a render pass instance, the command buffer is ready to 2149record the commands for the first subpass of that render pass. 2150 2151.Valid Usage 2152**** 2153 * [[VUID-vkCmdBeginRenderPass-initialLayout-00895]] 2154 If any of the pname:initialLayout or pname:finalLayout member of the 2155 sname:VkAttachmentDescription structures or the pname:layout member of 2156 the sname:VkAttachmentReference structures specified when creating the 2157 render pass specified in the pname:renderPass member of 2158 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 2159 then the corresponding attachment image subresource of the framebuffer 2160 specified in the pname:framebuffer member of pname:pRenderPassBegin 2161 must: have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 2162 set 2163// The VU below comes in an alternate version when the extension is 2164// enabled. 2165ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2166 * [[VUID-vkCmdBeginRenderPass-initialLayout-00896]] 2167 If any of the pname:initialLayout or pname:finalLayout member of the 2168 sname:VkAttachmentDescription structures or the pname:layout member of 2169 the sname:VkAttachmentReference structures specified when creating the 2170 render pass specified in the pname:renderPass member of 2171 pname:pRenderPassBegin is 2172 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or 2173 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the 2174 corresponding attachment image subresource of the framebuffer specified 2175 in the pname:framebuffer member of pname:pRenderPassBegin must: have 2176 been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set 2177endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2178// The nested ifdefs are there in anticipation of the hoped-for day when the 2179// VU extractor and validation layers can handle VU with imbedded 2180// conditionals. They are commented out until then. 2181ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2182 * [[VUID-vkCmdBeginRenderPass-initialLayout-01758]] 2183 If any of the pname:initialLayout or pname:finalLayout member of the 2184 sname:VkAttachmentDescription structures or the pname:layout member of 2185 the sname:VkAttachmentReference structures specified when creating the 2186 render pass specified in the pname:renderPass member of 2187 pname:pRenderPassBegin is 2188// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2189 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 2190 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 2191// endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2192 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or 2193 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the 2194 corresponding attachment image subresource of the framebuffer specified 2195 in the pname:framebuffer member of pname:pRenderPassBegin must: have 2196 been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set 2197endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2198 * [[VUID-vkCmdBeginRenderPass-initialLayout-00897]] 2199 If any of the pname:initialLayout or pname:finalLayout member of the 2200 sname:VkAttachmentDescription structures or the pname:layout member of 2201 the sname:VkAttachmentReference structures specified when creating the 2202 render pass specified in the pname:renderPass member of 2203 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 2204 then the corresponding attachment image subresource of the framebuffer 2205 specified in the pname:framebuffer member of pname:pRenderPassBegin 2206 must: have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT or 2207 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set 2208 * [[VUID-vkCmdBeginRenderPass-initialLayout-00898]] 2209 If any of the pname:initialLayout or pname:finalLayout member of the 2210 sname:VkAttachmentDescription structures or the pname:layout member of 2211 the sname:VkAttachmentReference structures specified when creating the 2212 render pass specified in the pname:renderPass member of 2213 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL 2214 then the corresponding attachment image subresource of the framebuffer 2215 specified in the pname:framebuffer member of pname:pRenderPassBegin 2216 must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set 2217 * [[VUID-vkCmdBeginRenderPass-initialLayout-00899]] 2218 If any of the pname:initialLayout or pname:finalLayout member of the 2219 sname:VkAttachmentDescription structures or the pname:layout member of 2220 the sname:VkAttachmentReference structures specified when creating the 2221 render pass specified in the pname:renderPass member of 2222 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL 2223 then the corresponding attachment image subresource of the framebuffer 2224 specified in the pname:framebuffer member of pname:pRenderPassBegin 2225 must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set 2226 * [[VUID-vkCmdBeginRenderPass-initialLayout-00900]] 2227 If any of the pname:initialLayout members of the 2228 sname:VkAttachmentDescription structures specified when creating the 2229 render pass specified in the pname:renderPass member of 2230 pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each 2231 such pname:initialLayout must: be equal to the current layout of the 2232 corresponding attachment image subresource of the framebuffer specified 2233 in the pname:framebuffer member of pname:pRenderPassBegin 2234 * [[VUID-vkCmdBeginRenderPass-srcStageMask-00901]] 2235 The pname:srcStageMask and pname:dstStageMask members of any element of 2236 the pname:pDependencies member of slink:VkRenderPassCreateInfo used to 2237 create pname:renderPass must: be supported by the capabilities of the 2238 queue family identified by the pname:queueFamilyIndex member of the 2239 slink:VkCommandPoolCreateInfo used to create the command pool which 2240 pname:commandBuffer was allocated from. 2241**** 2242 2243include::../validity/protos/vkCmdBeginRenderPass.txt[] 2244-- 2245 2246ifdef::VK_KHR_create_renderpass2[] 2247[open,refpage='vkCmdBeginRenderPass2KHR',desc='Begin a new render pass',type='protos'] 2248-- 2249 2250Alternatively to begin a render pass, call: 2251 2252include::../api/protos/vkCmdBeginRenderPass2KHR.txt[] 2253 2254 * pname:commandBuffer is the command buffer in which to record the 2255 command. 2256 * pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo 2257 structure (defined below) which indicates the render pass to begin an 2258 instance of, and the framebuffer the instance uses. 2259 * pname:pSubpassBeginInfo is a pointer to a slink:VkSubpassBeginInfoKHR 2260 structure which contains information about the subpass which is about to 2261 begin rendering. 2262 2263After beginning a render pass instance, the command buffer is ready to 2264record the commands for the first subpass of that render pass. 2265 2266.Valid Usage 2267**** 2268 * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03094]] 2269 If any of the pname:initialLayout or pname:finalLayout member of the 2270 sname:VkAttachmentDescription structures or the pname:layout member of 2271 the sname:VkAttachmentReference structures specified when creating the 2272 render pass specified in the pname:renderPass member of 2273 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 2274 then the corresponding attachment image subresource of the framebuffer 2275 specified in the pname:framebuffer member of pname:pRenderPassBegin 2276 must: have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 2277 set 2278// The VU below comes in an alternate version when the extension is 2279// enabled. 2280ifndef::VK_KHR_maintenance2[] 2281 * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03095]] 2282 If any of the pname:initialLayout or pname:finalLayout member of the 2283 sname:VkAttachmentDescription structures or the pname:layout member of 2284 the sname:VkAttachmentReference structures specified when creating the 2285 render pass specified in the pname:renderPass member of 2286 pname:pRenderPassBegin is 2287 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or 2288 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the 2289 corresponding attachment image subresource of the framebuffer specified 2290 in the pname:framebuffer member of pname:pRenderPassBegin must: have 2291 been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set 2292endif::VK_KHR_maintenance2[] 2293// The nested ifdefs are there in anticipation of the hoped-for day when the 2294// VU extractor and validation layers can handle VU with imbedded 2295// conditionals. 2296ifdef::VK_KHR_maintenance2[] 2297 * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03096]] 2298 If any of the pname:initialLayout or pname:finalLayout member of the 2299 sname:VkAttachmentDescription structures or the pname:layout member of 2300 the sname:VkAttachmentReference structures specified when creating the 2301 render pass specified in the pname:renderPass member of 2302 pname:pRenderPassBegin is 2303// ifdef::VK_KHR_maintenance2[] 2304 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 2305 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 2306// endif::VK_KHR_maintenance2[] 2307 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or 2308 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the 2309 corresponding attachment image subresource of the framebuffer specified 2310 in the pname:framebuffer member of pname:pRenderPassBegin must: have 2311 been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set 2312endif::VK_KHR_maintenance2[] 2313 * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03097]] 2314 If any of the pname:initialLayout or pname:finalLayout member of the 2315 sname:VkAttachmentDescription structures or the pname:layout member of 2316 the sname:VkAttachmentReference structures specified when creating the 2317 render pass specified in the pname:renderPass member of 2318 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 2319 then the corresponding attachment image subresource of the framebuffer 2320 specified in the pname:framebuffer member of pname:pRenderPassBegin 2321 must: have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT or 2322 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set 2323 * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03098]] 2324 If any of the pname:initialLayout or pname:finalLayout member of the 2325 sname:VkAttachmentDescription structures or the pname:layout member of 2326 the sname:VkAttachmentReference structures specified when creating the 2327 render pass specified in the pname:renderPass member of 2328 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL 2329 then the corresponding attachment image subresource of the framebuffer 2330 specified in the pname:framebuffer member of pname:pRenderPassBegin 2331 must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set 2332 * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03099]] 2333 If any of the pname:initialLayout or pname:finalLayout member of the 2334 sname:VkAttachmentDescription structures or the pname:layout member of 2335 the sname:VkAttachmentReference structures specified when creating the 2336 render pass specified in the pname:renderPass member of 2337 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL 2338 then the corresponding attachment image subresource of the framebuffer 2339 specified in the pname:framebuffer member of pname:pRenderPassBegin 2340 must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set 2341 * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03100]] 2342 If any of the pname:initialLayout members of the 2343 sname:VkAttachmentDescription structures specified when creating the 2344 render pass specified in the pname:renderPass member of 2345 pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each 2346 such pname:initialLayout must: be equal to the current layout of the 2347 corresponding attachment image subresource of the framebuffer specified 2348 in the pname:framebuffer member of pname:pRenderPassBegin 2349 * [[VUID-vkCmdBeginRenderPass2KHR-srcStageMask-03101]] 2350 The pname:srcStageMask and pname:dstStageMask members of any element of 2351 the pname:pDependencies member of slink:VkRenderPassCreateInfo used to 2352 create pname:renderPass must: be supported by the capabilities of the 2353 queue family identified by the pname:queueFamilyIndex member of the 2354 slink:VkCommandPoolCreateInfo used to create the command pool which 2355 pname:commandBuffer was allocated from. 2356**** 2357 2358include::../validity/protos/vkCmdBeginRenderPass2KHR.txt[] 2359-- 2360endif::VK_KHR_create_renderpass2[] 2361 2362[open,refpage='VkRenderPassBeginInfo',desc='Structure specifying render pass begin info',type='structs'] 2363-- 2364 2365The sname:VkRenderPassBeginInfo structure is defined as: 2366 2367include::../api/structs/VkRenderPassBeginInfo.txt[] 2368 2369 * pname:sType is the type of this structure. 2370 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2371 * pname:renderPass is the render pass to begin an instance of. 2372 * pname:framebuffer is the framebuffer containing the attachments that are 2373 used with the render pass. 2374 * pname:renderArea is the render area that is affected by the render pass 2375 instance, and is described in more detail below. 2376 * pname:clearValueCount is the number of elements in pname:pClearValues. 2377 * pname:pClearValues is an array of slink:VkClearValue structures that 2378 contains clear values for each attachment, if the attachment uses a 2379 pname:loadOp value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR or if the 2380 attachment has a depth/stencil format and uses a pname:stencilLoadOp 2381 value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR. 2382 The array is indexed by attachment number. 2383 Only elements corresponding to cleared attachments are used. 2384 Other elements of pname:pClearValues are ignored. 2385 2386pname:renderArea is the render area that is affected by the render pass 2387instance. 2388The effects of attachment load, store and multisample resolve operations are 2389restricted to the pixels whose x and y coordinates fall within the render 2390area on all attachments. 2391The render area extends to all layers of pname:framebuffer. 2392The application must: ensure (using scissor if necessary) that all rendering 2393is contained within the render area, otherwise the pixels outside of the 2394render area become undefined and shader side effects may: occur for 2395fragments outside the render area. 2396The render area must: be contained within the framebuffer dimensions. 2397 2398ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2399 2400When multiview is enabled, the resolve operation at the end of a subpass 2401applies to all views in the view mask. 2402 2403endif::VK_VERSION_1_1,VK_KHR_multiview[] 2404 2405[NOTE] 2406.Note 2407==== 2408There may: be a performance cost for using a render area smaller than the 2409framebuffer, unless it matches the render area granularity for the render 2410pass. 2411==== 2412 2413.Valid Usage 2414**** 2415 * [[VUID-VkRenderPassBeginInfo-clearValueCount-00902]] 2416 pname:clearValueCount must: be greater than the largest attachment index 2417 in pname:renderPass that specifies a pname:loadOp (or 2418 pname:stencilLoadOp, if the attachment has a depth/stencil format) of 2419 ename:VK_ATTACHMENT_LOAD_OP_CLEAR 2420 * [[VUID-VkRenderPassBeginInfo-clearValueCount-00903]] 2421 If pname:clearValueCount is not `0`, pname:pClearValues must: be a valid 2422 pointer to an array of pname:clearValueCount valid sname:VkClearValue 2423 unions 2424 * [[VUID-VkRenderPassBeginInfo-renderPass-00904]] 2425 pname:renderPass must: be <<renderpass-compatibility,compatible>> with 2426 the pname:renderPass member of the sname:VkFramebufferCreateInfo 2427 structure specified when creating pname:framebuffer. 2428**** 2429 2430include::../validity/structs/VkRenderPassBeginInfo.txt[] 2431-- 2432 2433ifdef::VK_EXT_sample_locations[] 2434 2435[open,refpage='VkRenderPassSampleLocationsBeginInfoEXT',desc='Structure specifying sample locations to use for the layout transition of custom sample locations compatible depth/stencil attachments',type='structs'] 2436-- 2437 2438The image layout of the depth aspect of a depth/stencil attachment referring 2439to an image created with 2440ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent 2441on the last sample locations used to render to the image subresource, thus 2442preserving the contents of such depth/stencil attachments across subpass 2443boundaries requires the application to specify these sample locations 2444whenever a layout transition of the attachment may: occur. 2445This information can: be provided by chaining an instance of the 2446sname:VkRenderPassSampleLocationsBeginInfoEXT structure to the pname:pNext 2447chain of sname:VkRenderPassBeginInfo. 2448 2449The sname:VkRenderPassSampleLocationsBeginInfoEXT structure is defined as: 2450 2451include::../api/structs/VkRenderPassSampleLocationsBeginInfoEXT.txt[] 2452 2453 * pname:sType is the type of this structure. 2454 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2455 * pname:attachmentInitialSampleLocationsCount is the number of elements in 2456 the pname:pAttachmentInitialSampleLocations array. 2457 * pname:pAttachmentInitialSampleLocations is an array of 2458 pname:attachmentInitialSampleLocationsCount 2459 slink:VkAttachmentSampleLocationsEXT structures specifying the 2460 attachment indices and their corresponding sample location state. 2461 Each element of pname:pAttachmentInitialSampleLocations can: specify the 2462 sample location state to use in the automatic layout transition 2463 performed to transition a depth/stencil attachment from the initial 2464 layout of the attachment to the image layout specified for the 2465 attachment in the first subpass using it. 2466 * pname:postSubpassSampleLocationsCount is the number of elements in the 2467 pname:pPostSubpassSampleLocations array. 2468 * pname:pPostSubpassSampleLocations is an array of 2469 pname:postSubpassSampleLocationsCount slink:VkSubpassSampleLocationsEXT 2470 structures specifying the subpass indices and their corresponding sample 2471 location state. 2472 Each element of pname:pPostSubpassSampleLocations can: specify the 2473 sample location state to use in the automatic layout transition 2474 performed to transition the depth/stencil attachment used by the 2475 specified subpass to the image layout specified in a dependent subpass 2476 or to the final layout of the attachment in case the specified subpass 2477 is the last subpass using that attachment. 2478 In addition, if 2479 slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations 2480 is ename:VK_FALSE, each element of pname:pPostSubpassSampleLocations 2481 must: specify the sample location state that matches the sample 2482 locations used by all pipelines that will be bound to a command buffer 2483 during the specified subpass. 2484 If pname:variableSampleLocations is ename:VK_TRUE, the sample locations 2485 used for rasterization do not depend on 2486 pname:pPostSubpassSampleLocations. 2487 2488include::../validity/structs/VkRenderPassSampleLocationsBeginInfoEXT.txt[] 2489-- 2490 2491[open,refpage='VkAttachmentSampleLocationsEXT',desc='Structure specifying the sample locations state to use in the initial layout transition of attachments',type='structs'] 2492-- 2493 2494The sname:VkAttachmentSampleLocationsEXT structure is defined as: 2495 2496include::../api/structs/VkAttachmentSampleLocationsEXT.txt[] 2497 2498 * pname:attachmentIndex is the index of the attachment for which the 2499 sample locations state is provided. 2500 * pname:sampleLocationsInfo is the sample locations state to use for the 2501 layout transition of the given attachment from the initial layout of the 2502 attachment to the image layout specified for the attachment in the first 2503 subpass using it. 2504 2505If the image referenced by the framebuffer attachment at index 2506pname:attachmentIndex was not created with 2507ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT then the 2508values specified in pname:sampleLocationsInfo are ignored. 2509 2510.Valid Usage 2511**** 2512 * [[VUID-VkAttachmentSampleLocationsEXT-attachmentIndex-01531]] 2513 pname:attachmentIndex must: be less than the pname:attachmentCount 2514 specified in slink:VkRenderPassCreateInfo the render pass specified by 2515 slink:VkRenderPassBeginInfo::pname:renderPass was created with 2516**** 2517 2518include::../validity/structs/VkAttachmentSampleLocationsEXT.txt[] 2519-- 2520 2521[open,refpage='VkSubpassSampleLocationsEXT',desc='Structure specifying the sample locations state to use for layout transitions of attachments performed after a given subpass',type='structs'] 2522-- 2523 2524The sname:VkSubpassSampleLocationsEXT structure is defined as: 2525 2526include::../api/structs/VkSubpassSampleLocationsEXT.txt[] 2527 2528 * pname:subpassIndex is the index of the subpass for which the sample 2529 locations state is provided. 2530 * pname:sampleLocationsInfo is the sample locations state to use for the 2531 layout transition of the depth/stencil attachment away from the image 2532 layout the attachment is used with in the subpass specified in 2533 pname:subpassIndex. 2534 2535If the image referenced by the depth/stencil attachment used in the subpass 2536identified by pname:subpassIndex was not created with 2537ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT or if the 2538subpass does not use a depth/stencil attachment, and 2539slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations 2540is ename:VK_TRUE then the values specified in pname:sampleLocationsInfo are 2541ignored. 2542 2543.Valid Usage 2544**** 2545 * [[VUID-VkSubpassSampleLocationsEXT-subpassIndex-01532]] 2546 pname:subpassIndex must: be less than the pname:subpassCount specified 2547 in slink:VkRenderPassCreateInfo the render pass specified by 2548 slink:VkRenderPassBeginInfo::pname:renderPass was created with 2549**** 2550 2551include::../validity/structs/VkSubpassSampleLocationsEXT.txt[] 2552-- 2553 2554endif::VK_EXT_sample_locations[] 2555 2556ifdef::VK_KHR_create_renderpass2[] 2557[open,refpage='VkSubpassBeginInfoKHR',desc='Structure specifying subpass begin info',type='structs'] 2558-- 2559 2560The sname:VkSubpassBeginInfoKHR structure is defined as: 2561 2562include::../api/structs/VkSubpassBeginInfoKHR.txt[] 2563 2564 * pname:sType is the type of this structure. 2565 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2566 * pname:contents is a elink:VkSubpassContents value specifying how the 2567 commands in the next subpass will be provided. 2568 2569include::../validity/structs/VkSubpassBeginInfoKHR.txt[] 2570-- 2571endif::VK_KHR_create_renderpass2[] 2572 2573[open,refpage='VkSubpassContents',desc='Specify how commands in the first subpass of a render pass are provided',type='enums'] 2574-- 2575 2576Possible values of flink:vkCmdBeginRenderPass::pname:contents, specifying 2577how the commands in the first subpass will be provided, are: 2578 2579include::../api/enums/VkSubpassContents.txt[] 2580 2581 * ename:VK_SUBPASS_CONTENTS_INLINE specifies that the contents of the 2582 subpass will be recorded inline in the primary command buffer, and 2583 secondary command buffers must: not be executed within the subpass. 2584 * ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS specifies that the 2585 contents are recorded in secondary command buffers that will be called 2586 from the primary command buffer, and flink:vkCmdExecuteCommands is the 2587 only valid command on the command buffer until flink:vkCmdNextSubpass or 2588 flink:vkCmdEndRenderPass. 2589 2590-- 2591 2592ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2593 2594[open,refpage='VkDeviceGroupRenderPassBeginInfo',desc='Set the initial device mask and render areas for a render pass instance',type='structs'] 2595-- 2596 2597If the pname:pNext chain of slink:VkRenderPassBeginInfo includes a 2598sname:VkDeviceGroupRenderPassBeginInfo structure, then that structure 2599includes a device mask and set of render areas for the render pass instance. 2600 2601The sname:VkDeviceGroupRenderPassBeginInfo structure is defined as: 2602 2603include::../api/structs/VkDeviceGroupRenderPassBeginInfo.txt[] 2604 2605ifdef::VK_KHR_device_group[] 2606or the equivalent 2607 2608include::../api/structs/VkDeviceGroupRenderPassBeginInfoKHR.txt[] 2609endif::VK_KHR_device_group[] 2610 2611 * pname:sType is the type of this structure. 2612 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2613 * pname:deviceMask is the device mask for the render pass instance. 2614 * pname:deviceRenderAreaCount is the number of elements in the 2615 pname:pDeviceRenderAreas array. 2616 * pname:pDeviceRenderAreas is an array of structures of type 2617 slink:VkRect2D defining the render area for each physical device. 2618 2619The pname:deviceMask serves several purposes. 2620It is an upper bound on the set of physical devices that can: be used during 2621the render pass instance, and the initial device mask when the render pass 2622instance begins. 2623Render pass attachment load, store, and resolve operations only apply to 2624physical devices included in the device mask. 2625Subpass dependencies only apply to the physical devices in the device mask. 2626 2627If pname:deviceRenderAreaCount is not zero, then the elements of 2628pname:pDeviceRenderAreas override the value of 2629slink:VkRenderPassBeginInfo::pname:renderArea, and provide a render area 2630specific to each physical device. 2631These render areas serve the same purpose as 2632slink:VkRenderPassBeginInfo::pname:renderArea, including controlling the 2633region of attachments that are cleared by ename:VK_ATTACHMENT_LOAD_OP_CLEAR 2634and that are resolved into resolve attachments. 2635 2636If this structure is not present, the render pass instance's device mask is 2637the value of slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask. 2638If this structure is not present or if pname:deviceRenderAreaCount is zero, 2639slink:VkRenderPassBeginInfo::pname:renderArea is used for all physical 2640devices. 2641 2642.Valid Usage 2643**** 2644 * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00905]] 2645 pname:deviceMask must: be a valid device mask value 2646 * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00906]] 2647 pname:deviceMask must: not be zero 2648 * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00907]] 2649 pname:deviceMask must: be a subset of the command buffer's initial 2650 device mask 2651 * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceRenderAreaCount-00908]] 2652 pname:deviceRenderAreaCount must: either be zero or equal to the number 2653 of physical devices in the logical device. 2654**** 2655 2656include::../validity/structs/VkDeviceGroupRenderPassBeginInfo.txt[] 2657-- 2658 2659endif::VK_VERSION_1_1,VK_KHR_device_group[] 2660 2661[open,refpage='vkGetRenderAreaGranularity',desc='Returns the granularity for optimal render area',type='protos'] 2662-- 2663 2664To query the render area granularity, call: 2665 2666include::../api/protos/vkGetRenderAreaGranularity.txt[] 2667 2668 * pname:device is the logical device that owns the render pass. 2669 * pname:renderPass is a handle to a render pass. 2670 * pname:pGranularity points to a slink:VkExtent2D structure in which the 2671 granularity is returned. 2672 2673The conditions leading to an optimal pname:renderArea are: 2674 2675 * the pname:offset.x member in pname:renderArea is a multiple of the 2676 pname:width member of the returned slink:VkExtent2D (the horizontal 2677 granularity). 2678 * the pname:offset.y member in pname:renderArea is a multiple of the 2679 pname:height of the returned slink:VkExtent2D (the vertical 2680 granularity). 2681 * either the pname:offset.width member in pname:renderArea is a multiple 2682 of the horizontal granularity or pname:offset.x+pname:offset.width is 2683 equal to the pname:width of the pname:framebuffer in the 2684 slink:VkRenderPassBeginInfo. 2685 * either the pname:offset.height member in pname:renderArea is a multiple 2686 of the vertical granularity or pname:offset.y+pname:offset.height is 2687 equal to the pname:height of the pname:framebuffer in the 2688 slink:VkRenderPassBeginInfo. 2689 2690Subpass dependencies are not affected by the render area, and apply to the 2691entire image subresources attached to the framebuffer as specified in the 2692description of <<renderpass-layout-transitions,automatic layout 2693transitions>>. 2694Similarly, pipeline barriers are valid even if their effect extends outside 2695the render area. 2696 2697include::../validity/protos/vkGetRenderAreaGranularity.txt[] 2698-- 2699 2700[open,refpage='vkCmdNextSubpass',desc='Transition to the next subpass of a render pass',type='protos'] 2701-- 2702 2703To transition to the next subpass in the render pass instance after 2704recording the commands for a subpass, call: 2705 2706include::../api/protos/vkCmdNextSubpass.txt[] 2707 2708 * pname:commandBuffer is the command buffer in which to record the 2709 command. 2710 * pname:contents specifies how the commands in the next subpass will be 2711 provided, in the same fashion as the corresponding parameter of 2712 flink:vkCmdBeginRenderPass. 2713 2714The subpass index for a render pass begins at zero when 2715fname:vkCmdBeginRenderPass is recorded, and increments each time 2716fname:vkCmdNextSubpass is recorded. 2717 2718Moving to the next subpass automatically performs any multisample resolve 2719operations in the subpass being ended. 2720End-of-subpass multisample resolves are treated as color attachment writes 2721for the purposes of synchronization. 2722That is, they are considered to execute in the 2723ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their 2724writes are synchronized with ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 2725Synchronization between rendering within a subpass and any resolve 2726operations at the end of the subpass occurs automatically, without need for 2727explicit dependencies or pipeline barriers. 2728However, if the resolve attachment is also used in a different subpass, an 2729explicit dependency is needed. 2730 2731After transitioning to the next subpass, the application can: record the 2732commands for that subpass. 2733 2734.Valid Usage 2735**** 2736 * [[VUID-vkCmdNextSubpass-None-00909]] 2737 The current subpass index must: be less than the number of subpasses in 2738 the render pass minus one 2739**** 2740 2741include::../validity/protos/vkCmdNextSubpass.txt[] 2742-- 2743 2744ifdef::VK_KHR_create_renderpass2[] 2745 2746[open,refpage='vkCmdNextSubpass2KHR',desc='Transition to the next subpass of a render pass',type='protos'] 2747-- 2748 2749To transition to the next subpass in the render pass instance after 2750recording the commands for a subpass, call: 2751 2752include::../api/protos/vkCmdNextSubpass2KHR.txt[] 2753 2754 * pname:commandBuffer is the command buffer in which to record the 2755 command. 2756 * pname:pSubpassBeginInfo is a pointer to a slink:VkSubpassBeginInfoKHR 2757 structure which contains information about the subpass which is about to 2758 begin rendering. 2759 * pname:pSubpassEndInfo is a pointer to a slink:VkSubpassEndInfoKHR 2760 structure which contains information about how the previous subpass will 2761 be ended. 2762 2763fname:vkCmdNextSubpass2KHR is semantically identical to 2764flink:vkCmdNextSubpass, except that it is extensible, and that 2765pname:contents is provided as part of an extensible structure instead of as 2766a flat parameter. 2767 2768.Valid Usage 2769**** 2770 * [[VUID-vkCmdNextSubpass2KHR-None-03102]] 2771 The current subpass index must: be less than the number of subpasses in 2772 the render pass minus one 2773**** 2774 2775include::../validity/protos/vkCmdNextSubpass2KHR.txt[] 2776-- 2777 2778endif::VK_KHR_create_renderpass2[] 2779 2780[open,refpage='vkCmdEndRenderPass',desc='End the current render pass',type='protos'] 2781-- 2782 2783To record a command to end a render pass instance after recording the 2784commands for the last subpass, call: 2785 2786include::../api/protos/vkCmdEndRenderPass.txt[] 2787 2788 * pname:commandBuffer is the command buffer in which to end the current 2789 render pass instance. 2790 2791Ending a render pass instance performs any multisample resolve operations on 2792the final subpass. 2793 2794.Valid Usage 2795**** 2796 * [[VUID-vkCmdEndRenderPass-None-00910]] 2797 The current subpass index must: be equal to the number of subpasses in 2798 the render pass minus one 2799**** 2800 2801include::../validity/protos/vkCmdEndRenderPass.txt[] 2802-- 2803 2804 2805ifdef::VK_KHR_create_renderpass2[] 2806[open,refpage='vkCmdEndRenderPass2KHR',desc='End the current render pass',type='protos'] 2807-- 2808 2809To record a command to end a render pass instance after recording the 2810commands for the last subpass, call: 2811 2812include::../api/protos/vkCmdEndRenderPass2KHR.txt[] 2813 2814 * pname:commandBuffer is the command buffer in which to end the current 2815 render pass instance. 2816 * pname:pSubpassEndInfo is a pointer to a slink:VkSubpassEndInfoKHR 2817 structure which contains information about how the previous subpass will 2818 be ended. 2819 2820fname:vkCmdEndRenderPass2KHR is semantically identical to 2821flink:vkCmdEndRenderPass, except that it is extensible. 2822 2823.Valid Usage 2824**** 2825 * [[VUID-vkCmdEndRenderPass2KHR-None-03103]] 2826 The current subpass index must: be equal to the number of subpasses in 2827 the render pass minus one 2828**** 2829 2830include::../validity/protos/vkCmdEndRenderPass2KHR.txt[] 2831-- 2832 2833[open,refpage='VkSubpassEndInfoKHR',desc='Structure specifying subpass end info',type='structs'] 2834-- 2835 2836The sname:VkSubpassEndInfoKHR structure is defined as: 2837 2838include::../api/structs/VkSubpassEndInfoKHR.txt[] 2839 2840 * pname:sType is the type of this structure. 2841 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2842 2843include::../validity/structs/VkSubpassEndInfoKHR.txt[] 2844-- 2845 2846endif::VK_KHR_create_renderpass2[] 2847 2848