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