1  // Copyright (c) 2015-2019 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  
  11  A _render pass_ represents a collection of attachments, subpasses, and
  12  dependencies between the subpasses, and describes how the attachments are
  13  used over the course of the subpasses.
  14  The use of a render pass in a command buffer is a _render pass instance_.
  15  
  16  Render passes are represented by sname:VkRenderPass handles:
  17  
  18  include::{generated}/api/handles/VkRenderPass.txt[]
  19  
  20  --
  21  
  22  An _attachment description_ describes the properties of an attachment
  23  including its format, sample count, and how its contents are treated at the
  24  beginning and end of each render pass instance.
  25  
  26  [[renderpass-subpass]]
  27  A _subpass_ represents a phase of rendering that reads and writes a subset
  28  of the attachments in a render pass.
  29  Rendering commands are recorded into a particular subpass of a render pass
  30  instance.
  31  
  32  A _subpass description_ describes the subset of attachments that is involved
  33  in the execution of a subpass.
  34  Each subpass can: read from some attachments as _input attachments_, write
  35  to some as _color attachments_ or _depth/stencil attachments_, and perform
  36  _multisample resolve operations_ to _resolve attachments_.
  37  A subpass description can: also include a set of _preserve attachments_,
  38  which are attachments that are not read or written by the subpass but whose
  39  contents must: be preserved throughout the subpass.
  40  
  41  A subpass _uses an attachment_ if the attachment is a color, depth/stencil,
  42  resolve,
  43  ifdef::VK_KHR_depth_stencil_resolve[]
  44  depth/stencil resolve,
  45  endif::VK_KHR_depth_stencil_resolve[]
  46  or input attachment for that subpass (as determined by the
  47  pname:pColorAttachments, pname:pDepthStencilAttachment,
  48  pname:pResolveAttachments,
  49  ifdef::VK_KHR_depth_stencil_resolve[]
  50  slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:pDepthStencilResolveAttachment,
  51  endif::VK_KHR_depth_stencil_resolve[]
  52  and pname:pInputAttachments members of slink:VkSubpassDescription,
  53  respectively).
  54  A subpass does not use an attachment if that attachment is preserved by the
  55  subpass.
  56  The _first use of an attachment_ is in the lowest numbered subpass that uses
  57  that attachment.
  58  Similarly, the _last use of an attachment_ is in the highest numbered
  59  subpass that uses that attachment.
  60  
  61  The subpasses in a render pass all render to the same dimensions, and
  62  fragments for pixel (x,y,layer) in one subpass can: only read attachment
  63  contents written by previous subpasses at that same (x,y,layer) location.
  64  
  65  [NOTE]
  66  .Note
  67  ====
  68  By describing a complete set of subpasses in advance, render passes provide
  69  the implementation an opportunity to optimize the storage and transfer of
  70  attachment data between subpasses.
  71  
  72  In practice, this means that subpasses with a simple framebuffer-space
  73  dependency may: be merged into a single tiled rendering pass, keeping the
  74  attachment data on-chip for the duration of a render pass instance.
  75  However, it is also quite common for a render pass to only contain a single
  76  subpass.
  77  ====
  78  
  79  _Subpass dependencies_ describe <<synchronization-dependencies, execution
  80  and memory dependencies>> between subpasses.
  81  
  82  A _subpass dependency chain_ is a sequence of subpass dependencies in a
  83  render pass, where the source subpass of each subpass dependency (after the
  84  first) equals the destination subpass of the previous dependency.
  85  
  86  Execution of subpasses may: overlap or execute out of order with regards to
  87  other subpasses, unless otherwise enforced by an execution dependency.
  88  Each subpass only respects <<synchronization-submission-order, submission
  89  order>> for commands recorded in the same subpass, and the
  90  flink:vkCmdBeginRenderPass and flink:vkCmdEndRenderPass commands that
  91  delimit the render pass - commands within other subpasses are not included.
  92  This affects most other <<synchronization-implicit, implicit ordering
  93  guarantees>>.
  94  
  95  A render pass describes the structure of subpasses and attachments
  96  independent of any specific image views for the attachments.
  97  The specific image views that will be used for the attachments, and their
  98  dimensions, are specified in sname:VkFramebuffer objects.
  99  Framebuffers are created with respect to a specific render pass that the
 100  framebuffer is compatible with (see <<renderpass-compatibility,Render Pass
 101  Compatibility>>).
 102  Collectively, a render pass and a framebuffer define the complete render
 103  target state for one or more subpasses as well as the algorithmic
 104  dependencies between the subpasses.
 105  
 106  The various pipeline stages of the drawing commands for a given subpass may:
 107  execute concurrently and/or out of order, both within and across drawing
 108  commands, whilst still respecting <<synchronization-pipeline-stages-order,
 109  pipeline order>>.
 110  However for a given (x,y,layer,sample) sample location, certain per-sample
 111  operations are performed in <<primrast-order,rasterization order>>.
 112  
 113  
 114  [[renderpass-creation]]
 115  == Render Pass Creation
 116  
 117  [open,refpage='vkCreateRenderPass',desc='Create a new render pass object',type='protos']
 118  --
 119  
 120  To create a render pass, call:
 121  
 122  include::{generated}/api/protos/vkCreateRenderPass.txt[]
 123  
 124    * pname:device is the logical device that creates the render pass.
 125    * pname:pCreateInfo is a pointer to an instance of the
 126      slink:VkRenderPassCreateInfo structure that describes the parameters of
 127      the render pass.
 128    * pname:pAllocator controls host memory allocation as described in the
 129      <<memory-allocation, Memory Allocation>> chapter.
 130    * pname:pRenderPass points to a slink:VkRenderPass handle in which the
 131      resulting render pass object is returned.
 132  
 133  include::{generated}/validity/protos/vkCreateRenderPass.txt[]
 134  --
 135  
 136  [open,refpage='VkRenderPassCreateInfo',desc='Structure specifying parameters of a newly created render pass',type='structs']
 137  --
 138  
 139  The sname:VkRenderPassCreateInfo structure is defined as:
 140  
 141  include::{generated}/api/structs/VkRenderPassCreateInfo.txt[]
 142  
 143    * pname:sType is the type of this structure.
 144    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
 145    * pname:flags is reserved for future use.
 146    * pname:attachmentCount is the number of attachments used by this render
 147      pass.
 148    * pname:pAttachments points to an array of pname:attachmentCount
 149      slink:VkAttachmentDescription structures describing the attachments used
 150      by the render pass.
 151    * pname:subpassCount is the number of subpasses to create.
 152    * pname:pSubpasses points to an array of pname:subpassCount
 153      slink:VkSubpassDescription structures describing each subpass.
 154    * pname:dependencyCount is the number of memory dependencies between pairs
 155      of subpasses.
 156    * pname:pDependencies points to an array of pname:dependencyCount
 157      slink:VkSubpassDependency structures describing dependencies between
 158      pairs of subpasses.
 159  
 160  [NOTE]
 161  .Note
 162  ====
 163  Care should be taken to avoid a data race here; if any subpasses access
 164  attachments with overlapping memory locations, and one of those accesses is
 165  a write, a subpass dependency needs to be included between them.
 166  ====
 167  
 168  .Valid Usage
 169  ****
 170    * [[VUID-VkRenderPassCreateInfo-attachment-00834]]
 171      If the pname:attachment member of any element of
 172      pname:pInputAttachments, pname:pColorAttachments,
 173      pname:pResolveAttachments or pname:pDepthStencilAttachment, or any
 174      element of pname:pPreserveAttachments in any element of pname:pSubpasses
 175      is not ename:VK_ATTACHMENT_UNUSED, it must: be less than
 176      pname:attachmentCount
 177    * [[VUID-VkRenderPassCreateInfo-pAttachments-00836]]
 178      For any member of pname:pAttachments with a pname:loadOp equal to
 179      ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
 180      must: not specify a pname:layout equal to
 181      ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or
 182      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL.
 183    * [[VUID-VkRenderPassCreateInfo-pAttachments-02511]]
 184      For any member of pname:pAttachments with a pname:stencilLoadOp equal to
 185      ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
 186      must: not specify a pname:layout equal to
 187      ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or
 188      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL.
 189  ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
 190    * [[VUID-VkRenderPassCreateInfo-pAttachments-01566]]
 191      For any member of pname:pAttachments with a pname:loadOp equal to
 192      ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
 193      must: not specify a pname:layout equal to
 194      ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL.
 195    * [[VUID-VkRenderPassCreateInfo-pAttachments-01567]]
 196      For any member of pname:pAttachments with a pname:stencilLoadOp equal to
 197      ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
 198      must: not specify a pname:layout equal to
 199      ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL.
 200    * [[VUID-VkRenderPassCreateInfo-pNext-01926]]
 201      If the pname:pNext chain includes an instance of
 202      slink:VkRenderPassInputAttachmentAspectCreateInfo, the pname:subpass
 203      member of each element of its pname:pAspectReferences member must: be
 204      less than pname:subpassCount
 205    * [[VUID-VkRenderPassCreateInfo-pNext-01927]]
 206      If the pname:pNext chain includes an instance of
 207      slink:VkRenderPassInputAttachmentAspectCreateInfo, the
 208      pname:inputAttachmentIndex member of each element of its
 209      pname:pAspectReferences member must: be less than the value of
 210      pname:inputAttachmentCount in the member of pname:pSubpasses identified
 211      by its pname:subpass member
 212    * [[VUID-VkRenderPassCreateInfo-pNext-01963]]
 213      If the pname:pNext chain includes an instance of
 214      slink:VkRenderPassInputAttachmentAspectCreateInfo, for any element of
 215      the pname:pInputAttachments member of any element of pname:pSubpasses
 216      where the pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, the
 217      pname:aspectMask member of the corresponding element of
 218      slink:VkRenderPassInputAttachmentAspectCreateInfo::pname:pAspectReferences
 219      must: only include aspects that are present in images of the format
 220      specified by the element of pname:pAttachments at pname:attachment
 221  endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
 222  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
 223    * [[VUID-VkRenderPassCreateInfo-pNext-01928]]
 224      If the pname:pNext chain includes an instance of
 225      slink:VkRenderPassMultiviewCreateInfo, and its pname:subpassCount member
 226      is not zero, that member must: be equal to the value of
 227      pname:subpassCount
 228    * [[VUID-VkRenderPassCreateInfo-pNext-01929]]
 229      If the pname:pNext chain includes an instance of
 230      slink:VkRenderPassMultiviewCreateInfo, if its pname:dependencyCount
 231      member is not zero, it must: be equal to pname:dependencyCount
 232    * [[VUID-VkRenderPassCreateInfo-pNext-01930]]
 233      If the pname:pNext chain includes an instance of
 234      slink:VkRenderPassMultiviewCreateInfo, for each non-zero element of
 235      pname:pViewOffsets, the pname:srcSubpass and pname:dstSubpass members of
 236      pname:pDependencies at the same index must: not be equal
 237    * [[VUID-VkRenderPassCreateInfo-pNext-02512]]
 238      If the pname:pNext chain includes an instance of
 239      slink:VkRenderPassMultiviewCreateInfo, for any element of
 240      pname:pDependencies with a pname:dependencyFlags member that does not
 241      include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, the corresponding element of
 242      the pname:pViewOffsets member of that
 243      slink:VkRenderPassMultiviewCreateInfo instance must: be `0`
 244    * [[VUID-VkRenderPassCreateInfo-pNext-02513]]
 245      If the pname:pNext chain includes an instance of
 246      slink:VkRenderPassMultiviewCreateInfo, elements of its pname:pViewMasks
 247      member must: either all be `0`, or all not be `0`
 248    * [[VUID-VkRenderPassCreateInfo-pNext-02514]]
 249      If the pname:pNext chain includes an instance of
 250      slink:VkRenderPassMultiviewCreateInfo, and each element of its
 251      pname:pViewMasks member is `0`, the pname:dependencyFlags member of each
 252      element of pname:pDependencies must: not include
 253      ename:VK_DEPENDENCY_VIEW_LOCAL_BIT
 254    * [[VUID-VkRenderPassCreateInfo-pNext-02515]]
 255      If the pname:pNext chain includes an instance of
 256      slink:VkRenderPassMultiviewCreateInfo, and each element of its
 257      pname:pViewMasks member is `0`, pname:correlatedViewMaskCount must: be
 258      `0`
 259    * [[VUID-VkRenderPassCreateInfo-pNext-02516]]
 260      If the pname:pNext chain includes an instance of
 261      slink:VkRenderPassMultiviewCreateInfo, each element of its
 262      pname:pViewMask member must: not have a bit set at an index greater than
 263      or equal to slink:VkPhysicalDeviceLimits::pname:maxFramebufferLayers
 264  endif::VK_VERSION_1_1,VK_KHR_multiview[]
 265    * [[VUID-VkRenderPassCreateInfo-pDependencies-00837]]
 266      For any element of pname:pDependencies, if the pname:srcSubpass is not
 267      ename:VK_SUBPASS_EXTERNAL, all stage flags included in the
 268      pname:srcStageMask member of that dependency must: be a pipeline stage
 269      supported by the <<synchronization-pipeline-stages-types, pipeline>>
 270      identified by the pname:pipelineBindPoint member of the source subpass
 271    * [[VUID-VkRenderPassCreateInfo-pDependencies-00838]]
 272      For any element of pname:pDependencies, if the pname:dstSubpass is not
 273      ename:VK_SUBPASS_EXTERNAL, all stage flags included in the
 274      pname:dstStageMask member of that dependency must: be a pipeline stage
 275      supported by the <<synchronization-pipeline-stages-types, pipeline>>
 276      identified by the pname:pipelineBindPoint member of the destination
 277      subpass
 278    * [[VUID-VkRenderPassCreateInfo-srcSubpass-02517]]
 279      The pname:srcSubpass member of each element of pname:pDependencies must:
 280      be less than pname:subpassCount
 281    * [[VUID-VkRenderPassCreateInfo-dstSubpass-02518]]
 282      The pname:dstSubpass member of each element of pname:pDependencies must:
 283      be less than pname:subpassCount
 284  ****
 285  
 286  include::{generated}/validity/structs/VkRenderPassCreateInfo.txt[]
 287  --
 288  
 289  [open,refpage='VkRenderPassCreateFlags',desc='Reserved for future use',type='flags']
 290  --
 291  include::{generated}/api/flags/VkRenderPassCreateFlags.txt[]
 292  
 293  tname:VkRenderPassCreateFlags is a bitmask type for setting a mask, but is
 294  currently reserved for future use.
 295  --
 296  
 297  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
 298  
 299  [[renderpass-multiview]]
 300  [open,refpage='VkRenderPassMultiviewCreateInfo',desc='Structure containing multiview info for all subpasses',type='structs']
 301  --
 302  
 303  If the sname:VkRenderPassCreateInfo::pname:pNext chain includes a
 304  sname:VkRenderPassMultiviewCreateInfo structure, then that structure
 305  includes an array of view masks, view offsets, and correlation masks for the
 306  render pass.
 307  
 308  The sname:VkRenderPassMultiviewCreateInfo structure is defined as:
 309  
 310  include::{generated}/api/structs/VkRenderPassMultiviewCreateInfo.txt[]
 311  
 312  ifdef::VK_KHR_multiview[]
 313  or the equivalent
 314  
 315  include::{generated}/api/structs/VkRenderPassMultiviewCreateInfoKHR.txt[]
 316  endif::VK_KHR_multiview[]
 317  
 318    * pname:sType is the type of this structure.
 319    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
 320    * pname:subpassCount is zero or is the number of subpasses in the render
 321      pass.
 322    * pname:pViewMasks points to an array of pname:subpassCount number of view
 323      masks, where each mask is a bitfield of view indices describing which
 324      views rendering is broadcast to in each subpass, when multiview is
 325      enabled.
 326      If pname:subpassCount is zero, each view mask is treated as zero.
 327    * pname:dependencyCount is zero or the number of dependencies in the
 328      render pass.
 329    * pname:pViewOffsets points to an array of pname:dependencyCount view
 330      offsets, one for each dependency.
 331      If pname:dependencyCount is zero, each dependency's view offset is
 332      treated as zero.
 333      Each view offset controls which views in the source subpass the views in
 334      the destination subpass depend on.
 335    * pname:correlationMaskCount is zero or a number of correlation masks.
 336    * pname:pCorrelationMasks is an array of view masks indicating sets of
 337      views that may: be more efficient to render concurrently.
 338  
 339  When a subpass uses a non-zero view mask, _multiview_ functionality is
 340  considered to be enabled.
 341  Multiview is all-or-nothing for a render pass - that is, either all
 342  subpasses must: have a non-zero view mask (though some subpasses may: have
 343  only one view) or all must: be zero.
 344  Multiview causes all drawing and clear commands in the subpass to behave as
 345  if they were broadcast to each view, where a view is represented by one
 346  layer of the framebuffer attachments.
 347  All draws and clears are broadcast to each _view index_ whose bit is set in
 348  the view mask.
 349  The view index is provided in the code:ViewIndex shader input variable, and
 350  color, depth/stencil, and input attachments all read/write the layer of the
 351  framebuffer corresponding to the view index.
 352  
 353  If the view mask is zero for all subpasses, multiview is considered to be
 354  disabled and all drawing commands execute normally, without this additional
 355  broadcasting.
 356  
 357  Some implementations may: not support multiview in conjunction with
 358  <<features-multiview-gs,geometry shaders>> or
 359  <<features-multiview-tess,tessellation shaders>>.
 360  
 361  [[renderpass-multiview-view-local]]
 362  When multiview is enabled, the ename:VK_DEPENDENCY_VIEW_LOCAL_BIT bit in a
 363  dependency can: be used to express a view-local dependency, meaning that
 364  each view in the destination subpass depends on a single view in the source
 365  subpass.
 366  Unlike pipeline barriers, a subpass dependency can: potentially have a
 367  different view mask in the source subpass and the destination subpass.
 368  If the dependency is view-local, then each view ([eq]#dstView#) in the
 369  destination subpass depends on the view [eq]#dstView {plus}
 370  pname:pViewOffsets[dependency]# in the source subpass.
 371  If there is not such a view in the source subpass, then this dependency does
 372  not affect that view in the destination subpass.
 373  If the dependency is not view-local, then all views in the destination
 374  subpass depend on all views in the source subpass, and the view offset is
 375  ignored.
 376  A non-zero view offset is not allowed in a self-dependency.
 377  
 378  The elements of pname:pCorrelationMasks are a set of masks of views
 379  indicating that views in the same mask may: exhibit spatial coherency
 380  between the views, making it more efficient to render them concurrently.
 381  Correlation masks must: not have a functional effect on the results of the
 382  multiview rendering.
 383  
 384  When multiview is enabled, at the beginning of each subpass all non-render
 385  pass state is undefined:.
 386  In particular, each time flink:vkCmdBeginRenderPass or
 387  flink:vkCmdNextSubpass is called the graphics pipeline must: be bound, any
 388  relevant descriptor sets or vertex/index buffers must: be bound, and any
 389  relevant dynamic state or push constants must: be set before they are used.
 390  
 391  ifdef::VK_NVX_multiview_per_view_attributes[]
 392  
 393  A multiview subpass can: declare that its shaders will write per-view
 394  attributes for all views in a single invocation, by setting the
 395  ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit in the subpass
 396  description.
 397  The only supported per-view attributes are position and viewport mask, and
 398  per-view position and viewport masks are written to output array variables
 399  decorated with code:PositionPerViewNV and code:ViewportMaskPerViewNV,
 400  respectively.
 401  If `<<VK_NV_viewport_array2>>` is not supported and enabled,
 402  code:ViewportMaskPerViewNV must: not be used.
 403  Values written to elements of code:PositionPerViewNV and
 404  code:ViewportMaskPerViewNV must: not depend on the code:ViewIndex.
 405  The shader must: also write to an output variable decorated with
 406  code:Position, and the value written to code:Position must: equal the value
 407  written to code:PositionPerViewNV[code:ViewIndex].
 408  Similarly, if code:ViewportMaskPerViewNV is written to then the shader must:
 409  also write to an output variable decorated with code:ViewportMaskNV, and the
 410  value written to code:ViewportMaskNV must: equal the value written to
 411  code:ViewportMaskPerViewNV[code:ViewIndex].
 412  Implementations will either use values taken from code:Position and
 413  code:ViewportMaskNV and invoke the shader once for each view, or will use
 414  values taken from code:PositionPerViewNV and code:ViewportMaskPerViewNV and
 415  invoke the shader fewer times.
 416  The values written to code:Position and code:ViewportMaskNV must: not depend
 417  on the values written to code:PositionPerViewNV and
 418  code:ViewportMaskPerViewNV, or vice versa (to allow compilers to eliminate
 419  the unused outputs).
 420  All attributes that do not have `*PerViewNV` counterparts must: not depend
 421  on code:ViewIndex.
 422  
 423  Per-view attributes are all-or-nothing for a subpass.
 424  That is, all pipelines compiled against a subpass that includes the
 425  ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit must: write
 426  per-view attributes to the `*PerViewNV[]` shader outputs, in addition to the
 427  non-per-view (e.g. code:Position) outputs.
 428  Pipelines compiled against a subpass that does not include this bit must:
 429  not include the `*PerViewNV[]` outputs in their interfaces.
 430  
 431  endif::VK_NVX_multiview_per_view_attributes[]
 432  
 433  .Valid Usage
 434  ****
 435    * [[VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-00841]]
 436      Each view index must: not be set in more than one element of
 437      pname:pCorrelationMasks
 438  ****
 439  
 440  include::{generated}/validity/structs/VkRenderPassMultiviewCreateInfo.txt[]
 441  --
 442  
 443  endif::VK_VERSION_1_1,VK_KHR_multiview[]
 444  ifdef::VK_EXT_fragment_density_map[]
 445  
 446  [[renderpass-fragmentdensitymapattachment]]
 447  [open,refpage='VkRenderPassFragmentDensityMapCreateInfoEXT',desc='Structure containing fragment density map attachment for render pass',type='structs']
 448  --
 449  
 450  If the sname:VkRenderPassCreateInfo::pname:pNext chain includes a
 451  sname:VkRenderPassFragmentDensityMapCreateInfoEXT structure, then that
 452  structure includes a fragment density map attachment for the render pass.
 453  
 454  The sname:VkRenderPassFragmentDensityMapCreateInfoEXT structure is defined
 455  as:
 456  
 457  include::{generated}/api/structs/VkRenderPassFragmentDensityMapCreateInfoEXT.txt[]
 458  
 459    * pname:sType is the type of this structure.
 460    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
 461    * pname:fragmentDensityMapAttachment is the fragment density map to use
 462      for the render pass.
 463  
 464  The fragment density map attachment is read at an implementation-dependent
 465  time either by the host during flink:vkCmdBeginRenderPass if the
 466  attachment's image view was not created with pname:flags containing
 467  ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT, or by the
 468  device when drawing commands in the renderpass execute
 469  ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT.
 470  
 471  If this structure is not present, it is as if
 472  pname:fragmentDensityMapAttachment was given as ename:VK_ATTACHMENT_UNUSED.
 473  
 474  .Valid Usage
 475  ****
 476    * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02547]]
 477      If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED,
 478      pname:fragmentDensityMapAttachment must: be less than
 479      sname:VkRenderPassCreateInfo::pname:attachmentCount
 480    * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02548]]
 481      If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED,
 482      pname:fragmentDensityMapAttachment must: not be an element of
 483      sname:VkSubpassDescription::pname:pInputAttachments,
 484      sname:VkSubpassDescription::pname:pColorAttachments,
 485      sname:VkSubpassDescription::pname:pResolveAttachments,
 486      sname:VkSubpassDescription::pname:pDepthStencilAttachment, or
 487      sname:VkSubpassDescription::pname:pPreserveAttachments for any subpass
 488    * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02549]]
 489      If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED,
 490      pname:layout must: be equal to
 491      ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT, or
 492      ename:VK_IMAGE_LAYOUT_GENERAL
 493    * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02550]]
 494      If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED,
 495      pname:fragmentDensityMapAttachment must: reference an attachment with a
 496      pname:loadOp equal to ename:VK_ATTACHMENT_LOAD_OP_LOAD or
 497      ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE.
 498    * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02551]]
 499      If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED,
 500      pname:fragmentDensityMapAttachment must: reference an attachment with a
 501      pname:storeOp equal to ename:VK_ATTACHMENT_STORE_OP_DONT_CARE.
 502  ****
 503  
 504  include::{generated}/validity/structs/VkRenderPassFragmentDensityMapCreateInfoEXT.txt[]
 505  --
 506  
 507  endif::VK_EXT_fragment_density_map[]
 508  
 509  [open,refpage='VkAttachmentDescription',desc='Structure specifying an attachment description',type='structs']
 510  --
 511  
 512  The sname:VkAttachmentDescription structure is defined as:
 513  
 514  include::{generated}/api/structs/VkAttachmentDescription.txt[]
 515  
 516    * pname:flags is a bitmask of elink:VkAttachmentDescriptionFlagBits
 517      specifying additional properties of the attachment.
 518    * pname:format is a elink:VkFormat value specifying the format of the
 519      image view that will be used for the attachment.
 520    * pname:samples is the number of samples of the image as defined in
 521      elink:VkSampleCountFlagBits.
 522    * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the
 523      contents of color and depth components of the attachment are treated at
 524      the beginning of the subpass where it is first used.
 525    * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the
 526      contents of color and depth components of the attachment are treated at
 527      the end of the subpass where it is last used.
 528    * pname:stencilLoadOp is a elink:VkAttachmentLoadOp value specifying how
 529      the contents of stencil components of the attachment are treated at the
 530      beginning of the subpass where it is first used.
 531    * pname:stencilStoreOp is a elink:VkAttachmentStoreOp value specifying how
 532      the contents of stencil components of the attachment are treated at the
 533      end of the last subpass where it is used.
 534    * pname:initialLayout is the layout the attachment image subresource will
 535      be in when a render pass instance begins.
 536    * pname:finalLayout is the layout the attachment image subresource will be
 537      transitioned to when a render pass instance ends.
 538  
 539  [[renderpass-load-store-ops]]
 540  If the attachment uses a color format, then pname:loadOp and pname:storeOp
 541  are used, and pname:stencilLoadOp and pname:stencilStoreOp are ignored.
 542  If the format has depth and/or stencil components, pname:loadOp and
 543  pname:storeOp apply only to the depth data, while pname:stencilLoadOp and
 544  pname:stencilStoreOp define how the stencil data is handled.
 545  pname:loadOp and pname:stencilLoadOp define the _load operations_ that
 546  execute as part of the first subpass that uses the attachment.
 547  pname:storeOp and pname:stencilStoreOp define the _store operations_ that
 548  execute as part of the last subpass that uses the attachment.
 549  
 550  The load operation for each sample in an attachment happens-before any
 551  recorded command which accesses the sample in the first subpass where the
 552  attachment is used.
 553  Load operations for attachments with a depth/stencil format execute in the
 554  ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage.
 555  Load operations for attachments with a color format execute in the
 556  ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
 557  
 558  The store operation for each sample in an attachment happens-after any
 559  recorded command which accesses the sample in the last subpass where the
 560  attachment is used.
 561  Store operations for attachments with a depth/stencil format execute in the
 562  ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage.
 563  Store operations for attachments with a color format execute in the
 564  ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.
 565  
 566  If an attachment is not used by any subpass, then pname:loadOp,
 567  pname:storeOp, pname:stencilStoreOp, and pname:stencilLoadOp are ignored,
 568  and the attachment's memory contents will not be modified by execution of a
 569  render pass instance.
 570  
 571  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
 572  
 573  The load and store operations apply on the first and last use of each view
 574  in the render pass, respectively.
 575  If a view index of an attachment is not included in the view mask in any
 576  subpass that uses it, then the load and store operations are ignored, and
 577  the attachment's memory contents will not be modified by execution of a
 578  render pass instance.
 579  
 580  endif::VK_VERSION_1_1,VK_KHR_multiview[]
 581  
 582  [[renderpass-precision]]
 583  During a render pass instance, input/color attachments with color formats
 584  that have a component size of 8, 16, or 32 bits must: be represented in the
 585  attachment's format throughout the instance.
 586  Attachments with other floating- or fixed-point color formats, or with depth
 587  components may: be represented in a format with a precision higher than the
 588  attachment format, but must: be represented with the same range.
 589  When such a component is loaded via the pname:loadOp, it will be converted
 590  into an implementation-dependent format used by the render pass.
 591  Such components must: be converted from the render pass format, to the
 592  format of the attachment, before they are resolved or stored at the end of a
 593  render pass instance via pname:storeOp.
 594  Conversions occur as described in <<fundamentals-numerics,Numeric
 595  Representation and Computation>> and <<fundamentals-fixedconv, Fixed-Point
 596  Data Conversions>>.
 597  
 598  [[renderpass-aliasing]]
 599  If pname:flags includes ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then
 600  the attachment is treated as if it shares physical memory with another
 601  attachment in the same render pass.
 602  This information limits the ability of the implementation to reorder certain
 603  operations (like layout transitions and the pname:loadOp) such that it is
 604  not improperly reordered against other uses of the same physical memory via
 605  a different attachment.
 606  This is described in more detail below.
 607  
 608  .Valid Usage
 609  ****
 610    * [[VUID-VkAttachmentDescription-finalLayout-00843]]
 611      pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or
 612      ename:VK_IMAGE_LAYOUT_PREINITIALIZED
 613  ****
 614  
 615  include::{generated}/validity/structs/VkAttachmentDescription.txt[]
 616  --
 617  
 618  ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
 619  
 620  [open,refpage='VkRenderPassInputAttachmentAspectCreateInfo',desc='Structure specifying, for a given subpass/input attachment pair, which aspect can: be read.',type='structs']
 621  --
 622  
 623  To specify which aspects of an input attachment can: be read add a
 624  slink:VkRenderPassInputAttachmentAspectCreateInfo structure to the
 625  pname:pNext chain of the slink:VkRenderPassCreateInfo structure:
 626  
 627  The sname:VkRenderPassInputAttachmentAspectCreateInfo structure is defined
 628  as:
 629  
 630  include::{generated}/api/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[]
 631  
 632  ifdef::VK_KHR_maintenance2[]
 633  or the equivalent
 634  
 635  include::{generated}/api/structs/VkRenderPassInputAttachmentAspectCreateInfoKHR.txt[]
 636  endif::VK_KHR_maintenance2[]
 637  
 638    * pname:sType is the type of this structure.
 639    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
 640    * pname:aspectReferenceCount is the number of elements in the
 641      pname:pAspectReferences array.
 642    * pname:pAspectReferences points to an array of pname:aspectReferenceCount
 643      number of slink:VkInputAttachmentAspectReference structures describing
 644      which aspect(s) can: be accessed for a given input attachment within a
 645      given subpass.
 646  
 647  include::{generated}/validity/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[]
 648  --
 649  
 650  [open,refpage='VkInputAttachmentAspectReference',desc='Structure specifying a subpass/input attachment pair and an aspect mask that can: be read.',type='structs']
 651  --
 652  
 653  The sname:VkInputAttachmentAspectReference structure specifies an aspect
 654  mask for a specific input attachment of a specific subpass in the render
 655  pass.
 656  
 657  pname:subpass and pname:inputAttachmentIndex index into the render pass as:
 658  
 659  pname:pCreateInfo::pname:pSubpasses[pname:subpass].pname:pInputAttachments[pname:inputAttachmentIndex]
 660  
 661  include::{generated}/api/structs/VkInputAttachmentAspectReference.txt[]
 662  
 663  ifdef::VK_KHR_maintenance2[]
 664  or the equivalent
 665  
 666  include::{generated}/api/structs/VkInputAttachmentAspectReferenceKHR.txt[]
 667  endif::VK_KHR_maintenance2[]
 668  
 669    * pname:subpass is an index into the pname:pSubpasses array of the parent
 670      sname:VkRenderPassCreateInfo structure.
 671    * pname:inputAttachmentIndex is an index into the pname:pInputAttachments
 672      of the specified subpass.
 673    * pname:aspectMask is a mask of which aspect(s) can: be accessed within
 674      the specified subpass.
 675  
 676  .Valid Usage
 677  ****
 678    * [[VUID-VkInputAttachmentAspectReference-aspectMask-01964]]
 679      pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT
 680  ifdef::VK_EXT_image_drm_format_modifier[]
 681    * [[VUID-VkInputAttachmentAspectReference-aspectMask-02250]]
 682      pname:aspectMask must: not include
 683      etext:VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index etext:i.
 684  endif::VK_EXT_image_drm_format_modifier[]
 685  ****
 686  
 687  include::{generated}/validity/structs/VkInputAttachmentAspectReference.txt[]
 688  --
 689  
 690  ifdef::editing-notes[]
 691  [NOTE]
 692  .editing-note
 693  ====
 694  TODO (Jon) - it's unclear whether the following two paragraphs are intended
 695  to apply to slink:VkAttachmentDescription, one of the extension structures
 696  described immediately above, or something else.
 697  The following description of elink:VkAttachmentDescriptionFlagBits should:
 698  probably be moved up to near slink:VkAttachmentDescription.
 699  ====
 700  endif::editing-notes[]
 701  
 702  An application must: only access the specified aspect(s).
 703  
 704  An application can: access any aspect of an input attachment that does not
 705  have a specified aspect mask.
 706  
 707  endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
 708  
 709  [open,refpage='VkAttachmentDescriptionFlagBits',desc='Bitmask specifying additional properties of an attachment',type='enums']
 710  --
 711  
 712  Bits which can: be set in slink:VkAttachmentDescription::pname:flags
 713  describing additional properties of the attachment are:
 714  
 715  include::{generated}/api/enums/VkAttachmentDescriptionFlagBits.txt[]
 716  
 717    * ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT specifies that the
 718      attachment aliases the same device memory as other attachments.
 719  
 720  --
 721  
 722  [open,refpage='VkAttachmentDescriptionFlags',desc='Bitmask of VkAttachmentDescriptionFlagBits',type='flags']
 723  --
 724  include::{generated}/api/flags/VkAttachmentDescriptionFlags.txt[]
 725  
 726  tname:VkAttachmentDescriptionFlags is a bitmask type for setting a mask of
 727  zero or more elink:VkAttachmentDescriptionFlagBits.
 728  --
 729  
 730  [open,refpage='VkAttachmentLoadOp',desc='Specify how contents of an attachment are treated at the beginning of a subpass',type='enums']
 731  --
 732  
 733  Possible values of slink:VkAttachmentDescription::pname:loadOp and
 734  pname:stencilLoadOp, specifying how the contents of the attachment are
 735  treated, are:
 736  
 737  include::{generated}/api/enums/VkAttachmentLoadOp.txt[]
 738  
 739    * ename:VK_ATTACHMENT_LOAD_OP_LOAD specifies that the previous contents of
 740      the image within the render area will be preserved.
 741      For attachments with a depth/stencil format, this uses the access type
 742      ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT.
 743      For attachments with a color format, this uses the access type
 744      ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT.
 745    * ename:VK_ATTACHMENT_LOAD_OP_CLEAR specifies that the contents within the
 746      render area will be cleared to a uniform value, which is specified when
 747      a render pass instance is begun.
 748      For attachments with a depth/stencil format, this uses the access type
 749      ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
 750      For attachments with a color format, this uses the access type
 751      ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
 752    * ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE specifies that the previous
 753      contents within the area need not be preserved; the contents of the
 754      attachment will be undefined: inside the render area.
 755      For attachments with a depth/stencil format, this uses the access type
 756      ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
 757      For attachments with a color format, this uses the access type
 758      ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
 759  
 760  --
 761  
 762  [open,refpage='VkAttachmentStoreOp',desc='Specify how contents of an attachment are treated at the end of a subpass',type='enums']
 763  --
 764  
 765  Possible values of slink:VkAttachmentDescription::pname:storeOp and
 766  pname:stencilStoreOp, specifying how the contents of the attachment are
 767  treated, are:
 768  
 769  include::{generated}/api/enums/VkAttachmentStoreOp.txt[]
 770  
 771    * ename:VK_ATTACHMENT_STORE_OP_STORE specifies the contents generated
 772      during the render pass and within the render area are written to memory.
 773      For attachments with a depth/stencil format, this uses the access type
 774      ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
 775      For attachments with a color format, this uses the access type
 776      ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
 777    * ename:VK_ATTACHMENT_STORE_OP_DONT_CARE specifies the contents within the
 778      render area are not needed after rendering, and may: be discarded; the
 779      contents of the attachment will be undefined: inside the render area.
 780      For attachments with a depth/stencil format, this uses the access type
 781      ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
 782      For attachments with a color format, this uses the access type
 783      ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
 784  
 785  --
 786  
 787  ifdef::editing-notes[]
 788  [NOTE]
 789  .editing-note
 790  ====
 791  TODO (Jon) - the following text may need to be moved back to combine with
 792  flink:vkCreateRenderPass above for automatic ref page generation.
 793  ====
 794  endif::editing-notes[]
 795  
 796  If a render pass uses multiple attachments that alias the same device
 797  memory, those attachments must: each include the
 798  ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment
 799  description flags.
 800  Attachments aliasing the same memory occurs in multiple ways:
 801  
 802    * Multiple attachments being assigned the same image view as part of
 803      framebuffer creation.
 804    * Attachments using distinct image views that correspond to the same image
 805      subresource of an image.
 806    * Attachments using views of distinct image subresources which are bound
 807      to overlapping memory ranges.
 808  
 809  [NOTE]
 810  .Note
 811  ====
 812  Render passes must: include subpass dependencies (either directly or via a
 813  subpass dependency chain) between any two subpasses that operate on the same
 814  attachment or aliasing attachments and those subpass dependencies must:
 815  include execution and memory dependencies separating uses of the aliases, if
 816  at least one of those subpasses writes to one of the aliases.
 817  These dependencies must: not include the ename:VK_DEPENDENCY_BY_REGION_BIT
 818  if the aliases are views of distinct image subresources which overlap in
 819  memory.
 820  ====
 821  
 822  Multiple attachments that alias the same memory must: not be used in a
 823  single subpass.
 824  A given attachment index must: not be used multiple times in a single
 825  subpass, with one exception: two subpass attachments can: use the same
 826  attachment index if at least one use is as an input attachment and neither
 827  use is as a resolve or preserve attachment.
 828  In other words, the same view can: be used simultaneously as an input and
 829  color or depth/stencil attachment, but must: not be used as multiple color
 830  or depth/stencil attachments nor as resolve or preserve attachments.
 831  The precise set of valid scenarios is described in more detail
 832  <<renderpass-feedbackloop, below>>.
 833  
 834  If a set of attachments alias each other, then all except the first to be
 835  used in the render pass must: use an pname:initialLayout of
 836  ename:VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases
 837  make their contents undefined:.
 838  Once an alias has been used and a different alias has been used after it,
 839  the first alias must: not be used in any later subpasses.
 840  However, an application can: assign the same image view to multiple aliasing
 841  attachment indices, which allows that image view to be used multiple times
 842  even if other aliases are used in between.
 843  
 844  [NOTE]
 845  .Note
 846  ====
 847  Once an attachment needs the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT
 848  bit, there should: be no additional cost of introducing additional aliases,
 849  and using these additional aliases may: allow more efficient clearing of the
 850  attachments on multiple uses via ename:VK_ATTACHMENT_LOAD_OP_CLEAR.
 851  ====
 852  
 853  [open,refpage='VkSubpassDescription',desc='Structure specifying a subpass description',type='structs']
 854  --
 855  
 856  The sname:VkSubpassDescription structure is defined as:
 857  
 858  include::{generated}/api/structs/VkSubpassDescription.txt[]
 859  
 860    * pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits
 861      specifying usage of the subpass.
 862    * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying
 863      the pipeline type supported for this subpass.
 864    * pname:inputAttachmentCount is the number of input attachments.
 865    * pname:pInputAttachments is an array of slink:VkAttachmentReference
 866      structures defining the input attachments for this subpass and their
 867      layouts.
 868    * pname:colorAttachmentCount is the number of color attachments.
 869    * pname:pColorAttachments is an array of slink:VkAttachmentReference
 870      structures defining the color attachments for this subpass and their
 871      layouts.
 872    * pname:pResolveAttachments is an optional array of
 873      pname:colorAttachmentCount slink:VkAttachmentReference structures
 874      defining the resolve attachments for this subpass and their layouts.
 875    * pname:pDepthStencilAttachment is a pointer to a
 876      slink:VkAttachmentReference specifying the depth/stencil attachment for
 877      this subpass and its layout.
 878    * pname:preserveAttachmentCount is the number of preserved attachments.
 879    * pname:pPreserveAttachments is an array of pname:preserveAttachmentCount
 880      render pass attachment indices identifying attachments that are not used
 881      by this subpass, but whose contents must: be preserved throughout the
 882      subpass.
 883  
 884  Each element of the pname:pInputAttachments array corresponds to an input
 885  attachment index in a fragment shader, i.e. if a shader declares an image
 886  variable decorated with a code:InputAttachmentIndex value of *X*, then it
 887  uses the attachment provided in pname:pInputAttachments[*X*].
 888  Input attachments must: also be bound to the pipeline in a descriptor set.
 889  If the pname:attachment member of any element of pname:pInputAttachments is
 890  ename:VK_ATTACHMENT_UNUSED, the application must: not read from the
 891  corresponding input attachment index.
 892  Fragment shaders can: use subpass input variables to access the contents of
 893  an input attachment at the fragment's (x, y, layer) framebuffer coordinates.
 894  
 895  Each element of the pname:pColorAttachments array corresponds to an output
 896  location in the shader, i.e. if the shader declares an output variable
 897  decorated with a code:Location value of *X*, then it uses the attachment
 898  provided in pname:pColorAttachments[*X*].
 899  If the pname:attachment member of any element of pname:pColorAttachments is
 900  ename:VK_ATTACHMENT_UNUSED, writes to the corresponding location by a
 901  fragment are discarded.
 902  
 903  If pname:pResolveAttachments is not `NULL`, each of its elements corresponds
 904  to a color attachment (the element in pname:pColorAttachments at the same
 905  index), and a multisample resolve operation is defined for each attachment.
 906  At the end of each subpass, multisample resolve operations read the
 907  subpass's color attachments, and resolve the samples for each pixel to the
 908  same pixel location in the corresponding resolve attachments, unless the
 909  resolve attachment index is ename:VK_ATTACHMENT_UNUSED.
 910  
 911  ifdef::VK_KHR_depth_stencil_resolve[]
 912  Similarly, if
 913  slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:pDepthStencilResolveAttachment
 914  is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, it
 915  corresponds to the depth/stencil attachment in
 916  pname:pDepthStencilAttachment, and multisample resolve operations for depth
 917  and stencil are defined by
 918  slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:depthResolveMode and
 919  slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:stencilResolveMode,
 920  respectively.
 921  At the end of each subpass, multisample resolve operations read the
 922  subpass's depth/stencil attachment, and resolve the samples for each pixel
 923  to the same pixel location in the corresponding resolve attachment.
 924  If slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:depthResolveMode
 925  is ename:VK_RESOLVE_MODE_NONE_KHR, then the depth component of the resolve
 926  attachment is not written to and its contents are preserved.
 927  Similarly, if
 928  slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:stencilResolveMode
 929  is ename:VK_RESOLVE_MODE_NONE_KHR, then the stencil component of the resolve
 930  attachment is not written to and its contents are preserved.
 931  slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:depthResolveMode is
 932  ignored if the elink:VkFormat of the pname:pDepthStencilResolveAttachment
 933  does not have a depth component.
 934  Similarly,
 935  slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:stencilResolveMode
 936  is ignored if the elink:VkFormat of the pname:pDepthStencilResolveAttachment
 937  does not have a stencil component.
 938  
 939  ifdef::VK_EXT_sample_locations[]
 940  If the image subresource range referenced by the depth/stencil attachment is
 941  created with
 942  ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT, then the
 943  multisample resolve operation uses the sample locations state specified in
 944  the pname:sampleLocationsInfo member of the element of the
 945  sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pPostSubpassSampleLocations
 946  for the subpass.
 947  endif::VK_EXT_sample_locations[]
 948  
 949  endif::VK_KHR_depth_stencil_resolve[]
 950  
 951  If pname:pDepthStencilAttachment is `NULL`, or if its attachment index is
 952  ename:VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil attachment
 953  will be used in the subpass.
 954  
 955  The contents of an attachment within the render area become undefined: at
 956  the start of a subpass *S* if all of the following conditions are true:
 957  
 958    * The attachment is used as a color, depth/stencil, or resolve attachment
 959      in any subpass in the render pass.
 960    * There is a subpass *S~1~* that uses or preserves the attachment, and a
 961      subpass dependency from *S~1~* to *S*.
 962    * The attachment is not used or preserved in subpass *S*.
 963  
 964  Once the contents of an attachment become undefined: in subpass *S*, they
 965  remain undefined: for subpasses in subpass dependency chains starting with
 966  subpass *S* until they are written again.
 967  However, they remain valid for subpasses in other subpass dependency chains
 968  starting with subpass *S~1~* if those subpasses use or preserve the
 969  attachment.
 970  
 971  .Valid Usage
 972  ****
 973    * [[VUID-VkSubpassDescription-pipelineBindPoint-00844]]
 974      pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS
 975    * [[VUID-VkSubpassDescription-colorAttachmentCount-00845]]
 976      pname:colorAttachmentCount must: be less than or equal to
 977      sname:VkPhysicalDeviceLimits::pname:maxColorAttachments
 978    * [[VUID-VkSubpassDescription-loadOp-00846]]
 979      If the first use of an attachment in this render pass is as an input
 980      attachment, and the attachment is not also used as a color or
 981      depth/stencil attachment in the same subpass, then pname:loadOp must:
 982      not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR
 983    * [[VUID-VkSubpassDescription-pResolveAttachments-00847]]
 984      If pname:pResolveAttachments is not `NULL`, for each resolve attachment
 985      that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color
 986      attachment must: not be ename:VK_ATTACHMENT_UNUSED
 987    * [[VUID-VkSubpassDescription-pResolveAttachments-00848]]
 988      If pname:pResolveAttachments is not `NULL`, for each resolve attachment
 989      that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color
 990      attachment must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT
 991    * [[VUID-VkSubpassDescription-pResolveAttachments-00849]]
 992      If pname:pResolveAttachments is not `NULL`, each resolve attachment that
 993      is not ename:VK_ATTACHMENT_UNUSED must: have a sample count of
 994      ename:VK_SAMPLE_COUNT_1_BIT
 995    * [[VUID-VkSubpassDescription-pResolveAttachments-00850]]
 996      If pname:pResolveAttachments is not `NULL`, each resolve attachment that
 997      is not ename:VK_ATTACHMENT_UNUSED must: have the same elink:VkFormat as
 998      its corresponding color attachment
 999    * [[VUID-VkSubpassDescription-pColorAttachments-01417]]
