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