1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[renderpass]] 6= Render Pass 7 8<<drawing, Draw commands>> must: be recorded within a _render pass 9instance_. 10Each render pass instance defines a set of image resources, referred to as 11_attachments_, used during rendering. 12 13ifdef::VK_KHR_dynamic_rendering[] 14[open,refpage='vkCmdBeginRenderingKHR',desc='Begin a dynamic render pass instance',type='protos'] 15-- 16To begin a render pass instance, call: 17 18include::{generated}/api/protos/vkCmdBeginRenderingKHR.txt[] 19 20 * pname:commandBuffer is the command buffer in which to record the 21 command. 22 * pname:pRenderingInfo is a pointer to a slink:VkRenderingInfoKHR 23 structure specifying details of the render pass instance to begin. 24 25After beginning a render pass instance, the command buffer is ready to 26record <<drawing,draw commands>>. 27 28If pname:pRenderingInfo->flags includes ename:VK_RENDERING_RESUMING_BIT_KHR 29then this render pass is resumed from a render pass instance that has been 30suspended earlier in <<synchronization-submission-order, submission order>>. 31 32.Valid Usage 33**** 34 * [[VUID-vkCmdBeginRenderingKHR-dynamicRendering-06446]] 35 The <<features-dynamicRendering,pname:dynamicRendering>> feature must: 36 be enabled 37 * [[VUID-vkCmdBeginRenderingKHR-commandBuffer-06068]] 38 If pname:commandBuffer is a secondary command buffer, 39 pname:pRenderingInfo->flags must: not include 40 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR 41**** 42 43include::{generated}/validity/protos/vkCmdBeginRenderingKHR.txt[] 44-- 45 46[open,refpage='VkRenderingInfoKHR',desc='Structure specifying render pass instance begin info',type='structs'] 47-- 48The sname:VkRenderingInfoKHR structure is defined as: 49 50include::{generated}/api/structs/VkRenderingInfoKHR.txt[] 51 52 * pname:sType is the type of this structure. 53 * pname:pNext is `NULL` or a pointer to a structure extending this 54 structure. 55 * pname:flags is a bitmask of elink:VkRenderingFlagBitsKHR. 56 * pname:renderArea is the render area that is affected by the render pass 57 instance. 58 * pname:layerCount is the number of layers rendered to in each attachment 59 when pname:viewMask is `0`. 60 * pname:viewMask is the view mask indicating the indices of attachment 61 layers that will be rendered when it is not `0`. 62 * pname:colorAttachmentCount is the number of elements in 63 pname:pColorAttachments. 64 * pname:pColorAttachments is a pointer to an array of 65 pname:colorAttachmentCount slink:VkRenderingAttachmentInfoKHR structures 66 describing any color attachments used. 67 * pname:pDepthAttachment is a pointer to a 68 slink:VkRenderingAttachmentInfoKHR structure describing a depth 69 attachment. 70 * pname:pStencilAttachment is a pointer to a 71 slink:VkRenderingAttachmentInfoKHR structure describing a stencil 72 attachment. 73 74ifdef::VK_KHR_multiview,VK_VERSION_1_1[] 75If pname:viewMask is not `0`, multiview is enabled. 76endif::VK_KHR_multiview,VK_VERSION_1_1[] 77 78ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 79If there is an instance of slink:VkDeviceGroupRenderPassBeginInfo included 80in the pname:pNext chain and its pname:deviceCount member is not `0`, then 81pname:renderArea is ignored, and the render area is defined per-device by 82that structure. 83endif::VK_KHR_device_group,VK_VERSION_1_1[] 84 85Each element of the pname:pColorAttachments array corresponds to an output 86location in the shader, i.e. if the shader declares an output variable 87decorated with a code:Location value of *X*, then it uses the attachment 88provided in pname:pColorAttachments[*X*]. 89If the pname:imageView member of any element of pname:pColorAttachments is 90dlink:VK_NULL_HANDLE, writes to the corresponding location by a fragment are 91discarded. 92 93.Valid Usage 94**** 95 * [[VUID-VkRenderingInfoKHR-viewMask-06069]] 96 If pname:viewMask is `0`, pname:layerCount must: not be `0` 97 * [[VUID-VkRenderingInfoKHR-imageView-06070]] 98 If neither the apiext:VK_AMD_mixed_attachment_samples nor the 99 apiext:VK_NV_framebuffer_mixed_samples extensions are enabled, 100 pname:imageView members of pname:pDepthAttachment, 101 pname:pStencilAttachment, and elements of pname:pColorAttachments that 102 are not dlink:VK_NULL_HANDLE must: have been created with the same 103 pname:sampleCount 104ifndef::VK_VERSION_1_1,VK_KHR_device_group[] 105 * [[VUID-VkRenderingInfoKHR-renderArea-06071]] 106 pname:renderArea.offset.x must: be greater than or equal to 0 107 * [[VUID-VkRenderingInfoKHR-renderArea-06072]] 108 pname:renderArea.offset.y must: be greater than or equal to 0 109 * [[VUID-VkRenderingInfoKHR-renderArea-06073]] 110 The sum of pname:renderArea.offset.x and pname:renderArea.extent.width 111 must: be less than or equal to <<limits-maxFramebufferWidth, 112 pname:maxFramebufferWidth>> 113 * [[VUID-VkRenderingInfoKHR-renderArea-06074]] 114 The sum of pname:renderArea.offset.y and pname:renderArea.extent.height 115 must: be less than or equal to <<limits-maxFramebufferHeight, 116 pname:maxFramebufferHeight>> 117 * [[VUID-VkRenderingInfoKHR-imageView-06075]] 118 The width of the pname:imageView member of any element of 119 pname:pColorAttachments, pname:pDepthAttachment, or 120 pname:pStencilAttachment that is not dlink:VK_NULL_HANDLE must: be 121 greater than or equal to [eq]#pname:renderArea.offset.x {plus} 122 pname:renderArea.extent.width# 123 * [[VUID-VkRenderingInfoKHR-imageView-06076]] 124 The height of the pname:imageView member of any element of 125 pname:pColorAttachments, pname:pDepthAttachment, or 126 pname:pStencilAttachment that is not dlink:VK_NULL_HANDLE must: be 127 greater than or equal to [eq]#pname:renderArea.offset.y {plus} 128 pname:renderArea.extent.height# 129endif::VK_VERSION_1_1,VK_KHR_device_group[] 130ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 131 * [[VUID-VkRenderingInfoKHR-pNext-06077]] 132 If the pname:pNext chain does not contain 133 slink:VkDeviceGroupRenderPassBeginInfo or its 134 pname:deviceRenderAreaCount member is equal to 0, 135 pname:renderArea.offset.x must: be greater than or equal to 0 136 * [[VUID-VkRenderingInfoKHR-pNext-06078]] 137 If the pname:pNext chain does not contain 138 slink:VkDeviceGroupRenderPassBeginInfo or its 139 pname:deviceRenderAreaCount member is equal to 0, 140 pname:renderArea.offset.y must: be greater than or equal to 0 141 * [[VUID-VkRenderingInfoKHR-pNext-06079]] 142 If the pname:pNext chain does not contain 143 slink:VkDeviceGroupRenderPassBeginInfo or its 144 pname:deviceRenderAreaCount member is equal to 0, the width of the 145 pname:imageView member of any element of pname:pColorAttachments, 146 pname:pDepthAttachment, or pname:pStencilAttachment that is not 147 dlink:VK_NULL_HANDLE must: be greater than or equal to 148 [eq]#pname:renderArea.offset.x {plus} pname:renderArea.extent.width# 149 * [[VUID-VkRenderingInfoKHR-pNext-06080]] 150 If the pname:pNext chain does not contain 151 slink:VkDeviceGroupRenderPassBeginInfo or its 152 pname:deviceRenderAreaCount member is equal to 0, the height of the 153 pname:imageView member of any element of pname:pColorAttachments, 154 pname:pDepthAttachment, or pname:pStencilAttachment that is not 155 dlink:VK_NULL_HANDLE must: be greater than or equal to 156 [eq]#pname:renderArea.offset.y {plus} pname:renderArea.extent.height# 157 * [[VUID-VkRenderingInfoKHR-pNext-06083]] 158 If the pname:pNext chain contains 159 slink:VkDeviceGroupRenderPassBeginInfo, the width of the pname:imageView 160 member of any element of pname:pColorAttachments, 161 pname:pDepthAttachment, or pname:pStencilAttachment that is not 162 dlink:VK_NULL_HANDLE must: be greater than or equal to the sum of the 163 pname:offset.x and pname:extent.width members of each element of 164 pname:pDeviceRenderAreas 165 * [[VUID-VkRenderingInfoKHR-pNext-06084]] 166 If the pname:pNext chain contains 167 slink:VkDeviceGroupRenderPassBeginInfo, the height of the 168 pname:imageView member of any element of pname:pColorAttachments, 169 pname:pDepthAttachment, or pname:pStencilAttachment that is not 170 dlink:VK_NULL_HANDLE must: be greater than or equal to the sum of the 171 pname:offset.y and pname:extent.height members of each element of 172 pname:pDeviceRenderAreas 173 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06085]] 174 If neither pname:pDepthAttachment or pname:pStencilAttachment are `NULL` 175 and the pname:imageView member of either structure is not 176 dlink:VK_NULL_HANDLE, the pname:imageView member of each structure must: 177 be the same 178 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06086]] 179 If neither pname:pDepthAttachment or pname:pStencilAttachment are 180 `NULL`, and the pname:resolveMode member of each is not 181 ename:VK_RESOLVE_MODE_NONE, the pname:resolveImageView member of each 182 structure must: be the same 183endif::VK_VERSION_1_1,VK_KHR_device_group[] 184 * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06087]] 185 If pname:colorAttachmentCount is not `0` and the pname:imageView member 186 of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, 187 that pname:imageView must: have been created with 188 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 189 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06088]] 190 If pname:pDepthAttachment is not `NULL` and 191 pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, 192 pname:pDepthAttachment->imageView must: have been created with 193 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 194 * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06089]] 195 If pname:pStencilAttachment is not `NULL` and 196 pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, 197 pname:pStencilAttachment->imageView must: have been created with a 198 stencil usage including 199 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 200 * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06090]] 201 If pname:colorAttachmentCount is not `0` and the pname:imageView member 202 of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, 203 the pname:layout member of that element of pname:pColorAttachments must: 204 not be ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or 205 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 206 * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06091]] 207 If pname:colorAttachmentCount is not `0` and the pname:imageView member 208 of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, if 209 the pname:resolveMode member of that element of pname:pColorAttachments 210 is not ename:VK_RESOLVE_MODE_NONE, its pname:resolveImageLayout member 211 must: not be ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or 212 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 213 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06092]] 214 If pname:pDepthAttachment is not `NULL` and 215 pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, 216 pname:pDepthAttachment->layout must: not be 217 ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 218 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06093]] 219 If pname:pDepthAttachment is not `NULL`, 220 pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, and 221 pname:pDepthAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, 222 pname:pDepthAttachment->resolveImageLayout must: not be 223 ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 224 * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06094]] 225 If pname:pStencilAttachment is not `NULL` and 226 pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, 227 pname:pStencilAttachment->layout must: not be 228 ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 229 * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06095]] 230 If pname:pStencilAttachment is not `NULL`, 231 pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, and 232 pname:pStencilAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, 233 pname:pStencilAttachment->resolveImageLayout must: not be 234 ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 235ifdef::VK_KHR_maintenance2,VK_VERSION_1_1[] 236 * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06096]] 237 If pname:colorAttachmentCount is not `0` and the pname:imageView member 238 of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, 239 the pname:layout member of that element of pname:pColorAttachments must: 240 not be ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 241 or ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 242 * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06097]] 243 If pname:colorAttachmentCount is not `0` and the pname:imageView member 244 of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, if 245 the pname:resolveMode member of that element of pname:pColorAttachments 246 is not ename:VK_RESOLVE_MODE_NONE, its pname:resolveImageLayout member 247 must: not be 248 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL or 249 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 250 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06098]] 251 If pname:pDepthAttachment is not `NULL`, 252 pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, and 253 pname:pDepthAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, 254 pname:pDepthAttachment->resolveImageLayout must: not be 255 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 256 * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06099]] 257 If pname:pStencilAttachment is not `NULL`, 258 pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, and 259 pname:pStencilAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, 260 pname:pStencilAttachment->resolveImageLayout must: not be 261 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 262endif::VK_KHR_maintenance2,VK_VERSION_1_1[] 263ifdef::VK_KHR_separate_depth_stencil_layouts,VK_VERSION_1_2[] 264 * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06100]] 265 If pname:colorAttachmentCount is not `0` and the pname:imageView member 266 of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, 267 the pname:layout member of that element of pname:pColorAttachments must: 268 not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 269 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 270 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 271 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 272 * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06101]] 273 If pname:colorAttachmentCount is not `0` and the pname:imageView member 274 of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, if 275 the pname:resolveMode member of that element of pname:pColorAttachments 276 is not ename:VK_RESOLVE_MODE_NONE, its pname:resolveImageLayout member 277 must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 278 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 279 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 280 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 281endif::VK_KHR_separate_depth_stencil_layouts,VK_VERSION_1_2[] 282ifdef::VK_KHR_depth_stencil_resolve,VK_VERSION_1_2[] 283 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06102]] 284 If pname:pDepthAttachment is not `NULL` and 285 pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, 286 pname:pDepthAttachment->resolveMode must: be one of the bits set in 287 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:supportedDepthResolveModes 288 * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06103]] 289 If pname:pStencilAttachment is not `NULL` and 290 pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, 291 pname:pStencilAttachment->resolveMode must: be one of the bits set in 292 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:supportedStencilResolveModes 293 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06104]] 294 If pname:pDepthAttachment or pname:pStencilAttachment are both not 295 `NULL`, pname:pDepthAttachment->imageView and 296 pname:pStencilAttachment->imageView are both not dlink:VK_NULL_HANDLE, 297 and 298 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolveNone 299 is ename:VK_FALSE, the pname:resolveMode of both structures must: be the 300 same value 301 * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06105]] 302 If pname:pDepthAttachment or pname:pStencilAttachment are both not 303 `NULL`, pname:pDepthAttachment->imageView and 304 pname:pStencilAttachment->imageView are both not dlink:VK_NULL_HANDLE, 305 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolve 306 is ename:VK_FALSE, and the pname:resolveMode of neither structure is 307 ename:VK_RESOLVE_MODE_NONE, the pname:resolveMode of both structures 308 must: be the same value 309endif::VK_KHR_depth_stencil_resolve,VK_VERSION_1_2[] 310 * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06106]] 311 pname:colorAttachmentCount must: be less than or equal to 312 slink:VkPhysicalDeviceLimits::pname:maxColorAttachments 313ifdef::VK_EXT_fragment_density_map[] 314 * [[VUID-VkRenderingInfoKHR-imageView-06107]] 315 If the pname:imageView member of a 316 slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included 317 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and 318 <<features-fragmentDensityMapNonSubsampledImages,non-subsample image 319 feature>> is not enabled, valid pname:imageView and 320 pname:resolveImageView members of pname:pDepthAttachment, 321 pname:pStencilAttachment, and each element of pname:pColorAttachments 322 must: be a slink:VkImageView created with 323 ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT 324ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 325 * [[VUID-VkRenderingInfoKHR-imageView-06108]] 326 If the pname:imageView member of a 327 slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included 328 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and pname:viewMask 329 is not `0`, pname:imageView must: have a pname:layerCount greater than 330 or equal to the index of the most significant bit in pname:viewMask 331 * [[VUID-VkRenderingInfoKHR-imageView-06109]] 332 If the pname:imageView member of a 333 slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included 334 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and pname:viewMask 335 is `0`, pname:imageView must: have a pname:layerCount equal to `1` 336endif::VK_VERSION_1_1,VK_KHR_multiview[] 337ifndef::VK_VERSION_1_1,VK_KHR_device_group[] 338 * [[VUID-VkRenderingInfoKHR-imageView-06110]] 339 If the pname:imageView member of a 340 slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included 341 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView 342 must: have a width greater than or equal to 343 latexmath:[\left\lceil{\frac{renderArea_{x}+renderArea_{width}}{maxFragmentDensityTexelSize_{width}}}\right\rceil] 344 * [[VUID-VkRenderingInfoKHR-imageView-06111]] 345 If the pname:imageView member of a 346 slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included 347 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView 348 must: have a height greater than or equal to 349 latexmath:[\left\lceil{\frac{renderArea_{y}+renderArea_{height}}{maxFragmentDensityTexelSize_{height}}}\right\rceil] 350endif::VK_VERSION_1_1,VK_KHR_device_group[] 351ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 352 * [[VUID-VkRenderingInfoKHR-pNext-06112]] 353 If the pname:pNext chain does not contain 354 slink:VkDeviceGroupRenderPassBeginInfo or its 355 pname:deviceRenderAreaCount member is equal to 0 and the pname:imageView 356 member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT 357 structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, 358 pname:imageView must: have a width greater than or equal to 359 latexmath:[\left\lceil{\frac{renderArea_{x}+renderArea_{width}}{maxFragmentDensityTexelSize_{width}}}\right\rceil] 360 * [[VUID-VkRenderingInfoKHR-pNext-06113]] 361 If the pname:pNext chain contains a 362 slink:VkDeviceGroupRenderPassBeginInfo structure, its 363 pname:deviceRenderAreaCount member is not 0, and the pname:imageView 364 member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT 365 structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, 366 pname:imageView must: have a width greater than or equal to 367 latexmath:[\left\lceil{\frac{pDeviceRenderAreas_{x}+pDeviceRenderAreas_{width}}{maxFragmentDensityTexelSize_{width}}}\right\rceil] 368 for each element of pname:pDeviceRenderAreas 369 * [[VUID-VkRenderingInfoKHR-pNext-06114]] 370 If the pname:pNext chain does not contain 371 slink:VkDeviceGroupRenderPassBeginInfo or its 372 pname:deviceRenderAreaCount member is equal to 0 and the pname:imageView 373 member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT 374 structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, 375 pname:imageView must: have a height greater than or equal to 376 latexmath:[\left\lceil{\frac{renderArea_{y}+renderArea_{height}}{maxFragmentDensityTexelSize_{height}}}\right\rceil] 377 * [[VUID-VkRenderingInfoKHR-pNext-06115]] 378 If the pname:pNext chain contains a 379 slink:VkDeviceGroupRenderPassBeginInfo structure, its 380 pname:deviceRenderAreaCount member is not 0, and the pname:imageView 381 member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT 382 structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, 383 pname:imageView must: have a height greater than or equal to 384 latexmath:[\left\lceil{\frac{pDeviceRenderAreas_{y}+pDeviceRenderAreas_{height}}{maxFragmentDensityTexelSize_{height}}}\right\rceil] 385 for each element of pname:pDeviceRenderAreas 386endif::VK_VERSION_1_1,VK_KHR_device_group[] 387 * [[VUID-VkRenderingInfoKHR-imageView-06116]] 388 If the pname:imageView member of a 389 slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included 390 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, it must: not be 391 equal to the pname:imageView or pname:resolveImageView member of 392 pname:pDepthAttachment, pname:pStencilAttachment, or any element of 393 pname:pColorAttachments 394endif::VK_EXT_fragment_density_map[] 395ifdef::VK_KHR_fragment_shading_rate[] 396ifndef::VK_VERSION_1_1,VK_KHR_device_group[] 397 * [[VUID-VkRenderingInfoKHR-imageView-06117]] 398 If the pname:imageView member of a 399 slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included 400 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView 401 must: have a width greater than or equal to 402 latexmath:[\left\lceil{\frac{renderArea_{x}+renderArea_{width}}{shadingRateAttachmentTexelSize_{width}}}\right\rceil] 403 * [[VUID-VkRenderingInfoKHR-imageView-06118]] 404 If the pname:imageView member of a 405 slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included 406 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView 407 must: have a height greater than or equal to 408 latexmath:[\left\lceil{\frac{renderArea_{y}+renderArea_{height}}{shadingRateAttachmentTexelSize_{height}}}\right\rceil] 409endif::VK_VERSION_1_1,VK_KHR_device_group[] 410ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 411 * [[VUID-VkRenderingInfoKHR-pNext-06119]] 412 If the pname:pNext chain does not contain 413 slink:VkDeviceGroupRenderPassBeginInfo or its 414 pname:deviceRenderAreaCount member is equal to 0 and the pname:imageView 415 member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR 416 structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, 417 pname:imageView must: have a width greater than or equal to 418 latexmath:[\left\lceil{\frac{renderArea_{x}+renderArea_{width}}{shadingRateAttachmentTexelSize_{width}}}\right\rceil] 419 * [[VUID-VkRenderingInfoKHR-pNext-06120]] 420 If the pname:pNext chain contains a 421 slink:VkDeviceGroupRenderPassBeginInfo structure, its 422 pname:deviceRenderAreaCount member is not 0, and the pname:imageView 423 member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR 424 structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, 425 pname:imageView must: have a width greater than or equal to 426 latexmath:[\left\lceil{\frac{pDeviceRenderAreas_{x}+pDeviceRenderAreas_{width}}{shadingRateAttachmentTexelSize_{width}}}\right\rceil] 427 for each element of pname:pDeviceRenderAreas 428 * [[VUID-VkRenderingInfoKHR-pNext-06121]] 429 If the pname:pNext chain does not contain 430 slink:VkDeviceGroupRenderPassBeginInfo or its 431 pname:deviceRenderAreaCount member is equal to 0 and the pname:imageView 432 member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR 433 structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, 434 pname:imageView must: have a height greater than or equal to 435 latexmath:[\left\lceil{\frac{renderArea_{y}+renderArea_{height}}{shadingRateAttachmentTexelSize_{height}}}\right\rceil] 436 * [[VUID-VkRenderingInfoKHR-pNext-06122]] 437 If the pname:pNext chain contains a 438 slink:VkDeviceGroupRenderPassBeginInfo structure, its 439 pname:deviceRenderAreaCount member is not 0, and the pname:imageView 440 member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR 441 structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, 442 pname:imageView must: have a height greater than or equal to 443 latexmath:[\left\lceil{\frac{pDeviceRenderAreas_{y}+pDeviceRenderAreas_{height}}{shadingRateAttachmentTexelSize_{height}}}\right\rceil] 444 for each element of pname:pDeviceRenderAreas 445endif::VK_VERSION_1_1,VK_KHR_device_group[] 446 * [[VUID-VkRenderingInfoKHR-imageView-06123]] 447 If the pname:imageView member of a 448 slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included 449 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and pname:viewMask 450 is `0`, pname:imageView must: have a pname:layerCount that is either 451 equal to `1` or greater than or equal to pname:layerCount 452 * [[VUID-VkRenderingInfoKHR-imageView-06124]] 453 If the pname:imageView member of a 454 slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included 455 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and pname:viewMask 456 is not `0`, pname:imageView must: have a pname:layerCount that either 457 equal to `1` or greater than or equal to the index of the most 458 significant bit in pname:viewMask 459 * [[VUID-VkRenderingInfoKHR-imageView-06125]] 460 If the pname:imageView member of a 461 slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included 462 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, it must: not be 463 equal to the pname:imageView or pname:resolveImageView member of 464 pname:pDepthAttachment, pname:pStencilAttachment, or any element of 465 pname:pColorAttachments 466ifdef::VK_EXT_fragment_density_map[] 467 * [[VUID-VkRenderingInfoKHR-imageView-06126]] 468 If the pname:imageView member of a 469 slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included 470 in the pname:pNext chain is not dlink:VK_NULL_HANDLE, it must: not be 471 equal to the pname:imageView member of a 472 slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included 473 in the pname:pNext chain 474endif::VK_EXT_fragment_density_map[] 475endif::VK_KHR_fragment_shading_rate[] 476 * [[VUID-VkRenderingInfoKHR-multiview-06127]] 477 If the <<features-multiview,pname:multiview>> feature is not enabled, 478 pname:viewMask must: be `0` 479ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 480 * [[VUID-VkRenderingInfoKHR-viewMask-06128]] 481 The index of the most significant bit in pname:viewMask must: be less 482 than <<limits-maxMultiviewViewCount,pname:maxMultiviewViewCount>> 483endif::VK_VERSION_1_1,VK_KHR_multiview[] 484**** 485 486include::{generated}/validity/structs/VkRenderingInfoKHR.txt[] 487-- 488 489[open,refpage='VkRenderingFlagBitsKHR',desc='Bitmask specifying additional properties of a dynamic render pass instance',type='enums'] 490-- 491Bits which can: be set in slink:VkRenderingInfoKHR::pname:flags describing 492additional properties of the render pass are: 493 494include::{generated}/api/enums/VkRenderingFlagBitsKHR.txt[] 495 496 * ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR specifies 497 that draw calls for the render pass instance will be recorded in 498 secondary command buffers. 499 * ename:VK_RENDERING_RESUMING_BIT_KHR specifies that the render pass 500 instance is resuming an earlier suspended render pass instance. 501 * ename:VK_RENDERING_SUSPENDING_BIT_KHR specifies that the render pass 502 instance will be suspended. 503 504[[renderpass-suspension]] 505The contents of pname:pRenderingInfo must: match between suspended render 506pass instances and the render pass instances that resume them, other than 507the presence or absence of the ename:VK_RENDERING_RESUMING_BIT_KHR, 508ename:VK_RENDERING_SUSPENDING_BIT_KHR, and 509ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR flags. 510No action or synchronization commands, or other render pass instances, are 511allowed between suspending and resuming render pass instances. 512-- 513 514[open,refpage='VkRenderingFlagsKHR',desc='Bitmask of VkRenderingFlagBitsKHR',type='flags'] 515-- 516include::{generated}/api/flags/VkRenderingFlagsKHR.txt[] 517 518tname:VkRenderingFlagsKHR is a bitmask type for setting a mask of zero or 519more elink:VkRenderingFlagBitsKHR. 520-- 521 522[open,refpage='VkRenderingAttachmentInfoKHR',desc='Structure specifying attachment information',type='structs'] 523-- 524The sname:VkRenderingAttachmentInfoKHR structure is defined as: 525 526include::{generated}/api/structs/VkRenderingAttachmentInfoKHR.txt[] 527 528 * pname:sType is the type of this structure. 529 * pname:pNext is `NULL` or a pointer to a structure extending this 530 structure. 531 * pname:imageView is the image view that will be used for rendering. 532 * pname:imageLayout is the layout that pname:imageView will be in during 533 rendering. 534 * pname:resolveMode is a elink:VkResolveModeFlagBits value defining how 535 multisampled data written to pname:imageView will be resolved. 536 * pname:resolveImageView is an image view used to write resolved 537 multisample data at the end of rendering. 538 * pname:resolveImageLayout is the layout that pname:resolveImageView will 539 be in during rendering. 540 * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the 541 contents of pname:imageView are treated at the start of the render pass 542 instance. 543 * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the 544 contents of pname:imageView are treated at the end of the render pass 545 instance. 546 * pname:clearValue is a slink:VkClearValue structure defining values used 547 to clear pname:imageView when pname:loadOp is 548 ename:VK_ATTACHMENT_LOAD_OP_CLEAR. 549 550Values in pname:imageView are loaded and stored according to the values of 551pname:loadOp and pname:storeOp, within the render area 552ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 553for each device 554endif::VK_VERSION_1_1,VK_KHR_device_group[] 555specified in slink:VkRenderingInfoKHR. 556If pname:imageView is dlink:VK_NULL_HANDLE, other members of this structure 557are ignored; writes to this attachment will be discarded, and no load, 558store, or resolve operations will be performed. 559 560If pname:resolveMode is ename:VK_RESOLVE_MODE_NONE, then 561pname:resolveImageView is ignored. 562If pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, values in 563pname:resolveImageView within the render area become undefined: once 564rendering begins. 565At the end of rendering, the color values written to each pixel location in 566pname:imageView will be resolved according to pname:resolveMode and stored 567into the the same location in pname:resolveImageView. 568 569[NOTE] 570.Note 571==== 572The resolve mode and store operation are independent; it is valid to write 573both resolved and unresolved values, and equally valid to discard the 574unresolved values while writing the resolved ones. 575==== 576 577Store and resolve operations are only performed at the end of a render pass 578instance that does not specify the ename:VK_RENDERING_SUSPENDING_BIT_KHR 579flag. 580 581Load operations are only performed at the beginning of a render pass 582instance that does not specify the ename:VK_RENDERING_RESUMING_BIT_KHR flag. 583 584Image contents at the end of a suspended render pass instance remain defined 585for access by a resuming render pass instance. 586 587.Valid Usage 588**** 589 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06129]] 590 If pname:imageView is not dlink:VK_NULL_HANDLE and has a non-integer 591 color format, pname:resolveMode must: be ename:VK_RESOLVE_MODE_NONE or 592 ename:VK_RESOLVE_MODE_AVERAGE_BIT 593 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06130]] 594 If pname:imageView is not dlink:VK_NULL_HANDLE and has an integer color 595 format, pname:resolveMode must: be ename:VK_RESOLVE_MODE_NONE or 596 ename:VK_RESOLVE_MODE_SAMPLE_ZERO_BIT 597ifndef::VK_KHR_depth_stencil_resolve,VK_VERSION_1_2[] 598 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06131]] 599 If pname:imageView is not dlink:VK_NULL_HANDLE and has a depth or 600 stencil format, pname:resolveMode must: be ename:VK_RESOLVE_MODE_NONE 601endif::VK_KHR_depth_stencil_resolve,VK_VERSION_1_2[] 602 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06132]] 603 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 604 not ename:VK_RESOLVE_MODE_NONE, pname:imageView must: not have a sample 605 count of ename:VK_SAMPLE_COUNT_1_BIT 606 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06133]] 607 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 608 not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageView must: have a 609 sample count of ename:VK_SAMPLE_COUNT_1_BIT 610 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06134]] 611 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 612 not ename:VK_RESOLVE_MODE_NONE, pname:imageView and 613 pname:resolveImageView must: have the same elink:VkFormat 614 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06135]] 615 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not 616 be ename:VK_IMAGE_LAYOUT_UNDEFINED, 617 ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, 618 ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, 619 ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or 620 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 621 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06136]] 622 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 623 not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be 624 ename:VK_IMAGE_LAYOUT_UNDEFINED, 625 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 626 ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, 627 ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, 628 ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or 629 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 630ifdef::VK_KHR_separate_depth_stencil_layouts,VK_VERSION_1_2[] 631 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06137]] 632 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 633 not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be 634 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL or 635 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 636endif::VK_KHR_separate_depth_stencil_layouts,VK_VERSION_1_2[] 637ifdef::VK_NV_shading_rate_image[] 638 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06138]] 639 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not 640 be ename:VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV 641 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06139]] 642 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 643 not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be 644 ename:VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV 645endif::VK_NV_shading_rate_image[] 646ifdef::VK_EXT_fragment_density_map[] 647 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06140]] 648 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not 649 be ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT 650 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06141]] 651 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 652 not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be 653 ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT 654endif::VK_EXT_fragment_density_map[] 655ifdef::VK_KHR_synchronization2[] 656 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06142]] 657 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 658 not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be 659 ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR 660endif::VK_KHR_synchronization2[] 661ifdef::VK_KHR_fragment_shading_rate[] 662 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06143]] 663 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not 664 be ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR 665 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06144]] 666 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 667 not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be 668 ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR 669endif::VK_KHR_fragment_shading_rate[] 670ifdef::VK_KHR_swapchain[] 671 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06145]] 672 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not 673 be ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 674 * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06146]] 675 If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is 676 not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be 677 ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 678endif::VK_KHR_swapchain[] 679**** 680 681include::{generated}/validity/structs/VkRenderingAttachmentInfoKHR.txt[] 682-- 683 684ifdef::VK_KHR_fragment_shading_rate[] 685[open,refpage='VkRenderingFragmentShadingRateAttachmentInfoKHR',desc='Structure specifying fragment shading rate attachment information',type='structs'] 686-- 687The sname:VkRenderingFragmentShadingRateAttachmentInfoKHR structure is 688defined as: 689 690include::{generated}/api/structs/VkRenderingFragmentShadingRateAttachmentInfoKHR.txt[] 691 692 * pname:sType is the type of this structure. 693 * pname:pNext is `NULL` or a pointer to a structure extending this 694 structure. 695 * pname:imageView is the image view that will be used as a fragment 696 shading rate attachment. 697 * pname:imageLayout is the layout that pname:imageView will be in during 698 rendering. 699 * pname:shadingRateAttachmentTexelSize specifies the number of pixels 700 corresponding to each texel in pname:imageView. 701 702This structure can be included in the pname:pNext chain of 703slink:VkRenderingInfoKHR to define a 704<<primsrast-fragment-shading-rate-attachment, fragment shading rate 705attachment>>. 706If pname:imageView is dlink:VK_NULL_HANDLE, or if this structure is not 707specified, the implementation behaves as if a valid shading rate attachment 708was specified with all texels specifying a single pixel per fragment. 709 710.Valid Usage 711**** 712 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06147]] 713 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: be 714 ename:VK_IMAGE_LAYOUT_GENERAL or 715 ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR 716 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06148]] 717 If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have been 718 created with 719 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 720 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06149]] 721 If pname:imageView is not dlink:VK_NULL_HANDLE, 722 pname:shadingRateAttachmentTexelSize.width must: be a power of two value 723 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06150]] 724 If pname:imageView is not dlink:VK_NULL_HANDLE, 725 pname:shadingRateAttachmentTexelSize.width must: be less than or equal 726 to <<limits-maxFragmentShadingRateAttachmentTexelSize, 727 pname:maxFragmentShadingRateAttachmentTexelSize.width>> 728 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06151]] 729 If pname:imageView is not dlink:VK_NULL_HANDLE, 730 pname:shadingRateAttachmentTexelSize.width must: be greater than or 731 equal to <<limits-minFragmentShadingRateAttachmentTexelSize, 732 pname:minFragmentShadingRateAttachmentTexelSize.width>> 733 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06152]] 734 If pname:imageView is not dlink:VK_NULL_HANDLE, 735 pname:shadingRateAttachmentTexelSize.height must: be a power of two 736 value 737 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06153]] 738 If pname:imageView is not dlink:VK_NULL_HANDLE, 739 pname:shadingRateAttachmentTexelSize.height must: be less than or equal 740 to <<limits-maxFragmentShadingRateAttachmentTexelSize, 741 pname:maxFragmentShadingRateAttachmentTexelSize.height>> 742 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06154]] 743 If pname:imageView is not dlink:VK_NULL_HANDLE, 744 pname:shadingRateAttachmentTexelSize.height must: be greater than or 745 equal to <<limits-minFragmentShadingRateAttachmentTexelSize, 746 pname:minFragmentShadingRateAttachmentTexelSize.height>> 747 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06155]] 748 If pname:imageView is not dlink:VK_NULL_HANDLE, the quotient of 749 pname:shadingRateAttachmentTexelSize.width and 750 pname:shadingRateAttachmentTexelSize.height must: be less than or equal 751 to <<limits-maxFragmentShadingRateAttachmentTexelSizeAspectRatio, 752 pname:maxFragmentShadingRateAttachmentTexelSizeAspectRatio>> 753 * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06156]] 754 If pname:imageView is not dlink:VK_NULL_HANDLE, the quotient of 755 pname:shadingRateAttachmentTexelSize.height and 756 pname:shadingRateAttachmentTexelSize.width must: be less than or equal 757 to <<limits-maxFragmentShadingRateAttachmentTexelSizeAspectRatio, 758 pname:maxFragmentShadingRateAttachmentTexelSizeAspectRatio>> 759**** 760 761include::{generated}/validity/structs/VkRenderingFragmentShadingRateAttachmentInfoKHR.txt[] 762-- 763endif::VK_KHR_fragment_shading_rate[] 764 765ifdef::VK_EXT_fragment_density_map[] 766[open,refpage='VkRenderingFragmentDensityMapAttachmentInfoEXT',desc='Structure specifying fragment shading rate attachment information',type='structs'] 767-- 768The sname:VkRenderingFragmentDensityMapAttachmentInfoEXT structure is 769defined as: 770 771include::{generated}/api/structs/VkRenderingFragmentDensityMapAttachmentInfoEXT.txt[] 772 773 * pname:sType is the type of this structure. 774 * pname:pNext is `NULL` or a pointer to a structure extending this 775 structure. 776 * pname:imageView is the image view that will be used as a fragment 777 shading rate attachment. 778 * pname:imageLayout is the layout that pname:imageView will be in during 779 rendering. 780 781This structure can be included in the pname:pNext chain of 782slink:VkRenderingInfoKHR to define a fragment density map. 783If pname:imageView is dlink:VK_NULL_HANDLE, or if this structure is not 784specified, pname:imageView is dlink:VK_NULL_HANDLE. 785 786.Valid Usage 787**** 788 * [[VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06157]] 789 If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: be 790 ename:VK_IMAGE_LAYOUT_GENERAL or 791 ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT 792 * [[VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06158]] 793 If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have been 794 created with ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT 795 * [[VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06159]] 796 If pname:imageView is not dlink:VK_NULL_HANDLE, it must: not have been 797 created with ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT 798ifndef::VK_VERSION_1_1,VK_KHR_multiview[] 799 * [[VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06160]] 800 If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have a 801 pname:layerCount equal to `1` 802endif::VK_VERSION_1_1,VK_KHR_multiview[] 803**** 804 805include::{generated}/validity/structs/VkRenderingFragmentDensityMapAttachmentInfoEXT.txt[] 806-- 807endif::VK_EXT_fragment_density_map[] 808 809[open,refpage='vkCmdEndRenderingKHR',desc='End a dynamic render pass instance',type='protos'] 810-- 811To end a render pass instance, call: 812 813include::{generated}/api/protos/vkCmdEndRenderingKHR.txt[] 814 815 * pname:commandBuffer is the command buffer in which to record the 816 command. 817 818If the value of pname:pRenderingInfo->flags used to begin this render pass 819instance included ename:VK_RENDERING_SUSPENDING_BIT_KHR, then this render 820pass is suspended and will be resumed later in 821<<synchronization-submission-order, submission order>>. 822 823.Valid Usage 824**** 825 * [[VUID-vkCmdEndRenderingKHR-None-06161]] 826 The current render pass instance must: have been begun with 827 flink:vkCmdBeginRenderingKHR 828 * [[VUID-vkCmdEndRenderingKHR-commandBuffer-06162]] 829 The current render pass instance must: have been begun in 830 pname:commandBuffer 831**** 832include::{generated}/validity/protos/vkCmdEndRenderingKHR.txt[] 833-- 834 835[NOTE] 836.Note 837==== 838For more complex rendering graphs, it is possible to pre-define a static 839_render pass_ object, which as well as allowing draw commands, allows the 840definition of framebuffer-local dependencies between multiple subpasses. 841These objects have a lot of setup cost compared to 842flink:vkCmdBeginRenderingKHR, but use of subpass dependencies can confer 843important performance benefits on some devices. 844==== 845endif::VK_KHR_dynamic_rendering[] 846 847[open,refpage='VkRenderPass',desc='Opaque handle to a render pass object',type='handles'] 848-- 849A render pass object represents a collection of attachments, subpasses, and 850dependencies between the subpasses, and describes how the attachments are 851used over the course of the subpasses. 852 853Render passes are represented by sname:VkRenderPass handles: 854 855include::{generated}/api/handles/VkRenderPass.txt[] 856-- 857 858An _attachment description_ describes the properties of an attachment 859including its format, sample count, and how its contents are treated at the 860beginning and end of each render pass instance. 861 862[[renderpass-subpass]] 863A _subpass_ represents a phase of rendering that reads and writes a subset 864of the attachments in a render pass. 865Rendering commands are recorded into a particular subpass of a render pass 866instance. 867 868A _subpass description_ describes the subset of attachments that is involved 869in the execution of a subpass. 870Each subpass can: read from some attachments as _input attachments_, write 871to some as _color attachments_ or _depth/stencil attachments_, 872ifdef::VK_QCOM_render_pass_shader_resolve[] 873perform _shader resolve operations_ to _color_attachments_ or 874_depth/stencil_attachments_, 875endif::VK_QCOM_render_pass_shader_resolve[] 876and perform _multisample resolve operations_ to _resolve attachments_. 877A subpass description can: also include a set of _preserve attachments_, 878which are attachments that are not read or written by the subpass but whose 879contents must: be preserved throughout the subpass. 880 881A subpass _uses an attachment_ if the attachment is a color, depth/stencil, 882resolve, 883ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 884depth/stencil resolve, 885endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 886ifdef::VK_KHR_fragment_shading_rate[] 887fragment shading rate, 888endif::VK_KHR_fragment_shading_rate[] 889or input attachment for that subpass (as determined by the 890pname:pColorAttachments, pname:pDepthStencilAttachment, 891pname:pResolveAttachments, 892ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 893slink:VkSubpassDescriptionDepthStencilResolve::pname:pDepthStencilResolveAttachment, 894endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 895ifdef::VK_KHR_fragment_shading_rate[] 896slink:VkFragmentShadingRateAttachmentInfoKHR::pname:pFragmentShadingRateAttachment->attachment, 897endif::VK_KHR_fragment_shading_rate[] 898and pname:pInputAttachments members of slink:VkSubpassDescription, 899respectively). 900A subpass does not use an attachment if that attachment is preserved by the 901subpass. 902The _first use of an attachment_ is in the lowest numbered subpass that uses 903that attachment. 904Similarly, the _last use of an attachment_ is in the highest numbered 905subpass that uses that attachment. 906 907The subpasses in a render pass all render to the same dimensions, and 908fragments for pixel (x,y,layer) in one subpass can: only read attachment 909contents written by previous subpasses at that same (x,y,layer) location. 910ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate,VK_EXT_fragment_density_map[] 911For multi-pixel fragments, the pixel read from an input attachment is 912selected from the pixels covered by that fragment in an 913implementation-dependent manner. 914However, this selection must: be made consistently for any fragment with the 915same shading rate for the lifetime of the slink:VkDevice. 916endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate,VK_EXT_fragment_density_map[] 917 918[NOTE] 919.Note 920==== 921By describing a complete set of subpasses in advance, render passes provide 922the implementation an opportunity to optimize the storage and transfer of 923attachment data between subpasses. 924 925In practice, this means that subpasses with a simple framebuffer-space 926dependency may: be merged into a single tiled rendering pass, keeping the 927attachment data on-chip for the duration of a render pass instance. 928However, it is also quite common for a render pass to only contain a single 929subpass. 930==== 931 932_Subpass dependencies_ describe <<synchronization-dependencies, execution 933and memory dependencies>> between subpasses. 934 935A _subpass dependency chain_ is a sequence of subpass dependencies in a 936render pass, where the source subpass of each subpass dependency (after the 937first) equals the destination subpass of the previous dependency. 938 939Execution of subpasses may: overlap or execute out of order with regards to 940other subpasses, unless otherwise enforced by an execution dependency. 941Each subpass only respects <<synchronization-submission-order, submission 942order>> for commands recorded in the same subpass, and the 943flink:vkCmdBeginRenderPass and flink:vkCmdEndRenderPass commands that 944delimit the render pass - commands within other subpasses are not included. 945This affects most other <<synchronization-implicit, implicit ordering 946guarantees>>. 947 948A render pass describes the structure of subpasses and attachments 949independent of any specific image views for the attachments. 950The specific image views that will be used for the attachments, and their 951dimensions, are specified in sname:VkFramebuffer objects. 952Framebuffers are created with respect to a specific render pass that the 953framebuffer is compatible with (see <<renderpass-compatibility,Render Pass 954Compatibility>>). 955Collectively, a render pass and a framebuffer define the complete render 956target state for one or more subpasses as well as the algorithmic 957dependencies between the subpasses. 958 959The various pipeline stages of the drawing commands for a given subpass may: 960execute concurrently and/or out of order, both within and across drawing 961commands, whilst still respecting <<synchronization-pipeline-stages-order, 962pipeline order>>. 963However for a given (x,y,layer,sample) sample location, certain per-sample 964operations are performed in <<primsrast-order,rasterization order>>. 965 966[open,refpage='VK_ATTACHMENT_UNUSED',desc='Unused attachment sentinel',type='consts'] 967-- 968ename:VK_ATTACHMENT_UNUSED is a constant indicating that a render pass 969attachment is not used. 970 971include::{generated}/api/enums/VK_ATTACHMENT_UNUSED.txt[] 972-- 973 974 975[[renderpass-creation]] 976== Render Pass Creation 977 978[open,refpage='vkCreateRenderPass',desc='Create a new render pass object',type='protos'] 979-- 980To create a render pass, call: 981 982include::{generated}/api/protos/vkCreateRenderPass.txt[] 983 984 * pname:device is the logical device that creates the render pass. 985 * pname:pCreateInfo is a pointer to a slink:VkRenderPassCreateInfo 986 structure describing the parameters of the render pass. 987 * pname:pAllocator controls host memory allocation as described in the 988 <<memory-allocation, Memory Allocation>> chapter. 989 * pname:pRenderPass is a pointer to a slink:VkRenderPass handle in which 990 the resulting render pass object is returned. 991 992include::{generated}/validity/protos/vkCreateRenderPass.txt[] 993-- 994 995[open,refpage='VkRenderPassCreateInfo',desc='Structure specifying parameters of a newly created render pass',type='structs'] 996-- 997The sname:VkRenderPassCreateInfo structure is defined as: 998 999include::{generated}/api/structs/VkRenderPassCreateInfo.txt[] 1000 1001 * pname:sType is the type of this structure. 1002 * pname:pNext is `NULL` or a pointer to a structure extending this 1003 structure. 1004ifndef::VK_QCOM_render_pass_transform[] 1005 * pname:flags is reserved for future use. 1006endif::VK_QCOM_render_pass_transform[] 1007ifdef::VK_QCOM_render_pass_transform[] 1008 * pname:flags is a bitmask of elink:VkRenderPassCreateFlagBits 1009endif::VK_QCOM_render_pass_transform[] 1010 * pname:attachmentCount is the number of attachments used by this render 1011 pass. 1012 * pname:pAttachments is a pointer to an array of pname:attachmentCount 1013 slink:VkAttachmentDescription structures describing the attachments used 1014 by the render pass. 1015 * pname:subpassCount is the number of subpasses to create. 1016 * pname:pSubpasses is a pointer to an array of pname:subpassCount 1017 slink:VkSubpassDescription structures describing each subpass. 1018 * pname:dependencyCount is the number of memory dependencies between pairs 1019 of subpasses. 1020 * pname:pDependencies is a pointer to an array of pname:dependencyCount 1021 slink:VkSubpassDependency structures describing dependencies between 1022 pairs of subpasses. 1023 1024[NOTE] 1025.Note 1026==== 1027Care should be taken to avoid a data race here; if any subpasses access 1028attachments with overlapping memory locations, and one of those accesses is 1029a write, a subpass dependency needs to be included between them. 1030==== 1031 1032.Valid Usage 1033**** 1034 * [[VUID-VkRenderPassCreateInfo-attachment-00834]] 1035 If the pname:attachment member of any element of 1036 pname:pInputAttachments, pname:pColorAttachments, 1037 pname:pResolveAttachments or pname:pDepthStencilAttachment, or any 1038 element of pname:pPreserveAttachments in any element of pname:pSubpasses 1039 is not ename:VK_ATTACHMENT_UNUSED, then it must: be less than 1040 pname:attachmentCount 1041ifdef::VK_EXT_fragment_density_map[] 1042 * [[VUID-VkRenderPassCreateInfo-fragmentDensityMapAttachment-06471]] 1043 If the pNext chain includes a 1044 slink:VkRenderPassFragmentDensityMapCreateInfoEXT structure and the 1045 pname:fragmentDensityMapAttachment member is not 1046 ename:VK_ATTACHMENT_UNUSED, then pname:attachment must: be less than 1047 pname:attachmentCount 1048endif::VK_EXT_fragment_density_map[] 1049 * [[VUID-VkRenderPassCreateInfo-pAttachments-00836]] 1050 For any member of pname:pAttachments with a pname:loadOp equal to 1051 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 1052 must: not specify a pname:layout equal to 1053 ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or 1054 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 1055 * [[VUID-VkRenderPassCreateInfo-pAttachments-02511]] 1056 For any member of pname:pAttachments with a pname:stencilLoadOp equal to 1057 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 1058 must: not specify a pname:layout equal to 1059 ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or 1060 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 1061ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 1062 * [[VUID-VkRenderPassCreateInfo-pAttachments-01566]] 1063 For any member of pname:pAttachments with a pname:loadOp equal to 1064 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 1065 must: not specify a pname:layout equal to 1066 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 1067 * [[VUID-VkRenderPassCreateInfo-pAttachments-01567]] 1068 For any member of pname:pAttachments with a pname:stencilLoadOp equal to 1069 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 1070 must: not specify a pname:layout equal to 1071 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 1072 * [[VUID-VkRenderPassCreateInfo-pNext-01926]] 1073 If the pname:pNext chain includes a 1074 slink:VkRenderPassInputAttachmentAspectCreateInfo structure, the 1075 pname:subpass member of each element of its pname:pAspectReferences 1076 member must: be less than pname:subpassCount 1077 * [[VUID-VkRenderPassCreateInfo-pNext-01927]] 1078 If the pname:pNext chain includes a 1079 slink:VkRenderPassInputAttachmentAspectCreateInfo structure, the 1080 pname:inputAttachmentIndex member of each element of its 1081 pname:pAspectReferences member must: be less than the value of 1082 pname:inputAttachmentCount in the element of pname:pSubpasses identified 1083 by its pname:subpass member 1084 * [[VUID-VkRenderPassCreateInfo-pNext-01963]] 1085 If the pname:pNext chain includes a 1086 slink:VkRenderPassInputAttachmentAspectCreateInfo structure, for any 1087 element of the pname:pInputAttachments member of any element of 1088 pname:pSubpasses where the pname:attachment member is not 1089 ename:VK_ATTACHMENT_UNUSED, the pname:aspectMask member of the 1090 corresponding element of 1091 slink:VkRenderPassInputAttachmentAspectCreateInfo::pname:pAspectReferences 1092 must: only include aspects that are present in images of the format 1093 specified by the element of pname:pAttachments at pname:attachment 1094endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 1095ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1096 * [[VUID-VkRenderPassCreateInfo-pNext-01928]] 1097 If the pname:pNext chain includes a 1098 slink:VkRenderPassMultiviewCreateInfo structure, and its 1099 pname:subpassCount member is not zero, that member must: be equal to the 1100 value of pname:subpassCount 1101 * [[VUID-VkRenderPassCreateInfo-pNext-01929]] 1102 If the pname:pNext chain includes a 1103 slink:VkRenderPassMultiviewCreateInfo structure, if its 1104 pname:dependencyCount member is not zero, it must: be equal to 1105 pname:dependencyCount 1106 * [[VUID-VkRenderPassCreateInfo-pNext-01930]] 1107 If the pname:pNext chain includes a 1108 slink:VkRenderPassMultiviewCreateInfo structure, for each non-zero 1109 element of pname:pViewOffsets, the pname:srcSubpass and pname:dstSubpass 1110 members of pname:pDependencies at the same index must: not be equal 1111 * [[VUID-VkRenderPassCreateInfo-pNext-02512]] 1112 If the pname:pNext chain includes a 1113 slink:VkRenderPassMultiviewCreateInfo structure, for any element of 1114 pname:pDependencies with a pname:dependencyFlags member that does not 1115 include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, the corresponding element of 1116 the pname:pViewOffsets member of that 1117 slink:VkRenderPassMultiviewCreateInfo instance must: be `0` 1118 * [[VUID-VkRenderPassCreateInfo-pNext-02513]] 1119 If the pname:pNext chain includes a 1120 slink:VkRenderPassMultiviewCreateInfo structure, elements of its 1121 pname:pViewMasks member must: either all be `0`, or all not be `0` 1122 * [[VUID-VkRenderPassCreateInfo-pNext-02514]] 1123 If the pname:pNext chain includes a 1124 slink:VkRenderPassMultiviewCreateInfo structure, and each element of its 1125 pname:pViewMasks member is `0`, the pname:dependencyFlags member of each 1126 element of pname:pDependencies must: not include 1127 ename:VK_DEPENDENCY_VIEW_LOCAL_BIT 1128 * [[VUID-VkRenderPassCreateInfo-pNext-02515]] 1129 If the pname:pNext chain includes a 1130 slink:VkRenderPassMultiviewCreateInfo structure, and each element of its 1131 pname:pViewMasks member is `0`, its pname:correlationMaskCount member 1132 must: be `0` 1133endif::VK_VERSION_1_1,VK_KHR_multiview[] 1134 * [[VUID-VkRenderPassCreateInfo-pDependencies-00837]] 1135 For any element of pname:pDependencies, if the pname:srcSubpass is not 1136 ename:VK_SUBPASS_EXTERNAL, all stage flags included in the 1137 pname:srcStageMask member of that dependency must: be a pipeline stage 1138 supported by the <<synchronization-pipeline-stages-types, pipeline>> 1139 identified by the pname:pipelineBindPoint member of the source subpass 1140 * [[VUID-VkRenderPassCreateInfo-pDependencies-00838]] 1141 For any element of pname:pDependencies, if the pname:dstSubpass is not 1142 ename:VK_SUBPASS_EXTERNAL, all stage flags included in the 1143 pname:dstStageMask member of that dependency must: be a pipeline stage 1144 supported by the <<synchronization-pipeline-stages-types, pipeline>> 1145 identified by the pname:pipelineBindPoint member of the destination 1146 subpass 1147 * [[VUID-VkRenderPassCreateInfo-srcSubpass-02517]] 1148 The pname:srcSubpass member of each element of pname:pDependencies must: 1149 be less than pname:subpassCount 1150 * [[VUID-VkRenderPassCreateInfo-dstSubpass-02518]] 1151 The pname:dstSubpass member of each element of pname:pDependencies must: 1152 be less than pname:subpassCount 1153**** 1154 1155include::{generated}/validity/structs/VkRenderPassCreateInfo.txt[] 1156-- 1157 1158ifdef::VK_QCOM_render_pass_transform[] 1159[open,refpage='VkRenderPassCreateFlagBits',desc='Bitmask specifying additional properties of a render pass',type='enums'] 1160-- 1161Bits which can: be set in slink:VkRenderPassCreateInfo::pname:flags 1162describing additional properties of the render pass are: 1163 1164include::{generated}/api/enums/VkRenderPassCreateFlagBits.txt[] 1165 1166 * ename:VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM specifies that the 1167 created render pass is compatible with 1168 <<vertexpostproc-renderpass-transform, render pass transform>>. 1169-- 1170endif::VK_QCOM_render_pass_transform[] 1171 1172[open,refpage='VkRenderPassCreateFlags',desc='Bitmask of VkRenderPassCreateFlagBits',type='flags'] 1173-- 1174include::{generated}/api/flags/VkRenderPassCreateFlags.txt[] 1175 1176tname:VkRenderPassCreateFlags is a bitmask type for setting a mask of zero 1177or more elink:VkRenderPassCreateFlagBits. 1178-- 1179 1180ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1181[[renderpass-multiview]] 1182[open,refpage='VkRenderPassMultiviewCreateInfo',desc='Structure containing multiview information for all subpasses',type='structs'] 1183-- 1184If the slink:VkRenderPassCreateInfo::pname:pNext chain includes a 1185sname:VkRenderPassMultiviewCreateInfo structure, then that structure 1186includes an array of view masks, view offsets, and correlation masks for the 1187render pass. 1188 1189The sname:VkRenderPassMultiviewCreateInfo structure is defined as: 1190 1191include::{generated}/api/structs/VkRenderPassMultiviewCreateInfo.txt[] 1192 1193ifdef::VK_KHR_multiview[] 1194or the equivalent 1195 1196include::{generated}/api/structs/VkRenderPassMultiviewCreateInfoKHR.txt[] 1197endif::VK_KHR_multiview[] 1198 1199 * pname:sType is the type of this structure. 1200 * pname:pNext is `NULL` or a pointer to a structure extending this 1201 structure. 1202 * pname:subpassCount is zero or the number of subpasses in the render 1203 pass. 1204 * pname:pViewMasks is a pointer to an array of pname:subpassCount view 1205 masks, where each mask is a bitfield of view indices describing which 1206 views rendering is broadcast to in each subpass, when multiview is 1207 enabled. 1208 If pname:subpassCount is zero, each view mask is treated as zero. 1209 * pname:dependencyCount is zero or the number of dependencies in the 1210 render pass. 1211 * pname:pViewOffsets is a pointer to an array of pname:dependencyCount 1212 view offsets, one for each dependency. 1213 If pname:dependencyCount is zero, each dependency's view offset is 1214 treated as zero. 1215 Each view offset controls which views in the source subpass the views in 1216 the destination subpass depend on. 1217 * pname:correlationMaskCount is zero or the number of correlation masks. 1218 * pname:pCorrelationMasks is a pointer to an array of 1219 pname:correlationMaskCount view masks indicating sets of views that may: 1220 be more efficient to render concurrently. 1221 1222When a subpass uses a non-zero view mask, _multiview_ functionality is 1223considered to be enabled. 1224Multiview is all-or-nothing for a render pass - that is, either all 1225subpasses must: have a non-zero view mask (though some subpasses may: have 1226only one view) or all must: be zero. 1227Multiview causes all drawing and clear commands in the subpass to behave as 1228if they were broadcast to each view, where a view is represented by one 1229layer of the framebuffer attachments. 1230All draws and clears are broadcast to each _view index_ whose bit is set in 1231the view mask. 1232The view index is provided in the code:ViewIndex shader input variable, and 1233color, depth/stencil, and input attachments all read/write the layer of the 1234framebuffer corresponding to the view index. 1235 1236If the view mask is zero for all subpasses, multiview is considered to be 1237disabled and all drawing commands execute normally, without this additional 1238broadcasting. 1239 1240Some implementations may: not support multiview in conjunction with 1241<<features-multiview-gs,geometry shaders>> or 1242<<features-multiview-tess,tessellation shaders>>. 1243 1244[[renderpass-multiview-view-local]] 1245When multiview is enabled, the ename:VK_DEPENDENCY_VIEW_LOCAL_BIT bit in a 1246dependency can: be used to express a view-local dependency, meaning that 1247each view in the destination subpass depends on a single view in the source 1248subpass. 1249Unlike pipeline barriers, a subpass dependency can: potentially have a 1250different view mask in the source subpass and the destination subpass. 1251If the dependency is view-local, then each view ([eq]#dstView#) in the 1252destination subpass depends on the view [eq]#dstView {plus} 1253pname:pViewOffsets[dependency]# in the source subpass. 1254If there is not such a view in the source subpass, then this dependency does 1255not affect that view in the destination subpass. 1256If the dependency is not view-local, then all views in the destination 1257subpass depend on all views in the source subpass, and the view offset is 1258ignored. 1259A non-zero view offset is not allowed in a self-dependency. 1260 1261The elements of pname:pCorrelationMasks are a set of masks of views 1262indicating that views in the same mask may: exhibit spatial coherency 1263between the views, making it more efficient to render them concurrently. 1264Correlation masks must: not have a functional effect on the results of the 1265multiview rendering. 1266 1267When multiview is enabled, at the beginning of each subpass all non-render 1268pass state is undefined:. 1269In particular, each time flink:vkCmdBeginRenderPass or 1270flink:vkCmdNextSubpass is called the graphics pipeline must: be bound, any 1271relevant descriptor sets or vertex/index buffers must: be bound, and any 1272relevant dynamic state or push constants must: be set before they are used. 1273 1274ifdef::VK_NVX_multiview_per_view_attributes[] 1275 1276A multiview subpass can: declare that its shaders will write per-view 1277attributes for all views in a single invocation, by setting the 1278ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit in the subpass 1279description. 1280The only supported per-view attributes are position and viewport mask, and 1281per-view position and viewport masks are written to output array variables 1282decorated with code:PositionPerViewNV and code:ViewportMaskPerViewNV, 1283respectively. 1284If `apiext:VK_NV_viewport_array2` is not supported and enabled, 1285code:ViewportMaskPerViewNV must: not be used. 1286Values written to elements of code:PositionPerViewNV and 1287code:ViewportMaskPerViewNV must: not depend on the code:ViewIndex. 1288The shader must: also write to an output variable decorated with 1289code:Position, and the value written to code:Position must: equal the value 1290written to code:PositionPerViewNV[code:ViewIndex]. 1291Similarly, if code:ViewportMaskPerViewNV is written to then the shader must: 1292also write to an output variable decorated with code:ViewportMaskNV, and the 1293value written to code:ViewportMaskNV must: equal the value written to 1294code:ViewportMaskPerViewNV[code:ViewIndex]. 1295Implementations will either use values taken from code:Position and 1296code:ViewportMaskNV and invoke the shader once for each view, or will use 1297values taken from code:PositionPerViewNV and code:ViewportMaskPerViewNV and 1298invoke the shader fewer times. 1299The values written to code:Position and code:ViewportMaskNV must: not depend 1300on the values written to code:PositionPerViewNV and 1301code:ViewportMaskPerViewNV, or vice versa (to allow compilers to eliminate 1302the unused outputs). 1303All attributes that do not have `*PerViewNV` counterparts must: not depend 1304on code:ViewIndex. 1305 1306Per-view attributes are all-or-nothing for a subpass. 1307That is, all pipelines compiled against a subpass that includes the 1308ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit must: write 1309per-view attributes to the `*PerViewNV[]` shader outputs, in addition to the 1310non-per-view (e.g. code:Position) outputs. 1311Pipelines compiled against a subpass that does not include this bit must: 1312not include the `*PerViewNV[]` outputs in their interfaces. 1313 1314endif::VK_NVX_multiview_per_view_attributes[] 1315 1316.Valid Usage 1317**** 1318 * [[VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-00841]] 1319 Each view index must: not be set in more than one element of 1320 pname:pCorrelationMasks 1321**** 1322 1323include::{generated}/validity/structs/VkRenderPassMultiviewCreateInfo.txt[] 1324-- 1325endif::VK_VERSION_1_1,VK_KHR_multiview[] 1326 1327ifdef::VK_NVX_multiview_per_view_attributes[] 1328ifdef::VK_KHR_dynamic_rendering[] 1329 1330[open,refpage='VkMultiviewPerViewAttributesInfoNVX',desc='Structure specifying the multiview per-attribute properties',type='structs'] 1331-- 1332 1333The sname:VkMultiviewPerViewAttributesInfoNVX structure is defined as: 1334 1335include::{generated}/api/structs/VkMultiviewPerViewAttributesInfoNVX.txt[] 1336 1337 * pname:sType is the type of this structure. 1338 * pname:pNext is `NULL` or a pointer to a structure extending this 1339 structure. 1340 * pname:perViewAttributes specifies that shaders compiled for this 1341 pipeline write the attributes for all views in a single invocation of 1342 each vertex processing stage. 1343 All pipelines executed within a render pass instance that includes this 1344 bit must: write per-view attributes to the `*PerViewNV[]` shader 1345 outputs, in addition to the non-per-view (e.g. code:Position) outputs. 1346 * pname:perViewAttributesPositionXOnly specifies that shaders compiled for 1347 this pipeline use per-view positions which only differ in value in the x 1348 component. 1349 Per-view viewport mask can: also be used. 1350 1351When dynamic render pass instances are being used, instead of specifying 1352ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX or 1353ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX in the subpass 1354description flags, the per-attibute properties of the render pass instance 1355must: be specified by the sname:VkMultiviewPerViewAttributesInfoNVX 1356structure Include the sname:VkMultiviewPerViewAttributesInfoNVX structure in 1357the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo when creating a 1358graphics pipeline for dynamic rendering, slink:VkRenderingInfoKHR when 1359starting a dynamic render pass instance, and 1360slink:VkCommandBufferInheritanceInfo when specifying the dynamic render pass 1361instance parameters for secondary command buffers. 1362 1363.Valid Usage 1364**** 1365 * [[VUID-VkMultiviewPerViewAttributesInfoNVX-perViewAttributesPositionXOnly-06163]] 1366 If pname:perViewAttributesPositionXOnly is ename:VK_TRUE then 1367 pname:perViewAttributes must: also be ename:VK_TRUE 1368**** 1369 1370include::{generated}/validity/structs/VkMultiviewPerViewAttributesInfoNVX.txt[] 1371-- 1372endif::VK_KHR_dynamic_rendering[] 1373endif::VK_NVX_multiview_per_view_attributes[] 1374 1375ifdef::VK_EXT_fragment_density_map[] 1376[[renderpass-fragmentdensitymapattachment]] 1377[open,refpage='VkRenderPassFragmentDensityMapCreateInfoEXT',desc='Structure containing fragment density map attachment for render pass',type='structs'] 1378-- 1379If the slink:VkRenderPassCreateInfo::pname:pNext chain includes a 1380sname:VkRenderPassFragmentDensityMapCreateInfoEXT structure, then that 1381structure includes a fragment density map attachment for the render pass. 1382 1383The sname:VkRenderPassFragmentDensityMapCreateInfoEXT structure is defined 1384as: 1385 1386include::{generated}/api/structs/VkRenderPassFragmentDensityMapCreateInfoEXT.txt[] 1387 1388 * pname:sType is the type of this structure. 1389 * pname:pNext is `NULL` or a pointer to a structure extending this 1390 structure. 1391 * pname:fragmentDensityMapAttachment is the fragment density map to use 1392 for the render pass. 1393 1394The fragment density map is read at an implementation-dependent time with 1395the following constraints determined by the attachment's image view 1396pname:flags: 1397 1398 * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT 1399 specifies that the fragment density map will be read by the device 1400 during ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT 1401ifdef::VK_EXT_fragment_density_map2[] 1402 * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT 1403 specifies that the fragment density map will be read by the host during 1404 flink:vkEndCommandBuffer of the primary command buffer that the render 1405 pass is recorded into 1406endif::VK_EXT_fragment_density_map2[] 1407 * Otherwise the fragment density map will be read by the host during 1408 flink:vkCmdBeginRenderPass 1409 1410The fragment density map may: additionally be read by the device during 1411ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT for any mode. 1412 1413If this structure is not present, it is as if 1414pname:fragmentDensityMapAttachment was given as ename:VK_ATTACHMENT_UNUSED. 1415 1416.Valid Usage 1417**** 1418 * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02548]] 1419 If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, 1420 pname:fragmentDensityMapAttachment must: not be an element of 1421 sname:VkSubpassDescription::pname:pInputAttachments, 1422 sname:VkSubpassDescription::pname:pColorAttachments, 1423 sname:VkSubpassDescription::pname:pResolveAttachments, 1424 sname:VkSubpassDescription::pname:pDepthStencilAttachment, or 1425 sname:VkSubpassDescription::pname:pPreserveAttachments for any subpass 1426 * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02549]] 1427 If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, 1428 pname:layout must: be equal to 1429 ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT, or 1430 ename:VK_IMAGE_LAYOUT_GENERAL 1431 * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02550]] 1432 If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, 1433 pname:fragmentDensityMapAttachment must: reference an attachment with a 1434 pname:loadOp equal to ename:VK_ATTACHMENT_LOAD_OP_LOAD or 1435 ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE 1436 * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02551]] 1437 If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, 1438 pname:fragmentDensityMapAttachment must: reference an attachment with a 1439 pname:storeOp equal to ename:VK_ATTACHMENT_STORE_OP_DONT_CARE 1440**** 1441 1442include::{generated}/validity/structs/VkRenderPassFragmentDensityMapCreateInfoEXT.txt[] 1443-- 1444endif::VK_EXT_fragment_density_map[] 1445 1446[open,refpage='VkAttachmentDescription',desc='Structure specifying an attachment description',type='structs'] 1447-- 1448The sname:VkAttachmentDescription structure is defined as: 1449 1450include::{generated}/api/structs/VkAttachmentDescription.txt[] 1451 1452 * pname:flags is a bitmask of elink:VkAttachmentDescriptionFlagBits 1453 specifying additional properties of the attachment. 1454 * pname:format is a elink:VkFormat value specifying the format of the 1455 image view that will be used for the attachment. 1456 * pname:samples is a elink:VkSampleCountFlagBits value specifying the 1457 number of samples of the image. 1458 * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the 1459 contents of color and depth components of the attachment are treated at 1460 the beginning of the subpass where it is first used. 1461 * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the 1462 contents of color and depth components of the attachment are treated at 1463 the end of the subpass where it is last used. 1464 * pname:stencilLoadOp is a elink:VkAttachmentLoadOp value specifying how 1465 the contents of stencil components of the attachment are treated at the 1466 beginning of the subpass where it is first used. 1467 * pname:stencilStoreOp is a elink:VkAttachmentStoreOp value specifying how 1468 the contents of stencil components of the attachment are treated at the 1469 end of the last subpass where it is used. 1470 * pname:initialLayout is the layout the attachment image subresource will 1471 be in when a render pass instance begins. 1472 * pname:finalLayout is the layout the attachment image subresource will be 1473 transitioned to when a render pass instance ends. 1474 1475[[renderpass-load-store-ops]] 1476If the attachment uses a color format, then pname:loadOp and pname:storeOp 1477are used, and pname:stencilLoadOp and pname:stencilStoreOp are ignored. 1478If the format has depth and/or stencil components, pname:loadOp and 1479pname:storeOp apply only to the depth data, while pname:stencilLoadOp and 1480pname:stencilStoreOp define how the stencil data is handled. 1481pname:loadOp and pname:stencilLoadOp define the _load operations_ that 1482execute as part of the first subpass that uses the attachment. 1483pname:storeOp and pname:stencilStoreOp define the _store operations_ that 1484execute as part of the last subpass that uses the attachment. 1485 1486The load operation for each sample in an attachment happens-before any 1487recorded command which accesses the sample in the first subpass where the 1488attachment is used. 1489Load operations for attachments with a depth/stencil format execute in the 1490ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage. 1491Load operations for attachments with a color format execute in the 1492ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 1493 1494The store operation for each sample in an attachment happens-after any 1495recorded command which accesses the sample in the last subpass where the 1496attachment is used. 1497Store operations for attachments with a depth/stencil format execute in the 1498ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage. 1499Store operations for attachments with a color format execute in the 1500ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. 1501 1502If an attachment is not used by any subpass, then pname:loadOp, 1503pname:storeOp, pname:stencilStoreOp, and pname:stencilLoadOp are ignored, 1504and the attachment's memory contents will not be modified by execution of a 1505render pass instance. 1506 1507ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1508 1509The load and store operations apply on the first and last use of each view 1510in the render pass, respectively. 1511If a view index of an attachment is not included in the view mask in any 1512subpass that uses it, then the load and store operations are ignored, and 1513the attachment's memory contents will not be modified by execution of a 1514render pass instance. 1515 1516endif::VK_VERSION_1_1,VK_KHR_multiview[] 1517 1518[[renderpass-precision]] 1519During a render pass instance, input/color attachments with color formats 1520that have a component size of 8, 16, or 32 bits must: be represented in the 1521attachment's format throughout the instance. 1522Attachments with other floating- or fixed-point color formats, or with depth 1523components may: be represented in a format with a precision higher than the 1524attachment format, but must: be represented with the same range. 1525When such a component is loaded via the pname:loadOp, it will be converted 1526into an implementation-dependent format used by the render pass. 1527Such components must: be converted from the render pass format, to the 1528format of the attachment, before they are resolved or stored at the end of a 1529render pass instance via pname:storeOp. 1530Conversions occur as described in <<fundamentals-numerics,Numeric 1531Representation and Computation>> and <<fundamentals-fixedconv, Fixed-Point 1532Data Conversions>>. 1533 1534[[renderpass-aliasing]] 1535If pname:flags includes ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then 1536the attachment is treated as if it shares physical memory with another 1537attachment in the same render pass. 1538This information limits the ability of the implementation to reorder certain 1539operations (like layout transitions and the pname:loadOp) such that it is 1540not improperly reordered against other uses of the same physical memory via 1541a different attachment. 1542This is described in more detail below. 1543 1544If a render pass uses multiple attachments that alias the same device 1545memory, those attachments must: each include the 1546ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment 1547description flags. 1548Attachments aliasing the same memory occurs in multiple ways: 1549 1550 * Multiple attachments being assigned the same image view as part of 1551 framebuffer creation. 1552 * Attachments using distinct image views that correspond to the same image 1553 subresource of an image. 1554 * Attachments using views of distinct image subresources which are bound 1555 to overlapping memory ranges. 1556 1557[NOTE] 1558.Note 1559==== 1560Render passes must: include subpass dependencies (either directly or via a 1561subpass dependency chain) between any two subpasses that operate on the same 1562attachment or aliasing attachments and those subpass dependencies must: 1563include execution and memory dependencies separating uses of the aliases, if 1564at least one of those subpasses writes to one of the aliases. 1565These dependencies must: not include the ename:VK_DEPENDENCY_BY_REGION_BIT 1566if the aliases are views of distinct image subresources which overlap in 1567memory. 1568==== 1569 1570Multiple attachments that alias the same memory must: not be used in a 1571single subpass. 1572A given attachment index must: not be used multiple times in a single 1573subpass, with one exception: two subpass attachments can: use the same 1574attachment index if at least one use is as an input attachment and neither 1575use is as a resolve or preserve attachment. 1576In other words, the same view can: be used simultaneously as an input and 1577color or depth/stencil attachment, but must: not be used as multiple color 1578or depth/stencil attachments nor as resolve or preserve attachments. 1579The precise set of valid scenarios is described in more detail 1580<<renderpass-feedbackloop, below>>. 1581 1582If a set of attachments alias each other, then all except the first to be 1583used in the render pass must: use an pname:initialLayout of 1584ename:VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases 1585make their contents undefined:. 1586Once an alias has been used and a different alias has been used after it, 1587the first alias must: not be used in any later subpasses. 1588However, an application can: assign the same image view to multiple aliasing 1589attachment indices, which allows that image view to be used multiple times 1590even if other aliases are used in between. 1591 1592[NOTE] 1593.Note 1594==== 1595Once an attachment needs the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT 1596bit, there should: be no additional cost of introducing additional aliases, 1597and using these additional aliases may: allow more efficient clearing of the 1598attachments on multiple uses via ename:VK_ATTACHMENT_LOAD_OP_CLEAR. 1599==== 1600 1601.Valid Usage 1602**** 1603 * [[VUID-VkAttachmentDescription-finalLayout-00843]] 1604 pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or 1605 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 1606 * [[VUID-VkAttachmentDescription-format-03280]] 1607 If pname:format is a color format, pname:initialLayout must: not be 1608 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, 1609 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 1610 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or 1611 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 1612 * [[VUID-VkAttachmentDescription-format-03281]] 1613 If pname:format is a depth/stencil format, pname:initialLayout must: not 1614 be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 1615 * [[VUID-VkAttachmentDescription-format-03282]] 1616 If pname:format is a color format, pname:finalLayout must: not be 1617 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, 1618 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 1619 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or 1620 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 1621 * [[VUID-VkAttachmentDescription-format-03283]] 1622 If pname:format is a depth/stencil format, pname:finalLayout must: not 1623 be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 1624ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 1625 * [[VUID-VkAttachmentDescription-separateDepthStencilLayouts-03284]] 1626 If the <<features-separateDepthStencilLayouts, 1627 pname:separateDepthStencilLayouts>> feature is not enabled, 1628 pname:initialLayout must: not be 1629 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 1630 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 1631 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 1632 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 1633 * [[VUID-VkAttachmentDescription-separateDepthStencilLayouts-03285]] 1634 If the <<features-separateDepthStencilLayouts, 1635 pname:separateDepthStencilLayouts>> feature is not enabled, 1636 pname:finalLayout must: not be 1637 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 1638 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 1639 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 1640 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 1641 * [[VUID-VkAttachmentDescription-format-03286]] 1642 If pname:format is a color format, pname:initialLayout must: not be 1643 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 1644 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 1645 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 1646 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 1647 * [[VUID-VkAttachmentDescription-format-03287]] 1648 If pname:format is a color format, pname:finalLayout must: not be 1649 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 1650 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 1651 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 1652 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 1653 * [[VUID-VkAttachmentDescription-format-03288]] 1654 If pname:format is a depth/stencil format which includes both depth and 1655 stencil aspects, pname:initialLayout must: not be 1656 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 1657 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 1658 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 1659 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 1660 * [[VUID-VkAttachmentDescription-format-03289]] 1661 If pname:format is a depth/stencil format which includes both depth and 1662 stencil aspects, pname:finalLayout must: not be 1663 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 1664 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 1665 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 1666 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 1667 * [[VUID-VkAttachmentDescription-format-03290]] 1668 If pname:format is a depth/stencil format which includes only the depth 1669 aspect, pname:initialLayout must: not be 1670 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 1671 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 1672 * [[VUID-VkAttachmentDescription-format-03291]] 1673 If pname:format is a depth/stencil format which includes only the depth 1674 aspect, pname:finalLayout must: not be 1675 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 1676 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 1677 * [[VUID-VkAttachmentDescription-format-03292]] 1678 If pname:format is a depth/stencil format which includes only the 1679 stencil aspect, pname:initialLayout must: not be 1680 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or 1681 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL 1682 * [[VUID-VkAttachmentDescription-format-03293]] 1683 If pname:format is a depth/stencil format which includes only the 1684 stencil aspect, pname:finalLayout must: not be 1685 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or 1686 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL 1687endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 1688**** 1689 1690include::{generated}/validity/structs/VkAttachmentDescription.txt[] 1691-- 1692 1693[open,refpage='VkAttachmentDescriptionFlagBits',desc='Bitmask specifying additional properties of an attachment',type='enums'] 1694-- 1695Bits which can: be set in slink:VkAttachmentDescription::pname:flags 1696describing additional properties of the attachment are: 1697 1698include::{generated}/api/enums/VkAttachmentDescriptionFlagBits.txt[] 1699 1700 * ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT specifies that the 1701 attachment aliases the same device memory as other attachments. 1702-- 1703 1704[open,refpage='VkAttachmentDescriptionFlags',desc='Bitmask of VkAttachmentDescriptionFlagBits',type='flags'] 1705-- 1706include::{generated}/api/flags/VkAttachmentDescriptionFlags.txt[] 1707 1708tname:VkAttachmentDescriptionFlags is a bitmask type for setting a mask of 1709zero or more elink:VkAttachmentDescriptionFlagBits. 1710-- 1711 1712[open,refpage='VkAttachmentLoadOp',desc='Specify how contents of an attachment are treated at the beginning of a subpass',type='enums'] 1713-- 1714Possible values of slink:VkAttachmentDescription::pname:loadOp and 1715pname:stencilLoadOp, specifying how the contents of the attachment are 1716treated, are: 1717 1718include::{generated}/api/enums/VkAttachmentLoadOp.txt[] 1719 1720 * ename:VK_ATTACHMENT_LOAD_OP_LOAD specifies that the previous contents of 1721 the image within the render area will be preserved. 1722 For attachments with a depth/stencil format, this uses the access type 1723 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT. 1724 For attachments with a color format, this uses the access type 1725 ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT. 1726 * ename:VK_ATTACHMENT_LOAD_OP_CLEAR specifies that the contents within the 1727 render area will be cleared to a uniform value, which is specified when 1728 a render pass instance is begun. 1729 For attachments with a depth/stencil format, this uses the access type 1730 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 1731 For attachments with a color format, this uses the access type 1732 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 1733 * ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE specifies that the previous 1734 contents within the area need not be preserved; the contents of the 1735 attachment will be undefined: inside the render area. 1736 For attachments with a depth/stencil format, this uses the access type 1737 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 1738 For attachments with a color format, this uses the access type 1739 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 1740ifdef::VK_EXT_load_store_op_none[] 1741 * ename:VK_ATTACHMENT_LOAD_OP_NONE_EXT specifies that the previous 1742 contents of the image within the render area will be preserved, but the 1743 contents of the attachment will be undefined: inside the render pass. 1744 No access type is used as the image is not accessed. 1745endif::VK_EXT_load_store_op_none[] 1746-- 1747 1748[open,refpage='VkAttachmentStoreOp',desc='Specify how contents of an attachment are treated at the end of a subpass',type='enums'] 1749-- 1750Possible values of slink:VkAttachmentDescription::pname:storeOp and 1751pname:stencilStoreOp, specifying how the contents of the attachment are 1752treated, are: 1753 1754include::{generated}/api/enums/VkAttachmentStoreOp.txt[] 1755 1756 * ename:VK_ATTACHMENT_STORE_OP_STORE specifies the contents generated 1757 during the render pass and within the render area are written to memory. 1758 For attachments with a depth/stencil format, this uses the access type 1759 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 1760 For attachments with a color format, this uses the access type 1761 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 1762 * ename:VK_ATTACHMENT_STORE_OP_DONT_CARE specifies the contents within the 1763 render area are not needed after rendering, and may: be discarded; the 1764 contents of the attachment will be undefined: inside the render area. 1765 For attachments with a depth/stencil format, this uses the access type 1766 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 1767 For attachments with a color format, this uses the access type 1768 ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 1769ifdef::VK_EXT_load_store_op_none,VK_KHR_dynamic_rendering,VK_QCOM_render_pass_store_ops[] 1770 * ename:VK_ATTACHMENT_STORE_OP_NONE_KHR specifies the contents within the 1771 render area are not accessed by the store operation. 1772 However, if the attachment was written to during the render pass, the 1773 contents of the attachment will be undefined: inside the render area. 1774endif::VK_EXT_load_store_op_none,VK_KHR_dynamic_rendering,VK_QCOM_render_pass_store_ops[] 1775 1776[NOTE] 1777.Note 1778==== 1779ename:VK_ATTACHMENT_STORE_OP_DONT_CARE can: cause contents generated during 1780previous render passes to be discarded before reaching memory, even if no 1781write to the attachment occurs during the current render pass. 1782==== 1783-- 1784 1785ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 1786[open,refpage='VkRenderPassInputAttachmentAspectCreateInfo',desc='Structure specifying, for a given subpass/input attachment pair, which aspect can: be read.',type='structs'] 1787-- 1788The sname:VkRenderPassInputAttachmentAspectCreateInfo structure is defined 1789as: 1790 1791include::{generated}/api/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[] 1792 1793ifdef::VK_KHR_maintenance2[] 1794or the equivalent 1795 1796include::{generated}/api/structs/VkRenderPassInputAttachmentAspectCreateInfoKHR.txt[] 1797endif::VK_KHR_maintenance2[] 1798 1799 * pname:sType is the type of this structure. 1800 * pname:pNext is `NULL` or a pointer to a structure extending this 1801 structure. 1802 * pname:aspectReferenceCount is the number of elements in the 1803 pname:pAspectReferences array. 1804 * pname:pAspectReferences is a pointer to an array of 1805 pname:aspectReferenceCount slink:VkInputAttachmentAspectReference 1806 structures containing a mask describing which aspect(s) can: be accessed 1807 for a given input attachment within a given subpass. 1808 1809To specify which aspects of an input attachment can: be read, add a 1810slink:VkRenderPassInputAttachmentAspectCreateInfo structure to the 1811pname:pNext chain of the slink:VkRenderPassCreateInfo structure: 1812 1813An application can: access any aspect of an input attachment that does not 1814have a specified aspect mask in the pname:pAspectReferences array. 1815Otherwise, an application must: not access aspect(s) of an input attachment 1816other than those in its specified aspect mask. 1817 1818include::{generated}/validity/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[] 1819-- 1820 1821[open,refpage='VkInputAttachmentAspectReference',desc='Structure specifying a subpass/input attachment pair and an aspect mask that can: be read.',type='structs'] 1822-- 1823The sname:VkInputAttachmentAspectReference structure is defined as: 1824 1825include::{generated}/api/structs/VkInputAttachmentAspectReference.txt[] 1826 1827ifdef::VK_KHR_maintenance2[] 1828or the equivalent 1829 1830include::{generated}/api/structs/VkInputAttachmentAspectReferenceKHR.txt[] 1831endif::VK_KHR_maintenance2[] 1832 1833 * pname:subpass is an index into the pname:pSubpasses array of the parent 1834 sname:VkRenderPassCreateInfo structure. 1835 * pname:inputAttachmentIndex is an index into the pname:pInputAttachments 1836 of the specified subpass. 1837 * pname:aspectMask is a mask of which aspect(s) can: be accessed within 1838 the specified subpass. 1839 1840This structure specifies an aspect mask for a specific input attachment of a 1841specific subpass in the render pass. 1842 1843pname:subpass and pname:inputAttachmentIndex index into the render pass as: 1844 1845[source,c] 1846~~~~ 1847pCreateInfo->pSubpasses[subpass].pInputAttachments[inputAttachmentIndex] 1848~~~~ 1849 1850.Valid Usage 1851**** 1852 * [[VUID-VkInputAttachmentAspectReference-aspectMask-01964]] 1853 pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT 1854ifdef::VK_EXT_image_drm_format_modifier[] 1855 * [[VUID-VkInputAttachmentAspectReference-aspectMask-02250]] 1856 pname:aspectMask must: not include 1857 `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ 1858endif::VK_EXT_image_drm_format_modifier[] 1859**** 1860 1861include::{generated}/validity/structs/VkInputAttachmentAspectReference.txt[] 1862-- 1863endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 1864 1865[open,refpage='VkSubpassDescription',desc='Structure specifying a subpass description',type='structs'] 1866-- 1867The sname:VkSubpassDescription structure is defined as: 1868 1869include::{generated}/api/structs/VkSubpassDescription.txt[] 1870 1871 * pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits 1872 specifying usage of the subpass. 1873 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying 1874 the pipeline type supported for this subpass. 1875 * pname:inputAttachmentCount is the number of input attachments. 1876 * pname:pInputAttachments is a pointer to an array of 1877 slink:VkAttachmentReference structures defining the input attachments 1878 for this subpass and their layouts. 1879 * pname:colorAttachmentCount is the number of color attachments. 1880 * pname:pColorAttachments is a pointer to an array of 1881 pname:colorAttachmentCount slink:VkAttachmentReference structures 1882 defining the color attachments for this subpass and their layouts. 1883 * pname:pResolveAttachments is `NULL` or a pointer to an array of 1884 pname:colorAttachmentCount slink:VkAttachmentReference structures 1885 defining the resolve attachments for this subpass and their layouts. 1886 * pname:pDepthStencilAttachment is a pointer to a 1887 slink:VkAttachmentReference structure specifying the depth/stencil 1888 attachment for this subpass and its layout. 1889 * pname:preserveAttachmentCount is the number of preserved attachments. 1890 * pname:pPreserveAttachments is a pointer to an array of 1891 pname:preserveAttachmentCount render pass attachment indices identifying 1892 attachments that are not used by this subpass, but whose contents must: 1893 be preserved throughout the subpass. 1894 1895Each element of the pname:pInputAttachments array corresponds to an input 1896attachment index in a fragment shader, i.e. if a shader declares an image 1897variable decorated with a code:InputAttachmentIndex value of *X*, then it 1898uses the attachment provided in pname:pInputAttachments[*X*]. 1899Input attachments must: also be bound to the pipeline in a descriptor set. 1900If the pname:attachment member of any element of pname:pInputAttachments is 1901ename:VK_ATTACHMENT_UNUSED, the application must: not read from the 1902corresponding input attachment index. 1903Fragment shaders can: use subpass input variables to access the contents of 1904an input attachment at the fragment's (x, y, layer) framebuffer coordinates. 1905ifdef::VK_QCOM_render_pass_transform[] 1906Input attachments must: not be used by any subpasses within a render pass 1907that enables <<vertexpostproc-renderpass-transform, render pass transform>>. 1908endif::VK_QCOM_render_pass_transform[] 1909 1910Each element of the pname:pColorAttachments array corresponds to an output 1911location in the shader, i.e. if the shader declares an output variable 1912decorated with a code:Location value of *X*, then it uses the attachment 1913provided in pname:pColorAttachments[*X*]. 1914If the pname:attachment member of any element of pname:pColorAttachments is 1915ename:VK_ATTACHMENT_UNUSED, 1916ifdef::VK_EXT_color_write_enable[] 1917or if <<framebuffer-color-write-enable,Color Write Enable>> has been 1918disabled for the corresponding attachment index, 1919endif::VK_EXT_color_write_enable[] 1920then writes to the corresponding location by a fragment shader are 1921discarded. 1922 1923If 1924ifdef::VK_QCOM_render_pass_shader_resolve[] 1925pname:flags does not include 1926ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if 1927endif::VK_QCOM_render_pass_shader_resolve[] 1928pname:pResolveAttachments is not `NULL`, each of its elements corresponds to 1929a color attachment (the element in pname:pColorAttachments at the same 1930index), and a multisample resolve operation is defined for each attachment. 1931At the end of each subpass, multisample resolve operations read the 1932subpass's color attachments, and resolve the samples for each pixel within 1933the render area to the same pixel location in the corresponding resolve 1934attachments, unless the resolve attachment index is 1935ename:VK_ATTACHMENT_UNUSED. 1936 1937ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1938Similarly, if 1939ifdef::VK_QCOM_render_pass_shader_resolve[] 1940pname:flags does not include 1941ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and 1942endif::VK_QCOM_render_pass_shader_resolve[] 1943slink:VkSubpassDescriptionDepthStencilResolve::pname:pDepthStencilResolveAttachment 1944is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, it 1945corresponds to the depth/stencil attachment in 1946pname:pDepthStencilAttachment, and multisample resolve operations for depth 1947and stencil are defined by 1948slink:VkSubpassDescriptionDepthStencilResolve::pname:depthResolveMode and 1949slink:VkSubpassDescriptionDepthStencilResolve::pname:stencilResolveMode, 1950respectively. 1951At the end of each subpass, multisample resolve operations read the 1952subpass's depth/stencil attachment, and resolve the samples for each pixel 1953to the same pixel location in the corresponding resolve attachment. 1954If slink:VkSubpassDescriptionDepthStencilResolve::pname:depthResolveMode is 1955ename:VK_RESOLVE_MODE_NONE, then the depth component of the resolve 1956attachment is not written to and its contents are preserved. 1957Similarly, if 1958slink:VkSubpassDescriptionDepthStencilResolve::pname:stencilResolveMode is 1959ename:VK_RESOLVE_MODE_NONE, then the stencil component of the resolve 1960attachment is not written to and its contents are preserved. 1961slink:VkSubpassDescriptionDepthStencilResolve::pname:depthResolveMode is 1962ignored if the elink:VkFormat of the pname:pDepthStencilResolveAttachment 1963does not have a depth component. 1964Similarly, 1965slink:VkSubpassDescriptionDepthStencilResolve::pname:stencilResolveMode is 1966ignored if the elink:VkFormat of the pname:pDepthStencilResolveAttachment 1967does not have a stencil component. 1968 1969ifdef::VK_EXT_sample_locations[] 1970If the image subresource range referenced by the depth/stencil attachment is 1971created with 1972ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT, then the 1973multisample resolve operation uses the sample locations state specified in 1974the pname:sampleLocationsInfo member of the element of the 1975sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pPostSubpassSampleLocations 1976for the subpass. 1977endif::VK_EXT_sample_locations[] 1978 1979endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 1980 1981If pname:pDepthStencilAttachment is `NULL`, or if its attachment index is 1982ename:VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil attachment 1983will be used in the subpass. 1984 1985The contents of an attachment within the render area become undefined: at 1986the start of a subpass *S* if all of the following conditions are true: 1987 1988 * The attachment is used as a color, depth/stencil, or resolve attachment 1989 in any subpass in the render pass. 1990 * There is a subpass *S~1~* that uses or preserves the attachment, and a 1991 subpass dependency from *S~1~* to *S*. 1992 * The attachment is not used or preserved in subpass *S*. 1993 1994ifdef::VK_QCOM_render_pass_shader_resolve[] 1995In addition, the contents of an attachment within the render area become 1996undefined: at the start of a subpass *S* if all of the following conditions 1997are true: 1998 1999 * ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM is set. 2000 * The attachment is used as a color or depth/stencil in the subpass. 2001endif::VK_QCOM_render_pass_shader_resolve[] 2002 2003Once the contents of an attachment become undefined: in subpass *S*, they 2004remain undefined: for subpasses in subpass dependency chains starting with 2005subpass *S* until they are written again. 2006However, they remain valid for subpasses in other subpass dependency chains 2007starting with subpass *S~1~* if those subpasses use or preserve the 2008attachment. 2009 2010.Valid Usage 2011**** 2012ifndef::VK_HUAWEI_subpass_shading[] 2013 * [[VUID-VkSubpassDescription-pipelineBindPoint-00844]] 2014 pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS 2015endif::VK_HUAWEI_subpass_shading[] 2016ifdef::VK_HUAWEI_subpass_shading[] 2017 * [[VUID-VkSubpassDescription-pipelineBindPoint-04952]] 2018 pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS 2019 or ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI 2020endif::VK_HUAWEI_subpass_shading[] 2021 * [[VUID-VkSubpassDescription-colorAttachmentCount-00845]] 2022 pname:colorAttachmentCount must: be less than or equal to 2023 sname:VkPhysicalDeviceLimits::pname:maxColorAttachments 2024 * [[VUID-VkSubpassDescription-loadOp-00846]] 2025 If the first use of an attachment in this render pass is as an input 2026 attachment, and the attachment is not also used as a color or 2027 depth/stencil attachment in the same subpass, then pname:loadOp must: 2028 not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR 2029 * [[VUID-VkSubpassDescription-pResolveAttachments-00847]] 2030 If pname:pResolveAttachments is not `NULL`, for each resolve attachment 2031 that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color 2032 attachment must: not be ename:VK_ATTACHMENT_UNUSED 2033 * [[VUID-VkSubpassDescription-pResolveAttachments-00848]] 2034 If pname:pResolveAttachments is not `NULL`, for each resolve attachment 2035 that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color 2036 attachment must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT 2037 * [[VUID-VkSubpassDescription-pResolveAttachments-00849]] 2038 If pname:pResolveAttachments is not `NULL`, each resolve attachment that 2039 is not ename:VK_ATTACHMENT_UNUSED must: have a sample count of 2040 ename:VK_SAMPLE_COUNT_1_BIT 2041 * [[VUID-VkSubpassDescription-pResolveAttachments-00850]] 2042 If pname:pResolveAttachments is not `NULL`, each resolve attachment that 2043 is not ename:VK_ATTACHMENT_UNUSED must: have the same elink:VkFormat as 2044 its corresponding color attachment 2045 * [[VUID-VkSubpassDescription-pColorAttachments-01417]] 2046 All attachments in pname:pColorAttachments that are not 2047 ename:VK_ATTACHMENT_UNUSED must: have the same sample count 2048 * [[VUID-VkSubpassDescription-pInputAttachments-02647]] 2049 All attachments in pname:pInputAttachments that are not 2050 ename:VK_ATTACHMENT_UNUSED must: have image formats whose 2051 <<potential-format-features, potential format features>> contain at 2052 least ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or 2053 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 2054 * [[VUID-VkSubpassDescription-pColorAttachments-02648]] 2055 All attachments in pname:pColorAttachments that are not 2056 ename:VK_ATTACHMENT_UNUSED must: have image formats whose 2057 <<potential-format-features, potential format features>> contain 2058 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 2059 * [[VUID-VkSubpassDescription-pResolveAttachments-02649]] 2060 All attachments in pname:pResolveAttachments that are not 2061 ename:VK_ATTACHMENT_UNUSED must: have image formats whose 2062 <<potential-format-features, potential format features>> contain 2063 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 2064 * [[VUID-VkSubpassDescription-pDepthStencilAttachment-02650]] 2065 If pname:pDepthStencilAttachment is not `NULL` and the attachment is not 2066 ename:VK_ATTACHMENT_UNUSED then it must: have an image format whose 2067 <<potential-format-features, potential format features>> contain 2068 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 2069ifdef::VK_AMD_mixed_attachment_samples[] 2070 * [[VUID-VkSubpassDescription-pColorAttachments-01506]] 2071 If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, 2072 and all attachments in pname:pColorAttachments that are not 2073 ename:VK_ATTACHMENT_UNUSED must: have a sample count that is smaller 2074 than or equal to the sample count of pname:pDepthStencilAttachment if it 2075 is not ename:VK_ATTACHMENT_UNUSED 2076endif::VK_AMD_mixed_attachment_samples[] 2077 * [[VUID-VkSubpassDescription-pDepthStencilAttachment-01418]] 2078 If neither the `apiext:VK_AMD_mixed_attachment_samples` nor the 2079 `apiext:VK_NV_framebuffer_mixed_samples` extensions are enabled, and if 2080 pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and any 2081 attachments in pname:pColorAttachments are not 2082 ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count 2083 * [[VUID-VkSubpassDescription-attachment-00853]] 2084 Each element of pname:pPreserveAttachments must: not be 2085 ename:VK_ATTACHMENT_UNUSED 2086 * [[VUID-VkSubpassDescription-pPreserveAttachments-00854]] 2087 Each element of pname:pPreserveAttachments must: not also be an element 2088 of any other member of the subpass description 2089 * [[VUID-VkSubpassDescription-layout-02519]] 2090 If any attachment is used by more than one slink:VkAttachmentReference 2091 member, then each use must: use the same pname:layout 2092 * [[VUID-VkSubpassDescription-None-04437]] 2093 Each attachment must: follow the <<attachment-type-imagelayout, image 2094 layout requirements>> specified for its attachment type 2095ifdef::VK_NVX_multiview_per_view_attributes[] 2096 * [[VUID-VkSubpassDescription-flags-00856]] 2097 If pname:flags includes 2098 ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must: 2099 also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX 2100endif::VK_NVX_multiview_per_view_attributes[] 2101ifdef::VK_QCOM_render_pass_shader_resolve[] 2102 * [[VUID-VkSubpassDescription-flags-03341]] 2103 If pname:flags includes 2104 ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if 2105 pname:pResolveAttachments is not `NULL`, then each resolve attachment 2106 must: be ename:VK_ATTACHMENT_UNUSED 2107 * [[VUID-VkSubpassDescription-flags-03343]] 2108 If pname:flags includes 2109 ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass 2110 must: be the last subpass in a subpass dependency chain 2111endif::VK_QCOM_render_pass_shader_resolve[] 2112ifdef::VK_QCOM_render_pass_transform[] 2113 * [[VUID-VkSubpassDescription-pInputAttachments-02868]] 2114 If the render pass is created with 2115 ename:VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM each of the elements of 2116 pname:pInputAttachments must: be ename:VK_ATTACHMENT_UNUSED 2117endif::VK_QCOM_render_pass_transform[] 2118 * [[VUID-VkSubpassDescription-pDepthStencilAttachment-04438]] 2119 pname:pDepthStencilAttachment and pname:pColorAttachments must not 2120 contain references to the same attachment 2121**** 2122 2123include::{generated}/validity/structs/VkSubpassDescription.txt[] 2124-- 2125 2126[open,refpage='VkSubpassDescriptionFlagBits',desc='Bitmask specifying usage of a subpass',type='enums'] 2127-- 2128Bits which can: be set in slink:VkSubpassDescription::pname:flags, 2129specifying usage of the subpass, are: 2130 2131include::{generated}/api/enums/VkSubpassDescriptionFlagBits.txt[] 2132 2133ifdef::VK_NVX_multiview_per_view_attributes[] 2134 * ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX specifies that 2135 shaders compiled for this subpass write the attributes for all views in 2136 a single invocation of each 2137 <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 2138 stage>>. 2139 All pipelines compiled against a subpass that includes this bit must: 2140 write per-view attributes to the `*PerViewNV[]` shader outputs, in 2141 addition to the non-per-view (e.g. code:Position) outputs. 2142 * ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX specifies 2143 that shaders compiled for this subpass use per-view positions which only 2144 differ in value in the x component. 2145 Per-view viewport mask can: also be used. 2146endif::VK_NVX_multiview_per_view_attributes[] 2147ifdef::VK_QCOM_render_pass_shader_resolve[] 2148 * ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM specifies that the 2149 framebuffer region is the fragment region, that is, the minimum region 2150 dependencies are by pixel rather than by sample, such that any fragment 2151 shader invocation can: access any sample associated with that fragment 2152 shader invocation. 2153 * ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM specifies that the 2154 subpass performs shader resolve operations. 2155endif::VK_QCOM_render_pass_shader_resolve[] 2156ifdef::VK_ARM_rasterization_order_attachment_access[] 2157 * ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM 2158 specifies that this subpass supports pipelines created with 2159 ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM. 2160 * ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM 2161 specifies that this subpass supports pipelines created with 2162 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM. 2163 * ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM 2164 specifies that this subpass supports pipelines created with 2165 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM. 2166endif::VK_ARM_rasterization_order_attachment_access[] 2167 2168ifndef::VK_NVX_multiview_per_view_attributes,VK_QCOM_render_pass_shader_resolve[] 2169[NOTE] 2170.Note 2171==== 2172All bits for this type are defined by extensions, and none of those 2173extensions are enabled in this build of the specification. 2174==== 2175endif::VK_NVX_multiview_per_view_attributes,VK_QCOM_render_pass_shader_resolve[] 2176ifdef::VK_QCOM_render_pass_shader_resolve[] 2177[NOTE] 2178.Note 2179==== 2180Shader resolve operations allow for custom resolve operations, but 2181overdrawing pixels may: have a performance and/or power cost. 2182Furthermore, since the content of any depth stencil attachment or color 2183attachment is undefined: at the begining of a shader resolve subpass, any 2184depth testing, stencil testing, or blending operation which sources these 2185undefined: values also has undefined: result value. 2186==== 2187endif::VK_QCOM_render_pass_shader_resolve[] 2188-- 2189 2190[open,refpage='VkSubpassDescriptionFlags',desc='Bitmask of VkSubpassDescriptionFlagBits',type='flags'] 2191-- 2192include::{generated}/api/flags/VkSubpassDescriptionFlags.txt[] 2193 2194tname:VkSubpassDescriptionFlags is a bitmask type for setting a mask of zero 2195or more elink:VkSubpassDescriptionFlagBits. 2196-- 2197 2198[open,refpage='VkAttachmentReference',desc='Structure specifying an attachment reference',type='structs'] 2199-- 2200The sname:VkAttachmentReference structure is defined as: 2201 2202include::{generated}/api/structs/VkAttachmentReference.txt[] 2203 2204 * pname:attachment is either an integer value identifying an attachment at 2205 the corresponding index in 2206 slink:VkRenderPassCreateInfo::pname:pAttachments, or 2207 ename:VK_ATTACHMENT_UNUSED to signify that this attachment is not used. 2208 * pname:layout is a elink:VkImageLayout value specifying the layout the 2209 attachment uses during the subpass. 2210 2211.Valid Usage 2212**** 2213 * [[VUID-VkAttachmentReference-layout-00857]] 2214 If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout 2215 must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED, 2216 ename:VK_IMAGE_LAYOUT_PREINITIALIZED, 2217 ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR, 2218 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 2219 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 2220 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 2221 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 2222**** 2223 2224include::{generated}/validity/structs/VkAttachmentReference.txt[] 2225-- 2226 2227[open,refpage='VK_SUBPASS_EXTERNAL',desc='Subpass index sentinel expanding synchronization scope outside a subpass',type='consts'] 2228-- 2229ename:VK_SUBPASS_EXTERNAL is a special subpass index value expanding 2230synchronization scope outside a subpass. 2231It is described in more detail by slink:VkSubpassDependency. 2232 2233include::{generated}/api/enums/VK_SUBPASS_EXTERNAL.txt[] 2234-- 2235 2236[open,refpage='VkSubpassDependency',desc='Structure specifying a subpass dependency',type='structs'] 2237-- 2238:refpage: VkSubpassDependency 2239The sname:VkSubpassDependency structure is defined as: 2240 2241include::{generated}/api/structs/VkSubpassDependency.txt[] 2242 2243 * pname:srcSubpass is the subpass index of the first subpass in the 2244 dependency, or ename:VK_SUBPASS_EXTERNAL. 2245 * pname:dstSubpass is the subpass index of the second subpass in the 2246 dependency, or ename:VK_SUBPASS_EXTERNAL. 2247 * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits 2248 specifying the <<synchronization-pipeline-stages-masks, source stage 2249 mask>>. 2250 * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits 2251 specifying the <<synchronization-pipeline-stages-masks, destination 2252 stage mask>> 2253 * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 2254 <<synchronization-access-masks, source access mask>>. 2255 * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 2256 <<synchronization-access-masks, destination access mask>>. 2257 * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits. 2258 2259If pname:srcSubpass is equal to pname:dstSubpass then the 2260slink:VkSubpassDependency describes a 2261<<synchronization-pipeline-barriers-subpass-self-dependencies, subpass 2262self-dependency>>, and only constrains the pipeline barriers allowed within 2263a subpass instance. 2264Otherwise, when a render pass instance which includes a subpass dependency 2265is submitted to a queue, it defines a memory dependency between the 2266subpasses identified by pname:srcSubpass and pname:dstSubpass. 2267 2268If pname:srcSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the first 2269<<synchronization-dependencies-scopes, synchronization scope>> includes 2270commands that occur earlier in <<synchronization-submission-order,submission 2271order>> than the flink:vkCmdBeginRenderPass used to begin the render pass 2272instance. 2273Otherwise, the first set of commands includes all commands submitted as part 2274of the subpass instance identified by pname:srcSubpass and any load, store 2275or multisample resolve operations on attachments used in pname:srcSubpass. 2276In either case, the first synchronization scope is limited to operations on 2277the pipeline stages determined by the 2278<<synchronization-pipeline-stages-masks, source stage mask>> specified by 2279pname:srcStageMask. 2280 2281If pname:dstSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the second 2282<<synchronization-dependencies-scopes, synchronization scope>> includes 2283commands that occur later in <<synchronization-submission-order,submission 2284order>> than the flink:vkCmdEndRenderPass used to end the render pass 2285instance. 2286Otherwise, the second set of commands includes all commands submitted as 2287part of the subpass instance identified by pname:dstSubpass and any load, 2288store or multisample resolve operations on attachments used in 2289pname:dstSubpass. 2290In either case, the second synchronization scope is limited to operations on 2291the pipeline stages determined by the 2292<<synchronization-pipeline-stages-masks, destination stage mask>> specified 2293by pname:dstStageMask. 2294 2295The first <<synchronization-dependencies-access-scopes, access scope>> is 2296limited to accesses in the pipeline stages determined by the 2297<<synchronization-pipeline-stages-masks, source stage mask>> specified by 2298pname:srcStageMask. 2299It is also limited to access types in the <<synchronization-access-masks, 2300source access mask>> specified by pname:srcAccessMask. 2301 2302The second <<synchronization-dependencies-access-scopes, access scope>> is 2303limited to accesses in the pipeline stages determined by the 2304<<synchronization-pipeline-stages-masks, destination stage mask>> specified 2305by pname:dstStageMask. 2306It is also limited to access types in the <<synchronization-access-masks, 2307destination access mask>> specified by pname:dstAccessMask. 2308 2309The <<synchronization-dependencies-available-and-visible, availability and 2310visibility operations>> defined by a subpass dependency affect the execution 2311of <<renderpass-layout-transitions, image layout transitions>> within the 2312render pass. 2313 2314[NOTE] 2315.Note 2316==== 2317For non-attachment resources, the memory dependency expressed by subpass 2318dependency is nearly identical to that of a slink:VkMemoryBarrier (with 2319matching pname:srcAccessMask and pname:dstAccessMask parameters) submitted 2320as a part of a flink:vkCmdPipelineBarrier (with matching pname:srcStageMask 2321and pname:dstStageMask parameters). 2322The only difference being that its scopes are limited to the identified 2323subpasses rather than potentially affecting everything before and after. 2324 2325For attachments however, subpass dependencies work more like a 2326slink:VkImageMemoryBarrier defined similarly to the slink:VkMemoryBarrier 2327above, the queue family indices set to ename:VK_QUEUE_FAMILY_IGNORED, and 2328layouts as follows: 2329 2330 * The equivalent to pname:oldLayout is the attachment's layout according 2331 to the subpass description for pname:srcSubpass. 2332 * The equivalent to pname:newLayout is the attachment's layout according 2333 to the subpass description for pname:dstSubpass. 2334==== 2335 2336.Valid Usage 2337**** 2338:stageMaskName: srcStageMask 2339include::{chapters}/commonvalidity/stage_mask_common.txt[] 2340 2341:stageMaskName: dstStageMask 2342include::{chapters}/commonvalidity/stage_mask_common.txt[] 2343 2344 * [[VUID-VkSubpassDependency-srcSubpass-00864]] 2345 pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless 2346 one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies 2347 and ensure a valid execution order 2348 * [[VUID-VkSubpassDependency-srcSubpass-00865]] 2349 pname:srcSubpass and pname:dstSubpass must: not both be equal to 2350 ename:VK_SUBPASS_EXTERNAL 2351 * [[VUID-VkSubpassDependency-srcSubpass-00867]] 2352 If pname:srcSubpass is equal to pname:dstSubpass and not all of the 2353 stages in pname:srcStageMask and pname:dstStageMask are 2354 <<synchronization-framebuffer-regions,framebuffer-space stages>>, the 2355 <<synchronization-pipeline-stages-order, logically latest>> pipeline 2356 stage in pname:srcStageMask must: be 2357 <<synchronization-pipeline-stages-order, logically earlier>> than or 2358 equal to the <<synchronization-pipeline-stages-order, logically 2359 earliest>> pipeline stage in pname:dstStageMask 2360 * [[VUID-VkSubpassDependency-srcAccessMask-00868]] 2361 Any access flag included in pname:srcAccessMask must: be supported by 2362 one of the pipeline stages in pname:srcStageMask, as specified in the 2363 <<synchronization-access-types-supported, table of supported access 2364 types>> 2365 * [[VUID-VkSubpassDependency-dstAccessMask-00869]] 2366 Any access flag included in pname:dstAccessMask must: be supported by 2367 one of the pipeline stages in pname:dstStageMask, as specified in the 2368 <<synchronization-access-types-supported, table of supported access 2369 types>> 2370 * [[VUID-VkSubpassDependency-srcSubpass-02243]] 2371 If pname:srcSubpass equals pname:dstSubpass, and pname:srcStageMask and 2372 pname:dstStageMask both include a 2373 <<synchronization-framebuffer-regions,framebuffer-space stage>>, then 2374 pname:dependencyFlags must: include ename:VK_DEPENDENCY_BY_REGION_BIT 2375ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2376 * [[VUID-VkSubpassDependency-dependencyFlags-02520]] 2377 If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, 2378 pname:srcSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL 2379 * [[VUID-VkSubpassDependency-dependencyFlags-02521]] 2380 If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, 2381 pname:dstSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL 2382 * [[VUID-VkSubpassDependency-srcSubpass-00872]] 2383 If pname:srcSubpass equals pname:dstSubpass and that subpass has more 2384 than one bit set in the view mask, then pname:dependencyFlags must: 2385 include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT 2386endif::VK_VERSION_1_1,VK_KHR_multiview[] 2387**** 2388 2389include::{generated}/validity/structs/VkSubpassDependency.txt[] 2390-- 2391 2392ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2393 2394When multiview is enabled, the execution of the multiple views of one 2395subpass may: not occur simultaneously or even back-to-back, and rather may: 2396be interleaved with the execution of other subpasses. 2397The load and store operations apply to attachments on a per-view basis. 2398For example, an attachment using ename:VK_ATTACHMENT_LOAD_OP_CLEAR will have 2399each view cleared on first use, but the first use of one view may be 2400temporally distant from the first use of another view. 2401 2402[NOTE] 2403.Note 2404==== 2405A good mental model for multiview is to think of a multiview subpass as if 2406it were a collection of individual (per-view) subpasses that are logically 2407grouped together and described as a single multiview subpass in the API. 2408Similarly, a multiview attachment can be thought of like several individual 2409attachments that happen to be layers in a single image. 2410A view-local dependency between two multiview subpasses acts like a set of 2411one-to-one dependencies between corresponding pairs of per-view subpasses. 2412A view-global dependency between two multiview subpasses acts like a set of 2413[eq]#N {times} M# dependencies between all pairs of per-view subpasses in 2414the source and destination. 2415Thus, it is a more compact representation which also makes clear the 2416commonality and reuse that is present between views in a subpass. 2417This interpretation motivates the answers to questions like "`when does the 2418load op apply`" - it is on the first use of each view of an attachment, as 2419if each view was a separate attachment. 2420==== 2421 2422endif::VK_VERSION_1_1,VK_KHR_multiview[] 2423 2424ifdef::VK_EXT_transform_feedback[] 2425If any two subpasses of a render pass activate transform feedback to the 2426same bound transform feedback buffers, a subpass dependency must: be 2427included (either directly or via some intermediate subpasses) between them. 2428endif::VK_EXT_transform_feedback[] 2429 2430ifdef::editing-notes[] 2431[NOTE] 2432.editing-note 2433==== 2434The following two alleged implicit dependencies are practically no-ops, as 2435the operations they describe are already guaranteed by semaphores and 2436submission order (so they are almost entirely no-ops on their own). 2437The *only* reason they exist is because it simplifies reasoning about where 2438<<renderpass-layout-transitions, automatic layout transitions>> happen. 2439Further rewrites of this chapter could potentially remove the need for 2440these. 2441==== 2442endif::editing-notes[] 2443 2444[[renderpass-implicit-dependencies]] 2445If there is no subpass dependency from ename:VK_SUBPASS_EXTERNAL to the 2446first subpass that uses an attachment, then an implicit subpass dependency 2447exists from ename:VK_SUBPASS_EXTERNAL to the first subpass it is used in. 2448The implicit subpass dependency only exists if there exists an automatic 2449layout transition away from pname:initialLayout. 2450The subpass dependency operates as if defined with the following parameters: 2451 2452[source,c] 2453~~~~ 2454VkSubpassDependency implicitDependency = { 2455 .srcSubpass = VK_SUBPASS_EXTERNAL; 2456 .dstSubpass = firstSubpass; // First subpass attachment is used in 2457ifdef::VK_KHR_synchronization2[] 2458 .srcStageMask = VK_PIPELINE_STAGE_NONE_KHR; 2459endif::VK_KHR_synchronization2[] 2460ifndef::VK_KHR_synchronization2[] 2461 .srcStageMask = VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT; 2462endif::VK_KHR_synchronization2[] 2463 .dstStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT; 2464 .srcAccessMask = 0; 2465 .dstAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT | 2466 VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | 2467 VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | 2468 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT | 2469 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT; 2470 .dependencyFlags = 0; 2471}; 2472~~~~ 2473 2474Similarly, if there is no subpass dependency from the last subpass that uses 2475an attachment to ename:VK_SUBPASS_EXTERNAL, then an implicit subpass 2476dependency exists from the last subpass it is used in to 2477ename:VK_SUBPASS_EXTERNAL. 2478The implicit subpass dependency only exists if there exists an automatic 2479layout transition into pname:finalLayout. 2480The subpass dependency operates as if defined with the following parameters: 2481 2482[source,c] 2483~~~~ 2484VkSubpassDependency implicitDependency = { 2485 .srcSubpass = lastSubpass; // Last subpass attachment is used in 2486 .dstSubpass = VK_SUBPASS_EXTERNAL; 2487 .srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT; 2488ifdef::VK_KHR_synchronization2[] 2489 .dstStageMask = VK_PIPELINE_STAGE_NONE_KHR; 2490endif::VK_KHR_synchronization2[] 2491ifndef::VK_KHR_synchronization2[] 2492 .dstStageMask = VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT; 2493endif::VK_KHR_synchronization2[] 2494 .srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | 2495 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT; 2496 .dstAccessMask = 0; 2497 .dependencyFlags = 0; 2498}; 2499~~~~ 2500 2501[[renderpass-layout-transitions]] 2502As subpasses may: overlap or execute out of order with regards to other 2503subpasses unless a subpass dependency chain describes otherwise, the layout 2504transitions required between subpasses cannot: be known to an application. 2505Instead, an application provides the layout that each attachment must: be in 2506at the start and end of a render pass, and the layout it must: be in during 2507each subpass it is used in. 2508The implementation then must: execute layout transitions between subpasses 2509in order to guarantee that the images are in the layouts required by each 2510subpass, and in the final layout at the end of the render pass. 2511 2512Automatic layout transitions apply to the entire image subresource attached 2513to the framebuffer. 2514ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2515If the attachment view is a 2D or 2D array view of a 3D image, even if the 2516attachment view only refers to a subset of the slices of the selected mip 2517level of the 3D image, automatic layout transitions apply to the entire 2518subresource referenced which is the entire mip level in this case. 2519endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2520 2521Automatic layout transitions away from the layout used in a subpass 2522happen-after the availability operations for all dependencies with that 2523subpass as the pname:srcSubpass. 2524 2525Automatic layout transitions into the layout used in a subpass happen-before 2526the visibility operations for all dependencies with that subpass as the 2527pname:dstSubpass. 2528 2529Automatic layout transitions away from pname:initialLayout happen-after the 2530availability operations for all dependencies with a pname:srcSubpass equal 2531to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses the attachment 2532that will be transitioned. 2533For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, 2534automatic layout transitions away from pname:initialLayout happen-after the 2535availability operations for all dependencies with a pname:srcSubpass equal 2536to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses any aliased 2537attachment. 2538 2539Automatic layout transitions into pname:finalLayout happen-before the 2540visibility operations for all dependencies with a pname:dstSubpass equal to 2541ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses the attachment that 2542will be transitioned. 2543For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, 2544automatic layout transitions into pname:finalLayout happen-before the 2545visibility operations for all dependencies with a pname:dstSubpass equal to 2546ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses any aliased 2547attachment. 2548 2549ifdef::VK_EXT_sample_locations[] 2550 2551The image layout of the depth aspect of a depth/stencil attachment referring 2552to an image created with 2553ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent 2554on the last sample locations used to render to the attachment, thus 2555automatic layout transitions use the sample locations state specified in 2556slink:VkRenderPassSampleLocationsBeginInfoEXT. 2557 2558Automatic layout transitions of an attachment referring to a depth/stencil 2559image created with 2560ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT use the 2561sample locations the image subresource range referenced by the attachment 2562was last rendered with. 2563If the current render pass does not use the attachment as a depth/stencil 2564attachment in any subpass that happens-before, the automatic layout 2565transition uses the sample locations state specified in the 2566pname:sampleLocationsInfo member of the element of the 2567sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pAttachmentInitialSampleLocations 2568array for which the pname:attachmentIndex member equals the attachment index 2569of the attachment, if one is specified. 2570Otherwise, the automatic layout transition uses the sample locations state 2571specified in the pname:sampleLocationsInfo member of the element of the 2572sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pPostSubpassSampleLocations 2573array for which the pname:subpassIndex member equals the index of the 2574subpass that last used the attachment as a depth/stencil attachment, if one 2575is specified. 2576 2577If no sample locations state has been specified for an automatic layout 2578transition performed on an attachment referring to a depth/stencil image 2579created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT 2580the contents of the depth aspect of the depth/stencil attachment become 2581undefined: as if the layout of the attachment was transitioned from the 2582ename:VK_IMAGE_LAYOUT_UNDEFINED layout. 2583 2584endif::VK_EXT_sample_locations[] 2585 2586If two subpasses use the same attachment, and both subpasses use the 2587attachment in a read-only layout, no subpass dependency needs to be 2588specified between those subpasses. 2589If an implementation treats those layouts separately, it must: insert an 2590implicit subpass dependency between those subpasses to separate the uses in 2591each layout. 2592The subpass dependency operates as if defined with the following parameters: 2593 2594[source,c] 2595~~~~ 2596// Used for input attachments 2597VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT; 2598VkAccessFlags inputAttachmentDstAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT; 2599 2600// Used for depth/stencil attachments 2601VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT; 2602VkAccessFlags depthStencilAttachmentDstAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT; 2603 2604VkSubpassDependency implicitDependency = { 2605 .srcSubpass = firstSubpass; 2606 .dstSubpass = secondSubpass; 2607 .srcStageMask = inputAttachmentStages | depthStencilAttachmentStages; 2608 .dstStageMask = inputAttachmentStages | depthStencilAttachmentStages; 2609 .srcAccessMask = 0; 2610 .dstAccessMask = inputAttachmentDstAccess | depthStencilAttachmentDstAccess; 2611 .dependencyFlags = 0; 2612}; 2613~~~~ 2614 2615[[renderpass-feedbackloop]] 2616If a subpass uses the same attachment as both an input attachment and either 2617a color attachment or a depth/stencil attachment, writes via the color or 2618depth/stencil attachment are not automatically made visible to reads via the 2619input attachment, causing a _feedback loop_, except in any of the following 2620conditions: 2621 2622 * If the color components or depth/stencil components read by the input 2623 attachment are mutually exclusive with the components written by the 2624 color or depth/stencil attachments, then there is no feedback loop. 2625 This requires the graphics pipelines used by the subpass to disable 2626 writes to color components that are read as inputs via the 2627ifdef::VK_EXT_color_write_enable[] 2628 pname:colorWriteEnable or 2629endif::VK_EXT_color_write_enable[] 2630 pname:colorWriteMask, and to disable writes to depth/stencil components 2631 that are read as inputs via pname:depthWriteEnable or 2632 pname:stencilTestEnable. 2633 * If the attachment is used as an input attachment and depth/stencil 2634 attachment only, and the depth/stencil attachment is not written to. 2635 2636Rendering within a subpass containing a feedback loop creates a 2637<<memory-model-access-data-race, data race>>, except in the following cases: 2638 2639 * If a memory dependency is inserted between when the attachment is 2640 written and when it is subsequently read by later fragments. 2641 <<synchronization-pipeline-barriers, Pipeline barriers>> expressing a 2642 <<synchronization-pipeline-barriers-subpass-self-dependencies, subpass 2643 self-dependency>> are the only way to achieve this, and one must: be 2644 inserted every time a fragment will read values at a particular sample 2645 (x, y, layer, sample) coordinate, if those values have been written 2646 since the most recent pipeline barrier; or since the start of the 2647 subpass, if there have been no pipeline barriers since the start of the 2648 subpass. 2649ifdef::VK_ARM_rasterization_order_attachment_access[] 2650 * If the attachment is used as color and input attachment, and the 2651 pipeline performing the read was created with 2652 ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM 2653 included in the pname:flags member of the pname:pColorBlendState member 2654 of its slink:VkGraphicsPipelineCreateInfo. 2655 This creates a framebuffer-local memory dependency for each fragment 2656 generated by draw commands using this pipeline with the following 2657 properties: 2658 ** The first <<synchronization-dependencies-scopes, synchronization 2659 scope>> includes the 2660 ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage 2661 executed by all previous fragments (as defined by 2662 <<drawing-primitive-order, primitive order>>) in the corresponding 2663 <<synchronization-framebuffer-regions, framebuffer regions>> including 2664 those generated by the same draw command. 2665 ** The second <<synchronization-dependencies-scopes, synchronization 2666 scope>> includes the ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 2667 pipeline stage executed by the generated fragment. 2668 ** The first <<synchronization-dependencies-access-scopes, access scope>> 2669 includes all writes to color attachments. 2670 ** The second <<synchronization-dependencies-access-scopes, access scope>> 2671 includes all reads from input attachments. 2672 * If the attachment is used as depth/stencil and input attachment, and the 2673 pipeline performs a read of the depth aspect and was created with 2674 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM 2675 included in the pname:flags member of the pname:pDepthStencilState 2676 member of its slink:VkGraphicsPipelineCreateInfo. 2677 This creates a memory dependency for each fragment generated by draw 2678 commands using this pipeline with the following properties: 2679 ** The first <<synchronization-dependencies-scopes, synchronization 2680 scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 2681 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages 2682 executed by all previous fragments (as defined by 2683 <<drawing-primitive-order, primitive order>>) in the corresponding 2684 <<synchronization-framebuffer-regions, framebuffer regions>> including 2685 those generated by the same draw command. 2686 ** The second <<synchronization-dependencies-scopes, synchronization 2687 scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and 2688 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed 2689 by the generated fragment. 2690 ** The first <<synchronization-dependencies-access-scopes, access scope>> 2691 includes all writes to the depth aspect of depth/stencil attachments. 2692 ** The second <<synchronization-dependencies-access-scopes, access scope>> 2693 includes all reads from the depth aspect of input attachments. 2694 * If the attachment is used as depth/stencil and input attachment, and the 2695 pipeline performs a read of the stencil aspect and was created with 2696 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM 2697 included in the pname:flags member of the pname:pDepthStencilState 2698 member of its slink:VkGraphicsPipelineCreateInfo. 2699 This creates a memory dependency for each fragment generated by draw 2700 commands using this pipeline with the following properties: 2701 ** The first <<synchronization-dependencies-scopes, synchronization 2702 scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 2703 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages 2704 executed by all previous fragments (as defined by 2705 <<drawing-primitive-order, primitive order>>) in the corresponding 2706 <<synchronization-framebuffer-regions, framebuffer regions>> including 2707 those generated by the same draw command. 2708 ** The second <<synchronization-dependencies-scopes, synchronization 2709 scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and 2710 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages 2711 executed by the generated fragment. 2712 ** The first <<synchronization-dependencies-access-scopes, access scope>> 2713 includes all writes to the stencil aspect of depth/stencil attachments. 2714 ** The second <<synchronization-dependencies-access-scopes, access scope>> 2715 includes all reads from the stencil aspect of input attachments. 2716endif::VK_ARM_rasterization_order_attachment_access[] 2717 2718[[attachment-type-imagelayout]] 2719Attachments have requirements for a valid image layout depending on the 2720usage 2721 2722 * An attachment used as an input attachment must: be in the 2723ifdef::VK_KHR_shared_presentable_image[] 2724 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 2725endif::VK_KHR_shared_presentable_image[] 2726ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2727 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 2728 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 2729endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2730ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 2731 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 2732 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, 2733endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 2734 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 2735 ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or 2736 ename:VK_IMAGE_LAYOUT_GENERAL layout. 2737 * An attachment used only as a color attachment must: be in the 2738 ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or 2739ifdef::VK_KHR_shared_presentable_image[] 2740 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or 2741endif::VK_KHR_shared_presentable_image[] 2742 ename:VK_IMAGE_LAYOUT_GENERAL layout. 2743 * An attachment used as both an input attachment and a color attachment 2744 must: be in the 2745ifdef::VK_KHR_shared_presentable_image[] 2746 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or 2747endif::VK_KHR_shared_presentable_image[] 2748 ename:VK_IMAGE_LAYOUT_GENERAL layout. 2749 * An attachment used only as a depth/stencil attachment must: be in the 2750 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, 2751ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 2752 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 2753 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 2754 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, 2755 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, 2756endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 2757ifdef::VK_KHR_shared_presentable_image[] 2758 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 2759endif::VK_KHR_shared_presentable_image[] 2760ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2761 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 2762 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 2763endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2764 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or 2765 ename:VK_IMAGE_LAYOUT_GENERAL layout. 2766 * An attachment used as an input attachment and depth/stencil attachment 2767 must: be in the 2768ifdef::VK_KHR_shared_presentable_image[] 2769 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 2770endif::VK_KHR_shared_presentable_image[] 2771ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2772 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 2773 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 2774endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2775 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or 2776 ename:VK_IMAGE_LAYOUT_GENERAL layout. 2777 2778An attachment must: not be used as both a depth/stencil attachment and a 2779color attachment. 2780 2781ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 2782A more extensible version of render pass creation is also defined below. 2783 2784[open,refpage='vkCreateRenderPass2',desc='Create a new render pass object',type='protos',alias='vkCreateRenderPass2KHR'] 2785-- 2786To create a render pass, call: 2787 2788ifdef::VK_VERSION_1_2[] 2789include::{generated}/api/protos/vkCreateRenderPass2.txt[] 2790endif::VK_VERSION_1_2[] 2791 2792ifdef::VK_VERSION_1_2+VK_KHR_create_renderpass2[or the equivalent command] 2793 2794ifdef::VK_KHR_create_renderpass2[] 2795include::{generated}/api/protos/vkCreateRenderPass2KHR.txt[] 2796endif::VK_KHR_create_renderpass2[] 2797 2798 * pname:device is the logical device that creates the render pass. 2799 * pname:pCreateInfo is a pointer to a slink:VkRenderPassCreateInfo2 2800 structure describing the parameters of the render pass. 2801 * pname:pAllocator controls host memory allocation as described in the 2802 <<memory-allocation, Memory Allocation>> chapter. 2803 * pname:pRenderPass is a pointer to a slink:VkRenderPass handle in which 2804 the resulting render pass object is returned. 2805 2806This command is functionally identical to flink:vkCreateRenderPass, but 2807includes extensible sub-structures that include pname:sType and pname:pNext 2808parameters, allowing them to be more easily extended. 2809 2810include::{generated}/validity/protos/vkCreateRenderPass2.txt[] 2811-- 2812 2813[open,refpage='VkRenderPassCreateInfo2',desc='Structure specifying parameters of a newly created render pass',type='structs',alias='VkRenderPassCreateInfo2KHR'] 2814-- 2815The sname:VkRenderPassCreateInfo2 structure is defined as: 2816 2817include::{generated}/api/structs/VkRenderPassCreateInfo2.txt[] 2818 2819ifdef::VK_KHR_create_renderpass2[] 2820or the equivalent 2821 2822include::{generated}/api/structs/VkRenderPassCreateInfo2KHR.txt[] 2823endif::VK_KHR_create_renderpass2[] 2824 2825 * pname:sType is the type of this structure. 2826 * pname:pNext is `NULL` or a pointer to a structure extending this 2827 structure. 2828 * pname:flags is reserved for future use. 2829 * pname:attachmentCount is the number of attachments used by this render 2830 pass. 2831 * pname:pAttachments is a pointer to an array of pname:attachmentCount 2832 slink:VkAttachmentDescription2 structures describing the attachments 2833 used by the render pass. 2834 * pname:subpassCount is the number of subpasses to create. 2835 * pname:pSubpasses is a pointer to an array of pname:subpassCount 2836 slink:VkSubpassDescription2 structures describing each subpass. 2837 * pname:dependencyCount is the number of dependencies between pairs of 2838 subpasses. 2839 * pname:pDependencies is a pointer to an array of pname:dependencyCount 2840 slink:VkSubpassDependency2 structures describing dependencies between 2841 pairs of subpasses. 2842 * pname:correlatedViewMaskCount is the number of correlation masks. 2843 * pname:pCorrelatedViewMasks is a pointer to an array of view masks 2844 indicating sets of views that may: be more efficient to render 2845 concurrently. 2846 2847Parameters defined by this structure with the same name as those in 2848slink:VkRenderPassCreateInfo have the identical effect to those parameters; 2849the child structures are variants of those used in 2850slink:VkRenderPassCreateInfo which add pname:sType and pname:pNext 2851parameters, allowing them to be extended. 2852 2853If the slink:VkSubpassDescription2::pname:viewMask member of any element of 2854pname:pSubpasses is not zero, _multiview_ functionality is considered to be 2855enabled for this render pass. 2856 2857pname:correlatedViewMaskCount and pname:pCorrelatedViewMasks have the same 2858effect as slink:VkRenderPassMultiviewCreateInfo::pname:correlationMaskCount 2859and slink:VkRenderPassMultiviewCreateInfo::pname:pCorrelationMasks, 2860respectively. 2861 2862.Valid Usage 2863**** 2864 * [[VUID-VkRenderPassCreateInfo2-None-03049]] 2865 If any two subpasses operate on attachments with overlapping ranges of 2866 the same sname:VkDeviceMemory object, and at least one subpass writes to 2867 that area of sname:VkDeviceMemory, a subpass dependency must: be 2868 included (either directly or via some intermediate subpasses) between 2869 them 2870 * [[VUID-VkRenderPassCreateInfo2-attachment-03050]] 2871 If the pname:attachment member of any element of 2872 pname:pInputAttachments, pname:pColorAttachments, 2873 pname:pResolveAttachments or pname:pDepthStencilAttachment, or the 2874 attachment indexed by any element of pname:pPreserveAttachments in any 2875 given element of pname:pSubpasses is bound to a range of a 2876 sname:VkDeviceMemory object that overlaps with any other attachment in 2877 any subpass (including the same subpass), the 2878 sname:VkAttachmentDescription2 structures describing them must: include 2879 ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in pname:flags 2880 * [[VUID-VkRenderPassCreateInfo2-attachment-03051]] 2881 If the pname:attachment member of any element of 2882 pname:pInputAttachments, pname:pColorAttachments, 2883 pname:pResolveAttachments or pname:pDepthStencilAttachment, or any 2884 element of pname:pPreserveAttachments in any given element of 2885 pname:pSubpasses is not ename:VK_ATTACHMENT_UNUSED, then it must: be 2886 less than pname:attachmentCount 2887ifdef::VK_EXT_fragment_density_map[] 2888 * [[VUID-VkRenderPassCreateInfo2-fragmentDensityMapAttachment-06472]] 2889 If the pNext chain includes a 2890 slink:VkRenderPassFragmentDensityMapCreateInfoEXT structure and the 2891 pname:fragmentDensityMapAttachment member is not 2892 ename:VK_ATTACHMENT_UNUSED, then pname:attachment must: be less than 2893 pname:attachmentCount 2894endif::VK_EXT_fragment_density_map[] 2895ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 2896 * [[VUID-VkRenderPassCreateInfo2-pSubpasses-06473]] 2897 If the pname:pSubpasses pNext chain includes a 2898 slink:VkSubpassDescriptionDepthStencilResolve structure and the 2899 pname:pDepthStencilResolveAttachment member is not `NULL` and does not 2900 have the value ename:VK_ATTACHMENT_UNUSED, then pname:attachment must: 2901 be less than pname:attachmentCount 2902endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 2903 * [[VUID-VkRenderPassCreateInfo2-pAttachments-02522]] 2904 For any member of pname:pAttachments with a pname:loadOp equal to 2905 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 2906 must: not specify a pname:layout equal to 2907 ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, 2908 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or 2909 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 2910 * [[VUID-VkRenderPassCreateInfo2-pAttachments-02523]] 2911 For any member of pname:pAttachments with a pname:stencilLoadOp equal to 2912 ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment 2913 must: not specify a pname:layout equal to 2914 ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, 2915 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or 2916 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 2917 * [[VUID-VkRenderPassCreateInfo2-pDependencies-03054]] 2918 For any element of pname:pDependencies, if the pname:srcSubpass is not 2919 ename:VK_SUBPASS_EXTERNAL, all stage flags included in the 2920 pname:srcStageMask member of that dependency must: be a pipeline stage 2921 supported by the <<synchronization-pipeline-stages-types, pipeline>> 2922 identified by the pname:pipelineBindPoint member of the source subpass 2923 * [[VUID-VkRenderPassCreateInfo2-pDependencies-03055]] 2924 For any element of pname:pDependencies, if the pname:dstSubpass is not 2925 ename:VK_SUBPASS_EXTERNAL, all stage flags included in the 2926 pname:dstStageMask member of that dependency must: be a pipeline stage 2927 supported by the <<synchronization-pipeline-stages-types, pipeline>> 2928 identified by the pname:pipelineBindPoint member of the destination 2929 subpass 2930 * [[VUID-VkRenderPassCreateInfo2-pCorrelatedViewMasks-03056]] 2931 The set of bits included in any element of pname:pCorrelatedViewMasks 2932 must: not overlap with the set of bits included in any other element of 2933 pname:pCorrelatedViewMasks 2934 * [[VUID-VkRenderPassCreateInfo2-viewMask-03057]] 2935 If the slink:VkSubpassDescription2::pname:viewMask member of all 2936 elements of pname:pSubpasses is `0`, pname:correlatedViewMaskCount must: 2937 be `0` 2938 * [[VUID-VkRenderPassCreateInfo2-viewMask-03058]] 2939 The slink:VkSubpassDescription2::pname:viewMask member of all elements 2940 of pname:pSubpasses must: either all be `0`, or all not be `0` 2941 * [[VUID-VkRenderPassCreateInfo2-viewMask-03059]] 2942 If the slink:VkSubpassDescription2::pname:viewMask member of all 2943 elements of pname:pSubpasses is `0`, the pname:dependencyFlags member of 2944 any element of pname:pDependencies must: not include 2945 ename:VK_DEPENDENCY_VIEW_LOCAL_BIT 2946 * [[VUID-VkRenderPassCreateInfo2-pDependencies-03060]] 2947 For any element of pname:pDependencies where its pname:srcSubpass member 2948 equals its pname:dstSubpass member, if the pname:viewMask member of the 2949 corresponding element of pname:pSubpasses includes more than one bit, 2950 its pname:dependencyFlags member must: include 2951 ename:VK_DEPENDENCY_VIEW_LOCAL_BIT 2952 * [[VUID-VkRenderPassCreateInfo2-attachment-02525]] 2953 If the pname:attachment member of any element of the 2954 pname:pInputAttachments member of any element of pname:pSubpasses is not 2955 ename:VK_ATTACHMENT_UNUSED, the pname:aspectMask member of that element 2956 of pname:pInputAttachments must: only include aspects that are present 2957 in images of the format specified by the element of pname:pAttachments 2958 specified by pname:attachment 2959 * [[VUID-VkRenderPassCreateInfo2-srcSubpass-02526]] 2960 The pname:srcSubpass member of each element of pname:pDependencies must: 2961 be less than pname:subpassCount 2962 * [[VUID-VkRenderPassCreateInfo2-dstSubpass-02527]] 2963 The pname:dstSubpass member of each element of pname:pDependencies must: 2964 be less than pname:subpassCount 2965ifdef::VK_KHR_fragment_shading_rate[] 2966 * [[VUID-VkRenderPassCreateInfo2-pAttachments-04585]] 2967 If any element of pname:pAttachments is used as a fragment shading rate 2968 attachment in any subpass, it must: not be used as any other attachment 2969 in the render pass 2970ifdef::VK_QCOM_render_pass_transform[] 2971 * [[VUID-VkRenderPassCreateInfo2-flags-04521]] 2972 If pname:flags includes ename:VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM, 2973 an element of pname:pSubpasses includes an instance of 2974 slink:VkFragmentShadingRateAttachmentInfoKHR in its pname:pNext chain, 2975 and the pname:pFragmentShadingRateAttachment member of that structure is 2976 not equal to `NULL`, the pname:attachment member of 2977 pname:pFragmentShadingRateAttachment must: be ename:VK_ATTACHMENT_UNUSED 2978endif::VK_QCOM_render_pass_transform[] 2979 * [[VUID-VkRenderPassCreateInfo2-pAttachments-04586]] 2980 If any element of pname:pAttachments is used as a fragment shading rate 2981 attachment in any subpass, it must: have an image format whose 2982 <<potential-format-features, potential format features>> contain 2983 ename:VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 2984endif::VK_KHR_fragment_shading_rate[] 2985ifdef::VK_QCOM_render_pass_shader_resolve[] 2986 * [[VUID-VkRenderPassCreateInfo2-rasterizationSamples-04905]] 2987 If the pipeline is being created with fragment shader state, and the 2988 apiext:VK_QCOM_render_pass_shader_resolve extension is enabled, and if 2989 subpass has any input attachments, and if the subpass description 2990 contains ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then the 2991 sample count of the input attachments must: equal 2992 pname:rasterizationSamples 2993 * [[VUID-VkRenderPassCreateInfo2-sampleShadingEnable-04906]] 2994 If the pipeline is being created with fragment shader state, and the 2995 apiext:VK_QCOM_render_pass_shader_resolve extension is enabled, and if 2996 the subpass description contains 2997 ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then 2998 pname:sampleShadingEnable must: be false 2999 * [[VUID-VkRenderPassCreateInfo2-flags-04907]] 3000 If pname:flags includes 3001 ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if 3002 pname:pResolveAttachments is not `NULL`, then each resolve attachment 3003 must: be ename:VK_ATTACHMENT_UNUSED 3004 * [[VUID-VkRenderPassCreateInfo2-flags-04908]] 3005 If pname:flags includes 3006 ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if 3007 pname:pDepthStencilResolveAttachment is not `NULL`, then the 3008 depth/stencil resolve attachment must: be ename:VK_ATTACHMENT_UNUSED 3009 * [[VUID-VkRenderPassCreateInfo2-flags-04909]] 3010 If pname:flags includes 3011 ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass 3012 must: be the last subpass in a subpass dependency chain 3013endif::VK_QCOM_render_pass_shader_resolve[] 3014**** 3015 3016include::{generated}/validity/structs/VkRenderPassCreateInfo2.txt[] 3017-- 3018 3019[open,refpage='VkAttachmentDescription2',desc='Structure specifying an attachment description',type='structs',alias='VkAttachmentDescription2KHR'] 3020-- 3021The sname:VkAttachmentDescription2 structure is defined as: 3022 3023include::{generated}/api/structs/VkAttachmentDescription2.txt[] 3024 3025ifdef::VK_KHR_create_renderpass2[] 3026or the equivalent 3027 3028include::{generated}/api/structs/VkAttachmentDescription2KHR.txt[] 3029endif::VK_KHR_create_renderpass2[] 3030 3031 * pname:sType is the type of this structure. 3032 * pname:pNext is `NULL` or a pointer to a structure extending this 3033 structure. 3034 * pname:flags is a bitmask of elink:VkAttachmentDescriptionFlagBits 3035 specifying additional properties of the attachment. 3036 * pname:format is a elink:VkFormat value specifying the format of the 3037 image that will be used for the attachment. 3038 * pname:samples is a elink:VkSampleCountFlagBits value specifying the 3039 number of samples of the image. 3040 * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the 3041 contents of color and depth components of the attachment are treated at 3042 the beginning of the subpass where it is first used. 3043 * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the 3044 contents of color and depth components of the attachment are treated at 3045 the end of the subpass where it is last used. 3046 * pname:stencilLoadOp is a elink:VkAttachmentLoadOp value specifying how 3047 the contents of stencil components of the attachment are treated at the 3048 beginning of the subpass where it is first used. 3049 * pname:stencilStoreOp is a elink:VkAttachmentStoreOp value specifying how 3050 the contents of stencil components of the attachment are treated at the 3051 end of the last subpass where it is used. 3052 * pname:initialLayout is the layout the attachment image subresource will 3053 be in when a render pass instance begins. 3054 * pname:finalLayout is the layout the attachment image subresource will be 3055 transitioned to when a render pass instance ends. 3056 3057Parameters defined by this structure with the same name as those in 3058slink:VkAttachmentDescription have the identical effect to those parameters. 3059 3060ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3061If the <<features-separateDepthStencilLayouts, 3062pname:separateDepthStencilLayouts>> feature is enabled, and pname:format is 3063a depth/stencil format, pname:initialLayout and pname:finalLayout can: be 3064set to a layout that only specifies the layout of the depth aspect. 3065 3066If the pname:pNext chain includes a 3067slink:VkAttachmentDescriptionStencilLayout structure, then the 3068pname:stencilInitialLayout and pname:stencilFinalLayout members specify the 3069initial and final layouts of the stencil aspect of a depth/stencil format, 3070and pname:initialLayout and pname:finalLayout only apply to the depth 3071aspect. 3072For depth-only formats, the slink:VkAttachmentDescriptionStencilLayout 3073structure is ignored. 3074For stencil-only formats, the initial and final layouts of the stencil 3075aspect are taken from the slink:VkAttachmentDescriptionStencilLayout 3076structure if present, or pname:initialLayout and pname:finalLayout if not 3077present. 3078 3079If pname:format is a depth/stencil format, and either pname:initialLayout or 3080pname:finalLayout does not specify a layout for the stencil aspect, then the 3081application must: specify the initial and final layouts of the stencil 3082aspect by including a slink:VkAttachmentDescriptionStencilLayout structure 3083in the pname:pNext chain. 3084 3085endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3086 3087.Valid Usage 3088**** 3089 * [[VUID-VkAttachmentDescription2-finalLayout-03061]] 3090 pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or 3091 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 3092 * [[VUID-VkAttachmentDescription2-format-03294]] 3093 If pname:format is a color format, pname:initialLayout must: not be 3094 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, 3095 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 3096 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or 3097 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 3098 * [[VUID-VkAttachmentDescription2-format-03295]] 3099 If pname:format is a depth/stencil format, pname:initialLayout must: not 3100 be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 3101 * [[VUID-VkAttachmentDescription2-format-03296]] 3102 If pname:format is a color format, pname:finalLayout must: not be 3103 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, 3104 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 3105 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or 3106 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 3107 * [[VUID-VkAttachmentDescription2-format-03297]] 3108 If pname:format is a depth/stencil format, pname:finalLayout must: not 3109 be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 3110ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3111 * [[VUID-VkAttachmentDescription2-separateDepthStencilLayouts-03298]] 3112 If the <<features-separateDepthStencilLayouts, 3113 pname:separateDepthStencilLayouts>> feature is not enabled, 3114 pname:initialLayout must: not be 3115 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3116 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3117 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 3118 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 3119 * [[VUID-VkAttachmentDescription2-separateDepthStencilLayouts-03299]] 3120 If the <<features-separateDepthStencilLayouts, 3121 pname:separateDepthStencilLayouts>> feature is not enabled, 3122 pname:finalLayout must: not be 3123 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3124 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3125 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 3126 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 3127 * [[VUID-VkAttachmentDescription2-format-03300]] 3128 If pname:format is a color format, pname:initialLayout must: not be 3129 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3130 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3131 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 3132 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 3133 * [[VUID-VkAttachmentDescription2-format-03301]] 3134 If pname:format is a color format, pname:finalLayout must: not be 3135 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3136 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3137 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 3138 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 3139 * [[VUID-VkAttachmentDescription2-format-03302]] 3140 If pname:format is a depth/stencil format which includes both depth and 3141 stencil aspects, and pname:initialLayout is 3142 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or 3143 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pname:pNext chain 3144 must: include a slink:VkAttachmentDescriptionStencilLayout structure 3145 * [[VUID-VkAttachmentDescription2-format-03303]] 3146 If pname:format is a depth/stencil format which includes both depth and 3147 stencil aspects, and pname:finalLayout is 3148 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or 3149 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pname:pNext chain 3150 must: include a slink:VkAttachmentDescriptionStencilLayout structure 3151 * [[VUID-VkAttachmentDescription2-format-03304]] 3152 If pname:format is a depth/stencil format which includes only the depth 3153 aspect, pname:initialLayout must: not be 3154 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 3155 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 3156 * [[VUID-VkAttachmentDescription2-format-03305]] 3157 If pname:format is a depth/stencil format which includes only the depth 3158 aspect, pname:finalLayout must: not be 3159 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 3160 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 3161 * [[VUID-VkAttachmentDescription2-format-03306]] 3162 If pname:format is a depth/stencil format which includes only the 3163 stencil aspect, pname:initialLayout must: not be 3164 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or 3165 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL 3166 * [[VUID-VkAttachmentDescription2-format-03307]] 3167 If pname:format is a depth/stencil format which includes only the 3168 stencil aspect, pname:finalLayout must: not be 3169 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or 3170 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL 3171endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3172**** 3173 3174include::{generated}/validity/structs/VkAttachmentDescription2.txt[] 3175-- 3176 3177ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3178[open,refpage='VkAttachmentDescriptionStencilLayout',desc='Structure specifying an attachment description',type='structs',alias='VkAttachmentDescriptionStencilLayoutKHR'] 3179-- 3180The sname:VkAttachmentDescriptionStencilLayout structure is defined as: 3181 3182include::{generated}/api/structs/VkAttachmentDescriptionStencilLayout.txt[] 3183 3184ifdef::VK_KHR_separate_depth_stencil_layouts[] 3185or the equivalent 3186 3187include::{generated}/api/structs/VkAttachmentDescriptionStencilLayoutKHR.txt[] 3188endif::VK_KHR_separate_depth_stencil_layouts[] 3189 3190 * pname:sType is the type of this structure. 3191 * pname:pNext is `NULL` or a pointer to a structure extending this 3192 structure. 3193 * pname:stencilInitialLayout is the layout the stencil aspect of the 3194 attachment image subresource will be in when a render pass instance 3195 begins. 3196 * pname:stencilFinalLayout is the layout the stencil aspect of the 3197 attachment image subresource will be transitioned to when a render pass 3198 instance ends. 3199 3200.Valid Usage 3201**** 3202 * [[VUID-VkAttachmentDescriptionStencilLayout-stencilInitialLayout-03308]] 3203 pname:stencilInitialLayout must: not be 3204 ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, 3205 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3206 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3207 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, 3208 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 3209 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or 3210 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 3211 * [[VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-03309]] 3212 pname:stencilFinalLayout must: not be 3213 ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, 3214 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3215 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3216 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, 3217 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 3218 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or 3219 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 3220 * [[VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-03310]] 3221 pname:stencilFinalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or 3222 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 3223**** 3224 3225include::{generated}/validity/structs/VkAttachmentDescriptionStencilLayout.txt[] 3226-- 3227endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3228 3229[open,refpage='VkSubpassDescription2',desc='Structure specifying a subpass description',type='structs',alias='VkSubpassDescription2KHR'] 3230-- 3231The sname:VkSubpassDescription2 structure is defined as: 3232 3233include::{generated}/api/structs/VkSubpassDescription2.txt[] 3234 3235ifdef::VK_KHR_create_renderpass2[] 3236or the equivalent 3237 3238include::{generated}/api/structs/VkSubpassDescription2KHR.txt[] 3239endif::VK_KHR_create_renderpass2[] 3240 3241 * pname:sType is the type of this structure. 3242 * pname:pNext is `NULL` or a pointer to a structure extending this 3243 structure. 3244 * pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits 3245 specifying usage of the subpass. 3246 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying 3247 the pipeline type supported for this subpass. 3248 * pname:viewMask is a bitfield of view indices describing which views 3249 rendering is broadcast to in this subpass, when multiview is enabled. 3250 * pname:inputAttachmentCount is the number of input attachments. 3251 * pname:pInputAttachments is a pointer to an array of 3252 slink:VkAttachmentReference2 structures defining the input attachments 3253 for this subpass and their layouts. 3254 * pname:colorAttachmentCount is the number of color attachments. 3255 * pname:pColorAttachments is a pointer to an array of 3256 pname:colorAttachmentCount slink:VkAttachmentReference2 structures 3257 defining the color attachments for this subpass and their layouts. 3258 * pname:pResolveAttachments is `NULL` or a pointer to an array of 3259 pname:colorAttachmentCount slink:VkAttachmentReference2 structures 3260 defining the resolve attachments for this subpass and their layouts. 3261 * pname:pDepthStencilAttachment is a pointer to a 3262 slink:VkAttachmentReference2 structure specifying the depth/stencil 3263 attachment for this subpass and its layout. 3264 * pname:preserveAttachmentCount is the number of preserved attachments. 3265 * pname:pPreserveAttachments is a pointer to an array of 3266 pname:preserveAttachmentCount render pass attachment indices identifying 3267 attachments that are not used by this subpass, but whose contents must: 3268 be preserved throughout the subpass. 3269 3270Parameters defined by this structure with the same name as those in 3271slink:VkSubpassDescription have the identical effect to those parameters. 3272 3273pname:viewMask has the same effect for the described subpass as 3274slink:VkRenderPassMultiviewCreateInfo::pname:pViewMasks has on each 3275corresponding subpass. 3276 3277ifdef::VK_KHR_fragment_shading_rate[] 3278If a slink:VkFragmentShadingRateAttachmentInfoKHR structure is included in 3279the pname:pNext chain, pname:pFragmentShadingRateAttachment is not `NULL`, 3280and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, the 3281identified attachment defines a fragment shading rate attachment for that 3282subpass. 3283endif::VK_KHR_fragment_shading_rate[] 3284 3285.Valid Usage 3286**** 3287ifndef::VK_HUAWEI_subpass_shading[] 3288 * [[VUID-VkSubpassDescription2-pipelineBindPoint-03062]] 3289 pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS 3290endif::VK_HUAWEI_subpass_shading[] 3291ifdef::VK_HUAWEI_subpass_shading[] 3292 * [[VUID-VkSubpassDescription2-pipelineBindPoint-04953]] 3293 pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS 3294 or ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI 3295endif::VK_HUAWEI_subpass_shading[] 3296 * [[VUID-VkSubpassDescription2-colorAttachmentCount-03063]] 3297 pname:colorAttachmentCount must: be less than or equal to 3298 sname:VkPhysicalDeviceLimits::pname:maxColorAttachments 3299 * [[VUID-VkSubpassDescription2-loadOp-03064]] 3300 If the first use of an attachment in this render pass is as an input 3301 attachment, and the attachment is not also used as a color or 3302 depth/stencil attachment in the same subpass, then pname:loadOp must: 3303 not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR 3304 * [[VUID-VkSubpassDescription2-pResolveAttachments-03065]] 3305 If pname:pResolveAttachments is not `NULL`, for each resolve attachment 3306 that does not have the value ename:VK_ATTACHMENT_UNUSED, the 3307 corresponding color attachment must: not have the value 3308 ename:VK_ATTACHMENT_UNUSED 3309 * [[VUID-VkSubpassDescription2-pResolveAttachments-03066]] 3310 If pname:pResolveAttachments is not `NULL`, for each resolve attachment 3311 that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color 3312 attachment must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT 3313 * [[VUID-VkSubpassDescription2-pResolveAttachments-03067]] 3314 If pname:pResolveAttachments is not `NULL`, each resolve attachment that 3315 is not ename:VK_ATTACHMENT_UNUSED must: have a sample count of 3316 ename:VK_SAMPLE_COUNT_1_BIT 3317 * [[VUID-VkSubpassDescription2-pResolveAttachments-03068]] 3318 Any given element of pname:pResolveAttachments must: have the same 3319 elink:VkFormat as its corresponding color attachment 3320 * [[VUID-VkSubpassDescription2-pColorAttachments-03069]] 3321 All attachments in pname:pColorAttachments that are not 3322 ename:VK_ATTACHMENT_UNUSED must: have the same sample count 3323 * [[VUID-VkSubpassDescription2-pInputAttachments-02897]] 3324 All attachments in pname:pInputAttachments that are not 3325 ename:VK_ATTACHMENT_UNUSED must: have image formats whose 3326 <<potential-format-features, potential format features>> contain at 3327 least ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or 3328 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 3329 * [[VUID-VkSubpassDescription2-pColorAttachments-02898]] 3330 All attachments in pname:pColorAttachments that are not 3331 ename:VK_ATTACHMENT_UNUSED must: have image formats whose 3332 <<potential-format-features, potential format features>> contain 3333 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 3334 * [[VUID-VkSubpassDescription2-pResolveAttachments-02899]] 3335 All attachments in pname:pResolveAttachments that are not 3336 ename:VK_ATTACHMENT_UNUSED must: have image formats whose 3337 <<potential-format-features, potential format features>> contain 3338 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 3339 * [[VUID-VkSubpassDescription2-pDepthStencilAttachment-02900]] 3340 If pname:pDepthStencilAttachment is not `NULL` and the attachment is not 3341 ename:VK_ATTACHMENT_UNUSED then it must: have an image format whose 3342 <<potential-format-features, potential format features>> contain 3343 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 3344ifdef::VK_AMD_mixed_attachment_samples[] 3345 * [[VUID-VkSubpassDescription2-pColorAttachments-03070]] 3346 If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, 3347 all attachments in pname:pColorAttachments that are not 3348 ename:VK_ATTACHMENT_UNUSED must: have a sample count that is smaller 3349 than or equal to the sample count of pname:pDepthStencilAttachment if it 3350 is not ename:VK_ATTACHMENT_UNUSED 3351endif::VK_AMD_mixed_attachment_samples[] 3352 * [[VUID-VkSubpassDescription2-pDepthStencilAttachment-03071]] 3353 If neither the `apiext:VK_AMD_mixed_attachment_samples` nor the 3354 `apiext:VK_NV_framebuffer_mixed_samples` extensions are enabled, and if 3355 pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and any 3356 attachments in pname:pColorAttachments are not 3357 ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count 3358 * [[VUID-VkSubpassDescription2-attachment-03073]] 3359 Each element of pname:pPreserveAttachments must: not be 3360 ename:VK_ATTACHMENT_UNUSED 3361 * [[VUID-VkSubpassDescription2-pPreserveAttachments-03074]] 3362 Any given element of pname:pPreserveAttachments must: not also be an 3363 element of any other member of the subpass description 3364 * [[VUID-VkSubpassDescription2-layout-02528]] 3365 If any attachment is used by more than one slink:VkAttachmentReference2 3366 member, then each use must: use the same pname:layout 3367 * [[VUID-VkSubpassDescription2-None-04439]] 3368 Attachments must: follow the <<attachment-type-imagelayout, image layout 3369 requirements>> based on the type of attachment it is being used as 3370ifdef::VK_NVX_multiview_per_view_attributes[] 3371 * [[VUID-VkSubpassDescription2-flags-03076]] 3372 If pname:flags includes 3373 ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must: 3374 also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX 3375endif::VK_NVX_multiview_per_view_attributes[] 3376 * [[VUID-VkSubpassDescription2-attachment-02799]] 3377 If the pname:attachment member of any element of pname:pInputAttachments 3378 is not ename:VK_ATTACHMENT_UNUSED, then the pname:aspectMask member 3379 must: be a valid combination of elink:VkImageAspectFlagBits 3380 * [[VUID-VkSubpassDescription2-attachment-02800]] 3381 If the pname:attachment member of any element of pname:pInputAttachments 3382 is not ename:VK_ATTACHMENT_UNUSED, then the pname:aspectMask member 3383 must: not be `0` 3384 * [[VUID-VkSubpassDescription2-attachment-02801]] 3385 If the pname:attachment member of any element of pname:pInputAttachments 3386 is not ename:VK_ATTACHMENT_UNUSED, then the pname:aspectMask member 3387 must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT 3388ifdef::VK_EXT_image_drm_format_modifier[] 3389 * [[VUID-VkSubpassDescription2-attachment-04563]] 3390 If the pname:attachment member of any element of pname:pInputAttachments 3391 is not ename:VK_ATTACHMENT_UNUSED, then the pname:aspectMask member 3392 must: not include `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for 3393 any index _i_ 3394endif::VK_EXT_image_drm_format_modifier[] 3395 * [[VUID-VkSubpassDescription2-pDepthStencilAttachment-04440]] 3396 An attachment must: not be used in both pname:pDepthStencilAttachment 3397 and pname:pColorAttachments 3398**** 3399 3400include::{generated}/validity/structs/VkSubpassDescription2.txt[] 3401-- 3402 3403ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 3404[open,refpage='VkSubpassDescriptionDepthStencilResolve',desc='Structure specifying depth/stencil resolve operations for a subpass',type='structs',alias='VkSubpassDescriptionDepthStencilResolveKHR'] 3405-- 3406If the pname:pNext chain of sname:VkSubpassDescription2 includes a 3407sname:VkSubpassDescriptionDepthStencilResolve structure, then that structure 3408describes multisample resolve operations for the depth/stencil attachment in 3409a subpass. 3410 3411The sname:VkSubpassDescriptionDepthStencilResolve structure is defined as: 3412 3413include::{generated}/api/structs/VkSubpassDescriptionDepthStencilResolve.txt[] 3414 3415ifdef::VK_KHR_depth_stencil_resolve[] 3416or the equivalent 3417 3418include::{generated}/api/structs/VkSubpassDescriptionDepthStencilResolveKHR.txt[] 3419endif::VK_KHR_depth_stencil_resolve[] 3420 3421 * pname:sType is the type of this structure. 3422 * pname:pNext is `NULL` or a pointer to a structure extending this 3423 structure. 3424 * pname:depthResolveMode is a elink:VkResolveModeFlagBits value describing 3425 the depth resolve mode. 3426 * pname:stencilResolveMode is a elink:VkResolveModeFlagBits value 3427 describing the stencil resolve mode. 3428 * pname:pDepthStencilResolveAttachment is `NULL` or a pointer to a 3429 slink:VkAttachmentReference2 structure defining the depth/stencil 3430 resolve attachment for this subpass and its layout. 3431 3432If pname:pDepthStencilResolveAttachment is `NULL`, or if its attachment 3433index is ename:VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil 3434resolve attachment will be used in the subpass. 3435 3436.Valid Usage 3437**** 3438 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03177]] 3439 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3440 the value ename:VK_ATTACHMENT_UNUSED, pname:pDepthStencilAttachment 3441 must: not be `NULL` or have the value ename:VK_ATTACHMENT_UNUSED 3442 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03178]] 3443 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3444 the value ename:VK_ATTACHMENT_UNUSED, pname:depthResolveMode and 3445 pname:stencilResolveMode must: not both be ename:VK_RESOLVE_MODE_NONE 3446 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03179]] 3447 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3448 the value ename:VK_ATTACHMENT_UNUSED, pname:pDepthStencilAttachment 3449 must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT 3450 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03180]] 3451 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3452 the value ename:VK_ATTACHMENT_UNUSED, 3453 pname:pDepthStencilResolveAttachment must: have a sample count of 3454 ename:VK_SAMPLE_COUNT_1_BIT 3455 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-02651]] 3456 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3457 the value ename:VK_ATTACHMENT_UNUSED then it must: have an image format 3458 whose <<potential-format-features, potential format features>> contain 3459 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 3460 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03181]] 3461 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3462 the value ename:VK_ATTACHMENT_UNUSED and elink:VkFormat of 3463 pname:pDepthStencilResolveAttachment has a depth component, then the 3464 elink:VkFormat of pname:pDepthStencilAttachment must: have a depth 3465 component with the same number of bits and numerical type 3466 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03182]] 3467 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3468 the value ename:VK_ATTACHMENT_UNUSED, and elink:VkFormat of 3469 pname:pDepthStencilResolveAttachment has a stencil component, then the 3470 elink:VkFormat of pname:pDepthStencilAttachment must: have a stencil 3471 component with the same number of bits and numerical type 3472 * [[VUID-VkSubpassDescriptionDepthStencilResolve-depthResolveMode-03183]] 3473 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3474 the value ename:VK_ATTACHMENT_UNUSED and the elink:VkFormat of 3475 pname:pDepthStencilResolveAttachment has a depth component, then the 3476 value of pname:depthResolveMode must: be one of the bits set in 3477 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:supportedDepthResolveModes 3478 or ename:VK_RESOLVE_MODE_NONE 3479 * [[VUID-VkSubpassDescriptionDepthStencilResolve-stencilResolveMode-03184]] 3480 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3481 the value ename:VK_ATTACHMENT_UNUSED and the elink:VkFormat of 3482 pname:pDepthStencilResolveAttachment has a stencil component, then the 3483 value of pname:stencilResolveMode must: be one of the bits set in 3484 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:supportedStencilResolveModes 3485 or ename:VK_RESOLVE_MODE_NONE 3486 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03185]] 3487 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3488 the value ename:VK_ATTACHMENT_UNUSED, the elink:VkFormat of 3489 pname:pDepthStencilResolveAttachment has both depth and stencil 3490 components, 3491 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolve 3492 is ename:VK_FALSE, and 3493 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolveNone 3494 is ename:VK_FALSE, then the values of pname:depthResolveMode and 3495 pname:stencilResolveMode must: be identical 3496 * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03186]] 3497 If pname:pDepthStencilResolveAttachment is not `NULL` and does not have 3498 the value ename:VK_ATTACHMENT_UNUSED, the elink:VkFormat of 3499 pname:pDepthStencilResolveAttachment has both depth and stencil 3500 components, 3501 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolve 3502 is ename:VK_FALSE and 3503 slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolveNone 3504 is ename:VK_TRUE, then the values of pname:depthResolveMode and 3505 pname:stencilResolveMode must: be identical or one of them must: be 3506 ename:VK_RESOLVE_MODE_NONE 3507**** 3508 3509include::{generated}/validity/structs/VkSubpassDescriptionDepthStencilResolve.txt[] 3510-- 3511 3512[open,refpage='VkResolveModeFlagBits',desc='Bitmask indicating supported depth and stencil resolve modes',type='enums',alias='VkResolveModeFlagBitsKHR'] 3513-- 3514Possible values of 3515slink:VkSubpassDescriptionDepthStencilResolve::pname:depthResolveMode and 3516pname:stencilResolveMode, specifying the depth and stencil resolve modes, 3517are: 3518 3519include::{generated}/api/enums/VkResolveModeFlagBits.txt[] 3520 3521ifdef::VK_KHR_depth_stencil_resolve[] 3522or the equivalent 3523 3524include::{generated}/api/enums/VkResolveModeFlagBitsKHR.txt[] 3525endif::VK_KHR_depth_stencil_resolve[] 3526 3527 * ename:VK_RESOLVE_MODE_NONE indicates that no resolve operation is done. 3528 * ename:VK_RESOLVE_MODE_SAMPLE_ZERO_BIT indicates that result of the 3529 resolve operation is equal to the value of sample 0. 3530 * ename:VK_RESOLVE_MODE_AVERAGE_BIT indicates that result of the resolve 3531 operation is the average of the sample values. 3532 * ename:VK_RESOLVE_MODE_MIN_BIT indicates that result of the resolve 3533 operation is the minimum of the sample values. 3534 * ename:VK_RESOLVE_MODE_MAX_BIT indicates that result of the resolve 3535 operation is the maximum of the sample values. 3536-- 3537 3538[open,refpage='VkResolveModeFlags',desc='Bitmask of VkResolveModeFlagBits',type='flags',alias='VkResolveModeFlagsKHR'] 3539-- 3540include::{generated}/api/flags/VkResolveModeFlags.txt[] 3541 3542ifdef::VK_KHR_depth_stencil_resolve[] 3543or the equivalent 3544 3545include::{generated}/api/flags/VkResolveModeFlagsKHR.txt[] 3546endif::VK_KHR_depth_stencil_resolve[] 3547 3548tname:VkResolveModeFlags is a bitmask type for setting a mask of zero or 3549more elink:VkResolveModeFlagBits. 3550-- 3551endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 3552 3553 3554ifdef::VK_KHR_fragment_shading_rate[] 3555[open,refpage='VkFragmentShadingRateAttachmentInfoKHR',desc='Structure specifying a fragment shading rate attachment for a subpass',type='structs'] 3556-- 3557The sname:VkFragmentShadingRateAttachmentInfoKHR structure is defined as: 3558 3559include::{generated}/api/structs/VkFragmentShadingRateAttachmentInfoKHR.txt[] 3560 3561 * pname:sType is the type of this structure. 3562 * pname:pNext is `NULL` or a pointer to a structure extending this 3563 structure. 3564 * pname:pFragmentShadingRateAttachment is `NULL` or a pointer to a 3565 slink:VkAttachmentReference2 structure defining the fragment shading 3566 rate attachment for this subpass. 3567 * pname:shadingRateAttachmentTexelSize specifies the size of the portion 3568 of the framebuffer corresponding to each texel in 3569 pname:pFragmentShadingRateAttachment. 3570 3571If no shading rate attachment is specified, or if this structure is not 3572specified, the implementation behaves as if a valid shading rate attachment 3573was specified with all texels specifying a single pixel per fragment. 3574 3575.Valid Usage 3576**** 3577 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04524]] 3578 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3579 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, its 3580 pname:layout member must: be equal to ename:VK_IMAGE_LAYOUT_GENERAL or 3581 ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR 3582 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04525]] 3583 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3584 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, 3585 pname:shadingRateAttachmentTexelSize.width must: be a power of two value 3586 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04526]] 3587 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3588 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, 3589 pname:shadingRateAttachmentTexelSize.width must: be less than or equal 3590 to <<limits-maxFragmentShadingRateAttachmentTexelSize, 3591 pname:maxFragmentShadingRateAttachmentTexelSize.width>> 3592 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04527]] 3593 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3594 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, 3595 pname:shadingRateAttachmentTexelSize.width must: be greater than or 3596 equal to <<limits-minFragmentShadingRateAttachmentTexelSize, 3597 pname:minFragmentShadingRateAttachmentTexelSize.width>> 3598 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04528]] 3599 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3600 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, 3601 pname:shadingRateAttachmentTexelSize.height must: be a power of two 3602 value 3603 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04529]] 3604 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3605 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, 3606 pname:shadingRateAttachmentTexelSize.height must: be less than or equal 3607 to <<limits-maxFragmentShadingRateAttachmentTexelSize, 3608 pname:maxFragmentShadingRateAttachmentTexelSize.height>> 3609 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04530]] 3610 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3611 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, 3612 pname:shadingRateAttachmentTexelSize.height must: be greater than or 3613 equal to <<limits-minFragmentShadingRateAttachmentTexelSize, 3614 pname:minFragmentShadingRateAttachmentTexelSize.height>> 3615 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04531]] 3616 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3617 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, the quotient 3618 of pname:shadingRateAttachmentTexelSize.width and 3619 pname:shadingRateAttachmentTexelSize.height must: be less than or equal 3620 to <<limits-maxFragmentShadingRateAttachmentTexelSizeAspectRatio, 3621 pname:maxFragmentShadingRateAttachmentTexelSizeAspectRatio>> 3622 * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04532]] 3623 If pname:pFragmentShadingRateAttachment is not `NULL` and its 3624 pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, the quotient 3625 of pname:shadingRateAttachmentTexelSize.height and 3626 pname:shadingRateAttachmentTexelSize.width must: be less than or equal 3627 to <<limits-maxFragmentShadingRateAttachmentTexelSizeAspectRatio, 3628 pname:maxFragmentShadingRateAttachmentTexelSizeAspectRatio>> 3629**** 3630 3631include::{generated}/validity/structs/VkFragmentShadingRateAttachmentInfoKHR.txt[] 3632-- 3633endif::VK_KHR_fragment_shading_rate[] 3634 3635[open,refpage='VkAttachmentReference2',desc='Structure specifying an attachment reference',type='structs',alias='VkAttachmentReference2KHR'] 3636-- 3637The sname:VkAttachmentReference2 structure is defined as: 3638 3639include::{generated}/api/structs/VkAttachmentReference2.txt[] 3640 3641ifdef::VK_KHR_create_renderpass2[] 3642or the equivalent 3643 3644include::{generated}/api/structs/VkAttachmentReference2KHR.txt[] 3645endif::VK_KHR_create_renderpass2[] 3646 3647 * pname:sType is the type of this structure. 3648 * pname:pNext is `NULL` or a pointer to a structure extending this 3649 structure. 3650 * pname:attachment is either an integer value identifying an attachment at 3651 the corresponding index in 3652 slink:VkRenderPassCreateInfo2::pname:pAttachments, or 3653 ename:VK_ATTACHMENT_UNUSED to signify that this attachment is not used. 3654 * pname:layout is a elink:VkImageLayout value specifying the layout the 3655 attachment uses during the subpass. 3656 * pname:aspectMask is a mask of which aspect(s) can: be accessed within 3657 the specified subpass as an input attachment. 3658 3659Parameters defined by this structure with the same name as those in 3660slink:VkAttachmentReference have the identical effect to those parameters. 3661 3662pname:aspectMask is ignored when this structure is used to describe anything 3663other than an input attachment reference. 3664 3665ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3666If the <<features-separateDepthStencilLayouts, 3667pname:separateDepthStencilLayouts>> feature is enabled, and pname:attachment 3668has a depth/stencil format, pname:layout can: be set to a layout that only 3669specifies the layout of the depth aspect. 3670 3671If pname:layout only specifies the layout of the depth aspect of the 3672attachment, the layout of the stencil aspect is specified by the 3673pname:stencilLayout member of a slink:VkAttachmentReferenceStencilLayout 3674structure included in the pname:pNext chain. 3675Otherwise, pname:layout describes the layout for all relevant image aspects. 3676endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3677 3678.Valid Usage 3679**** 3680 * [[VUID-VkAttachmentReference2-layout-03077]] 3681 If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout 3682 must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED, 3683 ename:VK_IMAGE_LAYOUT_PREINITIALIZED, or 3684 ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 3685ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3686 * [[VUID-VkAttachmentReference2-separateDepthStencilLayouts-03313]] 3687 If the <<features-separateDepthStencilLayouts, 3688 pname:separateDepthStencilLayouts>> feature is not enabled, and 3689 pname:attachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout must: 3690 not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3691 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3692 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 3693 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, 3694 * [[VUID-VkAttachmentReference2-attachment-04754]] 3695 If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, and the format of 3696 the referenced attachment is a color format, pname:layout must: not be 3697 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3698 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3699 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 3700 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 3701 * [[VUID-VkAttachmentReference2-attachment-04755]] 3702 If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, and the format of 3703 the referenced attachment is a depth/stencil format which includes both 3704 depth and stencil aspects, and pname:layout is 3705 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or 3706 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pname:pNext chain 3707 must: include a slink:VkAttachmentReferenceStencilLayout structure 3708 * [[VUID-VkAttachmentReference2-attachment-04756]] 3709 If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, and the format of 3710 the referenced attachment is a depth/stencil format which includes only 3711 the depth aspect, pname:layout must: not be 3712 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or 3713 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 3714 * [[VUID-VkAttachmentReference2-attachment-04757]] 3715 If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, and the format of 3716 the referenced attachment is a depth/stencil format which includes only 3717 the stencil aspect, pname:layout must: not be 3718 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or 3719 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL 3720endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3721**** 3722 3723include::{generated}/validity/structs/VkAttachmentReference2.txt[] 3724-- 3725 3726ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3727[open,refpage='VkAttachmentReferenceStencilLayout',desc='Structure specifying an attachment description',type='structs',alias='VkAttachmentReferenceStencilLayoutKHR'] 3728-- 3729The sname:VkAttachmentReferenceStencilLayout structure is defined as: 3730 3731include::{generated}/api/structs/VkAttachmentReferenceStencilLayout.txt[] 3732 3733ifdef::VK_KHR_separate_depth_stencil_layouts[] 3734or the equivalent 3735 3736include::{generated}/api/structs/VkAttachmentReferenceStencilLayoutKHR.txt[] 3737endif::VK_KHR_separate_depth_stencil_layouts[] 3738 3739 * pname:sType is the type of this structure. 3740 * pname:pNext is `NULL` or a pointer to a structure extending this 3741 structure. 3742 * pname:stencilLayout is a elink:VkImageLayout value specifying the layout 3743 the stencil aspect of the attachment uses during the subpass. 3744 3745.Valid Usage 3746**** 3747 * [[VUID-VkAttachmentReferenceStencilLayout-stencilLayout-03318]] 3748 pname:stencilLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED, 3749 ename:VK_IMAGE_LAYOUT_PREINITIALIZED, 3750 ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, 3751 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 3752 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 3753 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, 3754 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 3755 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 3756 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, or 3757 ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 3758**** 3759 3760include::{generated}/validity/structs/VkAttachmentReferenceStencilLayout.txt[] 3761-- 3762endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3763 3764[open,refpage='VkSubpassDependency2',desc='Structure specifying a subpass dependency',type='structs',alias='VkSubpassDependency2KHR'] 3765-- 3766:refpage: VkSubpassDependency2 3767The sname:VkSubpassDependency2 structure is defined as: 3768 3769include::{generated}/api/structs/VkSubpassDependency2.txt[] 3770 3771ifdef::VK_KHR_create_renderpass2[] 3772or the equivalent 3773 3774include::{generated}/api/structs/VkSubpassDependency2KHR.txt[] 3775endif::VK_KHR_create_renderpass2[] 3776 3777 * pname:sType is the type of this structure. 3778 * pname:pNext is `NULL` or a pointer to a structure extending this 3779 structure. 3780 * pname:srcSubpass is the subpass index of the first subpass in the 3781 dependency, or ename:VK_SUBPASS_EXTERNAL. 3782 * pname:dstSubpass is the subpass index of the second subpass in the 3783 dependency, or ename:VK_SUBPASS_EXTERNAL. 3784 * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits 3785 specifying the <<synchronization-pipeline-stages-masks, source stage 3786 mask>>. 3787 * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits 3788 specifying the <<synchronization-pipeline-stages-masks, destination 3789 stage mask>> 3790 * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 3791 <<synchronization-access-masks, source access mask>>. 3792 * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a 3793 <<synchronization-access-masks, destination access mask>>. 3794 * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits. 3795 * pname:viewOffset controls which views in the source subpass the views in 3796 the destination subpass depend on. 3797 3798Parameters defined by this structure with the same name as those in 3799slink:VkSubpassDependency have the identical effect to those parameters. 3800 3801pname:viewOffset has the same effect for the described subpass dependency as 3802slink:VkRenderPassMultiviewCreateInfo::pname:pViewOffsets has on each 3803corresponding subpass dependency. 3804 3805ifdef::VK_KHR_synchronization2[] 3806If a slink:VkMemoryBarrier2KHR structure is included in the pname:pNext 3807chain, pname:srcStageMask, pname:dstStageMask, pname:srcAccessMask, and 3808pname:dstAccessMask parameters are ignored. 3809The synchronization and access scopes instead are defined by the parameters 3810of slink:VkMemoryBarrier2KHR. 3811endif::VK_KHR_synchronization2[] 3812 3813.Valid Usage 3814**** 3815:stageMaskName: srcStageMask 3816include::{chapters}/commonvalidity/stage_mask_common.txt[] 3817 3818:stageMaskName: dstStageMask 3819include::{chapters}/commonvalidity/stage_mask_common.txt[] 3820 3821 * [[VUID-VkSubpassDependency2-srcSubpass-03084]] 3822 pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless 3823 one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies 3824 and ensure a valid execution order 3825 * [[VUID-VkSubpassDependency2-srcSubpass-03085]] 3826 pname:srcSubpass and pname:dstSubpass must: not both be equal to 3827 ename:VK_SUBPASS_EXTERNAL 3828 * [[VUID-VkSubpassDependency2-srcSubpass-03087]] 3829 If pname:srcSubpass is equal to pname:dstSubpass and not all of the 3830 stages in pname:srcStageMask and pname:dstStageMask are 3831 <<synchronization-framebuffer-regions,framebuffer-space stages>>, the 3832 <<synchronization-pipeline-stages-order, logically latest>> pipeline 3833 stage in pname:srcStageMask must: be 3834 <<synchronization-pipeline-stages-order, logically earlier>> than or 3835 equal to the <<synchronization-pipeline-stages-order, logically 3836 earliest>> pipeline stage in pname:dstStageMask 3837 * [[VUID-VkSubpassDependency2-srcAccessMask-03088]] 3838 Any access flag included in pname:srcAccessMask must: be supported by 3839 one of the pipeline stages in pname:srcStageMask, as specified in the 3840 <<synchronization-access-types-supported, table of supported access 3841 types>> 3842 * [[VUID-VkSubpassDependency2-dstAccessMask-03089]] 3843 Any access flag included in pname:dstAccessMask must: be supported by 3844 one of the pipeline stages in pname:dstStageMask, as specified in the 3845 <<synchronization-access-types-supported, table of supported access 3846 types>> 3847 * [[VUID-VkSubpassDependency2-dependencyFlags-03090]] 3848 If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, 3849 pname:srcSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL 3850 * [[VUID-VkSubpassDependency2-dependencyFlags-03091]] 3851 If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, 3852 pname:dstSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL 3853 * [[VUID-VkSubpassDependency2-srcSubpass-02245]] 3854 If pname:srcSubpass equals pname:dstSubpass, and pname:srcStageMask and 3855 pname:dstStageMask both include a 3856 <<synchronization-framebuffer-regions,framebuffer-space stage>>, then 3857 pname:dependencyFlags must: include ename:VK_DEPENDENCY_BY_REGION_BIT 3858 * [[VUID-VkSubpassDependency2-viewOffset-02530]] 3859 If pname:viewOffset is not equal to `0`, pname:srcSubpass must: not be 3860 equal to pname:dstSubpass 3861 * [[VUID-VkSubpassDependency2-dependencyFlags-03092]] 3862 If pname:dependencyFlags does not include 3863 ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, pname:viewOffset must: be `0` 3864**** 3865 3866include::{generated}/validity/structs/VkSubpassDependency2.txt[] 3867-- 3868endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 3869 3870[open,refpage='vkDestroyRenderPass',desc='Destroy a render pass object',type='protos'] 3871-- 3872To destroy a render pass, call: 3873 3874include::{generated}/api/protos/vkDestroyRenderPass.txt[] 3875 3876 * pname:device is the logical device that destroys the render pass. 3877 * pname:renderPass is the handle of the render pass to destroy. 3878 * pname:pAllocator controls host memory allocation as described in the 3879 <<memory-allocation, Memory Allocation>> chapter. 3880 3881.Valid Usage 3882**** 3883 * [[VUID-vkDestroyRenderPass-renderPass-00873]] 3884 All submitted commands that refer to pname:renderPass must: have 3885 completed execution 3886 * [[VUID-vkDestroyRenderPass-renderPass-00874]] 3887 If sname:VkAllocationCallbacks were provided when pname:renderPass was 3888 created, a compatible set of callbacks must: be provided here 3889 * [[VUID-vkDestroyRenderPass-renderPass-00875]] 3890 If no sname:VkAllocationCallbacks were provided when pname:renderPass 3891 was created, pname:pAllocator must: be `NULL` 3892**** 3893 3894include::{generated}/validity/protos/vkDestroyRenderPass.txt[] 3895-- 3896 3897 3898[[renderpass-compatibility]] 3899== Render Pass Compatibility 3900 3901Framebuffers and graphics pipelines are created based on a specific render 3902pass object. 3903They must: only be used with that render pass object, or one compatible with 3904it. 3905 3906Two attachment references are compatible if they have matching format and 3907sample count, or are both ename:VK_ATTACHMENT_UNUSED or the pointer that 3908would contain the reference is `NULL`. 3909 3910Two arrays of attachment references are compatible if all corresponding 3911pairs of attachments are compatible. 3912If the arrays are of different lengths, attachment references not present in 3913the smaller array are treated as ename:VK_ATTACHMENT_UNUSED. 3914 3915Two render passes are compatible if their corresponding color, input, 3916resolve, and depth/stencil attachment references are compatible and if they 3917are otherwise identical except for: 3918 3919 * Initial and final image layout in attachment descriptions 3920 * Load and store operations in attachment descriptions 3921 * Image layout in attachment references 3922 3923As an additional special case, if two render passes have a single subpass, 3924the resolve attachment reference 3925ifdef::VK_KHR_depth_stencil_resolve[] 3926and depth/stencil resolve mode 3927endif::VK_KHR_depth_stencil_resolve[] 3928compatibility requirements are ignored. 3929 3930A framebuffer is compatible with a render pass if it was created using the 3931same render pass or a compatible render pass. 3932 3933 3934== Framebuffers 3935 3936[open,refpage='VkFramebuffer',desc='Opaque handle to a framebuffer object',type='handles'] 3937-- 3938Render passes operate in conjunction with _framebuffers_. 3939Framebuffers represent a collection of specific memory attachments that a 3940render pass instance uses. 3941 3942Framebuffers are represented by sname:VkFramebuffer handles: 3943 3944include::{generated}/api/handles/VkFramebuffer.txt[] 3945-- 3946 3947[open,refpage='vkCreateFramebuffer',desc='Create a new framebuffer object',type='protos'] 3948-- 3949To create a framebuffer, call: 3950 3951include::{generated}/api/protos/vkCreateFramebuffer.txt[] 3952 3953 * pname:device is the logical device that creates the framebuffer. 3954 * pname:pCreateInfo is a pointer to a slink:VkFramebufferCreateInfo 3955 structure describing additional information about framebuffer creation. 3956 * pname:pAllocator controls host memory allocation as described in the 3957 <<memory-allocation, Memory Allocation>> chapter. 3958 * pname:pFramebuffer is a pointer to a slink:VkFramebuffer handle in which 3959 the resulting framebuffer object is returned. 3960 3961.Valid Usage 3962**** 3963 * [[VUID-vkCreateFramebuffer-pCreateInfo-02777]] 3964 If pname:pCreateInfo->flags does not include 3965 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:attachmentCount is 3966 not `0`, each element of pname:pCreateInfo->pAttachments must: have been 3967 created on pname:device 3968**** 3969 3970include::{generated}/validity/protos/vkCreateFramebuffer.txt[] 3971-- 3972 3973[open,refpage='VkFramebufferCreateInfo',desc='Structure specifying parameters of a newly created framebuffer',type='structs'] 3974-- 3975The sname:VkFramebufferCreateInfo structure is defined as: 3976 3977include::{generated}/api/structs/VkFramebufferCreateInfo.txt[] 3978 3979 * pname:sType is the type of this structure. 3980 * pname:pNext is `NULL` or a pointer to a structure extending this 3981 structure. 3982 * pname:flags is a bitmask of elink:VkFramebufferCreateFlagBits 3983 * pname:renderPass is a render pass defining what render passes the 3984 framebuffer will be compatible with. 3985 See <<renderpass-compatibility,Render Pass Compatibility>> for details. 3986 * pname:attachmentCount is the number of attachments. 3987 * pname:pAttachments is a pointer to an array of slink:VkImageView 3988 handles, each of which will be used as the corresponding attachment in a 3989 render pass instance. 3990ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 3991 If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, this 3992 parameter is ignored. 3993endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 3994 * pname:width, pname:height and pname:layers define the dimensions of the 3995 framebuffer. 3996ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 3997 If the render pass uses multiview, then pname:layers must: be one and 3998 each attachment requires a number of layers that is greater than the 3999 maximum bit index set in the view mask in the subpasses in which it is 4000 used. 4001endif::VK_VERSION_1_1,VK_KHR_multiview[] 4002 4003Other than the exceptions listed below, applications must: ensure that all 4004accesses to memory that backs image subresources used as attachments in a 4005given render pass instance either happen-before the 4006<<renderpass-load-store-ops, load operations>> for those attachments, or 4007happen-after the <<renderpass-load-store-ops, store operations>> for those 4008attachments. 4009 4010[[renderpass-attachment-nonattachment]] 4011The exceptions to the general rule are: 4012 4013 * For depth/stencil attachments, an aspect can: be used separately as 4014 attachment and non-attachment if both accesses are read-only. 4015ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4016 * For depth/stencil attachments, each aspect can: be used separately as 4017 attachment and non-attachment as long as the non-attachment accesses are 4018 also via an image subresource in either the 4019 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL layout 4020 or the ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 4021 layout, and the attachment resource uses whichever of those two layouts 4022 the image accesses do not. 4023endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4024 4025Use of non-attachment aspects in these cases is only well defined if the 4026attachment is used in the subpass where the non-attachment access is being 4027made, or the layout of the image subresource is constant throughout the 4028entire render pass instance, including the pname:initialLayout and 4029pname:finalLayout. 4030 4031[NOTE] 4032.Note 4033==== 4034ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4035This restriction means 4036endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4037ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4038These restrictions mean 4039endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4040that the render pass has full knowledge of all uses of all of the 4041attachments, so that the implementation is able to make correct decisions 4042about when and how to perform layout transitions, when to overlap execution 4043of subpasses, etc. 4044==== 4045 4046[[renderpass-noattachments]] 4047It is legal for a subpass to use no color or depth/stencil attachments, 4048either because it has no attachment references or because all of them are 4049ename:VK_ATTACHMENT_UNUSED. 4050This kind of subpass can: use shader side effects such as image stores and 4051atomics to produce an output. 4052In this case, the subpass continues to use the pname:width, pname:height, 4053and pname:layers of the framebuffer to define the dimensions of the 4054rendering area, and the pname:rasterizationSamples from each pipeline's 4055slink:VkPipelineMultisampleStateCreateInfo to define the number of samples 4056used in rasterization; however, if 4057slink:VkPhysicalDeviceFeatures::pname:variableMultisampleRate is 4058ename:VK_FALSE, then all pipelines to be bound with the subpass must: have 4059the same value for 4060slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples. 4061 4062.Valid Usage 4063**** 4064 * [[VUID-VkFramebufferCreateInfo-attachmentCount-00876]] 4065 If pname:renderpass is not dlink:VK_NULL_HANDLE, pname:attachmentCount 4066 must: be equal to the attachment count specified in pname:renderPass 4067 * [[VUID-VkFramebufferCreateInfo-flags-02778]] 4068 If pname:renderpass is not dlink:VK_NULL_HANDLE, pname:flags does not 4069 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and 4070 pname:attachmentCount is not `0`, pname:pAttachments must: be a valid 4071 pointer to an array of pname:attachmentCount valid slink:VkImageView 4072 handles 4073 * [[VUID-VkFramebufferCreateInfo-pAttachments-00877]] 4074 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4075 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4076 pname:pAttachments that is used as a color attachment or resolve 4077 attachment by pname:renderPass must: have been created with a 4078 pname:usage value including ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 4079 * [[VUID-VkFramebufferCreateInfo-pAttachments-02633]] 4080 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4081 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4082 pname:pAttachments that is used as a depth/stencil attachment by 4083 pname:renderPass must: have been created with a pname:usage value 4084 including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4085ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 4086 * [[VUID-VkFramebufferCreateInfo-pAttachments-02634]] 4087 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4088 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4089 pname:pAttachments that is used as a depth/stencil resolve attachment by 4090 pname:renderPass must: have been created with a pname:usage value 4091 including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4092endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 4093 * [[VUID-VkFramebufferCreateInfo-pAttachments-00879]] 4094 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderpass is 4095 not dlink:VK_NULL_HANDLE, pname:flags does not include 4096 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4097 pname:pAttachments that is used as an input attachment by 4098 pname:renderPass must: have been created with a pname:usage value 4099 including ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 4100ifdef::VK_EXT_fragment_density_map[] 4101 * [[VUID-VkFramebufferCreateInfo-pAttachments-02552]] 4102 If pname:renderpass is not dlink:VK_NULL_HANDLE, each element of 4103 pname:pAttachments that is used as a fragment density map attachment by 4104 pname:renderPass must: not have been created with a pname:flags value 4105 including ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT 4106 * [[VUID-VkFramebufferCreateInfo-renderPass-02553]] 4107 If pname:renderpass is not dlink:VK_NULL_HANDLE, pname:renderPass has a 4108 fragment density map attachment, and 4109 <<features-fragmentDensityMapNonSubsampledImages,non-subsample image 4110 feature>> is not enabled, each element of pname:pAttachments must: have 4111 been created with a pname:flags value including 4112 ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT unless that element is the 4113 fragment density map attachment 4114endif::VK_EXT_fragment_density_map[] 4115 * [[VUID-VkFramebufferCreateInfo-pAttachments-00880]] 4116 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4117 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4118 pname:pAttachments must: have been created with a elink:VkFormat value 4119 that matches the elink:VkFormat specified by the corresponding 4120 sname:VkAttachmentDescription in pname:renderPass 4121 * [[VUID-VkFramebufferCreateInfo-pAttachments-00881]] 4122 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4123 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4124 pname:pAttachments must: have been created with a pname:samples value 4125 that matches the pname:samples value specified by the corresponding 4126 sname:VkAttachmentDescription in pname:renderPass 4127 * [[VUID-VkFramebufferCreateInfo-flags-04533]] 4128 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4129 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4130 pname:pAttachments that is used as an input, color, resolve, or 4131 depth/stencil attachment by pname:renderPass must: have been created 4132 with a slink:VkImageCreateInfo::pname:width greater than or equal to 4133 pname:width 4134 * [[VUID-VkFramebufferCreateInfo-flags-04534]] 4135 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4136 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4137 pname:pAttachments that is used as an input, color, resolve, or 4138 depth/stencil attachment by pname:renderPass must: have been created 4139 with a slink:VkImageCreateInfo::pname:height greater than or equal to 4140 pname:height 4141 * [[VUID-VkFramebufferCreateInfo-flags-04535]] 4142 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4143 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4144 pname:pAttachments that is used as an input, color, resolve, or 4145 depth/stencil attachment by pname:renderPass must: have been created 4146 with a slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount 4147 greater than or equal to pname:layers 4148ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 4149 * [[VUID-VkFramebufferCreateInfo-renderPass-04536]] 4150 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderPass was 4151 specified with non-zero view masks, each element of pname:pAttachments 4152 that is used as an input, color, resolve, or depth/stencil attachment by 4153 pname:renderPass must: have a pname:layerCount greater than the index of 4154 the most significant bit set in any of those view masks 4155endif::VK_VERSION_1_1,VK_KHR_multiview[] 4156ifdef::VK_EXT_fragment_density_map[] 4157ifndef::VK_VERSION_1_1,VK_KHR_multiview[] 4158 * [[VUID-VkFramebufferCreateInfo-pAttachments-02744]] 4159 If pname:renderpass is not dlink:VK_NULL_HANDLE, an element of 4160 pname:pAttachments that is referenced by 4161 pname:fragmentDensityMapAttachment must: have a pname:layerCount equal 4162 to `1` 4163endif::VK_VERSION_1_1,VK_KHR_multiview[] 4164ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 4165 * [[VUID-VkFramebufferCreateInfo-renderPass-02746]] 4166 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderPass was 4167 specified with non-zero view masks, each element of pname:pAttachments 4168 that is referenced by pname:fragmentDensityMapAttachment must: have a 4169 pname:layerCount equal to `1` or greater than the index of the most 4170 significant bit set in any of those view masks 4171 * [[VUID-VkFramebufferCreateInfo-renderPass-02747]] 4172 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderPass was 4173 not specified with non-zero view masks, each element of 4174 pname:pAttachments that is referenced by 4175 pname:fragmentDensityMapAttachment must: have a pname:layerCount equal 4176 to `1` 4177endif::VK_VERSION_1_1,VK_KHR_multiview[] 4178 * [[VUID-VkFramebufferCreateInfo-pAttachments-02555]] 4179 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4180 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of 4181 pname:pAttachments that is referenced by 4182 pname:fragmentDensityMapAttachment must: have a width at least as large 4183 as 4184 latexmath:[\left\lceil{\frac{width}{maxFragmentDensityTexelSize_{width}}}\right\rceil] 4185 * [[VUID-VkFramebufferCreateInfo-pAttachments-02556]] 4186 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4187 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of 4188 pname:pAttachments that is referenced by 4189 pname:fragmentDensityMapAttachment must: have a height at least as large 4190 as 4191 latexmath:[\left\lceil{\frac{height}{maxFragmentDensityTexelSize_{height}}}\right\rceil] 4192endif::VK_EXT_fragment_density_map[] 4193ifdef::VK_KHR_fragment_shading_rate[] 4194ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 4195 * [[VUID-VkFramebufferCreateInfo-flags-04537]] 4196 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4197 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:renderPass 4198 was specified with non-zero view masks, each element of 4199 pname:pAttachments that is used as a 4200 <<primsrast-fragment-shading-rate-attachment,fragment shading rate 4201 attachment>> by pname:renderPass must: have a pname:layerCount that is 4202 either `1`, or greater than the index of the most significant bit set in 4203 any of those view masks 4204 * [[VUID-VkFramebufferCreateInfo-flags-04538]] 4205 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4206 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:renderPass 4207 was not specified with non-zero view masks, each element of 4208 pname:pAttachments that is used as a 4209 <<primsrast-fragment-shading-rate-attachment,fragment shading rate 4210 attachment>> by pname:renderPass must: have a pname:layerCount that is 4211 either `1`, or greater than pname:layers 4212endif::VK_VERSION_1_1,VK_KHR_multiview[] 4213 * [[VUID-VkFramebufferCreateInfo-flags-04539]] 4214 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4215 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of 4216 pname:pAttachments that is used as a 4217 <<primsrast-fragment-shading-rate-attachment, fragment shading rate 4218 attachment>> must: have a width at least as large as 4219 [eq]#{lceil}pname:width / code:texelWidth{rceil}#, where code:texelWidth 4220 is the largest value of pname:shadingRateAttachmentTexelSize.width in a 4221 slink:VkFragmentShadingRateAttachmentInfoKHR which references that 4222 attachment 4223 * [[VUID-VkFramebufferCreateInfo-flags-04540]] 4224 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4225 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of 4226 pname:pAttachments that is used as a 4227 <<primsrast-fragment-shading-rate-attachment, fragment shading rate 4228 attachment>> must: have a height at least as large as 4229 [eq]#{lceil}pname:height / code:texelHeight{rceil}#, where 4230 code:texelHeight is the largest value of 4231 pname:shadingRateAttachmentTexelSize.height in a 4232 slink:VkFragmentShadingRateAttachmentInfoKHR which references that 4233 attachment 4234endif::VK_KHR_fragment_shading_rate[] 4235 * [[VUID-VkFramebufferCreateInfo-pAttachments-00883]] 4236 If pname:flags does not include 4237 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4238 pname:pAttachments must: only specify a single mip level 4239 * [[VUID-VkFramebufferCreateInfo-pAttachments-00884]] 4240 If pname:flags does not include 4241 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4242 pname:pAttachments must: have been created with the identity swizzle 4243 * [[VUID-VkFramebufferCreateInfo-width-00885]] 4244 pname:width must: be greater than `0` 4245 * [[VUID-VkFramebufferCreateInfo-width-00886]] 4246 pname:width must: be less than or equal to 4247 <<limits-maxFramebufferWidth,pname:maxFramebufferWidth>> 4248 * [[VUID-VkFramebufferCreateInfo-height-00887]] 4249 pname:height must: be greater than `0` 4250 * [[VUID-VkFramebufferCreateInfo-height-00888]] 4251 pname:height must: be less than or equal to 4252 <<limits-maxFramebufferHeight,pname:maxFramebufferHeight>> 4253 * [[VUID-VkFramebufferCreateInfo-layers-00889]] 4254 pname:layers must: be greater than `0` 4255 * [[VUID-VkFramebufferCreateInfo-layers-00890]] 4256 pname:layers must: be less than or equal to 4257 <<limits-maxFramebufferLayers,pname:maxFramebufferLayers>> 4258ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 4259 * [[VUID-VkFramebufferCreateInfo-renderPass-02531]] 4260 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderPass was 4261 specified with non-zero view masks, pname:layers must: be `1` 4262endif::VK_VERSION_1_1,VK_KHR_multiview[] 4263ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 4264 * [[VUID-VkFramebufferCreateInfo-pAttachments-00891]] 4265 If pname:flags does not include 4266 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4267 pname:pAttachments that is a 2D or 2D array image view taken from a 3D 4268 image must: not be a depth/stencil format 4269endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 4270ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4271 * [[VUID-VkFramebufferCreateInfo-flags-03189]] 4272 If the <<features-imagelessFramebuffer, imageless framebuffer>> feature 4273 is not enabled, pname:flags must: not include 4274 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT 4275 * [[VUID-VkFramebufferCreateInfo-flags-03190]] 4276 If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the 4277 pname:pNext chain must: include a 4278 slink:VkFramebufferAttachmentsCreateInfo structure 4279 * [[VUID-VkFramebufferCreateInfo-flags-03191]] 4280 If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the 4281 pname:attachmentImageInfoCount member of a 4282 slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext 4283 chain must: be equal to either zero or pname:attachmentCount 4284 * [[VUID-VkFramebufferCreateInfo-flags-04541]] 4285 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4286 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:width member of any 4287 element of the pname:pAttachmentImageInfos member of a 4288 slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext 4289 chain that is used as an input, color, resolve or depth/stencil 4290 attachment in pname:renderPass must: be greater than or equal to 4291 pname:width 4292 * [[VUID-VkFramebufferCreateInfo-flags-04542]] 4293 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4294 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:height member of 4295 any element of the pname:pAttachmentImageInfos member of a 4296 slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext 4297 chain that is used as an input, color, resolve or depth/stencil 4298 attachment in pname:renderPass must: be greater than or equal to 4299 pname:height 4300ifdef::VK_EXT_fragment_density_map[] 4301 * [[VUID-VkFramebufferCreateInfo-flags-03196]] 4302 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4303 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:width member of any 4304 element of the pname:pAttachmentImageInfos member of a 4305 slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext 4306 chain that is referenced by 4307 slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment 4308 in pname:renderPass must: be greater than or equal to 4309 latexmath:[\left\lceil{\frac{width}{maxFragmentDensityTexelSize_{width}}}\right\rceil] 4310 * [[VUID-VkFramebufferCreateInfo-flags-03197]] 4311 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4312 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:height member of 4313 any element of the pname:pAttachmentImageInfos member of a 4314 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4315 pname:pNext chain that is referenced by 4316 slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment 4317 in pname:renderPass must: be greater than or equal to 4318 latexmath:[\left\lceil{\frac{height}{maxFragmentDensityTexelSize_{height}}}\right\rceil] 4319endif::VK_EXT_fragment_density_map[] 4320ifdef::VK_KHR_fragment_shading_rate[] 4321 * [[VUID-VkFramebufferCreateInfo-flags-04543]] 4322 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4323 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:width member of any 4324 element of the pname:pAttachmentImageInfos member of a 4325 slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext 4326 chain that is used as a <<primsrast-fragment-shading-rate-attachment, 4327 fragment shading rate attachment>> must: be greater than or equal to 4328 [eq]#{lceil}pname:width / code:texelWidth{rceil}#, where code:texelWidth 4329 is the largest value of pname:shadingRateAttachmentTexelSize.width in a 4330 slink:VkFragmentShadingRateAttachmentInfoKHR which references that 4331 attachment 4332 * [[VUID-VkFramebufferCreateInfo-flags-04544]] 4333 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4334 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:height member of 4335 any element of the pname:pAttachmentImageInfos member of a 4336 slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext 4337 chain that is used as a <<primsrast-fragment-shading-rate-attachment, 4338 fragment shading rate attachment>> must: be greater than or equal to 4339 [eq]#{lceil}pname:height / code:texelHeight{rceil}#, where 4340 code:texelHeight is the largest value of 4341 pname:shadingRateAttachmentTexelSize.height in a 4342 slink:VkFragmentShadingRateAttachmentInfoKHR which references that 4343 attachment 4344 * [[VUID-VkFramebufferCreateInfo-flags-04545]] 4345 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4346 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:layerCount member 4347 of any element of the pname:pAttachmentImageInfos member of a 4348 slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext 4349 chain that is used as a <<primsrast-fragment-shading-rate-attachment, 4350 fragment shading rate attachment>> must: be either `1`, or greater than 4351 or equal to pname:layers 4352 * [[VUID-VkFramebufferCreateInfo-flags-04587]] 4353 If pname:renderpass is not dlink:VK_NULL_HANDLE, pname:flags includes 4354 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:renderPass was 4355 specified with non-zero view masks, each element of pname:pAttachments 4356 that is used as a <<primsrast-fragment-shading-rate-attachment,fragment 4357 shading rate attachment>> by pname:renderPass must: have a 4358 pname:layerCount that is either `1`, or greater than the index of the 4359 most significant bit set in any of those view masks 4360endif::VK_KHR_fragment_shading_rate[] 4361ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 4362 * [[VUID-VkFramebufferCreateInfo-renderPass-03198]] 4363 If pname:renderpass is not dlink:VK_NULL_HANDLE, multiview is enabled 4364 for pname:renderPass, and pname:flags includes 4365 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:layerCount member 4366 of any element of the pname:pAttachmentImageInfos member of a 4367 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4368 pname:pNext chain used as an input, color, resolve, or depth/stencil 4369 attachment in pname:renderPass must: be greater than the maximum bit 4370 index set in the view mask in the subpasses in which it is used in 4371 pname:renderPass 4372 * [[VUID-VkFramebufferCreateInfo-renderPass-04546]] 4373 If pname:renderpass is not dlink:VK_NULL_HANDLE, multiview is not 4374 enabled for pname:renderPass, and pname:flags includes 4375 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:layerCount member 4376 of any element of the pname:pAttachmentImageInfos member of a 4377 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4378 pname:pNext chain used as an input, color, resolve, or depth/stencil 4379 attachment in pname:renderPass must: be greater than or equal to 4380 pname:layers 4381endif::VK_VERSION_1_1,VK_KHR_multiview[] 4382ifndef::VK_VERSION_1_1+VK_KHR_multiview[] 4383 * [[VUID-VkFramebufferCreateInfo-flags-04547]] 4384 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4385 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:layerCount member 4386 of any element of the pname:pAttachmentImageInfos member of a 4387 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4388 pname:pNext chain used as an input, color, resolve, or depth/stencil 4389 attachment in pname:pRenderPass must: be greater than or equal to 4390 pname:layers 4391endif::VK_VERSION_1_1+VK_KHR_multiview[] 4392 * [[VUID-VkFramebufferCreateInfo-flags-03201]] 4393 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4394 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any 4395 element of the pname:pAttachmentImageInfos member of a 4396 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4397 pname:pNext chain that refers to an attachment used as a color 4398 attachment or resolve attachment by pname:renderPass must: include 4399 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 4400 * [[VUID-VkFramebufferCreateInfo-flags-03202]] 4401 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4402 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any 4403 element of the pname:pAttachmentImageInfos member of a 4404 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4405 pname:pNext chain that refers to an attachment used as a depth/stencil 4406 attachment by pname:renderPass must: include 4407 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4408ifdef::VK_KHR_depth_stencil_resolve[] 4409 * [[VUID-VkFramebufferCreateInfo-flags-03203]] 4410 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4411 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any 4412 element of the pname:pAttachmentImageInfos member of a 4413 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4414 pname:pNext chain that refers to an attachment used as a depth/stencil 4415 resolve attachment by pname:renderPass must: include 4416 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4417endif::VK_KHR_depth_stencil_resolve[] 4418 * [[VUID-VkFramebufferCreateInfo-flags-03204]] 4419 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4420 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any 4421 element of the pname:pAttachmentImageInfos member of a 4422 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4423 pname:pNext chain that refers to an attachment used as an input 4424 attachment by pname:renderPass must: include 4425 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 4426 * [[VUID-VkFramebufferCreateInfo-flags-03205]] 4427 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4428 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, at least one element of the 4429 pname:pViewFormats member of any element of the 4430 pname:pAttachmentImageInfos member of a 4431 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4432 pname:pNext chain must: be equal to the corresponding value of 4433 slink:VkAttachmentDescription::pname:format used to create 4434 pname:renderPass 4435endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4436 * [[VUID-VkFramebufferCreateInfo-flags-04113]] 4437 If pname:flags does not include 4438 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4439 pname:pAttachments must: have been created with 4440 slink:VkImageViewCreateInfo::pname:viewType not equal to 4441 ename:VK_IMAGE_VIEW_TYPE_3D 4442ifdef::VK_KHR_fragment_shading_rate[] 4443 * [[VUID-VkFramebufferCreateInfo-flags-04548]] 4444 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not 4445 include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of 4446 pname:pAttachments that is used as a fragment shading rate attachment by 4447 pname:renderPass must: have been created with a pname:usage value 4448 including ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 4449ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4450 * [[VUID-VkFramebufferCreateInfo-flags-04549]] 4451 If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes 4452 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any 4453 element of the pname:pAttachmentImageInfos member of a 4454 slink:VkFramebufferAttachmentsCreateInfo structure included in the 4455 pname:pNext chain that refers to an attachment used as a fragment 4456 shading rate attachment by pname:renderPass must: include 4457 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 4458endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4459endif::VK_KHR_fragment_shading_rate[] 4460**** 4461 4462include::{generated}/validity/structs/VkFramebufferCreateInfo.txt[] 4463-- 4464 4465ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4466[open,refpage='VkFramebufferAttachmentsCreateInfo',desc='Structure specifying parameters of images that will be used with a framebuffer',type='structs',alias='VkFramebufferAttachmentsCreateInfo'] 4467-- 4468The sname:VkFramebufferAttachmentsCreateInfo structure is defined as: 4469 4470include::{generated}/api/structs/VkFramebufferAttachmentsCreateInfo.txt[] 4471 4472ifdef::VK_KHR_imageless_framebuffer[] 4473or the equivalent 4474 4475include::{generated}/api/structs/VkFramebufferAttachmentsCreateInfoKHR.txt[] 4476endif::VK_KHR_imageless_framebuffer[] 4477 4478 * pname:sType is the type of this structure. 4479 * pname:pNext is `NULL` or a pointer to a structure extending this 4480 structure. 4481 * pname:attachmentImageInfoCount is the number of attachments being 4482 described. 4483 * pname:pAttachmentImageInfos is a pointer to an array of 4484 slink:VkFramebufferAttachmentImageInfo structures, each structure 4485 describing a number of parameters of the corresponding attachment in a 4486 render pass instance. 4487 4488include::{generated}/validity/structs/VkFramebufferAttachmentsCreateInfo.txt[] 4489-- 4490 4491[open,refpage='VkFramebufferAttachmentImageInfo',desc='Structure specifying parameters of an image that will be used with a framebuffer',type='structs',alias='VkFramebufferAttachmentImageInfoKHR'] 4492-- 4493The sname:VkFramebufferAttachmentImageInfo structure is defined as: 4494 4495include::{generated}/api/structs/VkFramebufferAttachmentImageInfo.txt[] 4496 4497ifdef::VK_KHR_imageless_framebuffer[] 4498or the equivalent 4499 4500include::{generated}/api/structs/VkFramebufferAttachmentImageInfoKHR.txt[] 4501endif::VK_KHR_imageless_framebuffer[] 4502 4503 4504 * pname:sType is the type of this structure. 4505 * pname:pNext is `NULL` or a pointer to a structure extending this 4506 structure. 4507 * pname:flags is a bitmask of elink:VkImageCreateFlagBits, matching the 4508 value of slink:VkImageCreateInfo::pname:flags used to create an image 4509 that will be used with this framebuffer. 4510 * pname:usage is a bitmask of elink:VkImageUsageFlagBits, matching the 4511 value of slink:VkImageCreateInfo::pname:usage used to create an image 4512 used with this framebuffer. 4513 * pname:width is the width of the image view used for rendering. 4514 * pname:height is the height of the image view used for rendering. 4515 * pname:layerCount is the number of array layers of the image view used 4516 for rendering. 4517 * pname:viewFormatCount is the number of entries in the pname:pViewFormats 4518 array, matching the value of 4519 slink:VkImageFormatListCreateInfo::pname:viewFormatCount used to create 4520 an image used with this framebuffer. 4521 * pname:pViewFormats is a pointer to an array of elink:VkFormat values 4522 specifying all of the formats which can: be used when creating views of 4523 the image, matching the value of 4524 slink:VkImageFormatListCreateInfo::pname:pViewFormats used to create an 4525 image used with this framebuffer. 4526 4527Images that can: be used with the framebuffer when beginning a render pass, 4528as specified by slink:VkRenderPassAttachmentBeginInfo, must: be created with 4529parameters that are identical to those specified here. 4530 4531 4532include::{generated}/validity/structs/VkFramebufferAttachmentImageInfo.txt[] 4533-- 4534endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4535 4536 4537[open,refpage='VkFramebufferCreateFlagBits',desc='Bitmask specifying framebuffer properties',type='enums'] 4538-- 4539Bits which can: be set in slink:VkFramebufferCreateInfo::pname:flags to 4540specify options for framebuffers are: 4541 4542include::{generated}/api/enums/VkFramebufferCreateFlagBits.txt[] 4543 4544ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4545 * ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT specifies that image views are 4546 not specified, and only attachment compatibility information will be 4547 provided via a slink:VkFramebufferAttachmentImageInfo structure. 4548endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4549 4550ifndef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4551[NOTE] 4552.Note 4553==== 4554All bits for this type are defined by extensions, and none of those 4555extensions are enabled in this build of the specification. 4556==== 4557endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 4558-- 4559 4560[open,refpage='VkFramebufferCreateFlags',desc='Bitmask of VkFramebufferCreateFlagBits',type='flags'] 4561-- 4562include::{generated}/api/flags/VkFramebufferCreateFlags.txt[] 4563 4564tname:VkFramebufferCreateFlags is a bitmask type for setting a mask of zero 4565or more elink:VkFramebufferCreateFlagBits. 4566-- 4567 4568[open,refpage='vkDestroyFramebuffer',desc='Destroy a framebuffer object',type='protos'] 4569-- 4570To destroy a framebuffer, call: 4571 4572include::{generated}/api/protos/vkDestroyFramebuffer.txt[] 4573 4574 * pname:device is the logical device that destroys the framebuffer. 4575 * pname:framebuffer is the handle of the framebuffer to destroy. 4576 * pname:pAllocator controls host memory allocation as described in the 4577 <<memory-allocation, Memory Allocation>> chapter. 4578 4579.Valid Usage 4580**** 4581 * [[VUID-vkDestroyFramebuffer-framebuffer-00892]] 4582 All submitted commands that refer to pname:framebuffer must: have 4583 completed execution 4584 * [[VUID-vkDestroyFramebuffer-framebuffer-00893]] 4585 If sname:VkAllocationCallbacks were provided when pname:framebuffer was 4586 created, a compatible set of callbacks must: be provided here 4587 * [[VUID-vkDestroyFramebuffer-framebuffer-00894]] 4588 If no sname:VkAllocationCallbacks were provided when pname:framebuffer 4589 was created, pname:pAllocator must: be `NULL` 4590**** 4591 4592include::{generated}/validity/protos/vkDestroyFramebuffer.txt[] 4593-- 4594 4595 4596[[renderpass-commands]] 4597== Render Pass Commands 4598 4599An application records the commands for a render pass instance one subpass 4600at a time, by beginning a render pass instance, iterating over the subpasses 4601to record commands for that subpass, and then ending the render pass 4602instance. 4603 4604[open,refpage='vkCmdBeginRenderPass',desc='Begin a new render pass',type='protos'] 4605-- 4606To begin a render pass instance, call: 4607 4608include::{generated}/api/protos/vkCmdBeginRenderPass.txt[] 4609 4610 * pname:commandBuffer is the command buffer in which to record the 4611 command. 4612 * pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo 4613 structure specifying the render pass to begin an instance of, and the 4614 framebuffer the instance uses. 4615 * pname:contents is a elink:VkSubpassContents value specifying how the 4616 commands in the first subpass will be provided. 4617 4618After beginning a render pass instance, the command buffer is ready to 4619record the commands for the first subpass of that render pass. 4620 4621.Valid Usage 4622**** 4623 * [[VUID-vkCmdBeginRenderPass-initialLayout-00895]] 4624 If any of the pname:initialLayout or pname:finalLayout member of the 4625 sname:VkAttachmentDescription structures or the pname:layout member of 4626 the sname:VkAttachmentReference structures specified when creating the 4627 render pass specified in the pname:renderPass member of 4628 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 4629 then the corresponding attachment image view of the framebuffer 4630 specified in the pname:framebuffer member of pname:pRenderPassBegin 4631 must: have been created with a pname:usage value including 4632 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 4633// The VU below comes in an alternate version when the extension is 4634// enabled. 4635ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4636 * [[VUID-vkCmdBeginRenderPass-initialLayout-00896]] 4637 If any of the pname:initialLayout or pname:finalLayout member of the 4638 sname:VkAttachmentDescription structures or the pname:layout member of 4639 the sname:VkAttachmentReference structures specified when creating the 4640 render pass specified in the pname:renderPass member of 4641 pname:pRenderPassBegin is 4642 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or 4643 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the 4644 corresponding attachment image view of the framebuffer specified in the 4645 pname:framebuffer member of pname:pRenderPassBegin must: have been 4646 created with a pname:usage value including 4647 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4648endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4649// The nested ifdefs are there in anticipation of the hoped-for day when the 4650// VU extractor and validation layers can handle VU with imbedded 4651// conditionals. They are commented out until then. 4652ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4653 * [[VUID-vkCmdBeginRenderPass-initialLayout-01758]] 4654 If any of the pname:initialLayout or pname:finalLayout member of the 4655 sname:VkAttachmentDescription structures or the pname:layout member of 4656 the sname:VkAttachmentReference structures specified when creating the 4657 render pass specified in the pname:renderPass member of 4658 pname:pRenderPassBegin is 4659// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4660 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 4661 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 4662// endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4663 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or 4664 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the 4665 corresponding attachment image view of the framebuffer specified in the 4666 pname:framebuffer member of pname:pRenderPassBegin must: have been 4667 created with a pname:usage value including 4668 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4669ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4670 * [[VUID-vkCmdBeginRenderPass-initialLayout-02842]] 4671 If any of the pname:initialLayout or pname:finalLayout member of the 4672 sname:VkAttachmentDescription structures or the pname:layout member of 4673 the sname:VkAttachmentReference structures specified when creating the 4674 render pass specified in the pname:renderPass member of 4675 pname:pRenderPassBegin is 4676 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or 4677 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 4678 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 4679 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding 4680 attachment image view of the framebuffer specified in the 4681 pname:framebuffer member of pname:pRenderPassBegin must: have been 4682 created with a pname:usage value including 4683 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4684 * [[VUID-vkCmdBeginRenderPass-stencilInitialLayout-02843]] 4685 If any of the pname:stencilInitialLayout or pname:stencilFinalLayout 4686 member of the sname:VkAttachmentDescriptionStencilLayout structures or 4687 the pname:stencilLayout member of the 4688 sname:VkAttachmentReferenceStencilLayout structures specified when 4689 creating the render pass specified in the pname:renderPass member of 4690 pname:pRenderPassBegin is 4691 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 4692 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding 4693 attachment image view of the framebuffer specified in the 4694 pname:framebuffer member of pname:pRenderPassBegin must: have been 4695 created with a pname:usage value including 4696 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4697endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4698endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4699 * [[VUID-vkCmdBeginRenderPass-initialLayout-00897]] 4700 If any of the pname:initialLayout or pname:finalLayout member of the 4701 sname:VkAttachmentDescription structures or the pname:layout member of 4702 the sname:VkAttachmentReference structures specified when creating the 4703 render pass specified in the pname:renderPass member of 4704 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 4705 then the corresponding attachment image view of the framebuffer 4706 specified in the pname:framebuffer member of pname:pRenderPassBegin 4707 must: have been created with a pname:usage value including 4708 ename:VK_IMAGE_USAGE_SAMPLED_BIT or 4709 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 4710 * [[VUID-vkCmdBeginRenderPass-initialLayout-00898]] 4711 If any of the pname:initialLayout or pname:finalLayout member of the 4712 sname:VkAttachmentDescription structures or the pname:layout member of 4713 the sname:VkAttachmentReference structures specified when creating the 4714 render pass specified in the pname:renderPass member of 4715 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL 4716 then the corresponding attachment image view of the framebuffer 4717 specified in the pname:framebuffer member of pname:pRenderPassBegin 4718 must: have been created with a pname:usage value including 4719 ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT 4720 * [[VUID-vkCmdBeginRenderPass-initialLayout-00899]] 4721 If any of the pname:initialLayout or pname:finalLayout member of the 4722 sname:VkAttachmentDescription structures or the pname:layout member of 4723 the sname:VkAttachmentReference structures specified when creating the 4724 render pass specified in the pname:renderPass member of 4725 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL 4726 then the corresponding attachment image view of the framebuffer 4727 specified in the pname:framebuffer member of pname:pRenderPassBegin 4728 must: have been created with a pname:usage value including 4729 ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT 4730 * [[VUID-vkCmdBeginRenderPass-initialLayout-00900]] 4731 If the pname:initialLayout member of any of the 4732 sname:VkAttachmentDescription structures specified when creating the 4733 render pass specified in the pname:renderPass member of 4734 pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each 4735 such pname:initialLayout must: be equal to the current layout of the 4736 corresponding attachment image subresource of the framebuffer specified 4737 in the pname:framebuffer member of pname:pRenderPassBegin 4738 * [[VUID-vkCmdBeginRenderPass-srcStageMask-06451]] 4739 The pname:srcStageMask members of any element of the pname:pDependencies 4740 member of slink:VkRenderPassCreateInfo used to create pname:renderPass 4741 must: be supported by the capabilities of the queue family identified by 4742 the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo 4743 used to create the command pool which pname:commandBuffer was allocated 4744 from 4745 * [[VUID-vkCmdBeginRenderPass-dstStageMask-06452]] 4746 The pname:dstStageMask members of any element of the pname:pDependencies 4747 member of slink:VkRenderPassCreateInfo used to create pname:renderPass 4748 must: be supported by the capabilities of the queue family identified by 4749 the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo 4750 used to create the command pool which pname:commandBuffer was allocated 4751 from 4752 * [[VUID-vkCmdBeginRenderPass-framebuffer-02532]] 4753 For any attachment in pname:framebuffer that is used by pname:renderPass 4754 and is bound to memory locations that are also bound to another 4755 attachment used by pname:renderPass, and if at least one of those uses 4756 causes either attachment to be written to, both attachments must: have 4757 had the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set 4758**** 4759 4760include::{generated}/validity/protos/vkCmdBeginRenderPass.txt[] 4761-- 4762 4763ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 4764[open,refpage='vkCmdBeginRenderPass2',desc='Begin a new render pass',type='protos',alias='vkCmdBeginRenderPass2KHR'] 4765-- 4766Alternatively to begin a render pass, call: 4767 4768ifdef::VK_VERSION_1_2[] 4769include::{generated}/api/protos/vkCmdBeginRenderPass2.txt[] 4770endif::VK_VERSION_1_2[] 4771 4772ifdef::VK_VERSION_1_2+VK_KHR_create_renderpass2[or the equivalent command] 4773 4774ifdef::VK_KHR_create_renderpass2[] 4775include::{generated}/api/protos/vkCmdBeginRenderPass2KHR.txt[] 4776endif::VK_KHR_create_renderpass2[] 4777 4778 * pname:commandBuffer is the command buffer in which to record the 4779 command. 4780 * pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo 4781 structure specifying the render pass to begin an instance of, and the 4782 framebuffer the instance uses. 4783 * pname:pSubpassBeginInfo is a pointer to a slink:VkSubpassBeginInfo 4784 structure containing information about the subpass which is about to 4785 begin rendering. 4786 4787After beginning a render pass instance, the command buffer is ready to 4788record the commands for the first subpass of that render pass. 4789 4790.Valid Usage 4791**** 4792 * [[VUID-vkCmdBeginRenderPass2-framebuffer-02779]] 4793 Both the pname:framebuffer and pname:renderPass members of 4794 pname:pRenderPassBegin must: have been created on the same 4795 slink:VkDevice that pname:commandBuffer was allocated on 4796 * [[VUID-vkCmdBeginRenderPass2-initialLayout-03094]] 4797 If any of the pname:initialLayout or pname:finalLayout member of the 4798 sname:VkAttachmentDescription structures or the pname:layout member of 4799 the sname:VkAttachmentReference structures specified when creating the 4800 render pass specified in the pname:renderPass member of 4801 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL 4802 then the corresponding attachment image view of the framebuffer 4803 specified in the pname:framebuffer member of pname:pRenderPassBegin 4804 must: have been created with a pname:usage value including 4805 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 4806 * [[VUID-vkCmdBeginRenderPass2-initialLayout-03096]] 4807 If any of the pname:initialLayout or pname:finalLayout member of the 4808 sname:VkAttachmentDescription structures or the pname:layout member of 4809 the sname:VkAttachmentReference structures specified when creating the 4810 render pass specified in the pname:renderPass member of 4811 pname:pRenderPassBegin is 4812 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 4813 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 4814 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or 4815 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the 4816 corresponding attachment image view of the framebuffer specified in the 4817 pname:framebuffer member of pname:pRenderPassBegin must: have been 4818 created with a pname:usage value including 4819 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4820ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4821 * [[VUID-vkCmdBeginRenderPass2-initialLayout-02844]] 4822 If any of the pname:initialLayout or pname:finalLayout member of the 4823 sname:VkAttachmentDescription structures or the pname:layout member of 4824 the sname:VkAttachmentReference structures specified when creating the 4825 render pass specified in the pname:renderPass member of 4826 pname:pRenderPassBegin is 4827 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or 4828 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 4829 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 4830 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding 4831 attachment image view of the framebuffer specified in the 4832 pname:framebuffer member of pname:pRenderPassBegin must: have been 4833 created with a pname:usage value including 4834 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4835 * [[VUID-vkCmdBeginRenderPass2-stencilInitialLayout-02845]] 4836 If any of the pname:stencilInitialLayout or pname:stencilFinalLayout 4837 member of the sname:VkAttachmentDescriptionStencilLayout structures or 4838 the pname:stencilLayout member of the 4839 sname:VkAttachmentReferenceStencilLayout structures specified when 4840 creating the render pass specified in the pname:renderPass member of 4841 pname:pRenderPassBegin is 4842 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or 4843 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding 4844 attachment image view of the framebuffer specified in the 4845 pname:framebuffer member of pname:pRenderPassBegin must: have been 4846 created with a pname:usage value including 4847 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 4848endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4849 * [[VUID-vkCmdBeginRenderPass2-initialLayout-03097]] 4850 If any of the pname:initialLayout or pname:finalLayout member of the 4851 sname:VkAttachmentDescription structures or the pname:layout member of 4852 the sname:VkAttachmentReference structures specified when creating the 4853 render pass specified in the pname:renderPass member of 4854 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 4855 then the corresponding attachment image view of the framebuffer 4856 specified in the pname:framebuffer member of pname:pRenderPassBegin 4857 must: have been created with a pname:usage value including 4858 ename:VK_IMAGE_USAGE_SAMPLED_BIT or 4859 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 4860 * [[VUID-vkCmdBeginRenderPass2-initialLayout-03098]] 4861 If any of the pname:initialLayout or pname:finalLayout member of the 4862 sname:VkAttachmentDescription structures or the pname:layout member of 4863 the sname:VkAttachmentReference structures specified when creating the 4864 render pass specified in the pname:renderPass member of 4865 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL 4866 then the corresponding attachment image view of the framebuffer 4867 specified in the pname:framebuffer member of pname:pRenderPassBegin 4868 must: have been created with a pname:usage value including 4869 ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT 4870 * [[VUID-vkCmdBeginRenderPass2-initialLayout-03099]] 4871 If any of the pname:initialLayout or pname:finalLayout member of the 4872 sname:VkAttachmentDescription structures or the pname:layout member of 4873 the sname:VkAttachmentReference structures specified when creating the 4874 render pass specified in the pname:renderPass member of 4875 pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL 4876 then the corresponding attachment image view of the framebuffer 4877 specified in the pname:framebuffer member of pname:pRenderPassBegin 4878 must: have been created with a pname:usage value including 4879 ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT 4880 * [[VUID-vkCmdBeginRenderPass2-initialLayout-03100]] 4881 If the pname:initialLayout member of any of the 4882 sname:VkAttachmentDescription structures specified when creating the 4883 render pass specified in the pname:renderPass member of 4884 pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each 4885 such pname:initialLayout must: be equal to the current layout of the 4886 corresponding attachment image subresource of the framebuffer specified 4887 in the pname:framebuffer member of pname:pRenderPassBegin 4888 * [[VUID-vkCmdBeginRenderPass2-srcStageMask-06453]] 4889 The pname:srcStageMask members of any element of the pname:pDependencies 4890 member of slink:VkRenderPassCreateInfo used to create pname:renderPass 4891 must: be supported by the capabilities of the queue family identified by 4892 the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo 4893 used to create the command pool which pname:commandBuffer was allocated 4894 from 4895 * [[VUID-vkCmdBeginRenderPass2-dstStageMask-06454]] 4896 The pname:dstStageMask members of any element of the pname:pDependencies 4897 member of slink:VkRenderPassCreateInfo used to create pname:renderPass 4898 must: be supported by the capabilities of the queue family identified by 4899 the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo 4900 used to create the command pool which pname:commandBuffer was allocated 4901 from 4902 * [[VUID-vkCmdBeginRenderPass2-framebuffer-02533]] 4903 For any attachment in pname:framebuffer that is used by pname:renderPass 4904 and is bound to memory locations that are also bound to another 4905 attachment used by pname:renderPass, and if at least one of those uses 4906 causes either attachment to be written to, both attachments must: have 4907 had the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set 4908**** 4909 4910include::{generated}/validity/protos/vkCmdBeginRenderPass2.txt[] 4911-- 4912endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 4913 4914[open,refpage='VkRenderPassBeginInfo',desc='Structure specifying render pass begin information',type='structs'] 4915-- 4916The sname:VkRenderPassBeginInfo structure is defined as: 4917 4918include::{generated}/api/structs/VkRenderPassBeginInfo.txt[] 4919 4920 * pname:sType is the type of this structure. 4921 * pname:pNext is `NULL` or a pointer to a structure extending this 4922 structure. 4923 * pname:renderPass is the render pass to begin an instance of. 4924 * pname:framebuffer is the framebuffer containing the attachments that are 4925 used with the render pass. 4926 * pname:renderArea is the render area that is affected by the render pass 4927 instance, and is described in more detail below. 4928 * pname:clearValueCount is the number of elements in pname:pClearValues. 4929 * pname:pClearValues is a pointer to an array of pname:clearValueCount 4930 slink:VkClearValue structures containing clear values for each 4931 attachment, if the attachment uses a pname:loadOp value of 4932 ename:VK_ATTACHMENT_LOAD_OP_CLEAR or if the attachment has a 4933 depth/stencil format and uses a pname:stencilLoadOp value of 4934 ename:VK_ATTACHMENT_LOAD_OP_CLEAR. 4935 The array is indexed by attachment number. 4936 Only elements corresponding to cleared attachments are used. 4937 Other elements of pname:pClearValues are ignored. 4938 4939pname:renderArea is the render area that is affected by the render pass 4940instance. 4941The effects of attachment load, store and multisample resolve operations are 4942restricted to the pixels whose x and y coordinates fall within the render 4943area on all attachments. 4944The render area extends to all layers of pname:framebuffer. 4945The application must: ensure (using scissor if necessary) that all rendering 4946is contained within the render area. 4947ifndef::VK_QCOM_render_pass_transform[] 4948The render area must: be contained within the framebuffer dimensions. 4949endif::VK_QCOM_render_pass_transform[] 4950ifdef::VK_QCOM_render_pass_transform[] 4951The render area, after any transform specified by 4952slink:VkRenderPassTransformBeginInfoQCOM::pname:transform is applied, must: 4953be contained within the framebuffer dimensions. 4954endif::VK_QCOM_render_pass_transform[] 4955 4956ifdef::VK_QCOM_render_pass_transform[] 4957If <<vertexpostproc-renderpass-transform, render pass transform>> is 4958enabled, then pname:renderArea must: equal the framebuffer pre-transformed 4959dimensions. 4960After pname:renderArea has been transformed by 4961slink:VkRenderPassTransformBeginInfoQCOM::pname:transform, the resulting 4962render area must: be equal to the framebuffer dimensions. 4963endif::VK_QCOM_render_pass_transform[] 4964 4965ifdef::VK_HUAWEI_subpass_shading[] 4966If <<features-subpassShading, subpass shading>> is enabled, then 4967pname:renderArea must: equal the framebuffer dimensions. 4968endif::VK_HUAWEI_subpass_shading[] 4969 4970ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 4971 4972When multiview is enabled, the resolve operation at the end of a subpass 4973applies to all views in the view mask. 4974 4975endif::VK_VERSION_1_1,VK_KHR_multiview[] 4976 4977[NOTE] 4978.Note 4979==== 4980There may: be a performance cost for using a render area smaller than the 4981framebuffer, unless it matches the render area granularity for the render 4982pass. 4983==== 4984 4985.Valid Usage 4986**** 4987 * [[VUID-VkRenderPassBeginInfo-clearValueCount-00902]] 4988 pname:clearValueCount must: be greater than the largest attachment index 4989 in pname:renderPass specifying a pname:loadOp (or pname:stencilLoadOp, 4990 if the attachment has a depth/stencil format) of 4991 ename:VK_ATTACHMENT_LOAD_OP_CLEAR 4992 * [[VUID-VkRenderPassBeginInfo-clearValueCount-04962]] 4993 If pname:clearValueCount is not `0`, pname:pClearValues must: be a valid 4994 pointer to an array of pname:clearValueCount slink:VkClearValue unions 4995 * [[VUID-VkRenderPassBeginInfo-renderPass-00904]] 4996 pname:renderPass must: be <<renderpass-compatibility,compatible>> with 4997 the pname:renderPass member of the slink:VkFramebufferCreateInfo 4998 structure specified when creating pname:framebuffer 4999ifndef::VK_VERSION_1_1,VK_KHR_device_group[] 5000 * [[VUID-VkRenderPassBeginInfo-renderArea-02846]] 5001 pname:renderArea.offset.x must: be greater than or equal to 0 5002 * [[VUID-VkRenderPassBeginInfo-renderArea-02847]] 5003 pname:renderArea.offset.y must: be greater than or equal to 0 5004 * [[VUID-VkRenderPassBeginInfo-renderArea-02848]] 5005 [eq]#pname:renderArea.offset.x {plus} pname:renderArea.extent.width# 5006 must: be less than or equal to 5007 slink:VkFramebufferCreateInfo::pname:width the pname:framebuffer was 5008 created with 5009 * [[VUID-VkRenderPassBeginInfo-renderArea-02849]] 5010 [eq]#pname:renderArea.offset.y {plus} pname:renderArea.extent.height# 5011 must: be less than or equal to 5012 slink:VkFramebufferCreateInfo::pname:height the pname:framebuffer was 5013 created with 5014endif::VK_VERSION_1_1,VK_KHR_device_group[] 5015ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5016 * [[VUID-VkRenderPassBeginInfo-pNext-02850]] 5017 If the pname:pNext chain does not contain 5018 slink:VkDeviceGroupRenderPassBeginInfo or its 5019 pname:deviceRenderAreaCount member is equal to 0, 5020 pname:renderArea.offset.x must: be greater than or equal to 0 5021 * [[VUID-VkRenderPassBeginInfo-pNext-02851]] 5022 If the pname:pNext chain does not contain 5023 slink:VkDeviceGroupRenderPassBeginInfo or its 5024 pname:deviceRenderAreaCount member is equal to 0, 5025 pname:renderArea.offset.y must: be greater than or equal to 0 5026 * [[VUID-VkRenderPassBeginInfo-pNext-02852]] 5027 If the pname:pNext chain does not contain 5028 slink:VkDeviceGroupRenderPassBeginInfo or its 5029 pname:deviceRenderAreaCount member is equal to 0, 5030 [eq]#pname:renderArea.offset.x {plus} pname:renderArea.extent.width# 5031 must: be less than or equal to 5032 slink:VkFramebufferCreateInfo::pname:width the pname:framebuffer was 5033 created with 5034 * [[VUID-VkRenderPassBeginInfo-pNext-02853]] 5035 If the pname:pNext chain does not contain 5036 slink:VkDeviceGroupRenderPassBeginInfo or its 5037 pname:deviceRenderAreaCount member is equal to 0, 5038 [eq]#pname:renderArea.offset.y {plus} pname:renderArea.extent.height# 5039 must: be less than or equal to 5040 slink:VkFramebufferCreateInfo::pname:height the pname:framebuffer was 5041 created with 5042 * [[VUID-VkRenderPassBeginInfo-pNext-02856]] 5043 If the pname:pNext chain contains 5044 slink:VkDeviceGroupRenderPassBeginInfo, [eq]#pname:offset.x {plus} 5045 pname:extent.width# of each element of pname:pDeviceRenderAreas must: be 5046 less than or equal to slink:VkFramebufferCreateInfo::pname:width the 5047 pname:framebuffer was created with 5048 * [[VUID-VkRenderPassBeginInfo-pNext-02857]] 5049 If the pname:pNext chain contains 5050 slink:VkDeviceGroupRenderPassBeginInfo, [eq]#pname:offset.y {plus} 5051 pname:extent.height# of each element of pname:pDeviceRenderAreas must: 5052 be less than or equal to slink:VkFramebufferCreateInfo::pname:height the 5053 pname:framebuffer was created with 5054endif::VK_VERSION_1_1,VK_KHR_device_group[] 5055ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 5056 * [[VUID-VkRenderPassBeginInfo-framebuffer-03207]] 5057 If pname:framebuffer was created with a 5058 slink:VkFramebufferCreateInfo::pname:flags value that did not include 5059 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and the pname:pNext chain 5060 includes a slink:VkRenderPassAttachmentBeginInfo structure, its 5061 pname:attachmentCount must: be zero 5062 * [[VUID-VkRenderPassBeginInfo-framebuffer-03208]] 5063 If pname:framebuffer was created with a 5064 slink:VkFramebufferCreateInfo::pname:flags value that included 5065 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:attachmentCount of 5066 a slink:VkRenderPassAttachmentBeginInfo structure included in the 5067 pname:pNext chain must: be equal to the value of 5068 slink:VkFramebufferAttachmentsCreateInfo::pname:attachmentImageInfoCount 5069 used to create pname:framebuffer 5070 * [[VUID-VkRenderPassBeginInfo-framebuffer-02780]] 5071 If pname:framebuffer was created with a 5072 slink:VkFramebufferCreateInfo::pname:flags value that included 5073 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5074 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5075 structure included in the pname:pNext chain must: have been created on 5076 the same slink:VkDevice as pname:framebuffer and pname:renderPass 5077 * [[VUID-VkRenderPassBeginInfo-framebuffer-03209]] 5078 If pname:framebuffer was created with a 5079 slink:VkFramebufferCreateInfo::pname:flags value that included 5080 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5081 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5082 structure included in the pname:pNext chain must: be a slink:VkImageView 5083 of an image created with a value of slink:VkImageCreateInfo::pname:flags 5084 equal to the pname:flags member of the corresponding element of 5085 slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos 5086 used to create pname:framebuffer 5087 * [[VUID-VkRenderPassBeginInfo-framebuffer-04627]] 5088 If pname:framebuffer was created with a 5089 slink:VkFramebufferCreateInfo::pname:flags value that included 5090 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5091 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5092 structure included in the pname:pNext chain must: be a slink:VkImageView 5093 with <<resources-image-inherited-usage, an inherited usage>> equal to 5094 the pname:usage member of the corresponding element of 5095 slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos 5096 used to create pname:framebuffer 5097 * [[VUID-VkRenderPassBeginInfo-framebuffer-03211]] 5098 If pname:framebuffer was created with a 5099 slink:VkFramebufferCreateInfo::pname:flags value that included 5100 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5101 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5102 structure included in the pname:pNext chain must: be a slink:VkImageView 5103 with a width equal to the pname:width member of the corresponding 5104 element of 5105 slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos 5106 used to create pname:framebuffer 5107 * [[VUID-VkRenderPassBeginInfo-framebuffer-03212]] 5108 If pname:framebuffer was created with a 5109 slink:VkFramebufferCreateInfo::pname:flags value that included 5110 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5111 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5112 structure included in the pname:pNext chain must: be a slink:VkImageView 5113 with a height equal to the pname:height member of the corresponding 5114 element of 5115 slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos 5116 used to create pname:framebuffer 5117 * [[VUID-VkRenderPassBeginInfo-framebuffer-03213]] 5118 If pname:framebuffer was created with a 5119 slink:VkFramebufferCreateInfo::pname:flags value that included 5120 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5121 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5122 structure included in the pname:pNext chain must: be a slink:VkImageView 5123 of an image created with a value of 5124 slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount equal to 5125 the pname:layerCount member of the corresponding element of 5126 slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos 5127 used to create pname:framebuffer 5128 * [[VUID-VkRenderPassBeginInfo-framebuffer-03214]] 5129 If pname:framebuffer was created with a 5130 slink:VkFramebufferCreateInfo::pname:flags value that included 5131 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5132 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5133 structure included in the pname:pNext chain must: be a slink:VkImageView 5134 of an image created with a value of 5135 slink:VkImageFormatListCreateInfo::pname:viewFormatCount equal to the 5136 pname:viewFormatCount member of the corresponding element of 5137 slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos 5138 used to create pname:framebuffer 5139 * [[VUID-VkRenderPassBeginInfo-framebuffer-03215]] 5140 If pname:framebuffer was created with a 5141 slink:VkFramebufferCreateInfo::pname:flags value that included 5142 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5143 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5144 structure included in the pname:pNext chain must: be a slink:VkImageView 5145 of an image created with a set of elements in 5146 slink:VkImageFormatListCreateInfo::pname:pViewFormats equal to the set 5147 of elements in the pname:pViewFormats member of the corresponding 5148 element of 5149 slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos 5150 used to create pname:framebuffer 5151 * [[VUID-VkRenderPassBeginInfo-framebuffer-03216]] 5152 If pname:framebuffer was created with a 5153 slink:VkFramebufferCreateInfo::pname:flags value that included 5154 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5155 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5156 structure included in the pname:pNext chain must: be a slink:VkImageView 5157 of an image created with a value of 5158 slink:VkImageViewCreateInfo::pname:format equal to the corresponding 5159 value of slink:VkAttachmentDescription::pname:format in pname:renderPass 5160 * [[VUID-VkRenderPassBeginInfo-framebuffer-03217]] 5161 If pname:framebuffer was created with a 5162 slink:VkFramebufferCreateInfo::pname:flags value that included 5163 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the 5164 pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo 5165 structure included in the pname:pNext chain must: be a slink:VkImageView 5166 of an image created with a value of 5167 slink:VkImageCreateInfo::pname:samples equal to the corresponding value 5168 of slink:VkAttachmentDescription::pname:samples in pname:renderPass 5169endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 5170ifdef::VK_QCOM_render_pass_transform[] 5171 * [[VUID-VkRenderPassBeginInfo-pNext-02869]] 5172 If the pname:pNext chain includes 5173 slink:VkRenderPassTransformBeginInfoQCOM, pname:renderArea.offset must: 5174 equal (0,0) 5175 * [[VUID-VkRenderPassBeginInfo-pNext-02870]] 5176 If the pname:pNext chain includes 5177 slink:VkRenderPassTransformBeginInfoQCOM, pname:renderArea.extent 5178 transformed by slink:VkRenderPassTransformBeginInfoQCOM::pname:transform 5179 must: equal the pname:framebuffer dimensions 5180endif::VK_QCOM_render_pass_transform[] 5181**** 5182 5183include::{generated}/validity/structs/VkRenderPassBeginInfo.txt[] 5184-- 5185 5186ifdef::VK_EXT_sample_locations[] 5187[open,refpage='VkRenderPassSampleLocationsBeginInfoEXT',desc='Structure specifying sample locations to use for the layout transition of custom sample locations compatible depth/stencil attachments',type='structs'] 5188-- 5189The image layout of the depth aspect of a depth/stencil attachment referring 5190to an image created with 5191ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent 5192on the last sample locations used to render to the image subresource, thus 5193preserving the contents of such depth/stencil attachments across subpass 5194boundaries requires the application to specify these sample locations 5195whenever a layout transition of the attachment may: occur. 5196This information can: be provided by adding a 5197sname:VkRenderPassSampleLocationsBeginInfoEXT structure to the pname:pNext 5198chain of sname:VkRenderPassBeginInfo. 5199 5200The sname:VkRenderPassSampleLocationsBeginInfoEXT structure is defined as: 5201 5202include::{generated}/api/structs/VkRenderPassSampleLocationsBeginInfoEXT.txt[] 5203 5204 * pname:sType is the type of this structure. 5205 * pname:pNext is `NULL` or a pointer to a structure extending this 5206 structure. 5207 * pname:attachmentInitialSampleLocationsCount is the number of elements in 5208 the pname:pAttachmentInitialSampleLocations array. 5209 * pname:pAttachmentInitialSampleLocations is a pointer to an array of 5210 pname:attachmentInitialSampleLocationsCount 5211 slink:VkAttachmentSampleLocationsEXT structures specifying the 5212 attachment indices and their corresponding sample location state. 5213 Each element of pname:pAttachmentInitialSampleLocations can: specify the 5214 sample location state to use in the automatic layout transition 5215 performed to transition a depth/stencil attachment from the initial 5216 layout of the attachment to the image layout specified for the 5217 attachment in the first subpass using it. 5218 * pname:postSubpassSampleLocationsCount is the number of elements in the 5219 pname:pPostSubpassSampleLocations array. 5220 * pname:pPostSubpassSampleLocations is a pointer to an array of 5221 pname:postSubpassSampleLocationsCount slink:VkSubpassSampleLocationsEXT 5222 structures specifying the subpass indices and their corresponding sample 5223 location state. 5224 Each element of pname:pPostSubpassSampleLocations can: specify the 5225 sample location state to use in the automatic layout transition 5226 performed to transition the depth/stencil attachment used by the 5227 specified subpass to the image layout specified in a dependent subpass 5228 or to the final layout of the attachment in case the specified subpass 5229 is the last subpass using that attachment. 5230 In addition, if 5231 slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations 5232 is ename:VK_FALSE, each element of pname:pPostSubpassSampleLocations 5233 must: specify the sample location state that matches the sample 5234 locations used by all pipelines that will be bound to a command buffer 5235 during the specified subpass. 5236 If pname:variableSampleLocations is ename:VK_TRUE, the sample locations 5237 used for rasterization do not depend on 5238 pname:pPostSubpassSampleLocations. 5239 5240include::{generated}/validity/structs/VkRenderPassSampleLocationsBeginInfoEXT.txt[] 5241-- 5242 5243[open,refpage='VkAttachmentSampleLocationsEXT',desc='Structure specifying the sample locations state to use in the initial layout transition of attachments',type='structs'] 5244-- 5245The sname:VkAttachmentSampleLocationsEXT structure is defined as: 5246 5247include::{generated}/api/structs/VkAttachmentSampleLocationsEXT.txt[] 5248 5249 * pname:attachmentIndex is the index of the attachment for which the 5250 sample locations state is provided. 5251 * pname:sampleLocationsInfo is the sample locations state to use for the 5252 layout transition of the given attachment from the initial layout of the 5253 attachment to the image layout specified for the attachment in the first 5254 subpass using it. 5255 5256If the image referenced by the framebuffer attachment at index 5257pname:attachmentIndex was not created with 5258ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT then the 5259values specified in pname:sampleLocationsInfo are ignored. 5260 5261.Valid Usage 5262**** 5263 * [[VUID-VkAttachmentSampleLocationsEXT-attachmentIndex-01531]] 5264 pname:attachmentIndex must: be less than the pname:attachmentCount 5265 specified in slink:VkRenderPassCreateInfo the render pass specified by 5266 slink:VkRenderPassBeginInfo::pname:renderPass was created with 5267**** 5268 5269include::{generated}/validity/structs/VkAttachmentSampleLocationsEXT.txt[] 5270-- 5271 5272[open,refpage='VkSubpassSampleLocationsEXT',desc='Structure specifying the sample locations state to use for layout transitions of attachments performed after a given subpass',type='structs'] 5273-- 5274The sname:VkSubpassSampleLocationsEXT structure is defined as: 5275 5276include::{generated}/api/structs/VkSubpassSampleLocationsEXT.txt[] 5277 5278 * pname:subpassIndex is the index of the subpass for which the sample 5279 locations state is provided. 5280 * pname:sampleLocationsInfo is the sample locations state to use for the 5281 layout transition of the depth/stencil attachment away from the image 5282 layout the attachment is used with in the subpass specified in 5283 pname:subpassIndex. 5284 5285If the image referenced by the depth/stencil attachment used in the subpass 5286identified by pname:subpassIndex was not created with 5287ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT or if the 5288subpass does not use a depth/stencil attachment, and 5289slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations 5290is ename:VK_TRUE then the values specified in pname:sampleLocationsInfo are 5291ignored. 5292 5293.Valid Usage 5294**** 5295 * [[VUID-VkSubpassSampleLocationsEXT-subpassIndex-01532]] 5296 pname:subpassIndex must: be less than the pname:subpassCount specified 5297 in slink:VkRenderPassCreateInfo the render pass specified by 5298 slink:VkRenderPassBeginInfo::pname:renderPass was created with 5299**** 5300 5301include::{generated}/validity/structs/VkSubpassSampleLocationsEXT.txt[] 5302-- 5303endif::VK_EXT_sample_locations[] 5304 5305ifdef::VK_QCOM_render_pass_transform[] 5306[open,refpage='VkRenderPassTransformBeginInfoQCOM',desc='Structure describing transform parameters of a render pass instance',type='structs'] 5307-- 5308To begin a render pass instance with <<vertexpostproc-renderpass-transform, 5309render pass transform>> enabled, add the 5310slink:VkRenderPassTransformBeginInfoQCOM to the pname:pNext chain of 5311slink:VkRenderPassBeginInfo structure passed to the 5312flink:vkCmdBeginRenderPass command specifying the render pass transform. 5313 5314The sname:VkRenderPassTransformBeginInfoQCOM structure is defined as: 5315 5316include::{generated}/api/structs/VkRenderPassTransformBeginInfoQCOM.txt[] 5317 5318 * pname:sType is the type of this structure. 5319 * pname:pNext is `NULL` or a pointer to a structure extending this 5320 structure. 5321 * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value 5322 describing the transform to be applied to rasterization. 5323 5324.Valid Usage 5325**** 5326 * [[VUID-VkRenderPassTransformBeginInfoQCOM-transform-02871]] 5327 pname:transform must: be ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, 5328 ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, 5329 ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or 5330 ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR 5331 * [[VUID-VkRenderPassTransformBeginInfoQCOM-flags-02872]] 5332 The pname:renderpass must: have been created with 5333 slink:VkRenderPassCreateInfo::pname:flags containing 5334 ename:VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM 5335**** 5336 5337include::{generated}/validity/structs/VkRenderPassTransformBeginInfoQCOM.txt[] 5338-- 5339endif::VK_QCOM_render_pass_transform[] 5340 5341ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 5342[open,refpage='VkSubpassBeginInfo',desc='Structure specifying subpass begin information',type='structs',alias='VkSubpassBeginInfoKHR'] 5343-- 5344The sname:VkSubpassBeginInfo structure is defined as: 5345 5346include::{generated}/api/structs/VkSubpassBeginInfo.txt[] 5347 5348ifdef::VK_KHR_create_renderpass2[] 5349or the equivalent 5350 5351include::{generated}/api/structs/VkSubpassBeginInfoKHR.txt[] 5352endif::VK_KHR_create_renderpass2[] 5353 5354 * pname:sType is the type of this structure. 5355 * pname:pNext is `NULL` or a pointer to a structure extending this 5356 structure. 5357 * pname:contents is a elink:VkSubpassContents value specifying how the 5358 commands in the next subpass will be provided. 5359 5360include::{generated}/validity/structs/VkSubpassBeginInfo.txt[] 5361-- 5362endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 5363 5364[open,refpage='VkSubpassContents',desc='Specify how commands in the first subpass of a render pass are provided',type='enums'] 5365-- 5366Possible values of flink:vkCmdBeginRenderPass::pname:contents, specifying 5367how the commands in the first subpass will be provided, are: 5368 5369include::{generated}/api/enums/VkSubpassContents.txt[] 5370 5371 * ename:VK_SUBPASS_CONTENTS_INLINE specifies that the contents of the 5372 subpass will be recorded inline in the primary command buffer, and 5373 secondary command buffers must: not be executed within the subpass. 5374 * ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS specifies that the 5375 contents are recorded in secondary command buffers that will be called 5376 from the primary command buffer, and flink:vkCmdExecuteCommands is the 5377 only valid command on the command buffer until flink:vkCmdNextSubpass or 5378 flink:vkCmdEndRenderPass. 5379-- 5380 5381ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5382[open,refpage='VkDeviceGroupRenderPassBeginInfo',desc='Set the initial device mask and render areas for a render pass instance',type='structs'] 5383-- 5384If the pname:pNext chain of slink:VkRenderPassBeginInfo 5385ifdef::VK_KHR_dynamic_rendering[or slink:VkRenderingInfoKHR] 5386includes a sname:VkDeviceGroupRenderPassBeginInfo structure, then that 5387structure includes a device mask and set of render areas for the render pass 5388instance. 5389 5390The sname:VkDeviceGroupRenderPassBeginInfo structure is defined as: 5391 5392include::{generated}/api/structs/VkDeviceGroupRenderPassBeginInfo.txt[] 5393 5394ifdef::VK_KHR_device_group[] 5395or the equivalent 5396 5397include::{generated}/api/structs/VkDeviceGroupRenderPassBeginInfoKHR.txt[] 5398endif::VK_KHR_device_group[] 5399 5400 * pname:sType is the type of this structure. 5401 * pname:pNext is `NULL` or a pointer to a structure extending this 5402 structure. 5403 * pname:deviceMask is the device mask for the render pass instance. 5404 * pname:deviceRenderAreaCount is the number of elements in the 5405 pname:pDeviceRenderAreas array. 5406 * pname:pDeviceRenderAreas is a pointer to an array of slink:VkRect2D 5407 structures defining the render area for each physical device. 5408 5409The pname:deviceMask serves several purposes. 5410It is an upper bound on the set of physical devices that can: be used during 5411the render pass instance, and the initial device mask when the render pass 5412instance begins. 5413In addition, commands transitioning to the next subpass in a render pass 5414instance and commands ending the render pass instance, and, accordingly 5415render pass attachment load, store, and resolve operations and subpass 5416dependencies corresponding to the render pass instance, are executed on the 5417physical devices included in the device mask provided here. 5418 5419If pname:deviceRenderAreaCount is not zero, then the elements of 5420pname:pDeviceRenderAreas override the value of 5421slink:VkRenderPassBeginInfo::pname:renderArea, and provide a render area 5422specific to each physical device. 5423These render areas serve the same purpose as 5424slink:VkRenderPassBeginInfo::pname:renderArea, including controlling the 5425region of attachments that are cleared by ename:VK_ATTACHMENT_LOAD_OP_CLEAR 5426and that are resolved into resolve attachments. 5427 5428If this structure is not present, the render pass instance's device mask is 5429the value of slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask. 5430If this structure is not present or if pname:deviceRenderAreaCount is zero, 5431slink:VkRenderPassBeginInfo::pname:renderArea is used for all physical 5432devices. 5433 5434.Valid Usage 5435**** 5436 * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00905]] 5437 pname:deviceMask must: be a valid device mask value 5438 * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00906]] 5439 pname:deviceMask must: not be zero 5440 * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00907]] 5441 pname:deviceMask must: be a subset of the command buffer's initial 5442 device mask 5443 * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceRenderAreaCount-00908]] 5444 pname:deviceRenderAreaCount must: either be zero or equal to the number 5445 of physical devices in the logical device 5446 * [[VUID-VkDeviceGroupRenderPassBeginInfo-offset-06166]] 5447 The pname:offset.x member of any element of pname:pDeviceRenderAreas 5448 must: be greater than or equal to 0 5449 * [[VUID-VkDeviceGroupRenderPassBeginInfo-offset-06167]] 5450 The pname:offset.y member of any element of pname:pDeviceRenderAreas 5451 must: be greater than or equal to 0 5452 * [[VUID-VkDeviceGroupRenderPassBeginInfo-offset-06168]] 5453 The sum of the pname:offset.x and pname:extent.width members of any 5454 element of pname:pDeviceRenderAreas must: be less than or equal to 5455 <<limits-maxFramebufferWidth, pname:maxFramebufferWidth>> 5456 * [[VUID-VkDeviceGroupRenderPassBeginInfo-offset-06169]] 5457 The sum of the pname:offset.y and pname:extent.height members of any 5458 element of pname:pDeviceRenderAreas must: be less than or equal to 5459 <<limits-maxFramebufferHeight, pname:maxFramebufferHeight>> 5460**** 5461 5462include::{generated}/validity/structs/VkDeviceGroupRenderPassBeginInfo.txt[] 5463-- 5464endif::VK_VERSION_1_1,VK_KHR_device_group[] 5465 5466ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 5467[open,refpage='VkRenderPassAttachmentBeginInfo',desc='Structure specifying images to be used as framebuffer attachments',type='structs',alias='VkRenderPassAttachmentBeginInfoKHR'] 5468-- 5469The sname:VkRenderPassAttachmentBeginInfo structure is defined as: 5470 5471include::{generated}/api/structs/VkRenderPassAttachmentBeginInfo.txt[] 5472 5473ifdef::VK_KHR_imageless_framebuffer[] 5474or the equivalent 5475 5476include::{generated}/api/structs/VkRenderPassAttachmentBeginInfoKHR.txt[] 5477endif::VK_KHR_imageless_framebuffer[] 5478 5479 * pname:sType is the type of this structure. 5480 * pname:pNext is `NULL` or a pointer to a structure extending this 5481 structure. 5482 * pname:attachmentCount is the number of attachments. 5483 * pname:pAttachments is a pointer to an array of sname:VkImageView 5484 handles, each of which will be used as the corresponding attachment in 5485 the render pass instance. 5486 5487.Valid Usage 5488**** 5489 * [[VUID-VkRenderPassAttachmentBeginInfo-pAttachments-03218]] 5490 Each element of pname:pAttachments must: only specify a single mip level 5491 * [[VUID-VkRenderPassAttachmentBeginInfo-pAttachments-03219]] 5492 Each element of pname:pAttachments must: have been created with the 5493 identity swizzle 5494 * [[VUID-VkRenderPassAttachmentBeginInfo-pAttachments-04114]] 5495 Each element of pname:pAttachments must: have been created with 5496 slink:VkImageViewCreateInfo::pname:viewType not equal to 5497 ename:VK_IMAGE_VIEW_TYPE_3D 5498**** 5499 5500include::{generated}/validity/structs/VkRenderPassAttachmentBeginInfo.txt[] 5501-- 5502endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] 5503 5504[open,refpage='vkGetRenderAreaGranularity',desc='Returns the granularity for optimal render area',type='protos'] 5505-- 5506To query the render area granularity, call: 5507 5508include::{generated}/api/protos/vkGetRenderAreaGranularity.txt[] 5509 5510 * pname:device is the logical device that owns the render pass. 5511 * pname:renderPass is a handle to a render pass. 5512 * pname:pGranularity is a pointer to a slink:VkExtent2D structure in which 5513 the granularity is returned. 5514 5515The conditions leading to an optimal pname:renderArea are: 5516 5517 * the pname:offset.x member in pname:renderArea is a multiple of the 5518 pname:width member of the returned slink:VkExtent2D (the horizontal 5519 granularity). 5520 * the pname:offset.y member in pname:renderArea is a multiple of the 5521 pname:height member of the returned slink:VkExtent2D (the vertical 5522 granularity). 5523 * either the pname:extent.width member in pname:renderArea is a multiple 5524 of the horizontal granularity or pname:offset.x+pname:extent.width is 5525 equal to the pname:width of the pname:framebuffer in the 5526 slink:VkRenderPassBeginInfo. 5527 * either the pname:extent.height member in pname:renderArea is a multiple 5528 of the vertical granularity or pname:offset.y+pname:extent.height is 5529 equal to the pname:height of the pname:framebuffer in the 5530 slink:VkRenderPassBeginInfo. 5531 5532Subpass dependencies are not affected by the render area, and apply to the 5533entire image subresources attached to the framebuffer as specified in the 5534description of <<renderpass-layout-transitions,automatic layout 5535transitions>>. 5536Similarly, pipeline barriers are valid even if their effect extends outside 5537the render area. 5538 5539include::{generated}/validity/protos/vkGetRenderAreaGranularity.txt[] 5540-- 5541 5542[open,refpage='vkCmdNextSubpass',desc='Transition to the next subpass of a render pass',type='protos'] 5543-- 5544To transition to the next subpass in the render pass instance after 5545recording the commands for a subpass, call: 5546 5547include::{generated}/api/protos/vkCmdNextSubpass.txt[] 5548 5549 * pname:commandBuffer is the command buffer in which to record the 5550 command. 5551 * pname:contents specifies how the commands in the next subpass will be 5552 provided, in the same fashion as the corresponding parameter of 5553 flink:vkCmdBeginRenderPass. 5554 5555The subpass index for a render pass begins at zero when 5556fname:vkCmdBeginRenderPass is recorded, and increments each time 5557fname:vkCmdNextSubpass is recorded. 5558 5559Moving to the next subpass automatically performs any multisample resolve 5560operations in the subpass being ended. 5561End-of-subpass multisample resolves are treated as color attachment writes 5562for the purposes of synchronization. 5563ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 5564This applies to resolve operations for both color and depth/stencil 5565attachments. 5566endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 5567That is, they are considered to execute in the 5568ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their 5569writes are synchronized with ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. 5570Synchronization between rendering within a subpass and any resolve 5571operations at the end of the subpass occurs automatically, without need for 5572explicit dependencies or pipeline barriers. 5573However, if the resolve attachment is also used in a different subpass, an 5574explicit dependency is needed. 5575 5576After transitioning to the next subpass, the application can: record the 5577commands for that subpass. 5578 5579.Valid Usage 5580**** 5581 * [[VUID-vkCmdNextSubpass-None-00909]] 5582 The current subpass index must: be less than the number of subpasses in 5583 the render pass minus one 5584ifdef::VK_EXT_transform_feedback[] 5585 * [[VUID-vkCmdNextSubpass-None-02349]] 5586 This command must: not be recorded when transform feedback is active 5587endif::VK_EXT_transform_feedback[] 5588**** 5589 5590include::{generated}/validity/protos/vkCmdNextSubpass.txt[] 5591-- 5592 5593ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 5594[open,refpage='vkCmdNextSubpass2',desc='Transition to the next subpass of a render pass',type='protos',alias='vkCmdNextSubpass2KHR'] 5595-- 5596To transition to the next subpass in the render pass instance after 5597recording the commands for a subpass, call: 5598 5599ifdef::VK_VERSION_1_2[] 5600include::{generated}/api/protos/vkCmdNextSubpass2.txt[] 5601endif::VK_VERSION_1_2[] 5602 5603ifdef::VK_VERSION_1_2+VK_KHR_create_renderpass2[or the equivalent command] 5604 5605ifdef::VK_KHR_create_renderpass2[] 5606include::{generated}/api/protos/vkCmdNextSubpass2KHR.txt[] 5607endif::VK_KHR_create_renderpass2[] 5608 5609 * pname:commandBuffer is the command buffer in which to record the 5610 command. 5611 * pname:pSubpassBeginInfo is a pointer to a slink:VkSubpassBeginInfo 5612 structure containing information about the subpass which is about to 5613 begin rendering. 5614 * pname:pSubpassEndInfo is a pointer to a slink:VkSubpassEndInfo structure 5615 containing information about how the previous subpass will be ended. 5616 5617fname:vkCmdNextSubpass2 is semantically identical to flink:vkCmdNextSubpass, 5618except that it is extensible, and that pname:contents is provided as part of 5619an extensible structure instead of as a flat parameter. 5620 5621.Valid Usage 5622**** 5623 * [[VUID-vkCmdNextSubpass2-None-03102]] 5624 The current subpass index must: be less than the number of subpasses in 5625 the render pass minus one 5626ifdef::VK_EXT_transform_feedback[] 5627 * [[VUID-vkCmdNextSubpass2-None-02350]] 5628 This command must: not be recorded when transform feedback is active 5629endif::VK_EXT_transform_feedback[] 5630**** 5631 5632include::{generated}/validity/protos/vkCmdNextSubpass2.txt[] 5633-- 5634endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 5635 5636[open,refpage='vkCmdEndRenderPass',desc='End the current render pass',type='protos'] 5637-- 5638To record a command to end a render pass instance after recording the 5639commands for the last subpass, call: 5640 5641include::{generated}/api/protos/vkCmdEndRenderPass.txt[] 5642 5643 * pname:commandBuffer is the command buffer in which to end the current 5644 render pass instance. 5645 5646Ending a render pass instance performs any multisample resolve operations on 5647the final subpass. 5648 5649.Valid Usage 5650**** 5651 * [[VUID-vkCmdEndRenderPass-None-00910]] 5652 The current subpass index must: be equal to the number of subpasses in 5653 the render pass minus one 5654ifdef::VK_EXT_transform_feedback[] 5655 * [[VUID-vkCmdEndRenderPass-None-02351]] 5656 This command must: not be recorded when transform feedback is active 5657endif::VK_EXT_transform_feedback[] 5658ifdef::VK_KHR_dynamic_rendering[] 5659 * [[VUID-vkCmdEndRenderPass-None-06170]] 5660 The current render pass instance must: not have been begun with 5661 flink:vkCmdBeginRenderingKHR 5662endif::VK_KHR_dynamic_rendering[] 5663**** 5664 5665include::{generated}/validity/protos/vkCmdEndRenderPass.txt[] 5666-- 5667 5668ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 5669[open,refpage='vkCmdEndRenderPass2',desc='End the current render pass',type='protos',alias='vkCmdEndRenderPass2KHR'] 5670-- 5671To record a command to end a render pass instance after recording the 5672commands for the last subpass, call: 5673 5674ifdef::VK_VERSION_1_2[] 5675include::{generated}/api/protos/vkCmdEndRenderPass2.txt[] 5676endif::VK_VERSION_1_2[] 5677 5678ifdef::VK_VERSION_1_2+VK_KHR_create_renderpass2[or the equivalent command] 5679 5680ifdef::VK_KHR_create_renderpass2[] 5681include::{generated}/api/protos/vkCmdEndRenderPass2KHR.txt[] 5682endif::VK_KHR_create_renderpass2[] 5683 5684 * pname:commandBuffer is the command buffer in which to end the current 5685 render pass instance. 5686 * pname:pSubpassEndInfo is a pointer to a slink:VkSubpassEndInfo structure 5687 containing information about how the previous subpass will be ended. 5688 5689fname:vkCmdEndRenderPass2 is semantically identical to 5690flink:vkCmdEndRenderPass, except that it is extensible. 5691 5692.Valid Usage 5693**** 5694 * [[VUID-vkCmdEndRenderPass2-None-03103]] 5695 The current subpass index must: be equal to the number of subpasses in 5696 the render pass minus one 5697ifdef::VK_EXT_transform_feedback[] 5698 * [[VUID-vkCmdEndRenderPass2-None-02352]] 5699 This command must: not be recorded when transform feedback is active 5700endif::VK_EXT_transform_feedback[] 5701ifdef::VK_KHR_dynamic_rendering[] 5702 * [[VUID-vkCmdEndRenderPass2-None-06171]] 5703 The current render pass instance must: not have been begun with 5704 flink:vkCmdBeginRenderingKHR 5705endif::VK_KHR_dynamic_rendering[] 5706**** 5707 5708include::{generated}/validity/protos/vkCmdEndRenderPass2.txt[] 5709-- 5710 5711[open,refpage='VkSubpassEndInfo',desc='Structure specifying subpass end information',type='structs',alias='VkSubpassEndInfoKHR'] 5712-- 5713The sname:VkSubpassEndInfo structure is defined as: 5714 5715include::{generated}/api/structs/VkSubpassEndInfo.txt[] 5716 5717ifdef::VK_KHR_create_renderpass2[] 5718or the equivalent 5719 5720include::{generated}/api/structs/VkSubpassEndInfoKHR.txt[] 5721endif::VK_KHR_create_renderpass2[] 5722 5723 * pname:sType is the type of this structure. 5724 * pname:pNext is `NULL` or a pointer to a structure extending this 5725 structure. 5726 5727include::{generated}/validity/structs/VkSubpassEndInfo.txt[] 5728-- 5729endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 5730