1000      All attachments in pname:pColorAttachments that are not
1001      ename:VK_ATTACHMENT_UNUSED must: have the same sample count
1002    * [[VUID-VkSubpassDescription-pInputAttachments-02647]]
1003      All attachments in pname:pInputAttachments that are not
1004      ename:VK_ATTACHMENT_UNUSED must: have formats whose features contain at
1005      least one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or
1006      ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT.
1007    * [[VUID-VkSubpassDescription-pColorAttachments-02648]]
1008      All attachments in pname:pColorAttachments that are not
1009      ename:VK_ATTACHMENT_UNUSED must: have formats whose features contain
1010      ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT
1011    * [[VUID-VkSubpassDescription-pResolveAttachments-02649]]
1012      All attachments in pname:pResolveAttachments that are not
1013      ename:VK_ATTACHMENT_UNUSED must: have formats whose features contain
1014      ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT
1015    * [[VUID-VkSubpassDescription-pDepthStencilAttachment-02650]]
1016      If pname:pDepthStencilAttachment is not `NULL` and the attachment is not
1017      ename:VK_ATTACHMENT_UNUSED then it must: have a format whose features
1018      contain ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
1019  ifdef::VK_AMD_mixed_attachment_samples[]
1020    * [[VUID-VkSubpassDescription-pColorAttachments-01506]]
1021      If the `VK_AMD_mixed_attachment_samples` extension is enabled, and all
1022      attachments in pname:pColorAttachments that are not
1023      ename:VK_ATTACHMENT_UNUSED must: have a sample count that is smaller
1024      than or equal to the sample count of pname:pDepthStencilAttachment if it
1025      is not ename:VK_ATTACHMENT_UNUSED
1026  endif::VK_AMD_mixed_attachment_samples[]
1027    * [[VUID-VkSubpassDescription-pDepthStencilAttachment-01418]]
1028      If neither the `VK_AMD_mixed_attachment_samples` nor the
1029      `VK_NV_framebuffer_mixed_samples` extensions are enabled, and if
1030      pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and any
1031      attachments in pname:pColorAttachments are not
1032      ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count
1033    * [[VUID-VkSubpassDescription-attachment-00853]]
1034      The pname:attachment member of each element of
1035      pname:pPreserveAttachments must: not be ename:VK_ATTACHMENT_UNUSED
1036    * [[VUID-VkSubpassDescription-pPreserveAttachments-00854]]
1037      Each element of pname:pPreserveAttachments must: not also be an element
1038      of any other member of the subpass description
1039    * [[VUID-VkSubpassDescription-layout-02519]]
1040      If any attachment is used by more than one slink:VkAttachmentReference
1041      member, then each use must: use the same pname:layout
1042  ifdef::VK_NVX_multiview_per_view_attributes[]
1043    * [[VUID-VkSubpassDescription-flags-00856]]
1044      If pname:flags includes
1045      ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must:
1046      also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX.
1047  endif::VK_NVX_multiview_per_view_attributes[]
1048  ****
1049  
1050  include::{generated}/validity/structs/VkSubpassDescription.txt[]
1051  --
1052  
1053  [open,refpage='VkSubpassDescriptionFlagBits',desc='Bitmask specifying usage of a subpass',type='enums']
1054  --
1055  
1056  Bits which can: be set in slink:VkSubpassDescription::pname:flags,
1057  specifying usage of the subpass, are:
1058  
1059  include::{generated}/api/enums/VkSubpassDescriptionFlagBits.txt[]
1060  
1061  ifdef::VK_NVX_multiview_per_view_attributes[]
1062    * ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX specifies that
1063      shaders compiled for this subpass write the attributes for all views in
1064      a single invocation of each vertex processing stage.
1065      All pipelines compiled against a subpass that includes this bit must:
1066      write per-view attributes to the `*PerViewNV[]` shader outputs, in
1067      addition to the non-per-view (e.g. code:Position) outputs.
1068    * ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX specifies
1069      that shaders compiled for this subpass use per-view positions which only
1070      differ in value in the x component.
1071      Per-view viewport mask can: also be used.
1072  endif::VK_NVX_multiview_per_view_attributes[]
1073  
1074  ifndef::VK_NVX_multiview_per_view_attributes[]
1075  [NOTE]
1076  .Note
1077  ====
1078  All bits for this type are defined by extensions, and none of those
1079  extensions are enabled in this build of the specification.
1080  ====
1081  endif::VK_NVX_multiview_per_view_attributes[]
1082  --
1083  
1084  [open,refpage='VkSubpassDescriptionFlags',desc='Bitmask of VkSubpassDescriptionFlagBits',type='flags']
1085  --
1086  include::{generated}/api/flags/VkSubpassDescriptionFlags.txt[]
1087  
1088  tname:VkSubpassDescriptionFlags is a bitmask type for setting a mask of zero
1089  or more elink:VkSubpassDescriptionFlagBits.
1090  --
1091  
1092  [open,refpage='VkAttachmentReference',desc='Structure specifying an attachment reference',type='structs']
1093  --
1094  
1095  The sname:VkAttachmentReference structure is defined as:
1096  
1097  include::{generated}/api/structs/VkAttachmentReference.txt[]
1098  
1099    * pname:attachment is either an integer value identifying an attachment at
1100      the corresponding index in
1101      slink:VkRenderPassCreateInfo::pname:pAttachments, or
1102      ename:VK_ATTACHMENT_UNUSED to signify that this attachment is not used.
1103    * pname:layout is a elink:VkImageLayout value specifying the layout the
1104      attachment uses during the subpass.
1105  
1106  .Valid Usage
1107  ****
1108    * [[VUID-VkAttachmentReference-layout-00857]]
1109      If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout
1110      must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or
1111      ename:VK_IMAGE_LAYOUT_PREINITIALIZED
1112  ****
1113  
1114  include::{generated}/validity/structs/VkAttachmentReference.txt[]
1115  --
1116  
1117  [open,refpage='VkSubpassDependency',desc='Structure specifying a subpass dependency',type='structs']
1118  --
1119  
1120  The sname:VkSubpassDependency structure is defined as:
1121  
1122  include::{generated}/api/structs/VkSubpassDependency.txt[]
1123  
1124    * pname:srcSubpass is the subpass index of the first subpass in the
1125      dependency, or ename:VK_SUBPASS_EXTERNAL.
1126    * pname:dstSubpass is the subpass index of the second subpass in the
1127      dependency, or ename:VK_SUBPASS_EXTERNAL.
1128    * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits
1129      specifying the <<synchronization-pipeline-stages-masks, source stage
1130      mask>>.
1131    * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits
1132      specifying the <<synchronization-pipeline-stages-masks, destination
1133      stage mask>>
1134    * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a
1135      <<synchronization-access-masks, source access mask>>.
1136    * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a
1137      <<synchronization-access-masks, destination access mask>>.
1138    * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits.
1139  
1140  If pname:srcSubpass is equal to pname:dstSubpass then the
1141  slink:VkSubpassDependency describes a
1142  <<synchronization-pipeline-barriers-subpass-self-dependencies, subpass
1143  self-dependency>>, and only constrains the pipeline barriers allowed within
1144  a subpass instance.
1145  Otherwise, when a render pass instance which includes a subpass dependency
1146  is submitted to a queue, it defines a memory dependency between the
1147  subpasses identified by pname:srcSubpass and pname:dstSubpass.
1148  
1149  If pname:srcSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the first
1150  <<synchronization-dependencies-scopes, synchronization scope>> includes
1151  commands that occur earlier in <<synchronization-submission-order,submission
1152  order>> than the flink:vkCmdBeginRenderPass used to begin the render pass
1153  instance.
1154  Otherwise, the first set of commands includes all commands submitted as part
1155  of the subpass instance identified by pname:srcSubpass and any load, store
1156  or multisample resolve operations on attachments used in pname:srcSubpass.
1157  In either case, the first synchronization scope is limited to operations on
1158  the pipeline stages determined by the
1159  <<synchronization-pipeline-stages-masks, source stage mask>> specified by
1160  pname:srcStageMask.
1161  
1162  If pname:dstSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the second
1163  <<synchronization-dependencies-scopes, synchronization scope>> includes
1164  commands that occur later in <<synchronization-submission-order,submission
1165  order>> than the flink:vkCmdEndRenderPass used to end the render pass
1166  instance.
1167  Otherwise, the second set of commands includes all commands submitted as
1168  part of the subpass instance identified by pname:dstSubpass and any load,
1169  store or multisample resolve operations on attachments used in
1170  pname:dstSubpass.
1171  In either case, the second synchronization scope is limited to operations on
1172  the pipeline stages determined by the
1173  <<synchronization-pipeline-stages-masks, destination stage mask>> specified
1174  by pname:dstStageMask.
1175  
1176  The first <<synchronization-dependencies-access-scopes, access scope>> is
1177  limited to access in the pipeline stages determined by the
1178  <<synchronization-pipeline-stages-masks, source stage mask>> specified by
1179  pname:srcStageMask.
1180  It is also limited to access types in the <<synchronization-access-masks,
1181  source access mask>> specified by pname:srcAccessMask.
1182  
1183  The second <<synchronization-dependencies-access-scopes, access scope>> is
1184  limited to access in the pipeline stages determined by the
1185  <<synchronization-pipeline-stages-masks, destination stage mask>> specified
1186  by pname:dstStageMask.
1187  It is also limited to access types in the <<synchronization-access-masks,
1188  destination access mask>> specified by pname:dstAccessMask.
1189  
1190  The <<synchronization-dependencies-available-and-visible, availability and
1191  visibility operations>> defined by a subpass dependency affect the execution
1192  of <<renderpass-layout-transitions, image layout transitions>> within the
1193  render pass.
1194  
1195  [NOTE]
1196  .Note
1197  ====
1198  For non-attachment resources, the memory dependency expressed by subpass
1199  dependency is nearly identical to that of a slink:VkMemoryBarrier (with
1200  matching pname:srcAccessMask/pname:dstAccessMask parameters) submitted as a
1201  part of a flink:vkCmdPipelineBarrier (with matching
1202  pname:srcStageMask/pname:dstStageMask parameters).
1203  The only difference being that its scopes are limited to the identified
1204  subpasses rather than potentially affecting everything before and after.
1205  
1206  For attachments however, subpass dependencies work more like a
1207  slink:VkImageMemoryBarrier defined similarly to the slink:VkMemoryBarrier
1208  above, the queue family indices set to ename:VK_QUEUE_FAMILY_IGNORED, and
1209  layouts as follows:
1210  
1211    * The equivalent to pname:oldLayout is the attachment's layout according
1212      to the subpass description for pname:srcSubpass.
1213    * The equivalent to pname:newLayout is the attachment's layout according
1214      to the subpass description for pname:dstSubpass.
1215  ====
1216  
1217  .Valid Usage
1218  ****
1219    * [[VUID-VkSubpassDependency-srcSubpass-00858]]
1220      If pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:srcStageMask
1221      must: not include ename:VK_PIPELINE_STAGE_HOST_BIT
1222    * [[VUID-VkSubpassDependency-dstSubpass-00859]]
1223      If pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:dstStageMask
1224      must: not include ename:VK_PIPELINE_STAGE_HOST_BIT
1225    * [[VUID-VkSubpassDependency-srcStageMask-00860]]
1226      If the <<features-geometryShader,geometry shaders>> feature is not
1227      enabled, pname:srcStageMask must: not contain
1228      ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
1229    * [[VUID-VkSubpassDependency-dstStageMask-00861]]
1230      If the <<features-geometryShader,geometry shaders>> feature is not
1231      enabled, pname:dstStageMask must: not contain
1232      ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
1233    * [[VUID-VkSubpassDependency-srcStageMask-00862]]
1234      If the <<features-tessellationShader,tessellation shaders>> feature is
1235      not enabled, pname:srcStageMask must: not contain
1236      ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
1237      ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
1238    * [[VUID-VkSubpassDependency-dstStageMask-00863]]
1239      If the <<features-tessellationShader,tessellation shaders>> feature is
1240      not enabled, pname:dstStageMask must: not contain
1241      ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
1242      ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
1243    * [[VUID-VkSubpassDependency-srcSubpass-00864]]
1244      pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless
1245      one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies
1246      and ensure a valid execution order
1247    * [[VUID-VkSubpassDependency-srcSubpass-00865]]
1248      pname:srcSubpass and pname:dstSubpass must: not both be equal to
1249      ename:VK_SUBPASS_EXTERNAL
1250    * [[VUID-VkSubpassDependency-srcSubpass-01989]]
1251      If pname:srcSubpass is equal to pname:dstSubpass, pname:srcStageMask and
1252      pname:dstStageMask must: not set any bits that are neither
1253      ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT, nor one of the
1254      <<synchronization-pipeline-stages-types,graphics pipeline stages>>
1255    * [[VUID-VkSubpassDependency-srcSubpass-00867]]
1256      If pname:srcSubpass is equal to pname:dstSubpass and not all of the
1257      stages in pname:srcStageMask and pname:dstStageMask are
1258      <<synchronization-framebuffer-regions,framebuffer-space stages>>, the
1259      <<synchronization-pipeline-stages-order, logically latest>> pipeline
1260      stage in pname:srcStageMask must: be
1261      <<synchronization-pipeline-stages-order, logically earlier>> than or
1262      equal to the <<synchronization-pipeline-stages-order, logically
1263      earliest>> pipeline stage in pname:dstStageMask
1264    * [[VUID-VkSubpassDependency-srcAccessMask-00868]]
1265      Any access flag included in pname:srcAccessMask must: be supported by
1266      one of the pipeline stages in pname:srcStageMask, as specified in the
1267      <<synchronization-access-types-supported, table of supported access
1268      types>>
1269    * [[VUID-VkSubpassDependency-dstAccessMask-00869]]
1270      Any access flag included in pname:dstAccessMask must: be supported by
1271      one of the pipeline stages in pname:dstStageMask, as specified in the
1272      <<synchronization-access-types-supported, table of supported access
1273      types>>
1274    * [[VUID-VkSubpassDependency-srcSubpass-02243]]
1275      If pname:srcSubpass equals pname:dstSubpass, and pname:srcStageMask and
1276      pname:dstStageMask both include a
1277      <<synchronization-framebuffer-regions,framebuffer-space stage>>, then
1278      pname:dependencyFlags must: include ename:VK_DEPENDENCY_BY_REGION_BIT
1279  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
1280    * [[VUID-VkSubpassDependency-dependencyFlags-02520]]
1281      If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT,
1282      pname:srcSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL
1283    * [[VUID-VkSubpassDependency-dependencyFlags-02521]]
1284      If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT,
1285      pname:dstSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL
1286    * [[VUID-VkSubpassDependency-srcSubpass-00872]]
1287      If pname:srcSubpass equals pname:dstSubpass and that subpass has more
1288      than one bit set in the view mask, then pname:dependencyFlags must:
1289      include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT
1290  endif::VK_VERSION_1_1,VK_KHR_multiview[]
1291  ifdef::VK_NV_mesh_shader[]
1292    * [[VUID-VkSubpassDependency-srcStageMask-02099]]
1293      If the <<features-meshShader,mesh shaders>> feature is not enabled,
1294      pname:srcStageMask must: not contain
1295      ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV
1296    * [[VUID-VkSubpassDependency-srcStageMask-02100]]
1297      If the <<features-taskShader,task shaders>> feature is not enabled,
1298      pname:srcStageMask must: not contain
1299      ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV
1300    * [[VUID-VkSubpassDependency-dstStageMask-02101]]
1301      If the <<features-meshShader,mesh shaders>> feature is not enabled,
1302      pname:dstStageMask must: not contain
1303      ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV
1304    * [[VUID-VkSubpassDependency-dstStageMask-02102]]
1305      If the <<features-taskShader,task shaders>> feature is not enabled,
1306      pname:dstStageMask must: not contain
1307      ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV
1308  endif::VK_NV_mesh_shader[]
1309  ****
1310  
1311  include::{generated}/validity/structs/VkSubpassDependency.txt[]
1312  --
1313  
1314  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
1315  
1316  When multiview is enabled, the execution of the multiple views of one
1317  subpass may: not occur simultaneously or even back-to-back, and rather may:
1318  be interleaved with the execution of other subpasses.
1319  The load and store operations apply to attachments on a per-view basis.
1320  For example, an attachment using ename:VK_ATTACHMENT_LOAD_OP_CLEAR will have
1321  each view cleared on first use, but the first use of one view may be
1322  temporally distant from the first use of another view.
1323  
1324  [NOTE]
1325  .Note
1326  ====
1327  A good mental model for multiview is to think of a multiview subpass as if
1328  it were a collection of individual (per-view) subpasses that are logically
1329  grouped together and described as a single multiview subpass in the API.
1330  Similarly, a multiview attachment can be thought of like several individual
1331  attachments that happen to be layers in a single image.
1332  A view-local dependency between two multiview subpasses acts like a set of
1333  one-to-one dependencies between corresponding pairs of per-view subpasses.
1334  A view-global dependency between two multiview subpasses acts like a set of
1335  [eq]#N {times} M# dependencies between all pairs of per-view subpasses in
1336  the source and destination.
1337  Thus, it is a more compact representation which also makes clear the
1338  commonality and reuse that is present between views in a subpass.
1339  This interpretation motivates the answers to questions like "`when does the
1340  load op apply`" - it is on the first use of each view of an attachment, as
1341  if each view were a separate attachment.
1342  ====
1343  
1344  endif::VK_VERSION_1_1,VK_KHR_multiview[]
1345  
1346  ifdef::VK_EXT_transform_feedback[]
1347  If any two subpasses of a render pass activate transform feedback to the
1348  same bound transform feedback buffers, a subpass dependency must: be
1349  included (either directly or via some intermediate subpasses) between them.
1350  endif::VK_EXT_transform_feedback[]
1351  
1352  ifdef::editing-notes[]
1353  [NOTE]
1354  .editing-note
1355  ====
1356  The following two alleged implicit dependencies are practically no-ops, as
1357  the operations they describe are already guaranteed by semaphores and
1358  submission order (so they are almost entirely no-ops on their own).
1359  The *only* reason they exist is because it simplifies reasoning about where
1360  <<renderpass-layout-transitions, automatic layout transitions>> happen.
1361  Further rewrites of this chapter could potentially remove the need for
1362  these.
1363  ====
1364  endif::editing-notes[]
1365  
1366  If there is no subpass dependency from ename:VK_SUBPASS_EXTERNAL to the
1367  first subpass that uses an attachment, then an implicit subpass dependency
1368  exists from ename:VK_SUBPASS_EXTERNAL to the first subpass it is used in.
1369  The subpass dependency operates as if defined with the following parameters:
1370  
1371  [source,c]
1372  ---------------------------------------------------
1373  VkSubpassDependency implicitDependency = {
1374      .srcSubpass = VK_SUBPASS_EXTERNAL;
1375      .dstSubpass = firstSubpass; // First subpass attachment is used in
1376      .srcStageMask = VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT;
1377      .dstStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT;
1378      .srcAccessMask = 0;
1379      .dstAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT |
1380                       VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
1381                       VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
1382                       VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT |
1383                       VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT;
1384      .dependencyFlags = 0;
1385  };
1386  ---------------------------------------------------
1387  
1388  Similarly, if there is no subpass dependency from the last subpass that uses
1389  an attachment to ename:VK_SUBPASS_EXTERNAL, then an implicit subpass
1390  dependency exists from the last subpass it is used in to
1391  ename:VK_SUBPASS_EXTERNAL.
1392  The subpass dependency operates as if defined with the following parameters:
1393  
1394  [source,c]
1395  ---------------------------------------------------
1396  VkSubpassDependency implicitDependency = {
1397      .srcSubpass = lastSubpass; // Last subpass attachment is used in
1398      .dstSubpass = VK_SUBPASS_EXTERNAL;
1399      .srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT;
1400      .dstStageMask = VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT;
1401      .srcAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT |
1402                       VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
1403                       VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
1404                       VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT |
1405                       VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT;
1406      .dstAccessMask = 0;
1407      .dependencyFlags = 0;
1408  };
1409  ---------------------------------------------------
1410  
1411  [[renderpass-layout-transitions]]
1412  As subpasses may: overlap or execute out of order with regards to other
1413  subpasses unless a subpass dependency chain describes otherwise, the layout
1414  transitions required between subpasses cannot: be known to an application.
1415  Instead, an application provides the layout that each attachment must: be in
1416  at the start and end of a render pass, and the layout it must: be in during
1417  each subpass it is used in.
1418  The implementation then must: execute layout transitions between subpasses
1419  in order to guarantee that the images are in the layouts required by each
1420  subpass, and in the final layout at the end of the render pass.
1421  
1422  Automatic layout transitions apply to the entire image subresource attached
1423  to the framebuffer.
1424  ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
1425  If the attachment view is a 2D or 2D array view of a 3D image, even if the
1426  attachment view only refers to a subset of the slices of the selected mip
1427  level of the 3D image, automatic layout transitions apply to the entire
1428  subresource referenced which is the entire mip level in this case.
1429  endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
1430  
1431  Automatic layout transitions away from the layout used in a subpass
1432  happen-after the availability operations for all dependencies with that
1433  subpass as the pname:srcSubpass.
1434  
1435  Automatic layout transitions into the layout used in a subpass happen-before
1436  the visibility operations for all dependencies with that subpass as the
1437  pname:dstSubpass.
1438  
1439  Automatic layout transitions away from pname:initialLayout happens-after the
1440  availability operations for all dependencies with a pname:srcSubpass equal
1441  to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses the attachment
1442  that will be transitioned.
1443  For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT,
1444  automatic layout transitions away from pname:initialLayout happen-after the
1445  availability operations for all dependencies with a pname:srcSubpass equal
1446  to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses any aliased
1447  attachment.
1448  
1449  Automatic layout transitions into pname:finalLayout happens-before the
1450  visibility operations for all dependencies with a pname:dstSubpass equal to
1451  ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses the attachment that
1452  will be transitioned.
1453  For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT,
1454  automatic layout transitions into pname:finalLayout happen-before the
1455  visibility operations for all dependencies with a pname:dstSubpass equal to
1456  ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses any aliased
1457  attachment.
1458  
1459  ifdef::VK_EXT_sample_locations[]
1460  
1461  The image layout of the depth aspect of a depth/stencil attachment referring
1462  to an image created with
1463  ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent
1464  on the last sample locations used to render to the attachment, thus
1465  automatic layout transitions use the sample locations state specified in
1466  slink:VkRenderPassSampleLocationsBeginInfoEXT.
1467  
1468  Automatic layout transitions of an attachment referring to a depth/stencil
1469  image created with
1470  ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT use the
1471  sample locations the image subresource range referenced by the attachment
1472  was last rendered with.
1473  If the current render pass does not use the attachment as a depth/stencil
1474  attachment in any subpass that happens-before, the automatic layout
1475  transition uses the sample locations state specified in the
1476  pname:sampleLocationsInfo member of the element of the
1477  sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pAttachmentInitialSampleLocations
1478  array for which the pname:attachmentIndex member equals the attachment index
1479  of the attachment, if one is specified.
1480  Otherwise, the automatic layout transition uses the sample locations state
1481  specified in the pname:sampleLocationsInfo member of the element of the
1482  sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pPostSubpassSampleLocations
1483  array for which the pname:subpassIndex member equals the index of the
1484  subpass that last used the attachment as a depth/stencil attachment, if one
1485  is specified.
1486  
1487  If no sample locations state has been specified for an automatic layout
1488  transition performed on an attachment referring to a depth/stencil image
1489  created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
1490  the contents of the depth aspect of the depth/stencil attachment become
1491  undefined: as if the layout of the attachment was transitioned from the
1492  ename:VK_IMAGE_LAYOUT_UNDEFINED layout.
1493  
1494  endif::VK_EXT_sample_locations[]
1495  
1496  If two subpasses use the same attachment in different layouts, and both
1497  layouts are read-only, no subpass dependency needs to be specified between
1498  those subpasses.
1499  If an implementation treats those layouts separately, it must: insert an
1500  implicit subpass dependency between those subpasses to separate the uses in
1501  each layout.
1502  The subpass dependency operates as if defined with the following parameters:
1503  
1504  [source,c]
1505  ---------------------------------------------------
1506  // Used for input attachments
1507  VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
1508  VkAccessFlags inputAttachmentAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT;
1509  
1510  // Used for depth/stencil attachments
1511  VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT;
1512  VkAccessFlags depthStencilAttachmentAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT;
1513  
1514  VkSubpassDependency implicitDependency = {
1515      .srcSubpass = firstSubpass;
1516      .dstSubpass = secondSubpass;
1517      .srcStageMask = inputAttachmentStages | depthStencilAttachmentStages;
1518      .dstStageMask = inputAttachmentStages | depthStencilAttachmentStages;
1519      .srcAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess;
1520      .dstAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess;
1521      .dependencyFlags = 0;
1522  };
1523  ---------------------------------------------------
1524  
1525  [[renderpass-feedbackloop]]
1526  If a subpass uses the same attachment as both an input attachment and either
1527  a color attachment or a depth/stencil attachment, writes via the color or
1528  depth/stencil attachment are not automatically made visible to reads via the
1529  input attachment, causing a _feedback loop_, except in any of the following
1530  conditions:
1531  
1532    * If the color components or depth/stencil components read by the input
1533      attachment are mutually exclusive with the components written by the
1534      color or depth/stencil attachments, then there is no feedback loop.
1535      This requires the graphics pipelines used by the subpass to disable
1536      writes to color components that are read as inputs via the
1537      pname:colorWriteMask, and to disable writes to depth/stencil components
1538      that are read as inputs via pname:depthWriteEnable or
1539      pname:stencilTestEnable.
1540    * If the attachment is used as an input attachment and depth/stencil
1541      attachment only, and the depth/stencil attachment is not written to.
1542    * If a memory dependency is inserted between when the attachment is
1543      written and when it is subsequently read by later fragments.
1544      <<synchronization-pipeline-barriers, Pipeline barriers>> expressing a
1545      <<synchronization-pipeline-barriers-subpass-self-dependencies, subpass
1546      self-dependency>> are the only way to achieve this, and one must: be
1547      inserted every time a fragment will read values at a particular sample
1548      (x, y, layer, sample) coordinate, if those values have been written
1549      since the most recent pipeline barrier; or the since start of the
1550      subpass if there have been no pipeline barriers since the start of the
1551      subpass.
1552  
1553  An attachment used as both an input attachment and a color attachment must:
1554  be in the
1555  ifdef::VK_KHR_shared_presentable_image[]
1556  ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or
1557  endif::VK_KHR_shared_presentable_image[]
1558  ename:VK_IMAGE_LAYOUT_GENERAL layout.
1559  An attachment used as an input attachment and depth/stencil attachment must:
1560  be in the
1561  ifdef::VK_KHR_shared_presentable_image[]
1562  ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
1563  endif::VK_KHR_shared_presentable_image[]
1564  ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
1565  ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
1566  ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
1567  endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
1568  ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or
1569  ename:VK_IMAGE_LAYOUT_GENERAL layout.
1570  An attachment must: not be used as both a depth/stencil attachment and a
1571  color attachment.
1572  
1573  ifdef::VK_KHR_create_renderpass2[]
1574  
1575  A more extensible version of render pass creation is also defined below.
1576  
1577  [open,refpage='vkCreateRenderPass2KHR',desc='Create a new render pass object',type='protos']
1578  --
1579  
1580  To create a render pass, call:
1581  
1582  include::{generated}/api/protos/vkCreateRenderPass2KHR.txt[]
1583  
1584    * pname:device is the logical device that creates the render pass.
1585    * pname:pCreateInfo is a pointer to an instance of the
1586      slink:VkRenderPassCreateInfo2KHR structure that describes the parameters
1587      of the render pass.
1588    * pname:pAllocator controls host memory allocation as described in the
1589      <<memory-allocation, Memory Allocation>> chapter.
1590    * pname:pRenderPass points to a sname:VkRenderPass handle in which the
1591      resulting render pass object is returned.
1592  
1593  This command is functionally identical to flink:vkCreateRenderPass, but
1594  includes extensible sub-structures that include pname:sType and pname:pNext
1595  parameters, allowing them to be more easily extended.
1596  
1597  include::{generated}/validity/protos/vkCreateRenderPass2KHR.txt[]
1598  --
1599  
1600  [open,refpage='VkRenderPassCreateInfo2KHR',desc='Structure specifying parameters of a newly created render pass',type='structs']
1601  --
1602  
1603  The sname:VkRenderPassCreateInfo2KHR structure is defined as:
1604  
1605  include::{generated}/api/structs/VkRenderPassCreateInfo2KHR.txt[]
1606  
1607    * pname:sType is the type of this structure.
1608    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
1609    * pname:flags is reserved for future use.
1610    * pname:attachmentCount is the number of attachments used by this render
1611      pass.
1612    * pname:pAttachments points to an array of pname:attachmentCount
1613      slink:VkAttachmentDescription2KHR structures describing the attachments
1614      used by the render pass.
1615    * pname:subpassCount is the number of subpasses to create.
1616    * pname:pSubpasses points to an array of pname:subpassCount
1617      slink:VkSubpassDescription2KHR structures describing each subpass.
1618    * pname:dependencyCount is the number of dependencies between pairs of
1619      subpasses.
1620    * pname:pDependencies points to an array of pname:dependencyCount
1621      slink:VkSubpassDependency2KHR structures describing dependencies between
1622      pairs of subpasses.
1623    * pname:correlatedViewMaskCount is the number of correlation masks.
1624    * pname:pCorrelatedViewMasks is an array of view masks indicating sets of
1625      views that may: be more efficient to render concurrently.
1626  
1627  Parameters defined by this structure with the same name as those in
1628  slink:VkRenderPassCreateInfo have the identical effect to those parameters;
1629  the child structures are variants of those used in
1630  slink:VkRenderPassCreateInfo which include pname:sType and pname:pNext
1631  parameters, allowing them to be extended.
1632  
1633  If the slink:VkSubpassDescription2KHR::pname:viewMask member of any element
1634  of pname:pSubpasses is not zero, _multiview_ functionality is considered to
1635  be enabled for this render pass.
1636  
1637  pname:correlatedViewMaskCount and pname:pCorrelatedViewMasks have the same
1638  effect as slink:VkRenderPassMultiviewCreateInfo::pname:correlationMaskCount
1639  and slink:VkRenderPassMultiviewCreateInfo::pname:pCorrelationMasks,
1640  respectively.
1641  
1642  .Valid Usage
1643  ****
1644    * [[VUID-VkRenderPassCreateInfo2KHR-None-03049]]
1645      If any two subpasses operate on attachments with overlapping ranges of
1646      the same sname:VkDeviceMemory object, and at least one subpass writes to
1647      that area of sname:VkDeviceMemory, a subpass dependency must: be
1648      included (either directly or via some intermediate subpasses) between
1649      them
1650    * [[VUID-VkRenderPassCreateInfo2KHR-attachment-03050]]
1651      If the pname:attachment member of any element of
1652      pname:pInputAttachments, pname:pColorAttachments,
1653      pname:pResolveAttachments or pname:pDepthStencilAttachment, or the
1654      attachment indexed by any element of pname:pPreserveAttachments in any
1655      given element of pname:pSubpasses is bound to a range of a
1656      sname:VkDeviceMemory object that overlaps with any other attachment in
1657      any subpass (including the same subpass), the
1658      sname:VkAttachmentDescription2KHR structures describing them must:
1659      include ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in pname:flags
1660    * [[VUID-VkRenderPassCreateInfo2KHR-attachment-03051]]
1661      If the pname:attachment member of any element of
1662      pname:pInputAttachments, pname:pColorAttachments,
1663      pname:pResolveAttachments or pname:pDepthStencilAttachment, or any
1664      element of pname:pPreserveAttachments in any given element of
1665      pname:pSubpasses is not ename:VK_ATTACHMENT_UNUSED, it must: be less
1666      than pname:attachmentCount
1667    * [[VUID-VkRenderPassCreateInfo2KHR-pAttachments-02522]]
1668      For any member of pname:pAttachments with a pname:loadOp equal to
1669      ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
1670      must: not specify a pname:layout equal to
1671      ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL,
1672      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or
1673      ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
1674    * [[VUID-VkRenderPassCreateInfo2KHR-pAttachments-02523]]
1675      For any member of pname:pAttachments with a pname:stencilLoadOp equal to
1676      ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment
1677      must: not specify a pname:layout equal to
1678      ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL,
1679      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or
1680      ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL.
1681    * [[VUID-VkRenderPassCreateInfo2KHR-pDependencies-03054]]
1682      For any element of pname:pDependencies, if the pname:srcSubpass is not
1683      ename:VK_SUBPASS_EXTERNAL, all stage flags included in the
1684      pname:srcStageMask member of that dependency must: be a pipeline stage
1685      supported by the <<synchronization-pipeline-stages-types, pipeline>>
1686      identified by the pname:pipelineBindPoint member of the source subpass
1687    * [[VUID-VkRenderPassCreateInfo2KHR-pDependencies-03055]]
1688      For any element of pname:pDependencies, if the pname:dstSubpass is not
1689      ename:VK_SUBPASS_EXTERNAL, all stage flags included in the
1690      pname:dstStageMask member of that dependency must: be a pipeline stage
1691      supported by the <<synchronization-pipeline-stages-types, pipeline>>
1692      identified by the pname:pipelineBindPoint member of the destination
1693      subpass
1694    * [[VUID-VkRenderPassCreateInfo2KHR-pCorrelatedViewMasks-03056]]
1695      The set of bits included in any element of pname:pCorrelatedViewMasks
1696      must: not overlap with the set of bits included in any other element of
1697      pname:pCorrelatedViewMasks
1698    * [[VUID-VkRenderPassCreateInfo2KHR-viewMask-03057]]
1699      If the slink:VkSubpassDescription2KHR::pname:viewMask member of all
1700      elements of pname:pSubpasses is `0`, pname:correlatedViewMaskCount must:
1701      be `0`
1702    * [[VUID-VkRenderPassCreateInfo2KHR-viewMask-03058]]
1703      The slink:VkSubpassDescription2KHR::pname:viewMask member of all
1704      elements of pname:pSubpasses must: either all be `0`, or all not be `0`
1705    * [[VUID-VkRenderPassCreateInfo2KHR-viewMask-03059]]
1706      If the slink:VkSubpassDescription2KHR::pname:viewMask member of all
1707      elements of pname:pSubpasses is `0`, the pname:dependencyFlags member of
1708      any element of pname:pDependencies must: not include
1709      ename:VK_DEPENDENCY_VIEW_LOCAL_BIT
1710    * [[VUID-VkRenderPassCreateInfo2KHR-pDependencies-03060]]
1711      For any element of pname:pDependencies where its pname:srcSubpass member
1712      equals its pname:dstSubpass member, if the pname:viewMask member of the
1713      corresponding element of pname:pSubpasses includes more than one bit,
1714      its pname:dependencyFlags member must: include
1715      ename:VK_DEPENDENCY_VIEW_LOCAL_BIT
1716    * [[VUID-VkRenderPassCreateInfo2KHR-viewMask-02524]]
1717      The pname:viewMask member must: not have a bit set at an index greater
1718      than or equal to
1719      slink:VkPhysicalDeviceLimits::pname:maxFramebufferLayers
1720    * [[VUID-VkRenderPassCreateInfo2KHR-attachment-02525]]
1721      If the pname:attachment member of any element of the
1722      pname:pInputAttachments member of any element of pname:pSubpasses is not
1723      ename:VK_ATTACHMENT_UNUSED, the pname:aspectMask member of that element
1724      of pname:pInputAttachments must: only include aspects that are present
1725      in images of the format specified by the element of pname:pAttachments
1726      specified by pname:attachment
1727    * [[VUID-VkRenderPassCreateInfo2KHR-srcSubpass-02526]]
1728      The pname:srcSubpass member of each element of pname:pDependencies must:
1729      be less than pname:subpassCount
1730    * [[VUID-VkRenderPassCreateInfo2KHR-dstSubpass-02527]]
1731      The pname:dstSubpass member of each element of pname:pDependencies must:
1732      be less than pname:subpassCount
1733  ****
1734  
1735  include::{generated}/validity/structs/VkRenderPassCreateInfo2KHR.txt[]
1736  --
1737  
1738  [open,refpage='VkAttachmentDescription2KHR',desc='Structure specifying an attachment description',type='structs']
1739  --
1740  
1741  The sname:VkAttachmentDescription2KHR structure is defined as:
1742  
1743  include::{generated}/api/structs/VkAttachmentDescription2KHR.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:flags is a bitmask of elink:VkAttachmentDescriptionFlagBits
1748      specifying additional properties of the attachment.
1749    * pname:format is a elink:VkFormat value specifying the format of the
1750      image that will be used for the attachment.
1751    * pname:samples is the number of samples of the image as defined in
1752      elink:VkSampleCountFlagBits.
1753    * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the
1754      contents of color and depth components of the attachment are treated at
1755      the beginning of the subpass where it is first used.
1756    * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the
1757      contents of color and depth components of the attachment are treated at
1758      the end of the subpass where it is last used.
1759    * pname:stencilLoadOp is a elink:VkAttachmentLoadOp value specifying how
1760      the contents of stencil components of the attachment are treated at the
1761      beginning of the subpass where it is first used.
1762    * pname:stencilStoreOp is a elink:VkAttachmentStoreOp value specifying how
1763      the contents of stencil components of the attachment are treated at the
1764      end of the last subpass where it is used.
1765    * pname:initialLayout is the layout the attachment image subresource will
1766      be in when a render pass instance begins.
1767    * pname:finalLayout is the layout the attachment image subresource will be
1768      transitioned to when a render pass instance ends.
1769  
1770  Parameters defined by this structure with the same name as those in
1771  slink:VkAttachmentDescription have the identical effect to those parameters.
1772  
1773  .Valid Usage
1774  ****
1775    * [[VUID-VkAttachmentDescription2KHR-finalLayout-03061]]
1776      pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or
1777      ename:VK_IMAGE_LAYOUT_PREINITIALIZED
1778  ****
1779  
1780  include::{generated}/validity/structs/VkAttachmentDescription2KHR.txt[]
1781  --
1782  
1783  [open,refpage='VkSubpassDescription2KHR',desc='Structure specifying a subpass description',type='structs']
1784  --
1785  
1786  The sname:VkSubpassDescription2KHR structure is defined as:
1787  
1788  include::{generated}/api/structs/VkSubpassDescription2KHR.txt[]
1789  
1790    * pname:sType is the type of this structure.
1791    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
1792    * pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits
1793      specifying usage of the subpass.
1794    * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying
1795      the pipeline type supported for this subpass.
1796    * pname:viewMask is a bitfield of view indices describing which views
1797      rendering is broadcast to in this subpass, when multiview is enabled.
1798    * pname:inputAttachmentCount is the number of input attachments.
1799    * pname:pInputAttachments is an array of slink:VkAttachmentReference2KHR
1800      structures defining the input attachments for this subpass and their
1801      layouts.
1802    * pname:colorAttachmentCount is the number of color attachments.
1803    * pname:pColorAttachments is an array of slink:VkAttachmentReference2KHR
1804      structures defining the color attachments for this subpass and their
1805      layouts.
1806    * pname:pResolveAttachments is an optional array of
1807      pname:colorAttachmentCount slink:VkAttachmentReference2KHR structures
1808      defining the resolve attachments for this subpass and their layouts.
1809    * pname:pDepthStencilAttachment is a pointer to a
1810      slink:VkAttachmentReference2KHR specifying the depth/stencil attachment
1811      for this subpass and its layout.
1812    * pname:preserveAttachmentCount is the number of preserved attachments.
1813    * pname:pPreserveAttachments is an array of pname:preserveAttachmentCount
1814      render pass attachment indices identifying attachments that are not used
1815      by this subpass, but whose contents must: be preserved throughout the
1816      subpass.
1817  
1818  Parameters defined by this structure with the same name as those in
1819  slink:VkSubpassDescription have the identical effect to those parameters.
1820  
1821  pname:viewMask has the same effect for the described subpass as
1822  slink:VkRenderPassMultiviewCreateInfo::pname:pViewMasks has on each
1823  corresponding subpass.
1824  
1825  .Valid Usage
1826  ****
1827    * [[VUID-VkSubpassDescription2KHR-pipelineBindPoint-03062]]
1828      pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS
1829    * [[VUID-VkSubpassDescription2KHR-colorAttachmentCount-03063]]
1830      pname:colorAttachmentCount must: be less than or equal to
1831      sname:VkPhysicalDeviceLimits::pname:maxColorAttachments
1832    * [[VUID-VkSubpassDescription2KHR-loadOp-03064]]
1833      If the first use of an attachment in this render pass is as an input
1834      attachment, and the attachment is not also used as a color or
1835      depth/stencil attachment in the same subpass, then pname:loadOp must:
1836      not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR
1837    * [[VUID-VkSubpassDescription2KHR-pResolveAttachments-03065]]
1838      If pname:pResolveAttachments is not `NULL`, for each resolve attachment
1839      that does not have the value ename:VK_ATTACHMENT_UNUSED, the
1840      corresponding color attachment must: not have the value
1841      ename:VK_ATTACHMENT_UNUSED
1842    * [[VUID-VkSubpassDescription2KHR-pResolveAttachments-03066]]
1843      If pname:pResolveAttachments is not `NULL`, for each resolve attachment
1844      that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color
1845      attachment must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT
1846    * [[VUID-VkSubpassDescription2KHR-pResolveAttachments-03067]]
1847      If pname:pResolveAttachments is not `NULL`, each resolve attachment that
1848      is not ename:VK_ATTACHMENT_UNUSED must: have a sample count of
1849      ename:VK_SAMPLE_COUNT_1_BIT
1850    * [[VUID-VkSubpassDescription2KHR-pResolveAttachments-03068]]
1851      Any given element of pname:pResolveAttachments must: have the same
1852      elink:VkFormat as its corresponding color attachment
1853    * [[VUID-VkSubpassDescription2KHR-pColorAttachments-03069]]
1854      All attachments in pname:pColorAttachments that are not
1855      ename:VK_ATTACHMENT_UNUSED must: have the same sample count
1856  ifdef::VK_AMD_mixed_attachment_samples[]
1857    * [[VUID-VkSubpassDescription2KHR-pColorAttachments-03070]]
1858      If the `VK_AMD_mixed_attachment_samples` extension is enabled, all
1859      attachments in pname:pColorAttachments that are not
1860      ename:VK_ATTACHMENT_UNUSED must: have a sample count that is smaller
1861      than or equal to the sample count of pname:pDepthStencilAttachment if it
1862      is not ename:VK_ATTACHMENT_UNUSED
1863  endif::VK_AMD_mixed_attachment_samples[]
1864    * [[VUID-VkSubpassDescription2KHR-pDepthStencilAttachment-03071]]
1865      If neither the `VK_AMD_mixed_attachment_samples` nor the
1866      `VK_NV_framebuffer_mixed_samples` extensions are enabled, and if
1867      pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and any
1868      attachments in pname:pColorAttachments are not
1869      ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count
1870    * [[VUID-VkSubpassDescription2KHR-attachment-03073]]
1871      The pname:attachment member of any element of pname:pPreserveAttachments
1872      must: not be ename:VK_ATTACHMENT_UNUSED
1873    * [[VUID-VkSubpassDescription2KHR-pPreserveAttachments-03074]]
1874      Any given element of pname:pPreserveAttachments must: not also be an
1875      element of any other member of the subpass description
1876    * [[VUID-VkSubpassDescription2KHR-layout-02528]]
1877      If any attachment is used by more than one slink:VkAttachmentReference
1878      member, then each use must: use the same pname:layout
1879  ifdef::VK_NVX_multiview_per_view_attributes[]
1880    * [[VUID-VkSubpassDescription2KHR-flags-03076]]
1881      If pname:flags includes
1882      ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must:
1883      also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX.
1884  endif::VK_NVX_multiview_per_view_attributes[]
1885    * [[VUID-VkSubpassDescription2KHR-aspectMask-03175]]
1886      The pname:aspectMask member of any element of pname:pInputAttachments
1887      must: be a valid combination of elink:VkImageAspectFlagBits
1888    * [[VUID-VkSubpassDescription2KHR-aspectMask-03176]]
1889      The pname:aspectMask member of any element of pname:pInputAttachments
1890      must: not be `0`
1891    * [[VUID-VkSubpassDescription2KHR-aspectMask-02529]]
1892      The pname:aspectMask member of each element of pname:pInputAttachments
1893      must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT
1894  ****
1895  
1896  include::{generated}/validity/structs/VkSubpassDescription2KHR.txt[]
1897  --
1898  
1899  ifdef::VK_KHR_depth_stencil_resolve[]
1900  [open,refpage='VkSubpassDescriptionDepthStencilResolveKHR',desc='Structure specifying depth/stencil resolve operations for a subpass',type='structs']
1901  --
1902  
1903  If the pname:pNext list of sname:VkSubpassDescription2KHR includes a
1904  sname:VkSubpassDescriptionDepthStencilResolveKHR structure, then that
1905  structure describes multisample resolve operations for the depth/stencil
1906  attachment in a subpass.
1907  
1908  The sname:VkSubpassDescriptionDepthStencilResolveKHR structure is defined
1909  as:
1910  
1911  include::{generated}/api/structs/VkSubpassDescriptionDepthStencilResolveKHR.txt[]
1912  
1913    * pname:sType is the type of this structure.
1914    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
1915    * pname:depthResolveMode is a bitmask of elink:VkResolveModeFlagBitsKHR
1916      describing the depth resolve mode.
1917    * pname:stencilResolveMode is a bitmask of elink:VkResolveModeFlagBitsKHR
1918      describing the stencil resolve mode.
1919    * pname:pDepthStencilResolveAttachment is an optional
1920      slink:VkAttachmentReference structure defining the depth/stencil resolve
1921      attachment for this subpass and its layout.
1922  
1923  .Valid Usage
1924  ****
1925    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-03177]]
1926      If pname:pDepthStencilResolveAttachment is not `NULL` and does not have
1927      the value ename:VK_ATTACHMENT_UNUSED, pname:pDepthStencilAttachment
1928      must: not have the value ename:VK_ATTACHMENT_UNUSED
1929    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-03178]]
1930      If pname:pDepthStencilResolveAttachment is not `NULL` and does not have
1931      the value ename:VK_ATTACHMENT_UNUSED, pname:depthResolveMode and
1932      pname:stencilResolveMode must: not both be
1933      ename:VK_RESOLVE_MODE_NONE_KHR
1934    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-03179]]
1935      If pname:pDepthStencilResolveAttachment is not `NULL` and does not have
1936      the value ename:VK_ATTACHMENT_UNUSED, pname:pDepthStencilAttachment
1937      must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT
1938    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-03180]]
1939      If pname:pDepthStencilResolveAttachment is not `NULL` and does not have
1940      the value ename:VK_ATTACHMENT_UNUSED,
1941      pname:pDepthStencilResolveAttachment must: have a sample count of
1942      ename:VK_SAMPLE_COUNT_1_BIT
1943    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-02651]]
1944      If pname:pDepthStencilResolveAttachment is not `NULL` and does not have
1945      the value ename:VK_ATTACHMENT_UNUSED then it must: have a format whose
1946      features contain ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
1947    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-03181]]
1948      If the elink:VkFormat of pname:pDepthStencilResolveAttachment has a
1949      depth component, then the elink:VkFormat of
1950      pname:pDepthStencilAttachment must: have a depth component with the same
1951      number of bits and numerical type
1952    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-03182]]
1953      If the elink:VkFormat of pname:pDepthStencilResolveAttachment has a
1954      stencil component, then the elink:VkFormat of
1955      pname:pDepthStencilAttachment must: have a stencil component with the
1956      same number of bits and numerical type
1957    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-depthResolveMode-03183]]
1958      The value of pname:depthResolveMode must: be one of the bits set in
1959      slink:VkPhysicalDeviceDepthStencilResolvePropertiesKHR::pname:supportedDepthResolveModes
1960      or ename:VK_RESOLVE_MODE_NONE_KHR
1961    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-stencilResolveMode-03184]]
1962      The value of pname:stencilResolveMode must: be one of the bits set in
1963      slink:VkPhysicalDeviceDepthStencilResolvePropertiesKHR::pname:supportedStencilResolveModes
1964      or ename:VK_RESOLVE_MODE_NONE_KHR
1965    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-03185]]
1966      If the elink:VkFormat of pname:pDepthStencilResolveAttachment has both
1967      depth and stencil components,
1968      slink:VkPhysicalDeviceDepthStencilResolvePropertiesKHR::pname:independentResolve
1969      is ename:VK_FALSE, and
1970      slink:VkPhysicalDeviceDepthStencilResolvePropertiesKHR::pname:independentResolveNone
1971      is ename:VK_FALSE, then the values of pname:depthResolveMode and
1972      pname:stencilResolveMode must: be identical
1973    * [[VUID-VkSubpassDescriptionDepthStencilResolveKHR-pDepthStencilResolveAttachment-03186]]
1974      If the elink:VkFormat of pname:pDepthStencilResolveAttachment has both
1975      depth and stencil components,
1976      slink:VkPhysicalDeviceDepthStencilResolvePropertiesKHR::pname:independentResolve
1977      is ename:VK_FALSE and
1978      slink:VkPhysicalDeviceDepthStencilResolvePropertiesKHR::pname:independentResolveNone
1979      is ename:VK_TRUE, then the values of pname:depthResolveMode and
1980      pname:stencilResolveMode must: be identical or one of them must: be
1981      ename:VK_RESOLVE_MODE_NONE_KHR
1982  ****
1983  
1984  include::{generated}/validity/structs/VkSubpassDescriptionDepthStencilResolveKHR.txt[]
1985  --
1986  
1987  [open,refpage='VkResolveModeFlagBitsKHR',desc='Bitmask indicating supported depth and stencil resolve modes',type='enums']
1988  --
1989  Possible values of
1990  slink:VkSubpassDescriptionDepthStencilResolveKHR::pname:depthResolveMode and
1991  pname:stencilResolveMode, specifying the depth and stencil resolve modes,
1992  are:
1993  
1994  include::{generated}/api/enums/VkResolveModeFlagBitsKHR.txt[]
1995  
1996    * ename:VK_RESOLVE_MODE_NONE_KHR indicates that no resolve operation is
1997      done.
1998    * ename:VK_RESOLVE_MODE_SAMPLE_ZERO_BIT_KHR indicates that result of the
1999      resolve operation is equal to the value of sample 0.
2000    * ename:VK_RESOLVE_MODE_AVERAGE_BIT_KHR indicates that result of the
2001      resolve operation is the average of the sample values.
2002    * ename:VK_RESOLVE_MODE_MIN_BIT_KHR indicates that result of the resolve
2003      operation is the minimum of the sample values.
2004    * ename:VK_RESOLVE_MODE_MAX_BIT_KHR indicates that result of the resolve
2005      operation is the maximum of the sample values.
2006  --
2007  
2008  [open,refpage='VkResolveModeFlagsKHR',desc='Bitmask of VkResolveModeFlagBitsKHR',type='flags']
2009  --
2010  include::{generated}/api/flags/VkResolveModeFlagsKHR.txt[]
2011  
2012  tname:VkResolveModeFlagsKHR is a bitmask type for setting a mask of zero or
2013  more elink:VkResolveModeFlagBitsKHR.
2014  --
2015  endif::VK_KHR_depth_stencil_resolve[]
2016  
2017  
2018  [open,refpage='VkAttachmentReference2KHR',desc='Structure specifying an attachment reference',type='structs']
2019  --
2020  
2021  The sname:VkAttachmentReference2KHR structure is defined as:
2022  
2023  include::{generated}/api/structs/VkAttachmentReference2KHR.txt[]
2024  
2025    * pname:sType is the type of this structure.
2026    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
2027    * pname:attachment is either an integer value identifying an attachment at
2028      the corresponding index in
2029      slink:VkRenderPassCreateInfo::pname:pAttachments, or
2030      ename:VK_ATTACHMENT_UNUSED to signify that this attachment is not used.
2031    * pname:layout is a elink:VkImageLayout value specifying the layout the
2032      attachment uses during the subpass.
2033    * pname:aspectMask is a mask of which aspect(s) can: be accessed within
2034      the specified subpass as an input attachment.
2035  
2036  Parameters defined by this structure with the same name as those in
2037  slink:VkAttachmentReference have the identical effect to those parameters.
2038  
2039  pname:aspectMask has the same effect for the described attachment as
2040  slink:VkInputAttachmentAspectReference::pname:aspectMask has on each
2041  corresponding attachment.
2042  It is ignored when this structure is used to describe anything other than an
2043  input attachment reference.
2044  
2045  .Valid Usage
2046  ****
2047    * [[VUID-VkAttachmentReference2KHR-layout-03077]]
2048      If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout
2049      must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or
2050      ename:VK_IMAGE_LAYOUT_PREINITIALIZED
2051  ****
2052  
2053  include::{generated}/validity/structs/VkAttachmentReference2KHR.txt[]
2054  --
2055  
2056  [open,refpage='VkSubpassDependency2KHR',desc='Structure specifying a subpass dependency',type='structs']
2057  --
2058  
2059  The sname:VkSubpassDependency2KHR structure is defined as:
2060  
2061  include::{generated}/api/structs/VkSubpassDependency2KHR.txt[]
2062  
2063    * pname:sType is the type of this structure.
2064    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
2065    * pname:srcSubpass is the subpass index of the first subpass in the
2066      dependency, or ename:VK_SUBPASS_EXTERNAL.
2067    * pname:dstSubpass is the subpass index of the second subpass in the
2068      dependency, or ename:VK_SUBPASS_EXTERNAL.
2069    * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits
2070      specifying the <<synchronization-pipeline-stages-masks, source stage
2071      mask>>.
2072    * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits
2073      specifying the <<synchronization-pipeline-stages-masks, destination
2074      stage mask>>
2075    * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a
2076      <<synchronization-access-masks, source access mask>>.
2077    * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a
2078      <<synchronization-access-masks, destination access mask>>.
2079    * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits.
2080    * pname:viewOffset controls which views in the source subpass the views in
2081      the destination subpass depend on.
2082  
2083  Parameters defined by this structure with the same name as those in
2084  slink:VkSubpassDependency have the identical effect to those parameters.
2085  
2086  pname:viewOffset has the same effect for the described subpass dependency as
2087  slink:VkRenderPassMultiviewCreateInfo::pname:pViewOffsets has on each
2088  corresponding subpass dependency.
2089  
2090  .Valid Usage
2091  ****
2092    * [[VUID-VkSubpassDependency2KHR-srcSubpass-03078]]
2093      If pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:srcStageMask
2094      must: not include ename:VK_PIPELINE_STAGE_HOST_BIT
2095    * [[VUID-VkSubpassDependency2KHR-dstSubpass-03079]]
2096      If pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL, pname:dstStageMask
2097      must: not include ename:VK_PIPELINE_STAGE_HOST_BIT
2098    * [[VUID-VkSubpassDependency2KHR-srcStageMask-03080]]
2099      If the <<features-geometryShader,geometry shaders>> feature is not
2100      enabled, pname:srcStageMask must: not contain
2101      ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
2102    * [[VUID-VkSubpassDependency2KHR-dstStageMask-03081]]
2103      If the <<features-geometryShader,geometry shaders>> feature is not
2104      enabled, pname:dstStageMask must: not contain
2105      ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
2106    * [[VUID-VkSubpassDependency2KHR-srcStageMask-03082]]
2107      If the <<features-tessellationShader,tessellation shaders>> feature is
2108      not enabled, pname:srcStageMask must: not contain
2109      ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
2110      ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
2111    * [[VUID-VkSubpassDependency2KHR-dstStageMask-03083]]
2112      If the <<features-tessellationShader,tessellation shaders>> feature is
2113      not enabled, pname:dstStageMask must: not contain
2114      ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
2115      ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
2116    * [[VUID-VkSubpassDependency2KHR-srcSubpass-03084]]
2117      pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless
2118      one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies
2119      and ensure a valid execution order
2120    * [[VUID-VkSubpassDependency2KHR-srcSubpass-03085]]
2121      pname:srcSubpass and pname:dstSubpass must: not both be equal to
2122      ename:VK_SUBPASS_EXTERNAL
2123    * [[VUID-VkSubpassDependency2KHR-srcSubpass-02244]]
2124      If pname:srcSubpass is equal to pname:dstSubpass, pname:srcStageMask and
2125      pname:dstStageMask must: not set any bits that are neither
2126      ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT, nor one of the
2127      <<synchronization-pipeline-stages-types,graphics pipeline stages>>
2128    * [[VUID-VkSubpassDependency2KHR-srcSubpass-03087]]
2129      If pname:srcSubpass is equal to pname:dstSubpass and not all of the
2130      stages in pname:srcStageMask and pname:dstStageMask are
2131      <<synchronization-framebuffer-regions,framebuffer-space stages>>, the
2132      <<synchronization-pipeline-stages-order, logically latest>> pipeline
2133      stage in pname:srcStageMask must: be
2134      <<synchronization-pipeline-stages-order, logically earlier>> than or
2135      equal to the <<synchronization-pipeline-stages-order, logically
2136      earliest>> pipeline stage in pname:dstStageMask
2137    * [[VUID-VkSubpassDependency2KHR-srcAccessMask-03088]]
2138      Any access flag included in pname:srcAccessMask must: be supported by
2139      one of the pipeline stages in pname:srcStageMask, as specified in the
2140      <<synchronization-access-types-supported, table of supported access
2141      types>>
2142    * [[VUID-VkSubpassDependency2KHR-dstAccessMask-03089]]
2143      Any access flag included in pname:dstAccessMask must: be supported by
2144      one of the pipeline stages in pname:dstStageMask, as specified in the
2145      <<synchronization-access-types-supported, table of supported access
2146      types>>
2147    * [[VUID-VkSubpassDependency2KHR-dependencyFlags-03090]]
2148      If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT,
2149      pname:srcSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL
2150    * [[VUID-VkSubpassDependency2KHR-dependencyFlags-03091]]
2151      If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT,
2152      pname:dstSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL
2153    * [[VUID-VkSubpassDependency2KHR-srcSubpass-02245]]
2154      If pname:srcSubpass equals pname:dstSubpass, and pname:srcStageMask and
2155      pname:dstStageMask both include a
2156      <<synchronization-framebuffer-regions,framebuffer-space stage>>, then
2157      pname:dependencyFlags must: include ename:VK_DEPENDENCY_BY_REGION_BIT
2158    * [[VUID-VkSubpassDependency2KHR-viewOffset-02530]]
2159      If pname:viewOffset is not equal to `0`, pname:srcSubpass must: not be
2160      equal to pname:dstSubpass
2161    * [[VUID-VkSubpassDependency2KHR-dependencyFlags-03092]]
2162      If pname:dependencyFlags does not include
2163      ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, pname:viewOffset must: be `0`
2164    * [[VUID-VkSubpassDependency2KHR-viewOffset-03093]]
2165      If pname:viewOffset is not `0`, pname:srcSubpass must: not be equal to
2166      pname:dstSubpass.
2167  ifdef::VK_NV_mesh_shader[]
2168    * [[VUID-VkSubpassDependency2KHR-srcStageMask-02103]]
2169      If the <<features-meshShader,mesh shaders>> feature is not enabled,
2170      pname:srcStageMask must: not contain
2171      ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV
2172    * [[VUID-VkSubpassDependency2KHR-srcStageMask-02104]]
2173      If the <<features-taskShader,task shaders>> feature is not enabled,
2174      pname:srcStageMask must: not contain
2175      ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV
2176    * [[VUID-VkSubpassDependency2KHR-dstStageMask-02105]]
2177      If the <<features-meshShader,mesh shaders>> feature is not enabled,
2178      pname:dstStageMask must: not contain
2179      ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV
2180    * [[VUID-VkSubpassDependency2KHR-dstStageMask-02106]]
2181      If the <<features-taskShader,task shaders>> feature is not enabled,
2182      pname:dstStageMask must: not contain
2183      ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV
2184  endif::VK_NV_mesh_shader[]
2185  ****
2186  
2187  include::{generated}/validity/structs/VkSubpassDependency2KHR.txt[]
2188  --
2189  
2190  
2191  endif::VK_KHR_create_renderpass2[]
2192  
2193  
2194  [open,refpage='vkDestroyRenderPass',desc='Destroy a render pass object',type='protos']
2195  --
2196  
2197  To destroy a render pass, call:
2198  
2199  include::{generated}/api/protos/vkDestroyRenderPass.txt[]
2200  
2201    * pname:device is the logical device that destroys the render pass.
2202    * pname:renderPass is the handle of the render pass to destroy.
2203    * pname:pAllocator controls host memory allocation as described in the
2204      <<memory-allocation, Memory Allocation>> chapter.
2205  
2206  .Valid Usage
2207  ****
2208    * [[VUID-vkDestroyRenderPass-renderPass-00873]]
2209      All submitted commands that refer to pname:renderPass must: have
2210      completed execution
2211    * [[VUID-vkDestroyRenderPass-renderPass-00874]]
2212      If sname:VkAllocationCallbacks were provided when pname:renderPass was
2213      created, a compatible set of callbacks must: be provided here
2214    * [[VUID-vkDestroyRenderPass-renderPass-00875]]
2215      If no sname:VkAllocationCallbacks were provided when pname:renderPass
2216      was created, pname:pAllocator must: be `NULL`
2217  ****
2218  
2219  include::{generated}/validity/protos/vkDestroyRenderPass.txt[]
2220  --
2221  
2222  
2223  [[renderpass-compatibility]]
2224  == Render Pass Compatibility
2225  
2226  Framebuffers and graphics pipelines are created based on a specific render
2227  pass object.
2228  They must: only be used with that render pass object, or one compatible with
2229  it.
2230  
2231  Two attachment references are compatible if they have matching format and
2232  sample count, or are both ename:VK_ATTACHMENT_UNUSED or the pointer that
2233  would contain the reference is `NULL`.
2234  
2235  Two arrays of attachment references are compatible if all corresponding
2236  pairs of attachments are compatible.
2237  If the arrays are of different lengths, attachment references not present in
2238  the smaller array are treated as ename:VK_ATTACHMENT_UNUSED.
2239  
2240  Two render passes are compatible if their corresponding color, input,
2241  resolve, and depth/stencil attachment references are compatible and if they
2242  are otherwise identical except for:
2243  
2244    * Initial and final image layout in attachment descriptions
2245    * Load and store operations in attachment descriptions
2246    * Image layout in attachment references
2247  
2248  As an additional special case, if two render passes have a single subpass,
2249  they are compatible even if they have different resolve attachment
2250  references
2251  ifdef::VK_KHR_depth_stencil_resolve[]
2252  or depth/stencil resolve modes
2253  endif::VK_KHR_depth_stencil_resolve[]
2254  but satisfy the other compatibility conditions.
2255  
2256  A framebuffer is compatible with a render pass if it was created using the
2257  same render pass or a compatible render pass.
2258  
2259  
2260  == Framebuffers
2261  
2262  [open,refpage='VkFramebuffer',desc='Opaque handle to a framebuffer object',type='handles']
2263  --
2264  
2265  Render passes operate in conjunction with _framebuffers_.
2266  Framebuffers represent a collection of specific memory attachments that a
2267  render pass instance uses.
2268  
2269  Framebuffers are represented by sname:VkFramebuffer handles:
2270  
2271  include::{generated}/api/handles/VkFramebuffer.txt[]
2272  
2273  --
2274  
2275  [open,refpage='vkCreateFramebuffer',desc='Create a new framebuffer object',type='protos']
2276  --
2277  
2278  To create a framebuffer, call:
2279  
2280  include::{generated}/api/protos/vkCreateFramebuffer.txt[]
2281  
2282    * pname:device is the logical device that creates the framebuffer.
2283    * pname:pCreateInfo points to a slink:VkFramebufferCreateInfo structure
2284      which describes additional information about framebuffer creation.
2285    * pname:pAllocator controls host memory allocation as described in the
2286      <<memory-allocation, Memory Allocation>> chapter.
2287    * pname:pFramebuffer points to a slink:VkFramebuffer handle in which the
2288      resulting framebuffer object is returned.
2289  
2290  include::{generated}/validity/protos/vkCreateFramebuffer.txt[]
2291  --
2292  
2293  [open,refpage='VkFramebufferCreateInfo',desc='Structure specifying parameters of a newly created framebuffer',type='structs']
2294  --
2295  
2296  The sname:VkFramebufferCreateInfo structure is defined as:
2297  
2298  include::{generated}/api/structs/VkFramebufferCreateInfo.txt[]
2299  
2300    * pname:sType is the type of this structure.
2301    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
2302    * pname:flags is a bitmask of elink:VkFramebufferCreateFlagBits
2303    * pname:renderPass is a render pass that defines what render passes the
2304      framebuffer will be compatible with.
2305      See <<renderpass-compatibility,Render Pass Compatibility>> for details.
2306    * pname:attachmentCount is the number of attachments.
2307    * pname:pAttachments is an array of slink:VkImageView handles, each of
2308      which will be used as the corresponding attachment in a render pass
2309      instance.
2310  ifdef::VK_KHR_imageless_framebuffer[]
2311      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2312      this parameter is ignored.
2313  endif::VK_KHR_imageless_framebuffer[]
2314    * pname:width, pname:height and pname:layers define the dimensions of the
2315      framebuffer.
2316  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
2317      If the render pass uses multiview, then pname:layers must: be one and
2318      each attachment requires a number of layers that is greater than the
2319      maximum bit index set in the view mask in the subpasses in which it is
2320      used.
2321  endif::VK_VERSION_1_1,VK_KHR_multiview[]
2322  
2323  Applications must: ensure that all accesses to memory that backs image
2324  subresources used as attachments in a given renderpass instance either
2325  happen-before the <<renderpass-load-store-ops, load operations>> for those
2326  attachments, or happen-after the <<renderpass-load-store-ops, store
2327  operations>> for those attachments.
2328  
2329  ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
2330  For depth/stencil attachments, each aspect can: be used separately as
2331  attachments and non-attachments as long as the non-attachment accesses are
2332  also via an image subresource in either the
2333  ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL layout or
2334  the ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL layout,
2335  and the attachment resource uses whichever of those two layouts the image
2336  accesses do not.
2337  Use of non-attachment aspects in this case is only well defined if the
2338  attachment is used in the subpass where the non-attachment access is being
2339  made, or the layout of the image subresource is constant throughout the
2340  entire render pass instance, including the pname:initialLayout and
2341  pname:finalLayout.
2342  endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
2343  
2344  [NOTE]
2345  .Note
2346  ====
2347  ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[]
2348  This restriction means
2349  endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
2350  ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
2351  These restrictions mean
2352  endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
2353  that the render pass has full knowledge of all uses of all of the
2354  attachments, so that the implementation is able to make correct decisions
2355  about when and how to perform layout transitions, when to overlap execution
2356  of subpasses, etc.
2357  ====
2358  
2359  
2360  [[renderpass-noattachments]]
2361  It is legal for a subpass to use no color or depth/stencil attachments, and
2362  rather use shader side effects such as image stores and atomics to produce
2363  an output.
2364  In this case, the subpass continues to use the pname:width, pname:height,
2365  and pname:layers of the framebuffer to define the dimensions of the
2366  rendering area, and the pname:rasterizationSamples from each pipeline's
2367  slink:VkPipelineMultisampleStateCreateInfo to define the number of samples
2368  used in rasterization; however, if
2369  slink:VkPhysicalDeviceFeatures::pname:variableMultisampleRate is
2370  ename:VK_FALSE, then all pipelines to be bound with a given zero-attachment
2371  subpass must: have the same value for
2372  slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples.
2373  
2374  .Valid Usage
2375  ****
2376    * [[VUID-VkFramebufferCreateInfo-attachmentCount-00876]]
2377      pname:attachmentCount must: be equal to the attachment count specified
2378      in pname:renderPass
2379    * [[VUID-VkFramebufferCreateInfo-pAttachments-00877]]
2380      If pname:flags does not include
2381      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2382      pname:pAttachments that is used as a color attachment or resolve
2383      attachment by pname:renderPass must: have been created with a
2384      pname:usage value including ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
2385    * [[VUID-VkFramebufferCreateInfo-pAttachments-02633]]
2386      If pname:flags does not include
2387      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2388      pname:pAttachments that is used as a depth/stencil attachment by
2389      pname:renderPass must: have been created with a pname:usage value
2390      including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
2391  ifdef::VK_KHR_depth_stencil_resolve[]
2392    * [[VUID-VkFramebufferCreateInfo-pAttachments-02634]]
2393      If pname:flags does not include
2394      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2395      pname:pAttachments that is used as a depth/stencil resolve attachment by
2396      pname:renderPass must: have been created with a pname:usage value
2397      including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
2398  endif::VK_KHR_depth_stencil_resolve[]
2399    * [[VUID-VkFramebufferCreateInfo-pAttachments-00879]]
2400      If pname:flags does not include
2401      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2402      pname:pAttachments that is used as an input attachment by
2403      pname:renderPass must: have been created with a pname:usage value
2404      including ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
2405  ifdef::VK_EXT_fragment_density_map[]
2406    * [[VUID-VkFramebufferCreateInfo-pAttachments-02552]]
2407      Each element of pname:pAttachments that is used as a fragment density
2408      map attachment by pname:renderPass must: not have been created with a
2409      pname:flags value including ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT.
2410    * [[VUID-VkFramebufferCreateInfo-renderPass-02553]]
2411      If pname:renderPass has a fragment density map attachment and
2412      <<features-nonsubsampledimages,non-subsample image feature>> is not
2413      enabled, each element of pname:pAttachments must: have been created with
2414      a pname:flags value including ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
2415      unless that element is the fragment density map attachment.
2416  endif::VK_EXT_fragment_density_map[]
2417    * [[VUID-VkFramebufferCreateInfo-pAttachments-00880]]
2418      If pname:flags does not include
2419      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2420      pname:pAttachments must: have been created with an elink:VkFormat value
2421      that matches the elink:VkFormat specified by the corresponding
2422      sname:VkAttachmentDescription in pname:renderPass
2423    * [[VUID-VkFramebufferCreateInfo-pAttachments-00881]]
2424      If pname:flags does not include
2425      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2426      pname:pAttachments must: have been created with a pname:samples value
2427      that matches the pname:samples value specified by the corresponding
2428      sname:VkAttachmentDescription in pname:renderPass
2429  ifndef::VK_EXT_fragment_density_map[]
2430    * [[VUID-VkFramebufferCreateInfo-pAttachments-00882]]
2431      If pname:flags does not include
2432      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2433      pname:pAttachments must: have dimensions at least as large as the
2434      corresponding framebuffer dimension
2435  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
2436    * [[VUID-VkFramebufferCreateInfo-renderPass-02743]]
2437      If pname:renderPass was specified with non-zero view masks, each element
2438      of pname:pAttachments must: have a pname:layerCount greater than the
2439      index of the most significant bit set in any of those view masks
2440  endif::VK_VERSION_1_1,VK_KHR_multiview[]
2441  endif::VK_EXT_fragment_density_map[]
2442  ifdef::VK_EXT_fragment_density_map[]
2443    * [[VUID-VkFramebufferCreateInfo-pAttachments-02554]]
2444      If pname:flags does not include
2445      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2446      pname:pAttachments must: have dimensions at least as large as the
2447      corresponding framebuffer dimension except for any element that is
2448      referenced by pname:fragmentDensityMapAttachment
2449  ifndef::VK_VERSION_1_1,VK_KHR_multiview[]
2450    * [[VUID-VkFramebufferCreateInfo-pAttachments-02744]]
2451      An element of pname:pAttachments that is referenced by
2452      pname:fragmentDensityMapAttachment must: have a pname:layerCount equal
2453      to `1`
2454  endif::VK_VERSION_1_1,VK_KHR_multiview[]
2455  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
2456    * [[VUID-VkFramebufferCreateInfo-renderPass-02745]]
2457      If pname:renderPass was specified with non-zero view masks, each element
2458      of pname:pAttachments that is not referenced by
2459      pname:fragmentDensityMapAttachment must: have a pname:layerCount greater
2460      than the index of the most significant bit set in any of those view
2461      masks
2462    * [[VUID-VkFramebufferCreateInfo-renderPass-02746]]
2463      If pname:renderPass was specified with non-zero view masks, each element
2464      of pname:pAttachments that is referenced by
2465      pname:fragmentDensityMapAttachment must: have a pname:layerCount equal
2466      to `1` or greater than the index of the most significant bit set in any
2467      of those view masks
2468    * [[VUID-VkFramebufferCreateInfo-renderPass-02747]]
2469      If pname:renderPass was not specified with non-zero view masks, each
2470      element of pname:pAttachments that is referenced by
2471      pname:fragmentDensityMapAttachment must: have a pname:layerCount equal
2472      to `1`
2473  endif::VK_VERSION_1_1,VK_KHR_multiview[]
2474    * [[VUID-VkFramebufferCreateInfo-pAttachments-02555]]
2475      If pname:flags does not include
2476      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, an element of
2477      pname:pAttachments that is referenced by
2478      pname:fragmentDensityMapAttachment must: have a width at least as large
2479      as
2480      latexmath:[\lceil{\frac{width}{maxFragmentDensityTexelSize_{width}}}\rceil]
2481    * [[VUID-VkFramebufferCreateInfo-pAttachments-02556]]
2482      If pname:flags does not include
2483      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, an element of
2484      pname:pAttachments that is referenced by
2485      pname:fragmentDensityMapAttachment must: have a height at least as large
2486      as
2487      latexmath:[\lceil{\frac{height}{maxFragmentDensityTexelSize_{height}}}\rceil]
2488  endif::VK_EXT_fragment_density_map[]
2489    * [[VUID-VkFramebufferCreateInfo-pAttachments-00883]]
2490      If pname:flags does not include
2491      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2492      pname:pAttachments must: only specify a single mip level
2493    * [[VUID-VkFramebufferCreateInfo-pAttachments-00884]]
2494      If pname:flags does not include
2495      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of
2496      pname:pAttachments must: have been created with the identity swizzle
2497    * [[VUID-VkFramebufferCreateInfo-width-00885]]
2498      pname:width must: be greater than `0`.
2499    * [[VUID-VkFramebufferCreateInfo-width-00886]]
2500      pname:width must: be less than or equal to
2501      sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth
2502    * [[VUID-VkFramebufferCreateInfo-height-00887]]
2503      pname:height must: be greater than `0`.
2504    * [[VUID-VkFramebufferCreateInfo-height-00888]]
2505      pname:height must: be less than or equal to
2506      sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight
2507    * [[VUID-VkFramebufferCreateInfo-layers-00889]]
2508      pname:layers must: be greater than `0`.
2509    * [[VUID-VkFramebufferCreateInfo-layers-00890]]
2510      pname:layers must: be less than or equal to
2511      sname:VkPhysicalDeviceLimits::pname:maxFramebufferLayers
2512  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
2513    * [[VUID-VkFramebufferCreateInfo-renderPass-02531]]
2514      If pname:renderPass was specified with non-zero view masks, pname:layers
2515      must: be `1`
2516  endif::VK_VERSION_1_1,VK_KHR_multiview[]
2517  ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
2518    * [[VUID-VkFramebufferCreateInfo-pAttachments-00891]]
2519      Each element of pname:pAttachments that is a 2D or 2D array image view
2520      taken from a 3D image must: not be a depth/stencil format
2521  endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
2522    * [[VUID-VkFramebufferCreateInfo-flags-03188]]
2523      If pname:flags does not include
2524      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, and pname:attachmentCount
2525      is not 0, pname:pAttachments must: be a valid pointer to an array of
2526      pname:attachmentCount valid slink:VkImageView handles
2527  ifdef::VK_KHR_imageless_framebuffer[]
2528    * [[VUID-VkFramebufferCreateInfo-flags-03189]]
2529      If the <<features-imagelessFramebuffer, imageless framebuffer>> feature
2530      is not enabled, pname:flags must: not include
2531      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR
2532    * [[VUID-VkFramebufferCreateInfo-flags-03190]]
2533      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2534      the pname:pNext chain must: include an instance of
2535      slink:VkFramebufferAttachmentsCreateInfoKHR
2536    * [[VUID-VkFramebufferCreateInfo-flags-03191]]
2537      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2538      the pname:attachmentImageInfoCount member of an instance of
2539      slink:VkFramebufferAttachmentsCreateInfoKHR in the pname:pNext chain
2540      must: be equal to either zero or pname:attachmentCount
2541  ifndef::VK_EXT_fragment_density_map[]
2542    * [[VUID-VkFramebufferCreateInfo-flags-03192]]
2543      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2544      the pname:width member of any element of the pname:pAttachmentImageInfos
2545      member of an instance of slink:VkFramebufferAttachmentsCreateInfoKHR in
2546      the pname:pNext chain must: be greater than or equal to pname:width
2547    * [[VUID-VkFramebufferCreateInfo-flags-03193]]
2548      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2549      the pname:height member of any element of the
2550      pname:pAttachmentImageInfos member of an instance of
2551      slink:VkFramebufferAttachmentsCreateInfoKHR in the pname:pNext chain
2552      must: be greater than or equal to pname:height
2553  endif::VK_EXT_fragment_density_map[]
2554  ifdef::VK_EXT_fragment_density_map[]
2555    * [[VUID-VkFramebufferCreateInfo-flags-03194]]
2556      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2557      the pname:width member of any element of the pname:pAttachmentImageInfos
2558      member of an instance of slink:VkFramebufferAttachmentsCreateInfoKHR in
2559      the pname:pNext chain must: be greater than or equal to pname:width,
2560      except for any element that is referenced by
2561      slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment
2562      in pname:renderPass
2563    * [[VUID-VkFramebufferCreateInfo-flags-03195]]
2564      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2565      the pname:height member of any element of the
2566      pname:pAttachmentImageInfos member of an instance of
2567      slink:VkFramebufferAttachmentsCreateInfoKHR in the pname:pNext chain
2568      must: be greater than or equal to pname:height, except for any element
2569      that is referenced by
2570      slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment
2571      in pname:renderPass
2572    * [[VUID-VkFramebufferCreateInfo-flags-03196]]
2573      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2574      the pname:width member of any element of the pname:pAttachmentImageInfos
2575      member of an instance of slink:VkFramebufferAttachmentsCreateInfoKHR in
2576      the pname:pNext chain that is referenced by
2577      slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment
2578      in pname:renderPass must: be greater than or equal to
2579      latexmath:[\lceil{\frac{width}{maxFragmentDensityTexelSize_{width}}}\rceil]
2580    * [[VUID-VkFramebufferCreateInfo-flags-03197]]
2581      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2582      the pname:height member of any element of the
2583      pname:pAttachmentImageInfos member of an instance of
2584      slink:VkFramebufferAttachmentsCreateInfoKHR in the pname:pNext chain
2585      that is referenced by
2586      slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment
2587      in pname:renderPass must: be greater than or equal to
2588      latexmath:[\lceil{\frac{height}{maxFragmentDensityTexelSize_{height}}}\rceil]
2589  endif::VK_EXT_fragment_density_map[]
2590  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
2591    * [[VUID-VkFramebufferCreateInfo-renderPass-03198]]
2592      If multiview is enabled for pname:renderPass, and pname:flags includes
2593      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the pname:layerCount
2594      member of any element of the pname:pAttachmentImageInfos member of an
2595      instance of slink:VkFramebufferAttachmentsCreateInfoKHR in the
2596      pname:pNext chain must: be greater than the maximum bit index set in the
2597      view mask in the subpasses in which it is used in pname:renderPass
2598    * [[VUID-VkFramebufferCreateInfo-renderPass-03199]]
2599      If multiview is not enabled for pname:renderPass, and pname:flags
2600      includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the
2601      pname:layerCount member of any element of the
2602      pname:pAttachmentImageInfos member of an instance of
2603      slink:VkFramebufferAttachmentsCreateInfoKHR in the pname:pNext chain
2604      must: be greater than or equal to pname:layers
2605  endif::VK_VERSION_1_1,VK_KHR_multiview[]
2606  ifndef::VK_VERSION_1_1+VK_KHR_multiview[]
2607    * [[VUID-VkFramebufferCreateInfo-flags-03200]]
2608      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2609      the pname:layerCount member of any element of the
2610      pname:pAttachmentImageInfos member of an instance of
2611      slink:VkFramebufferAttachmentsCreateInfoKHR in the pname:pNext chain
2612      must: be greater than or equal to pname:layers
2613  endif::VK_VERSION_1_1+VK_KHR_multiview[]
2614    * [[VUID-VkFramebufferCreateInfo-flags-03201]]
2615      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2616      the pname:usage member of any element of the pname:pAttachmentImageInfos
2617      member of an instance of slink:VkFramebufferAttachmentsCreateInfoKHR in
2618      the pname:pNext chain that refers to an attachment used as a color
2619      attachment or resolve attachment by pname:renderPass must: include
2620      ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
2621    * [[VUID-VkFramebufferCreateInfo-flags-03202]]
2622      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2623      the pname:usage member of any element of the pname:pAttachmentImageInfos
2624      member of an instance of slink:VkFramebufferAttachmentsCreateInfoKHR in
2625      the pname:pNext chain that refers to an attachment used as a
2626      depth/stencil attachment by pname:renderPass must: include
2627      ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
2628  ifdef::VK_KHR_depth_stencil_resolve[]
2629    * [[VUID-VkFramebufferCreateInfo-flags-03203]]
2630      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2631      the pname:usage member of any element of the pname:pAttachmentImageInfos
2632      member of an instance of slink:VkFramebufferAttachmentsCreateInfoKHR in
2633      the pname:pNext chain that refers to an attachment used as a
2634      depth/stencil resolve attachment by pname:renderPass must: include
2635      ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
2636  endif::VK_KHR_depth_stencil_resolve[]
2637    * [[VUID-VkFramebufferCreateInfo-flags-03204]]
2638      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2639      the pname:usage member of any element of the pname:pAttachmentImageInfos
2640      member of an instance of slink:VkFramebufferAttachmentsCreateInfoKHR in
2641      the pname:pNext chain that refers to an attachment used as an input
2642      attachment by pname:renderPass must: include
2643      ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
2644    * [[VUID-VkFramebufferCreateInfo-flags-03205]]
2645      If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR,
2646      at least one element of the pname:pViewFormats member of any element of
2647      the pname:pAttachmentImageInfos member of an instance of
2648      slink:VkFramebufferAttachmentsCreateInfoKHR in the pname:pNext chain
2649      must: be equal to the corresponding value of
2650      slink:VkAttachmentDescription::pname:format used to create
2651      pname:renderPass
2652  endif::VK_KHR_imageless_framebuffer[]
2653  ****
2654  
2655  include::{generated}/validity/structs/VkFramebufferCreateInfo.txt[]
2656  --
2657  
2658  ifdef::VK_KHR_imageless_framebuffer[]
2659  [open,refpage='VkFramebufferAttachmentsCreateInfoKHR',desc='Structure specifying parameters of images that will be used with a framebuffer',type='structs']
2660  --
2661  
2662  The sname:VkFramebufferAttachmentsCreateInfoKHR structure is defined as:
2663  
2664  include::{generated}/api/structs/VkFramebufferAttachmentsCreateInfoKHR.txt[]
2665  
2666    * pname:sType is the type of this structure.
2667    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
2668    * pname:attachmentImageInfoCount is the number of attachments being
2669      described.
2670    * pname:pAttachmentImageInfos is an array of
2671      slink:VkFramebufferAttachmentImageInfoKHR instances, each of which
2672      describes a number of parameters of the corresponding attachment in a
2673      render pass instance.
2674  
2675  include::{generated}/validity/structs/VkFramebufferAttachmentsCreateInfoKHR.txt[]
2676  --
2677  
2678  [open,refpage='VkFramebufferAttachmentImageInfoKHR',desc='Structure specifying parameters of an image that will be used with a framebuffer',type='structs']
2679  --
2680  
2681  The sname:VkFramebufferAttachmentImageInfoKHR structure is defined as:
2682  
2683  include::{generated}/api/structs/VkFramebufferAttachmentImageInfoKHR.txt[]
2684  
2685    * pname:sType is the type of this structure.
2686    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
2687    * pname:flags is a bitmask of elink:VkImageCreateFlagBits, matching the
2688      value of slink:VkImageCreateInfo::pname:flags used to create an image
2689      that will be used with this framebuffer.
2690    * pname:usage is a bitmask of elink:VkImageUsageFlagBits, matching the
2691      value of slink:VkImageCreateInfo::pname:usage used to create an image
2692      used with this framebuffer.
2693    * pname:width is the width of the image view used for rendering.
2694    * pname:height is the height of the image view used for rendering.
2695    * pname:viewFormatCount is the number of entries in the pname:pViewFormats
2696      array, matching the value of
2697      slink:VkImageFormatListCreateInfoKHR::pname:viewFormatCount used to
2698      create an image used with this framebuffer.
2699    * pname:pViewFormats is an array which lists of all formats which can: be
2700      used when creating views of the image, matching the value of
2701      slink:VkImageFormatListCreateInfoKHR::pViewFormats used to create an
2702      image used with this framebuffer.
2703  
2704  Images that can: be used with the framebuffer when beginning a render pass,
2705  as specified by slink:VkRenderPassAttachmentBeginInfoKHR, must: be created
2706  with parameters that are identical to those specified here.
2707  
2708  
2709  include::{generated}/validity/structs/VkFramebufferAttachmentImageInfoKHR.txt[]
2710  --
2711  endif::VK_KHR_imageless_framebuffer[]
2712  
2713  
2714  [open,refpage='VkFramebufferCreateFlagBits',desc='Bitmask specifying framebuffer properties',type='enums']
2715  --
2716  
2717  Bits which can: be set in slink:VkFramebufferCreateInfo::pname:flags to
2718  specify options for framebuffers are:
2719  
2720  include::{generated}/api/enums/VkFramebufferCreateFlagBits.txt[]
2721  
2722  ifdef::VK_KHR_imageless_framebuffer[]
2723    * ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR specifies that image views
2724      are not specified, and only attachment compatibility information will be
2725      provided via an instance of slink:VkFramebufferAttachmentImageInfoKHR.
2726  endif::VK_KHR_imageless_framebuffer[]
2727  
2728  ifndef::VK_KHR_imageless_framebuffer[]
2729  [NOTE]
2730  .Note
2731  ====
2732  All bits for this type are defined by extensions, and none of those
2733  extensions are enabled in this build of the specification.
2734  ====
2735  endif::VK_KHR_imageless_framebuffer[]
2736  --
2737  
2738  [open,refpage='VkFramebufferCreateFlags',desc='Bitmask of VkFramebufferCreateFlagBits',type='flags']
2739  --
2740  include::{generated}/api/flags/VkFramebufferCreateFlags.txt[]
2741  
2742  tname:VkFramebufferCreateFlags is a bitmask type for setting a mask of zero
2743  or more elink:VkFramebufferCreateFlagBits.
2744  --
2745  
2746  
2747  [open,refpage='vkDestroyFramebuffer',desc='Destroy a framebuffer object',type='protos']
2748  --
2749  
2750  To destroy a framebuffer, call:
2751  
2752  include::{generated}/api/protos/vkDestroyFramebuffer.txt[]
2753  
2754    * pname:device is the logical device that destroys the framebuffer.
2755    * pname:framebuffer is the handle of the framebuffer to destroy.
2756    * pname:pAllocator controls host memory allocation as described in the
2757      <<memory-allocation, Memory Allocation>> chapter.
2758  
2759  .Valid Usage
2760  ****
2761    * [[VUID-vkDestroyFramebuffer-framebuffer-00892]]
2762      All submitted commands that refer to pname:framebuffer must: have
2763      completed execution
2764    * [[VUID-vkDestroyFramebuffer-framebuffer-00893]]
2765      If sname:VkAllocationCallbacks were provided when pname:framebuffer was
2766      created, a compatible set of callbacks must: be provided here
2767    * [[VUID-vkDestroyFramebuffer-framebuffer-00894]]
2768      If no sname:VkAllocationCallbacks were provided when pname:framebuffer
2769      was created, pname:pAllocator must: be `NULL`
2770  ****
2771  
2772  include::{generated}/validity/protos/vkDestroyFramebuffer.txt[]
2773  --
2774  
2775  
2776  [[renderpass-commands]]
2777  == Render Pass Commands
2778  
2779  An application records the commands for a render pass instance one subpass
2780  at a time, by beginning a render pass instance, iterating over the subpasses
2781  to record commands for that subpass, and then ending the render pass
2782  instance.
2783  
2784  [open,refpage='vkCmdBeginRenderPass',desc='Begin a new render pass',type='protos']
2785  --
2786  
2787  To begin a render pass instance, call:
2788  
2789  include::{generated}/api/protos/vkCmdBeginRenderPass.txt[]
2790  
2791    * pname:commandBuffer is the command buffer in which to record the
2792      command.
2793    * pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo
2794      structure (defined below) which specifies the render pass to begin an
2795      instance of, and the framebuffer the instance uses.
2796    * pname:contents is a elink:VkSubpassContents value specifying how the
2797      commands in the first subpass will be provided.
2798  
2799  After beginning a render pass instance, the command buffer is ready to
2800  record the commands for the first subpass of that render pass.
2801  
2802  .Valid Usage
2803  ****
2804    * [[VUID-vkCmdBeginRenderPass-initialLayout-00895]]
2805      If any of the pname:initialLayout or pname:finalLayout member of the
2806      sname:VkAttachmentDescription structures or the pname:layout member of
2807      the sname:VkAttachmentReference structures specified when creating the
2808      render pass specified in the pname:renderPass member of
2809      pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
2810      then the corresponding attachment image view of the framebuffer
2811      specified in the pname:framebuffer member of pname:pRenderPassBegin
2812      must: have been created with a pname:usage value including
2813      ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
2814  // The VU below comes in an alternate version when the extension is
2815  // enabled.
2816  ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[]
2817    * [[VUID-vkCmdBeginRenderPass-initialLayout-00896]]
2818      If any of the pname:initialLayout or pname:finalLayout member of the
2819      sname:VkAttachmentDescription structures or the pname:layout member of
2820      the sname:VkAttachmentReference structures specified when creating the
2821      render pass specified in the pname:renderPass member of
2822      pname:pRenderPassBegin is
2823      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or
2824      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the
2825      corresponding attachment image view of the framebuffer specified in the
2826      pname:framebuffer member of pname:pRenderPassBegin must: have been
2827      created with a pname:usage value including
2828      ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
2829  endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
2830  // The nested ifdefs are there in anticipation of the hoped-for day when the
2831  // VU extractor and validation layers can handle VU with imbedded
2832  // conditionals. They are commented out until then.
2833  ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
2834    * [[VUID-vkCmdBeginRenderPass-initialLayout-01758]]
2835      If any of the pname:initialLayout or pname:finalLayout member of the
2836      sname:VkAttachmentDescription structures or the pname:layout member of
2837      the sname:VkAttachmentReference structures specified when creating the
2838      render pass specified in the pname:renderPass member of
2839      pname:pRenderPassBegin is
2840  // ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
2841      ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
2842      ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
2843  // endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
2844      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or
2845      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the
2846      corresponding attachment image view of the framebuffer specified in the
2847      pname:framebuffer member of pname:pRenderPassBegin must: have been
2848      created with a pname:usage value including
2849      ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
2850  endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
2851    * [[VUID-vkCmdBeginRenderPass-initialLayout-00897]]
2852      If any of the pname:initialLayout or pname:finalLayout member of the
2853      sname:VkAttachmentDescription structures or the pname:layout member of
2854      the sname:VkAttachmentReference structures specified when creating the
2855      render pass specified in the pname:renderPass member of
2856      pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
2857      then the corresponding attachment image view of the framebuffer
2858      specified in the pname:framebuffer member of pname:pRenderPassBegin
2859      must: have been created with a pname:usage value including
2860      ename:VK_IMAGE_USAGE_SAMPLED_BIT or
2861      ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
2862    * [[VUID-vkCmdBeginRenderPass-initialLayout-00898]]
2863      If any of the pname:initialLayout or pname:finalLayout member of the
2864      sname:VkAttachmentDescription structures or the pname:layout member of
2865      the sname:VkAttachmentReference structures specified when creating the
2866      render pass specified in the pname:renderPass member of
2867      pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
2868      then the corresponding attachment image view of the framebuffer
2869      specified in the pname:framebuffer member of pname:pRenderPassBegin
2870      must: have been created with a pname:usage value including
2871      ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT
2872    * [[VUID-vkCmdBeginRenderPass-initialLayout-00899]]
2873      If any of the pname:initialLayout or pname:finalLayout member of the
2874      sname:VkAttachmentDescription structures or the pname:layout member of
2875      the sname:VkAttachmentReference structures specified when creating the
2876      render pass specified in the pname:renderPass member of
2877      pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
2878      then the corresponding attachment image view of the framebuffer
2879      specified in the pname:framebuffer member of pname:pRenderPassBegin
2880      must: have been created with a pname:usage value including
2881      ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT
2882    * [[VUID-vkCmdBeginRenderPass-initialLayout-00900]]
2883      If any of the pname:initialLayout members of the
2884      sname:VkAttachmentDescription structures specified when creating the
2885      render pass specified in the pname:renderPass member of
2886      pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each
2887      such pname:initialLayout must: be equal to the current layout of the
2888      corresponding attachment image subresource of the framebuffer specified
2889      in the pname:framebuffer member of pname:pRenderPassBegin
2890    * [[VUID-vkCmdBeginRenderPass-srcStageMask-00901]]
2891      The pname:srcStageMask and pname:dstStageMask members of any element of
2892      the pname:pDependencies member of slink:VkRenderPassCreateInfo used to
2893      create pname:renderPass must: be supported by the capabilities of the
2894      queue family identified by the pname:queueFamilyIndex member of the
2895      slink:VkCommandPoolCreateInfo used to create the command pool which
2896      pname:commandBuffer was allocated from
2897    * [[VUID-vkCmdBeginRenderPass-framebuffer-02532]]
2898      For any attachment in pname:framebuffer that is used by pname:renderPass
2899      and is bound to memory locations that are also bound to another
2900      attachment used by pname:renderPass, and if at least one of those uses
2901      causes either attachment to be written to, both attachments must: have
2902      had the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set
2903  ****
2904  
2905  include::{generated}/validity/protos/vkCmdBeginRenderPass.txt[]
2906  --
2907  
2908  ifdef::VK_KHR_create_renderpass2[]
2909  [open,refpage='vkCmdBeginRenderPass2KHR',desc='Begin a new render pass',type='protos']
2910  --
2911  
2912  Alternatively to begin a render pass, call:
2913  
2914  include::{generated}/api/protos/vkCmdBeginRenderPass2KHR.txt[]
2915  
2916    * pname:commandBuffer is the command buffer in which to record the
2917      command.
2918    * pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo
2919      structure (defined below) which indicates the render pass to begin an
2920      instance of, and the framebuffer the instance uses.
2921    * pname:pSubpassBeginInfo is a pointer to a slink:VkSubpassBeginInfoKHR
2922      structure which contains information about the subpass which is about to
2923      begin rendering.
2924  
2925  After beginning a render pass instance, the command buffer is ready to
2926  record the commands for the first subpass of that render pass.
2927  
2928  .Valid Usage
2929  ****
2930    * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03094]]
2931      If any of the pname:initialLayout or pname:finalLayout member of the
2932      sname:VkAttachmentDescription structures or the pname:layout member of
2933      the sname:VkAttachmentReference structures specified when creating the
2934      render pass specified in the pname:renderPass member of
2935      pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
2936      then the corresponding attachment image view of the framebuffer
2937      specified in the pname:framebuffer member of pname:pRenderPassBegin
2938      must: have been created with a pname:usage value including
2939      ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
2940    * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03096]]
2941      If any of the pname:initialLayout or pname:finalLayout member of the
2942      sname:VkAttachmentDescription structures or the pname:layout member of
2943      the sname:VkAttachmentReference structures specified when creating the
2944      render pass specified in the pname:renderPass member of
2945      pname:pRenderPassBegin is
2946      ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
2947      ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
2948      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or
2949      ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the
2950      corresponding attachment image view of the framebuffer specified in the
2951      pname:framebuffer member of pname:pRenderPassBegin must: have been
2952      created with a pname:usage value including
2953      ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
2954    * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03097]]
2955      If any of the pname:initialLayout or pname:finalLayout member of the
2956      sname:VkAttachmentDescription structures or the pname:layout member of
2957      the sname:VkAttachmentReference structures specified when creating the
2958      render pass specified in the pname:renderPass member of
2959      pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
2960      then the corresponding attachment image view of the framebuffer
2961      specified in the pname:framebuffer member of pname:pRenderPassBegin
2962      must: have been created with a pname:usage value including
2963      ename:VK_IMAGE_USAGE_SAMPLED_BIT or
2964      ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
2965    * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03098]]
2966      If any of the pname:initialLayout or pname:finalLayout member of the
2967      sname:VkAttachmentDescription structures or the pname:layout member of
2968      the sname:VkAttachmentReference structures specified when creating the
2969      render pass specified in the pname:renderPass member of
2970      pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
2971      then the corresponding attachment image view of the framebuffer
2972      specified in the pname:framebuffer member of pname:pRenderPassBegin
2973      must: have been created with a pname:usage value including
2974      ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT
2975    * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03099]]
2976      If any of the pname:initialLayout or pname:finalLayout member of the
2977      sname:VkAttachmentDescription structures or the pname:layout member of
2978      the sname:VkAttachmentReference structures specified when creating the
2979      render pass specified in the pname:renderPass member of
2980      pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
2981      then the corresponding attachment image view of the framebuffer
2982      specified in the pname:framebuffer member of pname:pRenderPassBegin
2983      must: have been created with a pname:usage value including
2984      ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT
2985    * [[VUID-vkCmdBeginRenderPass2KHR-initialLayout-03100]]
2986      If any of the pname:initialLayout members of the
2987      sname:VkAttachmentDescription structures specified when creating the
2988      render pass specified in the pname:renderPass member of
2989      pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each
2990      such pname:initialLayout must: be equal to the current layout of the
2991      corresponding attachment image subresource of the framebuffer specified
2992      in the pname:framebuffer member of pname:pRenderPassBegin
2993    * [[VUID-vkCmdBeginRenderPass2KHR-srcStageMask-03101]]
2994      The pname:srcStageMask and pname:dstStageMask members of any element of
2995      the pname:pDependencies member of slink:VkRenderPassCreateInfo used to
2996      create pname:renderPass must: be supported by the capabilities of the
2997      queue family identified by the pname:queueFamilyIndex member of the
2998      slink:VkCommandPoolCreateInfo used to create the command pool which
2999      pname:commandBuffer was allocated from
3000    * [[VUID-vkCmdBeginRenderPass2KHR-framebuffer-02533]]
3001      For any attachment in pname:framebuffer that is used by pname:renderPass
3002      and is bound to memory locations that are also bound to another
3003      attachment used by pname:renderPass, and if at least one of those uses
3004      causes either attachment to be written to, both attachments must: have
3005      had the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set
3006  ****
3007  
3008  include::{generated}/validity/protos/vkCmdBeginRenderPass2KHR.txt[]
3009  --
3010  endif::VK_KHR_create_renderpass2[]
3011  
3012  [open,refpage='VkRenderPassBeginInfo',desc='Structure specifying render pass begin info',type='structs']
3013  --
3014  
3015  The sname:VkRenderPassBeginInfo structure is defined as:
3016  
3017  include::{generated}/api/structs/VkRenderPassBeginInfo.txt[]
3018  
3019    * pname:sType is the type of this structure.
3020    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
3021    * pname:renderPass is the render pass to begin an instance of.
3022    * pname:framebuffer is the framebuffer containing the attachments that are
3023      used with the render pass.
3024    * pname:renderArea is the render area that is affected by the render pass
3025      instance, and is described in more detail below.
3026    * pname:clearValueCount is the number of elements in pname:pClearValues.
3027    * pname:pClearValues is an array of slink:VkClearValue structures that
3028      contains clear values for each attachment, if the attachment uses a
3029      pname:loadOp value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR or if the
3030      attachment has a depth/stencil format and uses a pname:stencilLoadOp
3031      value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR.
3032      The array is indexed by attachment number.
3033      Only elements corresponding to cleared attachments are used.
3034      Other elements of pname:pClearValues are ignored.
3035  
3036  pname:renderArea is the render area that is affected by the render pass
3037  instance.
3038  The effects of attachment load, store and multisample resolve operations are
3039  restricted to the pixels whose x and y coordinates fall within the render
3040  area on all attachments.
3041  The render area extends to all layers of pname:framebuffer.
3042  The application must: ensure (using scissor if necessary) that all rendering
3043  is contained within the render area.
3044  The render area must: be contained within the framebuffer dimensions.
3045  
3046  ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
3047  
3048  When multiview is enabled, the resolve operation at the end of a subpass
3049  applies to all views in the view mask.
3050  
3051  endif::VK_VERSION_1_1,VK_KHR_multiview[]
3052  
3053  [NOTE]
3054  .Note
3055  ====
3056  There may: be a performance cost for using a render area smaller than the
3057  framebuffer, unless it matches the render area granularity for the render
3058  pass.
3059  ====
3060  
3061  .Valid Usage
3062  ****
3063    * [[VUID-VkRenderPassBeginInfo-clearValueCount-00902]]
3064      pname:clearValueCount must: be greater than the largest attachment index
3065      in pname:renderPass that specifies a pname:loadOp (or
3066      pname:stencilLoadOp, if the attachment has a depth/stencil format) of
3067      ename:VK_ATTACHMENT_LOAD_OP_CLEAR
3068    * [[VUID-VkRenderPassBeginInfo-renderPass-00904]]
3069      pname:renderPass must: be <<renderpass-compatibility,compatible>> with
3070      the pname:renderPass member of the sname:VkFramebufferCreateInfo
3071      structure specified when creating pname:framebuffer.
3072  ifdef::VK_KHR_imageless_framebuffer[]
3073    * [[VUID-VkRenderPassBeginInfo-pNext-03206]]
3074      If the <<features-imagelessFramebuffer, imageless framebuffer>> feature
3075      is not enabled, and the pname:pNext chain includes an instance of
3076      slink:VkRenderPassAttachmentBeginInfoKHR, its pname:attachmentCount
3077      must: be zero
3078    * [[VUID-VkRenderPassBeginInfo-framebuffer-03207]]
3079      If pname:framebuffer was created with a
3080      slink:VkFramebufferCreateInfo::pname:flags value that did not include
3081      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, and the pname:pNext chain
3082      includes an instance of slink:VkRenderPassAttachmentBeginInfoKHR, its
3083      pname:attachmentCount must: be zero
3084    * [[VUID-VkRenderPassBeginInfo-framebuffer-03208]]
3085      If pname:framebuffer was created with a
3086      slink:VkFramebufferCreateInfo::pname:flags value that included
3087      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the pname:attachmentCount
3088      of an instance of slink:VkRenderPassAttachmentBeginInfoKHR included in
3089      the pname:pNext chain must: be equal to the value of
3090      slink:VkFramebufferAttachmentsCreateInfoKHR::pname:attachmentImageInfoCount
3091      used to create pname:framebuffer
3092    * [[VUID-VkRenderPassBeginInfo-framebuffer-03209]]
3093      If pname:framebuffer was created with a
3094      slink:VkFramebufferCreateInfo::pname:flags value that included
3095      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3096      pname:attachments member of an instance of
3097      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3098      chain must: be a slink:VkImageView of an image created with a value of
3099      slink:VkImageCreateInfo::pname:flags equal to the pname:flags member of
3100      the corresponding element of
3101      slink:VkFramebufferAttachmentsCreateInfoKHR::pname:pAttachments used to
3102      create pname:framebuffer
3103    * [[VUID-VkRenderPassBeginInfo-framebuffer-03210]]
3104      If pname:framebuffer was created with a
3105      slink:VkFramebufferCreateInfo::pname:flags value that included
3106      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3107      pname:attachments member of an instance of
3108      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3109      chain must: be a slink:VkImageView of an image created with a value of
3110      slink:VkImageCreateInfo::pname:usage equal to the pname:usage member of
3111      the corresponding element of
3112      slink:VkFramebufferAttachmentsCreateInfoKHR::pname:pAttachments used to
3113      create pname:framebuffer
3114    * [[VUID-VkRenderPassBeginInfo-framebuffer-03211]]
3115      If pname:framebuffer was created with a
3116      slink:VkFramebufferCreateInfo::pname:flags value that included
3117      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3118      pname:attachments member of an instance of
3119      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3120      chain must: be a slink:VkImageView with a width equal to the pname:width
3121      member of the corresponding element of
3122      slink:VkFramebufferAttachmentsCreateInfoKHR::pname:pAttachments used to
3123      create pname:framebuffer
3124    * [[VUID-VkRenderPassBeginInfo-framebuffer-03212]]
3125      If pname:framebuffer was created with a
3126      slink:VkFramebufferCreateInfo::pname:flags value that included
3127      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3128      pname:attachments member of an instance of
3129      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3130      chain must: be a slink:VkImageView with a height equal to the
3131      pname:height member of the corresponding element of
3132      slink:VkFramebufferAttachmentsCreateInfoKHR::pname:pAttachments used to
3133      create pname:framebuffer
3134    * [[VUID-VkRenderPassBeginInfo-framebuffer-03213]]
3135      If pname:framebuffer was created with a
3136      slink:VkFramebufferCreateInfo::pname:flags value that included
3137      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3138      pname:attachments member of an instance of
3139      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3140      chain must: be a slink:VkImageView of an image created with a value of
3141      slink:VkImageViewCreateInfo::pname:subresourceRange.pname:layerCount
3142      equal to the pname:layerCount member of the corresponding element of
3143      slink:VkFramebufferAttachmentsCreateInfoKHR::pname:pAttachments used to
3144      create pname:framebuffer
3145    * [[VUID-VkRenderPassBeginInfo-framebuffer-03214]]
3146      If pname:framebuffer was created with a
3147      slink:VkFramebufferCreateInfo::pname:flags value that included
3148      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3149      pname:attachments member of an instance of
3150      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3151      chain must: be a slink:VkImageView of an image created with a value of
3152      slink:VkImageFormatListCreateInfoKHR::pname:viewFormatCount equal to the
3153      pname:viewFormatCount member of the corresponding element of
3154      slink:VkFramebufferAttachmentsCreateInfoKHR::pname:pAttachments used to
3155      create pname:framebuffer
3156    * [[VUID-VkRenderPassBeginInfo-framebuffer-03215]]
3157      If pname:framebuffer was created with a
3158      slink:VkFramebufferCreateInfo::pname:flags value that included
3159      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3160      pname:attachments member of an instance of
3161      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3162      chain must: be a slink:VkImageView of an image created with a set of
3163      elements in slink:VkImageFormatListCreateInfoKHR::pname:pViewFormats
3164      equal to the set of elements in the pname:pViewFormats member of the
3165      corresponding element of
3166      slink:VkFramebufferAttachmentsCreateInfoKHR::pname:pAttachments used to
3167      create pname:framebuffer
3168    * [[VUID-VkRenderPassBeginInfo-framebuffer-03216]]
3169      If pname:framebuffer was created with a
3170      slink:VkFramebufferCreateInfo::pname:flags value that included
3171      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3172      pname:attachments member of an instance of
3173      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3174      chain must: be a slink:VkImageView of an image created with a value of
3175      slink:VkImageViewCreateInfo::pname:format equal to the corresponding
3176      value of slink:VkAttachmentDescription::pname:format in pname:renderPass
3177    * [[VUID-VkRenderPassBeginInfo-framebuffer-03217]]
3178      If pname:framebuffer was created with a
3179      slink:VkFramebufferCreateInfo::pname:flags value that included
3180      ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of the
3181      pname:attachments member of an instance of
3182      slink:VkRenderPassAttachmentBeginInfoKHR included in the pname:pNext
3183      chain must: be a slink:VkImageView of an image created with a value of
3184      slink:VkImageCreateInfo::pname:samples equal to the corresponding value
3185      of slink:VkAttachmentDescription::pname:samples in pname:renderPass
3186  endif::VK_KHR_imageless_framebuffer[]
3187  ****
3188  
3189  include::{generated}/validity/structs/VkRenderPassBeginInfo.txt[]
3190  --
3191  
3192  ifdef::VK_EXT_sample_locations[]
3193  
3194  [open,refpage='VkRenderPassSampleLocationsBeginInfoEXT',desc='Structure specifying sample locations to use for the layout transition of custom sample locations compatible depth/stencil attachments',type='structs']
3195  --
3196  
3197  The image layout of the depth aspect of a depth/stencil attachment referring
3198  to an image created with
3199  ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent
3200  on the last sample locations used to render to the image subresource, thus
3201  preserving the contents of such depth/stencil attachments across subpass
3202  boundaries requires the application to specify these sample locations
3203  whenever a layout transition of the attachment may: occur.
3204  This information can: be provided by chaining an instance of the
3205  sname:VkRenderPassSampleLocationsBeginInfoEXT structure to the pname:pNext
3206  chain of sname:VkRenderPassBeginInfo.
3207  
3208  The sname:VkRenderPassSampleLocationsBeginInfoEXT structure is defined as:
3209  
3210  include::{generated}/api/structs/VkRenderPassSampleLocationsBeginInfoEXT.txt[]
3211  
3212    * pname:sType is the type of this structure.
3213    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
3214    * pname:attachmentInitialSampleLocationsCount is the number of elements in
3215      the pname:pAttachmentInitialSampleLocations array.
3216    * pname:pAttachmentInitialSampleLocations is an array of
3217      pname:attachmentInitialSampleLocationsCount
3218      slink:VkAttachmentSampleLocationsEXT structures specifying the
3219      attachment indices and their corresponding sample location state.
3220      Each element of pname:pAttachmentInitialSampleLocations can: specify the
3221      sample location state to use in the automatic layout transition
3222      performed to transition a depth/stencil attachment from the initial
3223      layout of the attachment to the image layout specified for the
3224      attachment in the first subpass using it.
3225    * pname:postSubpassSampleLocationsCount is the number of elements in the
3226      pname:pPostSubpassSampleLocations array.
3227    * pname:pPostSubpassSampleLocations is an array of
3228      pname:postSubpassSampleLocationsCount slink:VkSubpassSampleLocationsEXT
3229      structures specifying the subpass indices and their corresponding sample
3230      location state.
3231      Each element of pname:pPostSubpassSampleLocations can: specify the
3232      sample location state to use in the automatic layout transition
3233      performed to transition the depth/stencil attachment used by the
3234      specified subpass to the image layout specified in a dependent subpass
3235      or to the final layout of the attachment in case the specified subpass
3236      is the last subpass using that attachment.
3237      In addition, if
3238      slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations
3239      is ename:VK_FALSE, each element of pname:pPostSubpassSampleLocations
3240      must: specify the sample location state that matches the sample
3241      locations used by all pipelines that will be bound to a command buffer
3242      during the specified subpass.
3243      If pname:variableSampleLocations is ename:VK_TRUE, the sample locations
3244      used for rasterization do not depend on
3245      pname:pPostSubpassSampleLocations.
3246  
3247  include::{generated}/validity/structs/VkRenderPassSampleLocationsBeginInfoEXT.txt[]
3248  --
3249  
3250  [open,refpage='VkAttachmentSampleLocationsEXT',desc='Structure specifying the sample locations state to use in the initial layout transition of attachments',type='structs']
3251  --
3252  
3253  The sname:VkAttachmentSampleLocationsEXT structure is defined as:
3254  
3255  include::{generated}/api/structs/VkAttachmentSampleLocationsEXT.txt[]
3256  
3257    * pname:attachmentIndex is the index of the attachment for which the
3258      sample locations state is provided.
3259    * pname:sampleLocationsInfo is the sample locations state to use for the
3260      layout transition of the given attachment from the initial layout of the
3261      attachment to the image layout specified for the attachment in the first
3262      subpass using it.
3263  
3264  If the image referenced by the framebuffer attachment at index
3265  pname:attachmentIndex was not created with
3266  ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT then the
3267  values specified in pname:sampleLocationsInfo are ignored.
3268  
3269  .Valid Usage
3270  ****
3271    * [[VUID-VkAttachmentSampleLocationsEXT-attachmentIndex-01531]]
3272      pname:attachmentIndex must: be less than the pname:attachmentCount
3273      specified in slink:VkRenderPassCreateInfo the render pass specified by
3274      slink:VkRenderPassBeginInfo::pname:renderPass was created with
3275  ****
3276  
3277  include::{generated}/validity/structs/VkAttachmentSampleLocationsEXT.txt[]
3278  --
3279  
3280  [open,refpage='VkSubpassSampleLocationsEXT',desc='Structure specifying the sample locations state to use for layout transitions of attachments performed after a given subpass',type='structs']
3281  --
3282  
3283  The sname:VkSubpassSampleLocationsEXT structure is defined as:
3284  
3285  include::{generated}/api/structs/VkSubpassSampleLocationsEXT.txt[]
3286  
3287    * pname:subpassIndex is the index of the subpass for which the sample
3288      locations state is provided.
3289    * pname:sampleLocationsInfo is the sample locations state to use for the
3290      layout transition of the depth/stencil attachment away from the image
3291      layout the attachment is used with in the subpass specified in
3292      pname:subpassIndex.
3293  
3294  If the image referenced by the depth/stencil attachment used in the subpass
3295  identified by pname:subpassIndex was not created with
3296  ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT or if the
3297  subpass does not use a depth/stencil attachment, and
3298  slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations
3299  is ename:VK_TRUE then the values specified in pname:sampleLocationsInfo are
3300  ignored.
3301  
3302  .Valid Usage
3303  ****
3304    * [[VUID-VkSubpassSampleLocationsEXT-subpassIndex-01532]]
3305      pname:subpassIndex must: be less than the pname:subpassCount specified
3306      in slink:VkRenderPassCreateInfo the render pass specified by
3307      slink:VkRenderPassBeginInfo::pname:renderPass was created with
3308  ****
3309  
3310  include::{generated}/validity/structs/VkSubpassSampleLocationsEXT.txt[]
3311  --
3312  
3313  endif::VK_EXT_sample_locations[]
3314  
3315  ifdef::VK_KHR_create_renderpass2[]
3316  [open,refpage='VkSubpassBeginInfoKHR',desc='Structure specifying subpass begin info',type='structs']
3317  --
3318  
3319  The sname:VkSubpassBeginInfoKHR structure is defined as:
3320  
3321  include::{generated}/api/structs/VkSubpassBeginInfoKHR.txt[]
3322  
3323    * pname:sType is the type of this structure.
3324    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
3325    * pname:contents is a elink:VkSubpassContents value specifying how the
3326      commands in the next subpass will be provided.
3327  
3328  include::{generated}/validity/structs/VkSubpassBeginInfoKHR.txt[]
3329  --
3330  endif::VK_KHR_create_renderpass2[]
3331  
3332  [open,refpage='VkSubpassContents',desc='Specify how commands in the first subpass of a render pass are provided',type='enums']
3333  --
3334  
3335  Possible values of flink:vkCmdBeginRenderPass::pname:contents, specifying
3336  how the commands in the first subpass will be provided, are:
3337  
3338  include::{generated}/api/enums/VkSubpassContents.txt[]
3339  
3340    * ename:VK_SUBPASS_CONTENTS_INLINE specifies that the contents of the
3341      subpass will be recorded inline in the primary command buffer, and
3342      secondary command buffers must: not be executed within the subpass.
3343    * ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS specifies that the
3344      contents are recorded in secondary command buffers that will be called
3345      from the primary command buffer, and flink:vkCmdExecuteCommands is the
3346      only valid command on the command buffer until flink:vkCmdNextSubpass or
3347      flink:vkCmdEndRenderPass.
3348  
3349  --
3350  
3351  ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
3352  
3353  [open,refpage='VkDeviceGroupRenderPassBeginInfo',desc='Set the initial device mask and render areas for a render pass instance',type='structs']
3354  --
3355  
3356  If the pname:pNext chain of slink:VkRenderPassBeginInfo includes a
3357  sname:VkDeviceGroupRenderPassBeginInfo structure, then that structure
3358  includes a device mask and set of render areas for the render pass instance.
3359  
3360  The sname:VkDeviceGroupRenderPassBeginInfo structure is defined as:
3361  
3362  include::{generated}/api/structs/VkDeviceGroupRenderPassBeginInfo.txt[]
3363  
3364  ifdef::VK_KHR_device_group[]
3365  or the equivalent
3366  
3367  include::{generated}/api/structs/VkDeviceGroupRenderPassBeginInfoKHR.txt[]
3368  endif::VK_KHR_device_group[]
3369  
3370    * pname:sType is the type of this structure.
3371    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
3372    * pname:deviceMask is the device mask for the render pass instance.
3373    * pname:deviceRenderAreaCount is the number of elements in the
3374      pname:pDeviceRenderAreas array.
3375    * pname:pDeviceRenderAreas is an array of structures of type
3376      slink:VkRect2D defining the render area for each physical device.
3377  
3378  The pname:deviceMask serves several purposes.
3379  It is an upper bound on the set of physical devices that can: be used during
3380  the render pass instance, and the initial device mask when the render pass
3381  instance begins.
3382  In addition, commands transitioning to the next subpass in the render pass
3383  instance and commands ending the render pass instance, and, accordingly
3384  render pass attachment load, store, and resolve operations and subpass
3385  dependencies corresponding to the render pass instance, are executed on the
3386  physical devices included in the device mask provided here.
3387  
3388  If pname:deviceRenderAreaCount is not zero, then the elements of
3389  pname:pDeviceRenderAreas override the value of
3390  slink:VkRenderPassBeginInfo::pname:renderArea, and provide a render area
3391  specific to each physical device.
3392  These render areas serve the same purpose as
3393  slink:VkRenderPassBeginInfo::pname:renderArea, including controlling the
3394  region of attachments that are cleared by ename:VK_ATTACHMENT_LOAD_OP_CLEAR
3395  and that are resolved into resolve attachments.
3396  
3397  If this structure is not present, the render pass instance's device mask is
3398  the value of slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask.
3399  If this structure is not present or if pname:deviceRenderAreaCount is zero,
3400  slink:VkRenderPassBeginInfo::pname:renderArea is used for all physical
3401  devices.
3402  
3403  .Valid Usage
3404  ****
3405    * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00905]]
3406      pname:deviceMask must: be a valid device mask value
3407    * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00906]]
3408      pname:deviceMask must: not be zero
3409    * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00907]]
3410      pname:deviceMask must: be a subset of the command buffer's initial
3411      device mask
3412    * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceRenderAreaCount-00908]]
3413      pname:deviceRenderAreaCount must: either be zero or equal to the number
3414      of physical devices in the logical device.
3415  ****
3416  
3417  include::{generated}/validity/structs/VkDeviceGroupRenderPassBeginInfo.txt[]
3418  --
3419  
3420  endif::VK_VERSION_1_1,VK_KHR_device_group[]
3421  
3422  ifdef::VK_KHR_imageless_framebuffer[]
3423  [open,refpage='VkRenderPassAttachmentBeginInfoKHR',desc='Structure specifying images to be used as framebuffer attachments',type='structs']
3424  --
3425  The sname:VkRenderPassAttachmentBeginInfoKHR structure is defined as:
3426  
3427  include::{generated}/api/structs/VkRenderPassAttachmentBeginInfoKHR.txt[]
3428  
3429    * pname:sType is the type of this structure.
3430    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
3431    * pname:attachmentCount is the number of attachments.
3432    * pname:pAttachments is an array of sname:VkImageView handles, each of
3433      which will be used as the corresponding attachment in the render pass
3434      instance.
3435  
3436  .Valid Usage
3437  ****
3438    * [[VUID-VkRenderPassAttachmentBeginInfoKHR-pAttachments-03218]]
3439      Each element of pname:pAttachments must: only specify a single mip level
3440    * [[VUID-VkRenderPassAttachmentBeginInfoKHR-pAttachments-03219]]
3441      Each element of pname:pAttachments must: have been created with the
3442      identity swizzle
3443  ****
3444  
3445  include::{generated}/validity/structs/VkRenderPassAttachmentBeginInfoKHR.txt[]
3446  --
3447  endif::VK_KHR_imageless_framebuffer[]
3448  
3449  [open,refpage='vkGetRenderAreaGranularity',desc='Returns the granularity for optimal render area',type='protos']
3450  --
3451  
3452  To query the render area granularity, call:
3453  
3454  include::{generated}/api/protos/vkGetRenderAreaGranularity.txt[]
3455  
3456    * pname:device is the logical device that owns the render pass.
3457    * pname:renderPass is a handle to a render pass.
3458    * pname:pGranularity points to a slink:VkExtent2D structure in which the
3459      granularity is returned.
3460  
3461  The conditions leading to an optimal pname:renderArea are:
3462  
3463    * the pname:offset.x member in pname:renderArea is a multiple of the
3464      pname:width member of the returned slink:VkExtent2D (the horizontal
3465      granularity).
3466    * the pname:offset.y member in pname:renderArea is a multiple of the
3467      pname:height of the returned slink:VkExtent2D (the vertical
3468      granularity).
3469    * either the pname:offset.width member in pname:renderArea is a multiple
3470      of the horizontal granularity or pname:offset.x+pname:offset.width is
3471      equal to the pname:width of the pname:framebuffer in the
3472      slink:VkRenderPassBeginInfo.
3473    * either the pname:offset.height member in pname:renderArea is a multiple
3474      of the vertical granularity or pname:offset.y+pname:offset.height is
3475      equal to the pname:height of the pname:framebuffer in the
3476      slink:VkRenderPassBeginInfo.
3477  
3478  Subpass dependencies are not affected by the render area, and apply to the
3479  entire image subresources attached to the framebuffer as specified in the
3480  description of <<renderpass-layout-transitions,automatic layout
3481  transitions>>.
3482  Similarly, pipeline barriers are valid even if their effect extends outside
3483  the render area.
3484  
3485  include::{generated}/validity/protos/vkGetRenderAreaGranularity.txt[]
3486  --
3487  
3488  [open,refpage='vkCmdNextSubpass',desc='Transition to the next subpass of a render pass',type='protos']
3489  --
3490  
3491  To transition to the next subpass in the render pass instance after
3492  recording the commands for a subpass, call:
3493  
3494  include::{generated}/api/protos/vkCmdNextSubpass.txt[]
3495  
3496    * pname:commandBuffer is the command buffer in which to record the
3497      command.
3498    * pname:contents specifies how the commands in the next subpass will be
3499      provided, in the same fashion as the corresponding parameter of
3500      flink:vkCmdBeginRenderPass.
3501  
3502  The subpass index for a render pass begins at zero when
3503  fname:vkCmdBeginRenderPass is recorded, and increments each time
3504  fname:vkCmdNextSubpass is recorded.
3505  
3506  Moving to the next subpass automatically performs any multisample resolve
3507  operations in the subpass being ended.
3508  End-of-subpass multisample resolves are treated as color attachment writes
3509  for the purposes of synchronization.
3510  ifdef::VK_KHR_depth_stencil_resolve[]
3511  This applies to resolve operations for both color and depth/stencil
3512  attachments.
3513  endif::VK_KHR_depth_stencil_resolve[]
3514  That is, they are considered to execute in the
3515  ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their
3516  writes are synchronized with ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
3517  Synchronization between rendering within a subpass and any resolve
3518  operations at the end of the subpass occurs automatically, without need for
3519  explicit dependencies or pipeline barriers.
3520  However, if the resolve attachment is also used in a different subpass, an
3521  explicit dependency is needed.
3522  
3523  After transitioning to the next subpass, the application can: record the
3524  commands for that subpass.
3525  
3526  .Valid Usage
3527  ****
3528    * [[VUID-vkCmdNextSubpass-None-00909]]
3529      The current subpass index must: be less than the number of subpasses in
3530      the render pass minus one
3531  ifdef::VK_EXT_transform_feedback[]
3532    * [[VUID-vkCmdNextSubpass-None-02349]]
3533      This command must: not be recorded when transform feedback is active
3534  endif::VK_EXT_transform_feedback[]
3535  ****
3536  
3537  include::{generated}/validity/protos/vkCmdNextSubpass.txt[]
3538  --
3539  
3540  ifdef::VK_KHR_create_renderpass2[]
3541  
3542  [open,refpage='vkCmdNextSubpass2KHR',desc='Transition to the next subpass of a render pass',type='protos']
3543  --
3544  
3545  To transition to the next subpass in the render pass instance after
3546  recording the commands for a subpass, call:
3547  
3548  include::{generated}/api/protos/vkCmdNextSubpass2KHR.txt[]
3549  
3550    * pname:commandBuffer is the command buffer in which to record the
3551      command.
3552    * pname:pSubpassBeginInfo is a pointer to a slink:VkSubpassBeginInfoKHR
3553      structure which contains information about the subpass which is about to
3554      begin rendering.
3555    * pname:pSubpassEndInfo is a pointer to a slink:VkSubpassEndInfoKHR
3556      structure which contains information about how the previous subpass will
3557      be ended.
3558  
3559  fname:vkCmdNextSubpass2KHR is semantically identical to
3560  flink:vkCmdNextSubpass, except that it is extensible, and that
3561  pname:contents is provided as part of an extensible structure instead of as
3562  a flat parameter.
3563  
3564  .Valid Usage
3565  ****
3566    * [[VUID-vkCmdNextSubpass2KHR-None-03102]]
3567      The current subpass index must: be less than the number of subpasses in
3568      the render pass minus one
3569  ifdef::VK_EXT_transform_feedback[]
3570    * [[VUID-vkCmdNextSubpass2KHR-None-02350]]
3571      This command must: not be recorded when transform feedback is active
3572  endif::VK_EXT_transform_feedback[]
3573  ****
3574  
3575  include::{generated}/validity/protos/vkCmdNextSubpass2KHR.txt[]
3576  --
3577  
3578  endif::VK_KHR_create_renderpass2[]
3579  
3580  [open,refpage='vkCmdEndRenderPass',desc='End the current render pass',type='protos']
3581  --
3582  
3583  To record a command to end a render pass instance after recording the
3584  commands for the last subpass, call:
3585  
3586  include::{generated}/api/protos/vkCmdEndRenderPass.txt[]
3587  
3588    * pname:commandBuffer is the command buffer in which to end the current
3589      render pass instance.
3590  
3591  Ending a render pass instance performs any multisample resolve operations on
3592  the final subpass.
3593  
3594  .Valid Usage
3595  ****
3596    * [[VUID-vkCmdEndRenderPass-None-00910]]
3597      The current subpass index must: be equal to the number of subpasses in
3598      the render pass minus one
3599  ifdef::VK_EXT_transform_feedback[]
3600    * [[VUID-vkCmdEndRenderPass-None-02351]]
3601      This command must: not be recorded when transform feedback is active
3602  endif::VK_EXT_transform_feedback[]
3603  
3604  ****
3605  
3606  include::{generated}/validity/protos/vkCmdEndRenderPass.txt[]
3607  --
3608  
3609  
3610  ifdef::VK_KHR_create_renderpass2[]
3611  [open,refpage='vkCmdEndRenderPass2KHR',desc='End the current render pass',type='protos']
3612  --
3613  
3614  To record a command to end a render pass instance after recording the
3615  commands for the last subpass, call:
3616  
3617  include::{generated}/api/protos/vkCmdEndRenderPass2KHR.txt[]
3618  
3619    * pname:commandBuffer is the command buffer in which to end the current
3620      render pass instance.
3621    * pname:pSubpassEndInfo is a pointer to a slink:VkSubpassEndInfoKHR
3622      structure which contains information about how the previous subpass will
3623      be ended.
3624  
3625  fname:vkCmdEndRenderPass2KHR is semantically identical to
3626  flink:vkCmdEndRenderPass, except that it is extensible.
3627  
3628  .Valid Usage
3629  ****
3630    * [[VUID-vkCmdEndRenderPass2KHR-None-03103]]
3631      The current subpass index must: be equal to the number of subpasses in
3632      the render pass minus one
3633  ifdef::VK_EXT_transform_feedback[]
3634    * [[VUID-vkCmdEndRenderPass2KHR-None-02352]]
3635      This command must: not be recorded when transform feedback is active
3636  endif::VK_EXT_transform_feedback[]
3637  ****
3638  
3639  include::{generated}/validity/protos/vkCmdEndRenderPass2KHR.txt[]
3640  --
3641  
3642  [open,refpage='VkSubpassEndInfoKHR',desc='Structure specifying subpass end info',type='structs']
3643  --
3644  
3645  The sname:VkSubpassEndInfoKHR structure is defined as:
3646  
3647  include::{generated}/api/structs/VkSubpassEndInfoKHR.txt[]
3648  
3649    * pname:sType is the type of this structure.
3650    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
3651  
3652  include::{generated}/validity/structs/VkSubpassEndInfoKHR.txt[]
3653  --
3654  
3655  endif::VK_KHR_create_renderpass2[]