// Copyright 2015-2021 The Khronos Group, Inc. // // SPDX-License-Identifier: CC-BY-4.0 [[renderpass]] = Render Pass <> must: be recorded within a _render pass instance_. Each render pass instance defines a set of image resources, referred to as _attachments_, used during rendering. ifdef::VK_KHR_dynamic_rendering[] [open,refpage='vkCmdBeginRenderingKHR',desc='Begin a dynamic render pass instance',type='protos'] -- To begin a render pass instance, call: include::{generated}/api/protos/vkCmdBeginRenderingKHR.txt[] * pname:commandBuffer is the command buffer in which to record the command. * pname:pRenderingInfo is a pointer to a slink:VkRenderingInfoKHR structure specifying details of the render pass instance to begin. After beginning a render pass instance, the command buffer is ready to record <>. If pname:pRenderingInfo->flags includes ename:VK_RENDERING_RESUMING_BIT_KHR then this render pass is resumed from a render pass instance that has been suspended earlier in <>. .Valid Usage **** * [[VUID-vkCmdBeginRenderingKHR-dynamicRendering-06446]] The <> feature must: be enabled * [[VUID-vkCmdBeginRenderingKHR-commandBuffer-06068]] If pname:commandBuffer is a secondary command buffer, pname:pRenderingInfo->flags must: not include ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR **** include::{generated}/validity/protos/vkCmdBeginRenderingKHR.txt[] -- [open,refpage='VkRenderingInfoKHR',desc='Structure specifying render pass instance begin info',type='structs'] -- The sname:VkRenderingInfoKHR structure is defined as: include::{generated}/api/structs/VkRenderingInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is a bitmask of elink:VkRenderingFlagBitsKHR. * pname:renderArea is the render area that is affected by the render pass instance. * pname:layerCount is the number of layers rendered to in each attachment when pname:viewMask is `0`. * pname:viewMask is the view mask indicating the indices of attachment layers that will be rendered when it is not `0`. * pname:colorAttachmentCount is the number of elements in pname:pColorAttachments. * pname:pColorAttachments is a pointer to an array of pname:colorAttachmentCount slink:VkRenderingAttachmentInfoKHR structures describing any color attachments used. * pname:pDepthAttachment is a pointer to a slink:VkRenderingAttachmentInfoKHR structure describing a depth attachment. * pname:pStencilAttachment is a pointer to a slink:VkRenderingAttachmentInfoKHR structure describing a stencil attachment. ifdef::VK_KHR_multiview,VK_VERSION_1_1[] If pname:viewMask is not `0`, multiview is enabled. endif::VK_KHR_multiview,VK_VERSION_1_1[] ifdef::VK_KHR_device_group,VK_VERSION_1_1[] If there is an instance of slink:VkDeviceGroupRenderPassBeginInfo included in the pname:pNext chain and its pname:deviceCount member is not `0`, then pname:renderArea is ignored, and the render area is defined per-device by that structure. endif::VK_KHR_device_group,VK_VERSION_1_1[] Each element of the pname:pColorAttachments array corresponds to an output location in the shader, i.e. if the shader declares an output variable decorated with a code:Location value of *X*, then it uses the attachment provided in pname:pColorAttachments[*X*]. If the pname:imageView member of any element of pname:pColorAttachments is dlink:VK_NULL_HANDLE, writes to the corresponding location by a fragment are discarded. .Valid Usage **** * [[VUID-VkRenderingInfoKHR-viewMask-06069]] If pname:viewMask is `0`, pname:layerCount must: not be `0` * [[VUID-VkRenderingInfoKHR-imageView-06070]] If neither the apiext:VK_AMD_mixed_attachment_samples nor the apiext:VK_NV_framebuffer_mixed_samples extensions are enabled, pname:imageView members of pname:pDepthAttachment, pname:pStencilAttachment, and elements of pname:pColorAttachments that are not dlink:VK_NULL_HANDLE must: have been created with the same pname:sampleCount ifndef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-renderArea-06071]] pname:renderArea.offset.x must: be greater than or equal to 0 * [[VUID-VkRenderingInfoKHR-renderArea-06072]] pname:renderArea.offset.y must: be greater than or equal to 0 * [[VUID-VkRenderingInfoKHR-renderArea-06073]] The sum of pname:renderArea.offset.x and pname:renderArea.extent.width must: be less than or equal to <> * [[VUID-VkRenderingInfoKHR-renderArea-06074]] The sum of pname:renderArea.offset.y and pname:renderArea.extent.height must: be less than or equal to <> * [[VUID-VkRenderingInfoKHR-imageView-06075]] The width of the pname:imageView member of any element of pname:pColorAttachments, pname:pDepthAttachment, or pname:pStencilAttachment that is not dlink:VK_NULL_HANDLE must: be greater than or equal to [eq]#pname:renderArea.offset.x {plus} pname:renderArea.extent.width# * [[VUID-VkRenderingInfoKHR-imageView-06076]] The height of the pname:imageView member of any element of pname:pColorAttachments, pname:pDepthAttachment, or pname:pStencilAttachment that is not dlink:VK_NULL_HANDLE must: be greater than or equal to [eq]#pname:renderArea.offset.y {plus} pname:renderArea.extent.height# endif::VK_VERSION_1_1,VK_KHR_device_group[] ifdef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-pNext-06077]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, pname:renderArea.offset.x must: be greater than or equal to 0 * [[VUID-VkRenderingInfoKHR-pNext-06078]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, pname:renderArea.offset.y must: be greater than or equal to 0 * [[VUID-VkRenderingInfoKHR-pNext-06079]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, the width of the pname:imageView member of any element of pname:pColorAttachments, pname:pDepthAttachment, or pname:pStencilAttachment that is not dlink:VK_NULL_HANDLE must: be greater than or equal to [eq]#pname:renderArea.offset.x {plus} pname:renderArea.extent.width# * [[VUID-VkRenderingInfoKHR-pNext-06080]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, the height of the pname:imageView member of any element of pname:pColorAttachments, pname:pDepthAttachment, or pname:pStencilAttachment that is not dlink:VK_NULL_HANDLE must: be greater than or equal to [eq]#pname:renderArea.offset.y {plus} pname:renderArea.extent.height# * [[VUID-VkRenderingInfoKHR-pNext-06083]] If the pname:pNext chain contains slink:VkDeviceGroupRenderPassBeginInfo, the width of the pname:imageView member of any element of pname:pColorAttachments, pname:pDepthAttachment, or pname:pStencilAttachment that is not dlink:VK_NULL_HANDLE must: be greater than or equal to the sum of the pname:offset.x and pname:extent.width members of each element of pname:pDeviceRenderAreas * [[VUID-VkRenderingInfoKHR-pNext-06084]] If the pname:pNext chain contains slink:VkDeviceGroupRenderPassBeginInfo, the height of the pname:imageView member of any element of pname:pColorAttachments, pname:pDepthAttachment, or pname:pStencilAttachment that is not dlink:VK_NULL_HANDLE must: be greater than or equal to the sum of the pname:offset.y and pname:extent.height members of each element of pname:pDeviceRenderAreas * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06085]] If neither pname:pDepthAttachment or pname:pStencilAttachment are `NULL` and the pname:imageView member of either structure is not dlink:VK_NULL_HANDLE, the pname:imageView member of each structure must: be the same * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06086]] If neither pname:pDepthAttachment or pname:pStencilAttachment are `NULL`, and the pname:resolveMode member of each is not ename:VK_RESOLVE_MODE_NONE, the pname:resolveImageView member of each structure must: be the same endif::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06087]] If pname:colorAttachmentCount is not `0` and the pname:imageView member of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, that pname:imageView must: have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06088]] If pname:pDepthAttachment is not `NULL` and pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, pname:pDepthAttachment->imageView must: have been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06089]] If pname:pStencilAttachment is not `NULL` and pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, pname:pStencilAttachment->imageView must: have been created with a stencil usage including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06090]] If pname:colorAttachmentCount is not `0` and the pname:imageView member of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, the pname:layout member of that element of pname:pColorAttachments must: not be ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06091]] If pname:colorAttachmentCount is not `0` and the pname:imageView member of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, if the pname:resolveMode member of that element of pname:pColorAttachments is not ename:VK_RESOLVE_MODE_NONE, its pname:resolveImageLayout member must: not be ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06092]] If pname:pDepthAttachment is not `NULL` and pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, pname:pDepthAttachment->layout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06093]] If pname:pDepthAttachment is not `NULL`, pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, and pname:pDepthAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:pDepthAttachment->resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06094]] If pname:pStencilAttachment is not `NULL` and pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, pname:pStencilAttachment->layout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06095]] If pname:pStencilAttachment is not `NULL`, pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, and pname:pStencilAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:pStencilAttachment->resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL ifdef::VK_KHR_maintenance2,VK_VERSION_1_1[] * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06096]] If pname:colorAttachmentCount is not `0` and the pname:imageView member of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, the pname:layout member of that element of pname:pColorAttachments must: not be ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06097]] If pname:colorAttachmentCount is not `0` and the pname:imageView member of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, if the pname:resolveMode member of that element of pname:pColorAttachments is not ename:VK_RESOLVE_MODE_NONE, its pname:resolveImageLayout member must: not be ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06098]] If pname:pDepthAttachment is not `NULL`, pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, and pname:pDepthAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:pDepthAttachment->resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06099]] If pname:pStencilAttachment is not `NULL`, pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, and pname:pStencilAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:pStencilAttachment->resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL endif::VK_KHR_maintenance2,VK_VERSION_1_1[] ifdef::VK_KHR_separate_depth_stencil_layouts,VK_VERSION_1_2[] * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06100]] If pname:colorAttachmentCount is not `0` and the pname:imageView member of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, the pname:layout member of that element of pname:pColorAttachments must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06101]] If pname:colorAttachmentCount is not `0` and the pname:imageView member of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, if the pname:resolveMode member of that element of pname:pColorAttachments is not ename:VK_RESOLVE_MODE_NONE, its pname:resolveImageLayout member must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL endif::VK_KHR_separate_depth_stencil_layouts,VK_VERSION_1_2[] ifdef::VK_KHR_depth_stencil_resolve,VK_VERSION_1_2[] * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06102]] If pname:pDepthAttachment is not `NULL` and pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, pname:pDepthAttachment->resolveMode must: be one of the bits set in slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:supportedDepthResolveModes * [[VUID-VkRenderingInfoKHR-pStencilAttachment-06103]] If pname:pStencilAttachment is not `NULL` and pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, pname:pStencilAttachment->resolveMode must: be one of the bits set in slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:supportedStencilResolveModes * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06104]] If pname:pDepthAttachment or pname:pStencilAttachment are both not `NULL`, pname:pDepthAttachment->imageView and pname:pStencilAttachment->imageView are both not dlink:VK_NULL_HANDLE, and slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolveNone is ename:VK_FALSE, the pname:resolveMode of both structures must: be the same value * [[VUID-VkRenderingInfoKHR-pDepthAttachment-06105]] If pname:pDepthAttachment or pname:pStencilAttachment are both not `NULL`, pname:pDepthAttachment->imageView and pname:pStencilAttachment->imageView are both not dlink:VK_NULL_HANDLE, slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolve is ename:VK_FALSE, and the pname:resolveMode of neither structure is ename:VK_RESOLVE_MODE_NONE, the pname:resolveMode of both structures must: be the same value endif::VK_KHR_depth_stencil_resolve,VK_VERSION_1_2[] * [[VUID-VkRenderingInfoKHR-colorAttachmentCount-06106]] pname:colorAttachmentCount must: be less than or equal to slink:VkPhysicalDeviceLimits::pname:maxColorAttachments ifdef::VK_EXT_fragment_density_map[] * [[VUID-VkRenderingInfoKHR-imageView-06107]] If the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and <> is not enabled, valid pname:imageView and pname:resolveImageView members of pname:pDepthAttachment, pname:pStencilAttachment, and each element of pname:pColorAttachments must: be a slink:VkImageView created with ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkRenderingInfoKHR-imageView-06108]] If the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and pname:viewMask is not `0`, pname:imageView must: have a pname:layerCount greater than or equal to the index of the most significant bit in pname:viewMask * [[VUID-VkRenderingInfoKHR-imageView-06109]] If the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and pname:viewMask is `0`, pname:imageView must: have a pname:layerCount equal to `1` endif::VK_VERSION_1_1,VK_KHR_multiview[] ifndef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-imageView-06110]] If the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a width greater than or equal to latexmath:[\left\lceil{\frac{renderArea_{x}+renderArea_{width}}{maxFragmentDensityTexelSize_{width}}}\right\rceil] * [[VUID-VkRenderingInfoKHR-imageView-06111]] If the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a height greater than or equal to latexmath:[\left\lceil{\frac{renderArea_{y}+renderArea_{height}}{maxFragmentDensityTexelSize_{height}}}\right\rceil] endif::VK_VERSION_1_1,VK_KHR_device_group[] ifdef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-pNext-06112]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0 and the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a width greater than or equal to latexmath:[\left\lceil{\frac{renderArea_{x}+renderArea_{width}}{maxFragmentDensityTexelSize_{width}}}\right\rceil] * [[VUID-VkRenderingInfoKHR-pNext-06113]] If the pname:pNext chain contains a slink:VkDeviceGroupRenderPassBeginInfo structure, its pname:deviceRenderAreaCount member is not 0, and the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a width greater than or equal to latexmath:[\left\lceil{\frac{pDeviceRenderAreas_{x}+pDeviceRenderAreas_{width}}{maxFragmentDensityTexelSize_{width}}}\right\rceil] for each element of pname:pDeviceRenderAreas * [[VUID-VkRenderingInfoKHR-pNext-06114]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0 and the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a height greater than or equal to latexmath:[\left\lceil{\frac{renderArea_{y}+renderArea_{height}}{maxFragmentDensityTexelSize_{height}}}\right\rceil] * [[VUID-VkRenderingInfoKHR-pNext-06115]] If the pname:pNext chain contains a slink:VkDeviceGroupRenderPassBeginInfo structure, its pname:deviceRenderAreaCount member is not 0, and the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a height greater than or equal to latexmath:[\left\lceil{\frac{pDeviceRenderAreas_{y}+pDeviceRenderAreas_{height}}{maxFragmentDensityTexelSize_{height}}}\right\rceil] for each element of pname:pDeviceRenderAreas endif::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-imageView-06116]] If the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, it must: not be equal to the pname:imageView or pname:resolveImageView member of pname:pDepthAttachment, pname:pStencilAttachment, or any element of pname:pColorAttachments endif::VK_EXT_fragment_density_map[] ifdef::VK_KHR_fragment_shading_rate[] ifndef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-imageView-06117]] If the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a width greater than or equal to latexmath:[\left\lceil{\frac{renderArea_{x}+renderArea_{width}}{shadingRateAttachmentTexelSize_{width}}}\right\rceil] * [[VUID-VkRenderingInfoKHR-imageView-06118]] If the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a height greater than or equal to latexmath:[\left\lceil{\frac{renderArea_{y}+renderArea_{height}}{shadingRateAttachmentTexelSize_{height}}}\right\rceil] endif::VK_VERSION_1_1,VK_KHR_device_group[] ifdef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-pNext-06119]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0 and the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a width greater than or equal to latexmath:[\left\lceil{\frac{renderArea_{x}+renderArea_{width}}{shadingRateAttachmentTexelSize_{width}}}\right\rceil] * [[VUID-VkRenderingInfoKHR-pNext-06120]] If the pname:pNext chain contains a slink:VkDeviceGroupRenderPassBeginInfo structure, its pname:deviceRenderAreaCount member is not 0, and the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a width greater than or equal to latexmath:[\left\lceil{\frac{pDeviceRenderAreas_{x}+pDeviceRenderAreas_{width}}{shadingRateAttachmentTexelSize_{width}}}\right\rceil] for each element of pname:pDeviceRenderAreas * [[VUID-VkRenderingInfoKHR-pNext-06121]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0 and the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a height greater than or equal to latexmath:[\left\lceil{\frac{renderArea_{y}+renderArea_{height}}{shadingRateAttachmentTexelSize_{height}}}\right\rceil] * [[VUID-VkRenderingInfoKHR-pNext-06122]] If the pname:pNext chain contains a slink:VkDeviceGroupRenderPassBeginInfo structure, its pname:deviceRenderAreaCount member is not 0, and the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, pname:imageView must: have a height greater than or equal to latexmath:[\left\lceil{\frac{pDeviceRenderAreas_{y}+pDeviceRenderAreas_{height}}{shadingRateAttachmentTexelSize_{height}}}\right\rceil] for each element of pname:pDeviceRenderAreas endif::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderingInfoKHR-imageView-06123]] If the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and pname:viewMask is `0`, pname:imageView must: have a pname:layerCount that is either equal to `1` or greater than or equal to pname:layerCount * [[VUID-VkRenderingInfoKHR-imageView-06124]] If the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, and pname:viewMask is not `0`, pname:imageView must: have a pname:layerCount that either equal to `1` or greater than or equal to the index of the most significant bit in pname:viewMask * [[VUID-VkRenderingInfoKHR-imageView-06125]] If the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, it must: not be equal to the pname:imageView or pname:resolveImageView member of pname:pDepthAttachment, pname:pStencilAttachment, or any element of pname:pColorAttachments ifdef::VK_EXT_fragment_density_map[] * [[VUID-VkRenderingInfoKHR-imageView-06126]] If the pname:imageView member of a slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pname:pNext chain is not dlink:VK_NULL_HANDLE, it must: not be equal to the pname:imageView member of a slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pname:pNext chain endif::VK_EXT_fragment_density_map[] endif::VK_KHR_fragment_shading_rate[] * [[VUID-VkRenderingInfoKHR-multiview-06127]] If the <> feature is not enabled, pname:viewMask must: be `0` ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkRenderingInfoKHR-viewMask-06128]] The index of the most significant bit in pname:viewMask must: be less than <> endif::VK_VERSION_1_1,VK_KHR_multiview[] **** include::{generated}/validity/structs/VkRenderingInfoKHR.txt[] -- [open,refpage='VkRenderingFlagBitsKHR',desc='Bitmask specifying additional properties of a dynamic render pass instance',type='enums'] -- Bits which can: be set in slink:VkRenderingInfoKHR::pname:flags describing additional properties of the render pass are: include::{generated}/api/enums/VkRenderingFlagBitsKHR.txt[] * ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR specifies that draw calls for the render pass instance will be recorded in secondary command buffers. * ename:VK_RENDERING_RESUMING_BIT_KHR specifies that the render pass instance is resuming an earlier suspended render pass instance. * ename:VK_RENDERING_SUSPENDING_BIT_KHR specifies that the render pass instance will be suspended. [[renderpass-suspension]] The contents of pname:pRenderingInfo must: match between suspended render pass instances and the render pass instances that resume them, other than the presence or absence of the ename:VK_RENDERING_RESUMING_BIT_KHR, ename:VK_RENDERING_SUSPENDING_BIT_KHR, and ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR flags. No action or synchronization commands, or other render pass instances, are allowed between suspending and resuming render pass instances. -- [open,refpage='VkRenderingFlagsKHR',desc='Bitmask of VkRenderingFlagBitsKHR',type='flags'] -- include::{generated}/api/flags/VkRenderingFlagsKHR.txt[] tname:VkRenderingFlagsKHR is a bitmask type for setting a mask of zero or more elink:VkRenderingFlagBitsKHR. -- [open,refpage='VkRenderingAttachmentInfoKHR',desc='Structure specifying attachment information',type='structs'] -- The sname:VkRenderingAttachmentInfoKHR structure is defined as: include::{generated}/api/structs/VkRenderingAttachmentInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:imageView is the image view that will be used for rendering. * pname:imageLayout is the layout that pname:imageView will be in during rendering. * pname:resolveMode is a elink:VkResolveModeFlagBits value defining how multisampled data written to pname:imageView will be resolved. * pname:resolveImageView is an image view used to write resolved multisample data at the end of rendering. * pname:resolveImageLayout is the layout that pname:resolveImageView will be in during rendering. * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the contents of pname:imageView are treated at the start of the render pass instance. * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the contents of pname:imageView are treated at the end of the render pass instance. * pname:clearValue is a slink:VkClearValue structure defining values used to clear pname:imageView when pname:loadOp is ename:VK_ATTACHMENT_LOAD_OP_CLEAR. Values in pname:imageView are loaded and stored according to the values of pname:loadOp and pname:storeOp, within the render area ifdef::VK_VERSION_1_1,VK_KHR_device_group[] for each device endif::VK_VERSION_1_1,VK_KHR_device_group[] specified in slink:VkRenderingInfoKHR. If pname:imageView is dlink:VK_NULL_HANDLE, other members of this structure are ignored; writes to this attachment will be discarded, and no load, store, or resolve operations will be performed. If pname:resolveMode is ename:VK_RESOLVE_MODE_NONE, then pname:resolveImageView is ignored. If pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, values in pname:resolveImageView within the render area become undefined: once rendering begins. At the end of rendering, the color values written to each pixel location in pname:imageView will be resolved according to pname:resolveMode and stored into the the same location in pname:resolveImageView. [NOTE] .Note ==== The resolve mode and store operation are independent; it is valid to write both resolved and unresolved values, and equally valid to discard the unresolved values while writing the resolved ones. ==== Store and resolve operations are only performed at the end of a render pass instance that does not specify the ename:VK_RENDERING_SUSPENDING_BIT_KHR flag. Load operations are only performed at the beginning of a render pass instance that does not specify the ename:VK_RENDERING_RESUMING_BIT_KHR flag. Image contents at the end of a suspended render pass instance remain defined for access by a resuming render pass instance. .Valid Usage **** * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06129]] If pname:imageView is not dlink:VK_NULL_HANDLE and has a non-integer color format, pname:resolveMode must: be ename:VK_RESOLVE_MODE_NONE or ename:VK_RESOLVE_MODE_AVERAGE_BIT * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06130]] If pname:imageView is not dlink:VK_NULL_HANDLE and has an integer color format, pname:resolveMode must: be ename:VK_RESOLVE_MODE_NONE or ename:VK_RESOLVE_MODE_SAMPLE_ZERO_BIT ifndef::VK_KHR_depth_stencil_resolve,VK_VERSION_1_2[] * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06131]] If pname:imageView is not dlink:VK_NULL_HANDLE and has a depth or stencil format, pname:resolveMode must: be ename:VK_RESOLVE_MODE_NONE endif::VK_KHR_depth_stencil_resolve,VK_VERSION_1_2[] * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06132]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:imageView must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06133]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageView must: have a sample count of ename:VK_SAMPLE_COUNT_1_BIT * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06134]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:imageView and pname:resolveImageView must: have the same elink:VkFormat * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06135]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED, ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or ename:VK_IMAGE_LAYOUT_PREINITIALIZED * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06136]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or ename:VK_IMAGE_LAYOUT_PREINITIALIZED ifdef::VK_KHR_separate_depth_stencil_layouts,VK_VERSION_1_2[] * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06137]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL endif::VK_KHR_separate_depth_stencil_layouts,VK_VERSION_1_2[] ifdef::VK_NV_shading_rate_image[] * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06138]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not be ename:VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06139]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV endif::VK_NV_shading_rate_image[] ifdef::VK_EXT_fragment_density_map[] * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06140]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not be ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06141]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT endif::VK_EXT_fragment_density_map[] ifdef::VK_KHR_synchronization2[] * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06142]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR endif::VK_KHR_synchronization2[] ifdef::VK_KHR_fragment_shading_rate[] * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06143]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not be ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06144]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR endif::VK_KHR_fragment_shading_rate[] ifdef::VK_KHR_swapchain[] * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06145]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: not be ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR * [[VUID-VkRenderingAttachmentInfoKHR-imageView-06146]] If pname:imageView is not dlink:VK_NULL_HANDLE and pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR endif::VK_KHR_swapchain[] **** include::{generated}/validity/structs/VkRenderingAttachmentInfoKHR.txt[] -- ifdef::VK_KHR_fragment_shading_rate[] [open,refpage='VkRenderingFragmentShadingRateAttachmentInfoKHR',desc='Structure specifying fragment shading rate attachment information',type='structs'] -- The sname:VkRenderingFragmentShadingRateAttachmentInfoKHR structure is defined as: include::{generated}/api/structs/VkRenderingFragmentShadingRateAttachmentInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:imageView is the image view that will be used as a fragment shading rate attachment. * pname:imageLayout is the layout that pname:imageView will be in during rendering. * pname:shadingRateAttachmentTexelSize specifies the number of pixels corresponding to each texel in pname:imageView. This structure can be included in the pname:pNext chain of slink:VkRenderingInfoKHR to define a <>. If pname:imageView is dlink:VK_NULL_HANDLE, or if this structure is not specified, the implementation behaves as if a valid shading rate attachment was specified with all texels specifying a single pixel per fragment. .Valid Usage **** * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06147]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: be ename:VK_IMAGE_LAYOUT_GENERAL or ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06148]] If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have been created with ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06149]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:shadingRateAttachmentTexelSize.width must: be a power of two value * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06150]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:shadingRateAttachmentTexelSize.width must: be less than or equal to <> * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06151]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:shadingRateAttachmentTexelSize.width must: be greater than or equal to <> * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06152]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:shadingRateAttachmentTexelSize.height must: be a power of two value * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06153]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:shadingRateAttachmentTexelSize.height must: be less than or equal to <> * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06154]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:shadingRateAttachmentTexelSize.height must: be greater than or equal to <> * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06155]] If pname:imageView is not dlink:VK_NULL_HANDLE, the quotient of pname:shadingRateAttachmentTexelSize.width and pname:shadingRateAttachmentTexelSize.height must: be less than or equal to <> * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06156]] If pname:imageView is not dlink:VK_NULL_HANDLE, the quotient of pname:shadingRateAttachmentTexelSize.height and pname:shadingRateAttachmentTexelSize.width must: be less than or equal to <> **** include::{generated}/validity/structs/VkRenderingFragmentShadingRateAttachmentInfoKHR.txt[] -- endif::VK_KHR_fragment_shading_rate[] ifdef::VK_EXT_fragment_density_map[] [open,refpage='VkRenderingFragmentDensityMapAttachmentInfoEXT',desc='Structure specifying fragment shading rate attachment information',type='structs'] -- The sname:VkRenderingFragmentDensityMapAttachmentInfoEXT structure is defined as: include::{generated}/api/structs/VkRenderingFragmentDensityMapAttachmentInfoEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:imageView is the image view that will be used as a fragment shading rate attachment. * pname:imageLayout is the layout that pname:imageView will be in during rendering. This structure can be included in the pname:pNext chain of slink:VkRenderingInfoKHR to define a fragment density map. If pname:imageView is dlink:VK_NULL_HANDLE, or if this structure is not specified, pname:imageView is dlink:VK_NULL_HANDLE. .Valid Usage **** * [[VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06157]] If pname:imageView is not dlink:VK_NULL_HANDLE, pname:layout must: be ename:VK_IMAGE_LAYOUT_GENERAL or ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT * [[VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06158]] If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have been created with ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT * [[VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06159]] If pname:imageView is not dlink:VK_NULL_HANDLE, it must: not have been created with ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT ifndef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06160]] If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have a pname:layerCount equal to `1` endif::VK_VERSION_1_1,VK_KHR_multiview[] **** include::{generated}/validity/structs/VkRenderingFragmentDensityMapAttachmentInfoEXT.txt[] -- endif::VK_EXT_fragment_density_map[] [open,refpage='vkCmdEndRenderingKHR',desc='End a dynamic render pass instance',type='protos'] -- To end a render pass instance, call: include::{generated}/api/protos/vkCmdEndRenderingKHR.txt[] * pname:commandBuffer is the command buffer in which to record the command. If the value of pname:pRenderingInfo->flags used to begin this render pass instance included ename:VK_RENDERING_SUSPENDING_BIT_KHR, then this render pass is suspended and will be resumed later in <>. .Valid Usage **** * [[VUID-vkCmdEndRenderingKHR-None-06161]] The current render pass instance must: have been begun with flink:vkCmdBeginRenderingKHR * [[VUID-vkCmdEndRenderingKHR-commandBuffer-06162]] The current render pass instance must: have been begun in pname:commandBuffer **** include::{generated}/validity/protos/vkCmdEndRenderingKHR.txt[] -- [NOTE] .Note ==== For more complex rendering graphs, it is possible to pre-define a static _render pass_ object, which as well as allowing draw commands, allows the definition of framebuffer-local dependencies between multiple subpasses. These objects have a lot of setup cost compared to flink:vkCmdBeginRenderingKHR, but use of subpass dependencies can confer important performance benefits on some devices. ==== endif::VK_KHR_dynamic_rendering[] [open,refpage='VkRenderPass',desc='Opaque handle to a render pass object',type='handles'] -- A render pass object represents a collection of attachments, subpasses, and dependencies between the subpasses, and describes how the attachments are used over the course of the subpasses. Render passes are represented by sname:VkRenderPass handles: include::{generated}/api/handles/VkRenderPass.txt[] -- An _attachment description_ describes the properties of an attachment including its format, sample count, and how its contents are treated at the beginning and end of each render pass instance. [[renderpass-subpass]] A _subpass_ represents a phase of rendering that reads and writes a subset of the attachments in a render pass. Rendering commands are recorded into a particular subpass of a render pass instance. A _subpass description_ describes the subset of attachments that is involved in the execution of a subpass. Each subpass can: read from some attachments as _input attachments_, write to some as _color attachments_ or _depth/stencil attachments_, ifdef::VK_QCOM_render_pass_shader_resolve[] perform _shader resolve operations_ to _color_attachments_ or _depth/stencil_attachments_, endif::VK_QCOM_render_pass_shader_resolve[] and perform _multisample resolve operations_ to _resolve attachments_. A subpass description can: also include a set of _preserve attachments_, which are attachments that are not read or written by the subpass but whose contents must: be preserved throughout the subpass. A subpass _uses an attachment_ if the attachment is a color, depth/stencil, resolve, ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] depth/stencil resolve, endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] ifdef::VK_KHR_fragment_shading_rate[] fragment shading rate, endif::VK_KHR_fragment_shading_rate[] or input attachment for that subpass (as determined by the pname:pColorAttachments, pname:pDepthStencilAttachment, pname:pResolveAttachments, ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] slink:VkSubpassDescriptionDepthStencilResolve::pname:pDepthStencilResolveAttachment, endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] ifdef::VK_KHR_fragment_shading_rate[] slink:VkFragmentShadingRateAttachmentInfoKHR::pname:pFragmentShadingRateAttachment->attachment, endif::VK_KHR_fragment_shading_rate[] and pname:pInputAttachments members of slink:VkSubpassDescription, respectively). A subpass does not use an attachment if that attachment is preserved by the subpass. The _first use of an attachment_ is in the lowest numbered subpass that uses that attachment. Similarly, the _last use of an attachment_ is in the highest numbered subpass that uses that attachment. The subpasses in a render pass all render to the same dimensions, and fragments for pixel (x,y,layer) in one subpass can: only read attachment contents written by previous subpasses at that same (x,y,layer) location. ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate,VK_EXT_fragment_density_map[] For multi-pixel fragments, the pixel read from an input attachment is selected from the pixels covered by that fragment in an implementation-dependent manner. However, this selection must: be made consistently for any fragment with the same shading rate for the lifetime of the slink:VkDevice. endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate,VK_EXT_fragment_density_map[] [NOTE] .Note ==== By describing a complete set of subpasses in advance, render passes provide the implementation an opportunity to optimize the storage and transfer of attachment data between subpasses. In practice, this means that subpasses with a simple framebuffer-space dependency may: be merged into a single tiled rendering pass, keeping the attachment data on-chip for the duration of a render pass instance. However, it is also quite common for a render pass to only contain a single subpass. ==== _Subpass dependencies_ describe <> between subpasses. A _subpass dependency chain_ is a sequence of subpass dependencies in a render pass, where the source subpass of each subpass dependency (after the first) equals the destination subpass of the previous dependency. Execution of subpasses may: overlap or execute out of order with regards to other subpasses, unless otherwise enforced by an execution dependency. Each subpass only respects <> for commands recorded in the same subpass, and the flink:vkCmdBeginRenderPass and flink:vkCmdEndRenderPass commands that delimit the render pass - commands within other subpasses are not included. This affects most other <>. A render pass describes the structure of subpasses and attachments independent of any specific image views for the attachments. The specific image views that will be used for the attachments, and their dimensions, are specified in sname:VkFramebuffer objects. Framebuffers are created with respect to a specific render pass that the framebuffer is compatible with (see <>). Collectively, a render pass and a framebuffer define the complete render target state for one or more subpasses as well as the algorithmic dependencies between the subpasses. The various pipeline stages of the drawing commands for a given subpass may: execute concurrently and/or out of order, both within and across drawing commands, whilst still respecting <>. However for a given (x,y,layer,sample) sample location, certain per-sample operations are performed in <>. [open,refpage='VK_ATTACHMENT_UNUSED',desc='Unused attachment sentinel',type='consts'] -- ename:VK_ATTACHMENT_UNUSED is a constant indicating that a render pass attachment is not used. include::{generated}/api/enums/VK_ATTACHMENT_UNUSED.txt[] -- [[renderpass-creation]] == Render Pass Creation [open,refpage='vkCreateRenderPass',desc='Create a new render pass object',type='protos'] -- To create a render pass, call: include::{generated}/api/protos/vkCreateRenderPass.txt[] * pname:device is the logical device that creates the render pass. * pname:pCreateInfo is a pointer to a slink:VkRenderPassCreateInfo structure describing the parameters of the render pass. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pRenderPass is a pointer to a slink:VkRenderPass handle in which the resulting render pass object is returned. include::{generated}/validity/protos/vkCreateRenderPass.txt[] -- [open,refpage='VkRenderPassCreateInfo',desc='Structure specifying parameters of a newly created render pass',type='structs'] -- The sname:VkRenderPassCreateInfo structure is defined as: include::{generated}/api/structs/VkRenderPassCreateInfo.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. ifndef::VK_QCOM_render_pass_transform[] * pname:flags is reserved for future use. endif::VK_QCOM_render_pass_transform[] ifdef::VK_QCOM_render_pass_transform[] * pname:flags is a bitmask of elink:VkRenderPassCreateFlagBits endif::VK_QCOM_render_pass_transform[] * pname:attachmentCount is the number of attachments used by this render pass. * pname:pAttachments is a pointer to an array of pname:attachmentCount slink:VkAttachmentDescription structures describing the attachments used by the render pass. * pname:subpassCount is the number of subpasses to create. * pname:pSubpasses is a pointer to an array of pname:subpassCount slink:VkSubpassDescription structures describing each subpass. * pname:dependencyCount is the number of memory dependencies between pairs of subpasses. * pname:pDependencies is a pointer to an array of pname:dependencyCount slink:VkSubpassDependency structures describing dependencies between pairs of subpasses. [NOTE] .Note ==== Care should be taken to avoid a data race here; if any subpasses access attachments with overlapping memory locations, and one of those accesses is a write, a subpass dependency needs to be included between them. ==== .Valid Usage **** * [[VUID-VkRenderPassCreateInfo-attachment-00834]] If the pname:attachment member of any element of pname:pInputAttachments, pname:pColorAttachments, pname:pResolveAttachments or pname:pDepthStencilAttachment, or any element of pname:pPreserveAttachments in any element of pname:pSubpasses is not ename:VK_ATTACHMENT_UNUSED, then it must: be less than pname:attachmentCount ifdef::VK_EXT_fragment_density_map[] * [[VUID-VkRenderPassCreateInfo-fragmentDensityMapAttachment-06471]] If the pNext chain includes a slink:VkRenderPassFragmentDensityMapCreateInfoEXT structure and the pname:fragmentDensityMapAttachment member is not ename:VK_ATTACHMENT_UNUSED, then pname:attachment must: be less than pname:attachmentCount endif::VK_EXT_fragment_density_map[] * [[VUID-VkRenderPassCreateInfo-pAttachments-00836]] For any member of pname:pAttachments with a pname:loadOp equal to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must: not specify a pname:layout equal to ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkRenderPassCreateInfo-pAttachments-02511]] For any member of pname:pAttachments with a pname:stencilLoadOp equal to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must: not specify a pname:layout equal to ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] * [[VUID-VkRenderPassCreateInfo-pAttachments-01566]] For any member of pname:pAttachments with a pname:loadOp equal to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must: not specify a pname:layout equal to ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkRenderPassCreateInfo-pAttachments-01567]] For any member of pname:pAttachments with a pname:stencilLoadOp equal to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must: not specify a pname:layout equal to ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkRenderPassCreateInfo-pNext-01926]] If the pname:pNext chain includes a slink:VkRenderPassInputAttachmentAspectCreateInfo structure, the pname:subpass member of each element of its pname:pAspectReferences member must: be less than pname:subpassCount * [[VUID-VkRenderPassCreateInfo-pNext-01927]] If the pname:pNext chain includes a slink:VkRenderPassInputAttachmentAspectCreateInfo structure, the pname:inputAttachmentIndex member of each element of its pname:pAspectReferences member must: be less than the value of pname:inputAttachmentCount in the element of pname:pSubpasses identified by its pname:subpass member * [[VUID-VkRenderPassCreateInfo-pNext-01963]] If the pname:pNext chain includes a slink:VkRenderPassInputAttachmentAspectCreateInfo structure, for any element of the pname:pInputAttachments member of any element of pname:pSubpasses where the pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, the pname:aspectMask member of the corresponding element of slink:VkRenderPassInputAttachmentAspectCreateInfo::pname:pAspectReferences must: only include aspects that are present in images of the format specified by the element of pname:pAttachments at pname:attachment endif::VK_VERSION_1_1,VK_KHR_maintenance2[] ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkRenderPassCreateInfo-pNext-01928]] If the pname:pNext chain includes a slink:VkRenderPassMultiviewCreateInfo structure, and its pname:subpassCount member is not zero, that member must: be equal to the value of pname:subpassCount * [[VUID-VkRenderPassCreateInfo-pNext-01929]] If the pname:pNext chain includes a slink:VkRenderPassMultiviewCreateInfo structure, if its pname:dependencyCount member is not zero, it must: be equal to pname:dependencyCount * [[VUID-VkRenderPassCreateInfo-pNext-01930]] If the pname:pNext chain includes a slink:VkRenderPassMultiviewCreateInfo structure, for each non-zero element of pname:pViewOffsets, the pname:srcSubpass and pname:dstSubpass members of pname:pDependencies at the same index must: not be equal * [[VUID-VkRenderPassCreateInfo-pNext-02512]] If the pname:pNext chain includes a slink:VkRenderPassMultiviewCreateInfo structure, for any element of pname:pDependencies with a pname:dependencyFlags member that does not include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, the corresponding element of the pname:pViewOffsets member of that slink:VkRenderPassMultiviewCreateInfo instance must: be `0` * [[VUID-VkRenderPassCreateInfo-pNext-02513]] If the pname:pNext chain includes a slink:VkRenderPassMultiviewCreateInfo structure, elements of its pname:pViewMasks member must: either all be `0`, or all not be `0` * [[VUID-VkRenderPassCreateInfo-pNext-02514]] If the pname:pNext chain includes a slink:VkRenderPassMultiviewCreateInfo structure, and each element of its pname:pViewMasks member is `0`, the pname:dependencyFlags member of each element of pname:pDependencies must: not include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT * [[VUID-VkRenderPassCreateInfo-pNext-02515]] If the pname:pNext chain includes a slink:VkRenderPassMultiviewCreateInfo structure, and each element of its pname:pViewMasks member is `0`, its pname:correlationMaskCount member must: be `0` endif::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkRenderPassCreateInfo-pDependencies-00837]] For any element of pname:pDependencies, if the pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL, all stage flags included in the pname:srcStageMask member of that dependency must: be a pipeline stage supported by the <> identified by the pname:pipelineBindPoint member of the source subpass * [[VUID-VkRenderPassCreateInfo-pDependencies-00838]] For any element of pname:pDependencies, if the pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL, all stage flags included in the pname:dstStageMask member of that dependency must: be a pipeline stage supported by the <> identified by the pname:pipelineBindPoint member of the destination subpass * [[VUID-VkRenderPassCreateInfo-srcSubpass-02517]] The pname:srcSubpass member of each element of pname:pDependencies must: be less than pname:subpassCount * [[VUID-VkRenderPassCreateInfo-dstSubpass-02518]] The pname:dstSubpass member of each element of pname:pDependencies must: be less than pname:subpassCount **** include::{generated}/validity/structs/VkRenderPassCreateInfo.txt[] -- ifdef::VK_QCOM_render_pass_transform[] [open,refpage='VkRenderPassCreateFlagBits',desc='Bitmask specifying additional properties of a render pass',type='enums'] -- Bits which can: be set in slink:VkRenderPassCreateInfo::pname:flags describing additional properties of the render pass are: include::{generated}/api/enums/VkRenderPassCreateFlagBits.txt[] * ename:VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM specifies that the created render pass is compatible with <>. -- endif::VK_QCOM_render_pass_transform[] [open,refpage='VkRenderPassCreateFlags',desc='Bitmask of VkRenderPassCreateFlagBits',type='flags'] -- include::{generated}/api/flags/VkRenderPassCreateFlags.txt[] tname:VkRenderPassCreateFlags is a bitmask type for setting a mask of zero or more elink:VkRenderPassCreateFlagBits. -- ifdef::VK_VERSION_1_1,VK_KHR_multiview[] [[renderpass-multiview]] [open,refpage='VkRenderPassMultiviewCreateInfo',desc='Structure containing multiview information for all subpasses',type='structs'] -- If the slink:VkRenderPassCreateInfo::pname:pNext chain includes a sname:VkRenderPassMultiviewCreateInfo structure, then that structure includes an array of view masks, view offsets, and correlation masks for the render pass. The sname:VkRenderPassMultiviewCreateInfo structure is defined as: include::{generated}/api/structs/VkRenderPassMultiviewCreateInfo.txt[] ifdef::VK_KHR_multiview[] or the equivalent include::{generated}/api/structs/VkRenderPassMultiviewCreateInfoKHR.txt[] endif::VK_KHR_multiview[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:subpassCount is zero or the number of subpasses in the render pass. * pname:pViewMasks is a pointer to an array of pname:subpassCount view masks, where each mask is a bitfield of view indices describing which views rendering is broadcast to in each subpass, when multiview is enabled. If pname:subpassCount is zero, each view mask is treated as zero. * pname:dependencyCount is zero or the number of dependencies in the render pass. * pname:pViewOffsets is a pointer to an array of pname:dependencyCount view offsets, one for each dependency. If pname:dependencyCount is zero, each dependency's view offset is treated as zero. Each view offset controls which views in the source subpass the views in the destination subpass depend on. * pname:correlationMaskCount is zero or the number of correlation masks. * pname:pCorrelationMasks is a pointer to an array of pname:correlationMaskCount view masks indicating sets of views that may: be more efficient to render concurrently. When a subpass uses a non-zero view mask, _multiview_ functionality is considered to be enabled. Multiview is all-or-nothing for a render pass - that is, either all subpasses must: have a non-zero view mask (though some subpasses may: have only one view) or all must: be zero. Multiview causes all drawing and clear commands in the subpass to behave as if they were broadcast to each view, where a view is represented by one layer of the framebuffer attachments. All draws and clears are broadcast to each _view index_ whose bit is set in the view mask. The view index is provided in the code:ViewIndex shader input variable, and color, depth/stencil, and input attachments all read/write the layer of the framebuffer corresponding to the view index. If the view mask is zero for all subpasses, multiview is considered to be disabled and all drawing commands execute normally, without this additional broadcasting. Some implementations may: not support multiview in conjunction with <> or <>. [[renderpass-multiview-view-local]] When multiview is enabled, the ename:VK_DEPENDENCY_VIEW_LOCAL_BIT bit in a dependency can: be used to express a view-local dependency, meaning that each view in the destination subpass depends on a single view in the source subpass. Unlike pipeline barriers, a subpass dependency can: potentially have a different view mask in the source subpass and the destination subpass. If the dependency is view-local, then each view ([eq]#dstView#) in the destination subpass depends on the view [eq]#dstView {plus} pname:pViewOffsets[dependency]# in the source subpass. If there is not such a view in the source subpass, then this dependency does not affect that view in the destination subpass. If the dependency is not view-local, then all views in the destination subpass depend on all views in the source subpass, and the view offset is ignored. A non-zero view offset is not allowed in a self-dependency. The elements of pname:pCorrelationMasks are a set of masks of views indicating that views in the same mask may: exhibit spatial coherency between the views, making it more efficient to render them concurrently. Correlation masks must: not have a functional effect on the results of the multiview rendering. When multiview is enabled, at the beginning of each subpass all non-render pass state is undefined:. In particular, each time flink:vkCmdBeginRenderPass or flink:vkCmdNextSubpass is called the graphics pipeline must: be bound, any relevant descriptor sets or vertex/index buffers must: be bound, and any relevant dynamic state or push constants must: be set before they are used. ifdef::VK_NVX_multiview_per_view_attributes[] A multiview subpass can: declare that its shaders will write per-view attributes for all views in a single invocation, by setting the ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit in the subpass description. The only supported per-view attributes are position and viewport mask, and per-view position and viewport masks are written to output array variables decorated with code:PositionPerViewNV and code:ViewportMaskPerViewNV, respectively. If `apiext:VK_NV_viewport_array2` is not supported and enabled, code:ViewportMaskPerViewNV must: not be used. Values written to elements of code:PositionPerViewNV and code:ViewportMaskPerViewNV must: not depend on the code:ViewIndex. The shader must: also write to an output variable decorated with code:Position, and the value written to code:Position must: equal the value written to code:PositionPerViewNV[code:ViewIndex]. Similarly, if code:ViewportMaskPerViewNV is written to then the shader must: also write to an output variable decorated with code:ViewportMaskNV, and the value written to code:ViewportMaskNV must: equal the value written to code:ViewportMaskPerViewNV[code:ViewIndex]. Implementations will either use values taken from code:Position and code:ViewportMaskNV and invoke the shader once for each view, or will use values taken from code:PositionPerViewNV and code:ViewportMaskPerViewNV and invoke the shader fewer times. The values written to code:Position and code:ViewportMaskNV must: not depend on the values written to code:PositionPerViewNV and code:ViewportMaskPerViewNV, or vice versa (to allow compilers to eliminate the unused outputs). All attributes that do not have `*PerViewNV` counterparts must: not depend on code:ViewIndex. Per-view attributes are all-or-nothing for a subpass. That is, all pipelines compiled against a subpass that includes the ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX bit must: write per-view attributes to the `*PerViewNV[]` shader outputs, in addition to the non-per-view (e.g. code:Position) outputs. Pipelines compiled against a subpass that does not include this bit must: not include the `*PerViewNV[]` outputs in their interfaces. endif::VK_NVX_multiview_per_view_attributes[] .Valid Usage **** * [[VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-00841]] Each view index must: not be set in more than one element of pname:pCorrelationMasks **** include::{generated}/validity/structs/VkRenderPassMultiviewCreateInfo.txt[] -- endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_NVX_multiview_per_view_attributes[] ifdef::VK_KHR_dynamic_rendering[] [open,refpage='VkMultiviewPerViewAttributesInfoNVX',desc='Structure specifying the multiview per-attribute properties',type='structs'] -- The sname:VkMultiviewPerViewAttributesInfoNVX structure is defined as: include::{generated}/api/structs/VkMultiviewPerViewAttributesInfoNVX.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:perViewAttributes specifies that shaders compiled for this pipeline write the attributes for all views in a single invocation of each vertex processing stage. All pipelines executed within a render pass instance that includes this bit must: write per-view attributes to the `*PerViewNV[]` shader outputs, in addition to the non-per-view (e.g. code:Position) outputs. * pname:perViewAttributesPositionXOnly specifies that shaders compiled for this pipeline use per-view positions which only differ in value in the x component. Per-view viewport mask can: also be used. When dynamic render pass instances are being used, instead of specifying ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX or ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX in the subpass description flags, the per-attibute properties of the render pass instance must: be specified by the sname:VkMultiviewPerViewAttributesInfoNVX structure Include the sname:VkMultiviewPerViewAttributesInfoNVX structure in the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo when creating a graphics pipeline for dynamic rendering, slink:VkRenderingInfoKHR when starting a dynamic render pass instance, and slink:VkCommandBufferInheritanceInfo when specifying the dynamic render pass instance parameters for secondary command buffers. .Valid Usage **** * [[VUID-VkMultiviewPerViewAttributesInfoNVX-perViewAttributesPositionXOnly-06163]] If pname:perViewAttributesPositionXOnly is ename:VK_TRUE then pname:perViewAttributes must: also be ename:VK_TRUE **** include::{generated}/validity/structs/VkMultiviewPerViewAttributesInfoNVX.txt[] -- endif::VK_KHR_dynamic_rendering[] endif::VK_NVX_multiview_per_view_attributes[] ifdef::VK_EXT_fragment_density_map[] [[renderpass-fragmentdensitymapattachment]] [open,refpage='VkRenderPassFragmentDensityMapCreateInfoEXT',desc='Structure containing fragment density map attachment for render pass',type='structs'] -- If the slink:VkRenderPassCreateInfo::pname:pNext chain includes a sname:VkRenderPassFragmentDensityMapCreateInfoEXT structure, then that structure includes a fragment density map attachment for the render pass. The sname:VkRenderPassFragmentDensityMapCreateInfoEXT structure is defined as: include::{generated}/api/structs/VkRenderPassFragmentDensityMapCreateInfoEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:fragmentDensityMapAttachment is the fragment density map to use for the render pass. The fragment density map is read at an implementation-dependent time with the following constraints determined by the attachment's image view pname:flags: * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT specifies that the fragment density map will be read by the device during ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT ifdef::VK_EXT_fragment_density_map2[] * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT specifies that the fragment density map will be read by the host during flink:vkEndCommandBuffer of the primary command buffer that the render pass is recorded into endif::VK_EXT_fragment_density_map2[] * Otherwise the fragment density map will be read by the host during flink:vkCmdBeginRenderPass The fragment density map may: additionally be read by the device during ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT for any mode. If this structure is not present, it is as if pname:fragmentDensityMapAttachment was given as ename:VK_ATTACHMENT_UNUSED. .Valid Usage **** * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02548]] If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, pname:fragmentDensityMapAttachment must: not be an element of sname:VkSubpassDescription::pname:pInputAttachments, sname:VkSubpassDescription::pname:pColorAttachments, sname:VkSubpassDescription::pname:pResolveAttachments, sname:VkSubpassDescription::pname:pDepthStencilAttachment, or sname:VkSubpassDescription::pname:pPreserveAttachments for any subpass * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02549]] If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout must: be equal to ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT, or ename:VK_IMAGE_LAYOUT_GENERAL * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02550]] If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, pname:fragmentDensityMapAttachment must: reference an attachment with a pname:loadOp equal to ename:VK_ATTACHMENT_LOAD_OP_LOAD or ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE * [[VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02551]] If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, pname:fragmentDensityMapAttachment must: reference an attachment with a pname:storeOp equal to ename:VK_ATTACHMENT_STORE_OP_DONT_CARE **** include::{generated}/validity/structs/VkRenderPassFragmentDensityMapCreateInfoEXT.txt[] -- endif::VK_EXT_fragment_density_map[] [open,refpage='VkAttachmentDescription',desc='Structure specifying an attachment description',type='structs'] -- The sname:VkAttachmentDescription structure is defined as: include::{generated}/api/structs/VkAttachmentDescription.txt[] * pname:flags is a bitmask of elink:VkAttachmentDescriptionFlagBits specifying additional properties of the attachment. * pname:format is a elink:VkFormat value specifying the format of the image view that will be used for the attachment. * pname:samples is a elink:VkSampleCountFlagBits value specifying the number of samples of the image. * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the contents of color and depth components of the attachment are treated at the beginning of the subpass where it is first used. * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the contents of color and depth components of the attachment are treated at the end of the subpass where it is last used. * pname:stencilLoadOp is a elink:VkAttachmentLoadOp value specifying how the contents of stencil components of the attachment are treated at the beginning of the subpass where it is first used. * pname:stencilStoreOp is a elink:VkAttachmentStoreOp value specifying how the contents of stencil components of the attachment are treated at the end of the last subpass where it is used. * pname:initialLayout is the layout the attachment image subresource will be in when a render pass instance begins. * pname:finalLayout is the layout the attachment image subresource will be transitioned to when a render pass instance ends. [[renderpass-load-store-ops]] If the attachment uses a color format, then pname:loadOp and pname:storeOp are used, and pname:stencilLoadOp and pname:stencilStoreOp are ignored. If the format has depth and/or stencil components, pname:loadOp and pname:storeOp apply only to the depth data, while pname:stencilLoadOp and pname:stencilStoreOp define how the stencil data is handled. pname:loadOp and pname:stencilLoadOp define the _load operations_ that execute as part of the first subpass that uses the attachment. pname:storeOp and pname:stencilStoreOp define the _store operations_ that execute as part of the last subpass that uses the attachment. The load operation for each sample in an attachment happens-before any recorded command which accesses the sample in the first subpass where the attachment is used. Load operations for attachments with a depth/stencil format execute in the ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage. Load operations for attachments with a color format execute in the ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. The store operation for each sample in an attachment happens-after any recorded command which accesses the sample in the last subpass where the attachment is used. Store operations for attachments with a depth/stencil format execute in the ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage. Store operations for attachments with a color format execute in the ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. If an attachment is not used by any subpass, then pname:loadOp, pname:storeOp, pname:stencilStoreOp, and pname:stencilLoadOp are ignored, and the attachment's memory contents will not be modified by execution of a render pass instance. ifdef::VK_VERSION_1_1,VK_KHR_multiview[] The load and store operations apply on the first and last use of each view in the render pass, respectively. If a view index of an attachment is not included in the view mask in any subpass that uses it, then the load and store operations are ignored, and the attachment's memory contents will not be modified by execution of a render pass instance. endif::VK_VERSION_1_1,VK_KHR_multiview[] [[renderpass-precision]] During a render pass instance, input/color attachments with color formats that have a component size of 8, 16, or 32 bits must: be represented in the attachment's format throughout the instance. Attachments with other floating- or fixed-point color formats, or with depth components may: be represented in a format with a precision higher than the attachment format, but must: be represented with the same range. When such a component is loaded via the pname:loadOp, it will be converted into an implementation-dependent format used by the render pass. Such components must: be converted from the render pass format, to the format of the attachment, before they are resolved or stored at the end of a render pass instance via pname:storeOp. Conversions occur as described in <> and <>. [[renderpass-aliasing]] If pname:flags includes ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then the attachment is treated as if it shares physical memory with another attachment in the same render pass. This information limits the ability of the implementation to reorder certain operations (like layout transitions and the pname:loadOp) such that it is not improperly reordered against other uses of the same physical memory via a different attachment. This is described in more detail below. If a render pass uses multiple attachments that alias the same device memory, those attachments must: each include the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment description flags. Attachments aliasing the same memory occurs in multiple ways: * Multiple attachments being assigned the same image view as part of framebuffer creation. * Attachments using distinct image views that correspond to the same image subresource of an image. * Attachments using views of distinct image subresources which are bound to overlapping memory ranges. [NOTE] .Note ==== Render passes must: include subpass dependencies (either directly or via a subpass dependency chain) between any two subpasses that operate on the same attachment or aliasing attachments and those subpass dependencies must: include execution and memory dependencies separating uses of the aliases, if at least one of those subpasses writes to one of the aliases. These dependencies must: not include the ename:VK_DEPENDENCY_BY_REGION_BIT if the aliases are views of distinct image subresources which overlap in memory. ==== Multiple attachments that alias the same memory must: not be used in a single subpass. A given attachment index must: not be used multiple times in a single subpass, with one exception: two subpass attachments can: use the same attachment index if at least one use is as an input attachment and neither use is as a resolve or preserve attachment. In other words, the same view can: be used simultaneously as an input and color or depth/stencil attachment, but must: not be used as multiple color or depth/stencil attachments nor as resolve or preserve attachments. The precise set of valid scenarios is described in more detail <>. If a set of attachments alias each other, then all except the first to be used in the render pass must: use an pname:initialLayout of ename:VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases make their contents undefined:. Once an alias has been used and a different alias has been used after it, the first alias must: not be used in any later subpasses. However, an application can: assign the same image view to multiple aliasing attachment indices, which allows that image view to be used multiple times even if other aliases are used in between. [NOTE] .Note ==== Once an attachment needs the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit, there should: be no additional cost of introducing additional aliases, and using these additional aliases may: allow more efficient clearing of the attachments on multiple uses via ename:VK_ATTACHMENT_LOAD_OP_CLEAR. ==== .Valid Usage **** * [[VUID-VkAttachmentDescription-finalLayout-00843]] pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED * [[VUID-VkAttachmentDescription-format-03280]] If pname:format is a color format, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkAttachmentDescription-format-03281]] If pname:format is a depth/stencil format, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL * [[VUID-VkAttachmentDescription-format-03282]] If pname:format is a color format, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkAttachmentDescription-format-03283]] If pname:format is a depth/stencil format, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] * [[VUID-VkAttachmentDescription-separateDepthStencilLayouts-03284]] If the <> feature is not enabled, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-separateDepthStencilLayouts-03285]] If the <> feature is not enabled, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-format-03286]] If pname:format is a color format, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-format-03287]] If pname:format is a color format, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-format-03288]] If pname:format is a depth/stencil format which includes both depth and stencil aspects, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-format-03289]] If pname:format is a depth/stencil format which includes both depth and stencil aspects, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-format-03290]] If pname:format is a depth/stencil format which includes only the depth aspect, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-format-03291]] If pname:format is a depth/stencil format which includes only the depth aspect, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-format-03292]] If pname:format is a depth/stencil format which includes only the stencil aspect, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription-format-03293]] If pname:format is a depth/stencil format which includes only the stencil aspect, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] **** include::{generated}/validity/structs/VkAttachmentDescription.txt[] -- [open,refpage='VkAttachmentDescriptionFlagBits',desc='Bitmask specifying additional properties of an attachment',type='enums'] -- Bits which can: be set in slink:VkAttachmentDescription::pname:flags describing additional properties of the attachment are: include::{generated}/api/enums/VkAttachmentDescriptionFlagBits.txt[] * ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT specifies that the attachment aliases the same device memory as other attachments. -- [open,refpage='VkAttachmentDescriptionFlags',desc='Bitmask of VkAttachmentDescriptionFlagBits',type='flags'] -- include::{generated}/api/flags/VkAttachmentDescriptionFlags.txt[] tname:VkAttachmentDescriptionFlags is a bitmask type for setting a mask of zero or more elink:VkAttachmentDescriptionFlagBits. -- [open,refpage='VkAttachmentLoadOp',desc='Specify how contents of an attachment are treated at the beginning of a subpass',type='enums'] -- Possible values of slink:VkAttachmentDescription::pname:loadOp and pname:stencilLoadOp, specifying how the contents of the attachment are treated, are: include::{generated}/api/enums/VkAttachmentLoadOp.txt[] * ename:VK_ATTACHMENT_LOAD_OP_LOAD specifies that the previous contents of the image within the render area will be preserved. For attachments with a depth/stencil format, this uses the access type ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT. For attachments with a color format, this uses the access type ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT. * ename:VK_ATTACHMENT_LOAD_OP_CLEAR specifies that the contents within the render area will be cleared to a uniform value, which is specified when a render pass instance is begun. For attachments with a depth/stencil format, this uses the access type ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. * ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE specifies that the previous contents within the area need not be preserved; the contents of the attachment will be undefined: inside the render area. For attachments with a depth/stencil format, this uses the access type ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. ifdef::VK_EXT_load_store_op_none[] * ename:VK_ATTACHMENT_LOAD_OP_NONE_EXT specifies that the previous contents of the image within the render area will be preserved, but the contents of the attachment will be undefined: inside the render pass. No access type is used as the image is not accessed. endif::VK_EXT_load_store_op_none[] -- [open,refpage='VkAttachmentStoreOp',desc='Specify how contents of an attachment are treated at the end of a subpass',type='enums'] -- Possible values of slink:VkAttachmentDescription::pname:storeOp and pname:stencilStoreOp, specifying how the contents of the attachment are treated, are: include::{generated}/api/enums/VkAttachmentStoreOp.txt[] * ename:VK_ATTACHMENT_STORE_OP_STORE specifies the contents generated during the render pass and within the render area are written to memory. For attachments with a depth/stencil format, this uses the access type ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. * ename:VK_ATTACHMENT_STORE_OP_DONT_CARE specifies the contents within the render area are not needed after rendering, and may: be discarded; the contents of the attachment will be undefined: inside the render area. For attachments with a depth/stencil format, this uses the access type ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. ifdef::VK_EXT_load_store_op_none,VK_KHR_dynamic_rendering,VK_QCOM_render_pass_store_ops[] * ename:VK_ATTACHMENT_STORE_OP_NONE_KHR specifies the contents within the render area are not accessed by the store operation. However, if the attachment was written to during the render pass, the contents of the attachment will be undefined: inside the render area. endif::VK_EXT_load_store_op_none,VK_KHR_dynamic_rendering,VK_QCOM_render_pass_store_ops[] [NOTE] .Note ==== ename:VK_ATTACHMENT_STORE_OP_DONT_CARE can: cause contents generated during previous render passes to be discarded before reaching memory, even if no write to the attachment occurs during the current render pass. ==== -- ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] [open,refpage='VkRenderPassInputAttachmentAspectCreateInfo',desc='Structure specifying, for a given subpass/input attachment pair, which aspect can: be read.',type='structs'] -- The sname:VkRenderPassInputAttachmentAspectCreateInfo structure is defined as: include::{generated}/api/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[] ifdef::VK_KHR_maintenance2[] or the equivalent include::{generated}/api/structs/VkRenderPassInputAttachmentAspectCreateInfoKHR.txt[] endif::VK_KHR_maintenance2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:aspectReferenceCount is the number of elements in the pname:pAspectReferences array. * pname:pAspectReferences is a pointer to an array of pname:aspectReferenceCount slink:VkInputAttachmentAspectReference structures containing a mask describing which aspect(s) can: be accessed for a given input attachment within a given subpass. To specify which aspects of an input attachment can: be read, add a slink:VkRenderPassInputAttachmentAspectCreateInfo structure to the pname:pNext chain of the slink:VkRenderPassCreateInfo structure: An application can: access any aspect of an input attachment that does not have a specified aspect mask in the pname:pAspectReferences array. Otherwise, an application must: not access aspect(s) of an input attachment other than those in its specified aspect mask. include::{generated}/validity/structs/VkRenderPassInputAttachmentAspectCreateInfo.txt[] -- [open,refpage='VkInputAttachmentAspectReference',desc='Structure specifying a subpass/input attachment pair and an aspect mask that can: be read.',type='structs'] -- The sname:VkInputAttachmentAspectReference structure is defined as: include::{generated}/api/structs/VkInputAttachmentAspectReference.txt[] ifdef::VK_KHR_maintenance2[] or the equivalent include::{generated}/api/structs/VkInputAttachmentAspectReferenceKHR.txt[] endif::VK_KHR_maintenance2[] * pname:subpass is an index into the pname:pSubpasses array of the parent sname:VkRenderPassCreateInfo structure. * pname:inputAttachmentIndex is an index into the pname:pInputAttachments of the specified subpass. * pname:aspectMask is a mask of which aspect(s) can: be accessed within the specified subpass. This structure specifies an aspect mask for a specific input attachment of a specific subpass in the render pass. pname:subpass and pname:inputAttachmentIndex index into the render pass as: [source,c] ~~~~ pCreateInfo->pSubpasses[subpass].pInputAttachments[inputAttachmentIndex] ~~~~ .Valid Usage **** * [[VUID-VkInputAttachmentAspectReference-aspectMask-01964]] pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT ifdef::VK_EXT_image_drm_format_modifier[] * [[VUID-VkInputAttachmentAspectReference-aspectMask-02250]] pname:aspectMask must: not include `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ endif::VK_EXT_image_drm_format_modifier[] **** include::{generated}/validity/structs/VkInputAttachmentAspectReference.txt[] -- endif::VK_VERSION_1_1,VK_KHR_maintenance2[] [open,refpage='VkSubpassDescription',desc='Structure specifying a subpass description',type='structs'] -- The sname:VkSubpassDescription structure is defined as: include::{generated}/api/structs/VkSubpassDescription.txt[] * pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits specifying usage of the subpass. * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying the pipeline type supported for this subpass. * pname:inputAttachmentCount is the number of input attachments. * pname:pInputAttachments is a pointer to an array of slink:VkAttachmentReference structures defining the input attachments for this subpass and their layouts. * pname:colorAttachmentCount is the number of color attachments. * pname:pColorAttachments is a pointer to an array of pname:colorAttachmentCount slink:VkAttachmentReference structures defining the color attachments for this subpass and their layouts. * pname:pResolveAttachments is `NULL` or a pointer to an array of pname:colorAttachmentCount slink:VkAttachmentReference structures defining the resolve attachments for this subpass and their layouts. * pname:pDepthStencilAttachment is a pointer to a slink:VkAttachmentReference structure specifying the depth/stencil attachment for this subpass and its layout. * pname:preserveAttachmentCount is the number of preserved attachments. * pname:pPreserveAttachments is a pointer to an array of pname:preserveAttachmentCount render pass attachment indices identifying attachments that are not used by this subpass, but whose contents must: be preserved throughout the subpass. Each element of the pname:pInputAttachments array corresponds to an input attachment index in a fragment shader, i.e. if a shader declares an image variable decorated with a code:InputAttachmentIndex value of *X*, then it uses the attachment provided in pname:pInputAttachments[*X*]. Input attachments must: also be bound to the pipeline in a descriptor set. If the pname:attachment member of any element of pname:pInputAttachments is ename:VK_ATTACHMENT_UNUSED, the application must: not read from the corresponding input attachment index. Fragment shaders can: use subpass input variables to access the contents of an input attachment at the fragment's (x, y, layer) framebuffer coordinates. ifdef::VK_QCOM_render_pass_transform[] Input attachments must: not be used by any subpasses within a render pass that enables <>. endif::VK_QCOM_render_pass_transform[] Each element of the pname:pColorAttachments array corresponds to an output location in the shader, i.e. if the shader declares an output variable decorated with a code:Location value of *X*, then it uses the attachment provided in pname:pColorAttachments[*X*]. If the pname:attachment member of any element of pname:pColorAttachments is ename:VK_ATTACHMENT_UNUSED, ifdef::VK_EXT_color_write_enable[] or if <> has been disabled for the corresponding attachment index, endif::VK_EXT_color_write_enable[] then writes to the corresponding location by a fragment shader are discarded. If ifdef::VK_QCOM_render_pass_shader_resolve[] pname:flags does not include ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if endif::VK_QCOM_render_pass_shader_resolve[] pname:pResolveAttachments is not `NULL`, each of its elements corresponds to a color attachment (the element in pname:pColorAttachments at the same index), and a multisample resolve operation is defined for each attachment. At the end of each subpass, multisample resolve operations read the subpass's color attachments, and resolve the samples for each pixel within the render area to the same pixel location in the corresponding resolve attachments, unless the resolve attachment index is ename:VK_ATTACHMENT_UNUSED. ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] Similarly, if ifdef::VK_QCOM_render_pass_shader_resolve[] pname:flags does not include ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and endif::VK_QCOM_render_pass_shader_resolve[] slink:VkSubpassDescriptionDepthStencilResolve::pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, it corresponds to the depth/stencil attachment in pname:pDepthStencilAttachment, and multisample resolve operations for depth and stencil are defined by slink:VkSubpassDescriptionDepthStencilResolve::pname:depthResolveMode and slink:VkSubpassDescriptionDepthStencilResolve::pname:stencilResolveMode, respectively. At the end of each subpass, multisample resolve operations read the subpass's depth/stencil attachment, and resolve the samples for each pixel to the same pixel location in the corresponding resolve attachment. If slink:VkSubpassDescriptionDepthStencilResolve::pname:depthResolveMode is ename:VK_RESOLVE_MODE_NONE, then the depth component of the resolve attachment is not written to and its contents are preserved. Similarly, if slink:VkSubpassDescriptionDepthStencilResolve::pname:stencilResolveMode is ename:VK_RESOLVE_MODE_NONE, then the stencil component of the resolve attachment is not written to and its contents are preserved. slink:VkSubpassDescriptionDepthStencilResolve::pname:depthResolveMode is ignored if the elink:VkFormat of the pname:pDepthStencilResolveAttachment does not have a depth component. Similarly, slink:VkSubpassDescriptionDepthStencilResolve::pname:stencilResolveMode is ignored if the elink:VkFormat of the pname:pDepthStencilResolveAttachment does not have a stencil component. ifdef::VK_EXT_sample_locations[] If the image subresource range referenced by the depth/stencil attachment is created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT, then the multisample resolve operation uses the sample locations state specified in the pname:sampleLocationsInfo member of the element of the sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pPostSubpassSampleLocations for the subpass. endif::VK_EXT_sample_locations[] endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] If pname:pDepthStencilAttachment is `NULL`, or if its attachment index is ename:VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil attachment will be used in the subpass. The contents of an attachment within the render area become undefined: at the start of a subpass *S* if all of the following conditions are true: * The attachment is used as a color, depth/stencil, or resolve attachment in any subpass in the render pass. * There is a subpass *S~1~* that uses or preserves the attachment, and a subpass dependency from *S~1~* to *S*. * The attachment is not used or preserved in subpass *S*. ifdef::VK_QCOM_render_pass_shader_resolve[] In addition, the contents of an attachment within the render area become undefined: at the start of a subpass *S* if all of the following conditions are true: * ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM is set. * The attachment is used as a color or depth/stencil in the subpass. endif::VK_QCOM_render_pass_shader_resolve[] Once the contents of an attachment become undefined: in subpass *S*, they remain undefined: for subpasses in subpass dependency chains starting with subpass *S* until they are written again. However, they remain valid for subpasses in other subpass dependency chains starting with subpass *S~1~* if those subpasses use or preserve the attachment. .Valid Usage **** ifndef::VK_HUAWEI_subpass_shading[] * [[VUID-VkSubpassDescription-pipelineBindPoint-00844]] pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS endif::VK_HUAWEI_subpass_shading[] ifdef::VK_HUAWEI_subpass_shading[] * [[VUID-VkSubpassDescription-pipelineBindPoint-04952]] pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS or ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI endif::VK_HUAWEI_subpass_shading[] * [[VUID-VkSubpassDescription-colorAttachmentCount-00845]] pname:colorAttachmentCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxColorAttachments * [[VUID-VkSubpassDescription-loadOp-00846]] If the first use of an attachment in this render pass is as an input attachment, and the attachment is not also used as a color or depth/stencil attachment in the same subpass, then pname:loadOp must: not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR * [[VUID-VkSubpassDescription-pResolveAttachments-00847]] If pname:pResolveAttachments is not `NULL`, for each resolve attachment that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color attachment must: not be ename:VK_ATTACHMENT_UNUSED * [[VUID-VkSubpassDescription-pResolveAttachments-00848]] If pname:pResolveAttachments is not `NULL`, for each resolve attachment that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color attachment must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT * [[VUID-VkSubpassDescription-pResolveAttachments-00849]] If pname:pResolveAttachments is not `NULL`, each resolve attachment that is not ename:VK_ATTACHMENT_UNUSED must: have a sample count of ename:VK_SAMPLE_COUNT_1_BIT * [[VUID-VkSubpassDescription-pResolveAttachments-00850]] If pname:pResolveAttachments is not `NULL`, each resolve attachment that is not ename:VK_ATTACHMENT_UNUSED must: have the same elink:VkFormat as its corresponding color attachment * [[VUID-VkSubpassDescription-pColorAttachments-01417]] All attachments in pname:pColorAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have the same sample count * [[VUID-VkSubpassDescription-pInputAttachments-02647]] All attachments in pname:pInputAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain at least ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkSubpassDescription-pColorAttachments-02648]] All attachments in pname:pColorAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT * [[VUID-VkSubpassDescription-pResolveAttachments-02649]] All attachments in pname:pResolveAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT * [[VUID-VkSubpassDescription-pDepthStencilAttachment-02650]] If pname:pDepthStencilAttachment is not `NULL` and the attachment is not ename:VK_ATTACHMENT_UNUSED then it must: have an image format whose <> contain ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT ifdef::VK_AMD_mixed_attachment_samples[] * [[VUID-VkSubpassDescription-pColorAttachments-01506]] If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, and all attachments in pname:pColorAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have a sample count that is smaller than or equal to the sample count of pname:pDepthStencilAttachment if it is not ename:VK_ATTACHMENT_UNUSED endif::VK_AMD_mixed_attachment_samples[] * [[VUID-VkSubpassDescription-pDepthStencilAttachment-01418]] If neither the `apiext:VK_AMD_mixed_attachment_samples` nor the `apiext:VK_NV_framebuffer_mixed_samples` extensions are enabled, and if pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and any attachments in pname:pColorAttachments are not ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count * [[VUID-VkSubpassDescription-attachment-00853]] Each element of pname:pPreserveAttachments must: not be ename:VK_ATTACHMENT_UNUSED * [[VUID-VkSubpassDescription-pPreserveAttachments-00854]] Each element of pname:pPreserveAttachments must: not also be an element of any other member of the subpass description * [[VUID-VkSubpassDescription-layout-02519]] If any attachment is used by more than one slink:VkAttachmentReference member, then each use must: use the same pname:layout * [[VUID-VkSubpassDescription-None-04437]] Each attachment must: follow the <> specified for its attachment type ifdef::VK_NVX_multiview_per_view_attributes[] * [[VUID-VkSubpassDescription-flags-00856]] If pname:flags includes ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must: also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX endif::VK_NVX_multiview_per_view_attributes[] ifdef::VK_QCOM_render_pass_shader_resolve[] * [[VUID-VkSubpassDescription-flags-03341]] If pname:flags includes ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pname:pResolveAttachments is not `NULL`, then each resolve attachment must: be ename:VK_ATTACHMENT_UNUSED * [[VUID-VkSubpassDescription-flags-03343]] If pname:flags includes ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass must: be the last subpass in a subpass dependency chain endif::VK_QCOM_render_pass_shader_resolve[] ifdef::VK_QCOM_render_pass_transform[] * [[VUID-VkSubpassDescription-pInputAttachments-02868]] If the render pass is created with ename:VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM each of the elements of pname:pInputAttachments must: be ename:VK_ATTACHMENT_UNUSED endif::VK_QCOM_render_pass_transform[] * [[VUID-VkSubpassDescription-pDepthStencilAttachment-04438]] pname:pDepthStencilAttachment and pname:pColorAttachments must not contain references to the same attachment **** include::{generated}/validity/structs/VkSubpassDescription.txt[] -- [open,refpage='VkSubpassDescriptionFlagBits',desc='Bitmask specifying usage of a subpass',type='enums'] -- Bits which can: be set in slink:VkSubpassDescription::pname:flags, specifying usage of the subpass, are: include::{generated}/api/enums/VkSubpassDescriptionFlagBits.txt[] ifdef::VK_NVX_multiview_per_view_attributes[] * ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX specifies that shaders compiled for this subpass write the attributes for all views in a single invocation of each <>. All pipelines compiled against a subpass that includes this bit must: write per-view attributes to the `*PerViewNV[]` shader outputs, in addition to the non-per-view (e.g. code:Position) outputs. * ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX specifies that shaders compiled for this subpass use per-view positions which only differ in value in the x component. Per-view viewport mask can: also be used. endif::VK_NVX_multiview_per_view_attributes[] ifdef::VK_QCOM_render_pass_shader_resolve[] * ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM specifies that the framebuffer region is the fragment region, that is, the minimum region dependencies are by pixel rather than by sample, such that any fragment shader invocation can: access any sample associated with that fragment shader invocation. * ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM specifies that the subpass performs shader resolve operations. endif::VK_QCOM_render_pass_shader_resolve[] ifdef::VK_ARM_rasterization_order_attachment_access[] * ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM specifies that this subpass supports pipelines created with ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM. * ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM specifies that this subpass supports pipelines created with ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM. * ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM specifies that this subpass supports pipelines created with ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM. endif::VK_ARM_rasterization_order_attachment_access[] ifndef::VK_NVX_multiview_per_view_attributes,VK_QCOM_render_pass_shader_resolve[] [NOTE] .Note ==== All bits for this type are defined by extensions, and none of those extensions are enabled in this build of the specification. ==== endif::VK_NVX_multiview_per_view_attributes,VK_QCOM_render_pass_shader_resolve[] ifdef::VK_QCOM_render_pass_shader_resolve[] [NOTE] .Note ==== Shader resolve operations allow for custom resolve operations, but overdrawing pixels may: have a performance and/or power cost. Furthermore, since the content of any depth stencil attachment or color attachment is undefined: at the begining of a shader resolve subpass, any depth testing, stencil testing, or blending operation which sources these undefined: values also has undefined: result value. ==== endif::VK_QCOM_render_pass_shader_resolve[] -- [open,refpage='VkSubpassDescriptionFlags',desc='Bitmask of VkSubpassDescriptionFlagBits',type='flags'] -- include::{generated}/api/flags/VkSubpassDescriptionFlags.txt[] tname:VkSubpassDescriptionFlags is a bitmask type for setting a mask of zero or more elink:VkSubpassDescriptionFlagBits. -- [open,refpage='VkAttachmentReference',desc='Structure specifying an attachment reference',type='structs'] -- The sname:VkAttachmentReference structure is defined as: include::{generated}/api/structs/VkAttachmentReference.txt[] * pname:attachment is either an integer value identifying an attachment at the corresponding index in slink:VkRenderPassCreateInfo::pname:pAttachments, or ename:VK_ATTACHMENT_UNUSED to signify that this attachment is not used. * pname:layout is a elink:VkImageLayout value specifying the layout the attachment uses during the subpass. .Valid Usage **** * [[VUID-VkAttachmentReference-layout-00857]] If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED, ename:VK_IMAGE_LAYOUT_PREINITIALIZED, ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL **** include::{generated}/validity/structs/VkAttachmentReference.txt[] -- [open,refpage='VK_SUBPASS_EXTERNAL',desc='Subpass index sentinel expanding synchronization scope outside a subpass',type='consts'] -- ename:VK_SUBPASS_EXTERNAL is a special subpass index value expanding synchronization scope outside a subpass. It is described in more detail by slink:VkSubpassDependency. include::{generated}/api/enums/VK_SUBPASS_EXTERNAL.txt[] -- [open,refpage='VkSubpassDependency',desc='Structure specifying a subpass dependency',type='structs'] -- :refpage: VkSubpassDependency The sname:VkSubpassDependency structure is defined as: include::{generated}/api/structs/VkSubpassDependency.txt[] * pname:srcSubpass is the subpass index of the first subpass in the dependency, or ename:VK_SUBPASS_EXTERNAL. * pname:dstSubpass is the subpass index of the second subpass in the dependency, or ename:VK_SUBPASS_EXTERNAL. * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits specifying the <>. * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits specifying the <> * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a <>. * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a <>. * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits. If pname:srcSubpass is equal to pname:dstSubpass then the slink:VkSubpassDependency describes a <>, and only constrains the pipeline barriers allowed within a subpass instance. Otherwise, when a render pass instance which includes a subpass dependency is submitted to a queue, it defines a memory dependency between the subpasses identified by pname:srcSubpass and pname:dstSubpass. If pname:srcSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the first <> includes commands that occur earlier in <> than the flink:vkCmdBeginRenderPass used to begin the render pass instance. Otherwise, the first set of commands includes all commands submitted as part of the subpass instance identified by pname:srcSubpass and any load, store or multisample resolve operations on attachments used in pname:srcSubpass. In either case, the first synchronization scope is limited to operations on the pipeline stages determined by the <> specified by pname:srcStageMask. If pname:dstSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the second <> includes commands that occur later in <> than the flink:vkCmdEndRenderPass used to end the render pass instance. Otherwise, the second set of commands includes all commands submitted as part of the subpass instance identified by pname:dstSubpass and any load, store or multisample resolve operations on attachments used in pname:dstSubpass. In either case, the second synchronization scope is limited to operations on the pipeline stages determined by the <> specified by pname:dstStageMask. The first <> is limited to accesses in the pipeline stages determined by the <> specified by pname:srcStageMask. It is also limited to access types in the <> specified by pname:srcAccessMask. The second <> is limited to accesses in the pipeline stages determined by the <> specified by pname:dstStageMask. It is also limited to access types in the <> specified by pname:dstAccessMask. The <> defined by a subpass dependency affect the execution of <> within the render pass. [NOTE] .Note ==== For non-attachment resources, the memory dependency expressed by subpass dependency is nearly identical to that of a slink:VkMemoryBarrier (with matching pname:srcAccessMask and pname:dstAccessMask parameters) submitted as a part of a flink:vkCmdPipelineBarrier (with matching pname:srcStageMask and pname:dstStageMask parameters). The only difference being that its scopes are limited to the identified subpasses rather than potentially affecting everything before and after. For attachments however, subpass dependencies work more like a slink:VkImageMemoryBarrier defined similarly to the slink:VkMemoryBarrier above, the queue family indices set to ename:VK_QUEUE_FAMILY_IGNORED, and layouts as follows: * The equivalent to pname:oldLayout is the attachment's layout according to the subpass description for pname:srcSubpass. * The equivalent to pname:newLayout is the attachment's layout according to the subpass description for pname:dstSubpass. ==== .Valid Usage **** :stageMaskName: srcStageMask include::{chapters}/commonvalidity/stage_mask_common.txt[] :stageMaskName: dstStageMask include::{chapters}/commonvalidity/stage_mask_common.txt[] * [[VUID-VkSubpassDependency-srcSubpass-00864]] pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies and ensure a valid execution order * [[VUID-VkSubpassDependency-srcSubpass-00865]] pname:srcSubpass and pname:dstSubpass must: not both be equal to ename:VK_SUBPASS_EXTERNAL * [[VUID-VkSubpassDependency-srcSubpass-00867]] If pname:srcSubpass is equal to pname:dstSubpass and not all of the stages in pname:srcStageMask and pname:dstStageMask are <>, the <> pipeline stage in pname:srcStageMask must: be <> than or equal to the <> pipeline stage in pname:dstStageMask * [[VUID-VkSubpassDependency-srcAccessMask-00868]] Any access flag included in pname:srcAccessMask must: be supported by one of the pipeline stages in pname:srcStageMask, as specified in the <> * [[VUID-VkSubpassDependency-dstAccessMask-00869]] Any access flag included in pname:dstAccessMask must: be supported by one of the pipeline stages in pname:dstStageMask, as specified in the <> * [[VUID-VkSubpassDependency-srcSubpass-02243]] If pname:srcSubpass equals pname:dstSubpass, and pname:srcStageMask and pname:dstStageMask both include a <>, then pname:dependencyFlags must: include ename:VK_DEPENDENCY_BY_REGION_BIT ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkSubpassDependency-dependencyFlags-02520]] If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, pname:srcSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL * [[VUID-VkSubpassDependency-dependencyFlags-02521]] If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, pname:dstSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL * [[VUID-VkSubpassDependency-srcSubpass-00872]] If pname:srcSubpass equals pname:dstSubpass and that subpass has more than one bit set in the view mask, then pname:dependencyFlags must: include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT endif::VK_VERSION_1_1,VK_KHR_multiview[] **** include::{generated}/validity/structs/VkSubpassDependency.txt[] -- ifdef::VK_VERSION_1_1,VK_KHR_multiview[] When multiview is enabled, the execution of the multiple views of one subpass may: not occur simultaneously or even back-to-back, and rather may: be interleaved with the execution of other subpasses. The load and store operations apply to attachments on a per-view basis. For example, an attachment using ename:VK_ATTACHMENT_LOAD_OP_CLEAR will have each view cleared on first use, but the first use of one view may be temporally distant from the first use of another view. [NOTE] .Note ==== A good mental model for multiview is to think of a multiview subpass as if it were a collection of individual (per-view) subpasses that are logically grouped together and described as a single multiview subpass in the API. Similarly, a multiview attachment can be thought of like several individual attachments that happen to be layers in a single image. A view-local dependency between two multiview subpasses acts like a set of one-to-one dependencies between corresponding pairs of per-view subpasses. A view-global dependency between two multiview subpasses acts like a set of [eq]#N {times} M# dependencies between all pairs of per-view subpasses in the source and destination. Thus, it is a more compact representation which also makes clear the commonality and reuse that is present between views in a subpass. This interpretation motivates the answers to questions like "`when does the load op apply`" - it is on the first use of each view of an attachment, as if each view was a separate attachment. ==== endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_EXT_transform_feedback[] If any two subpasses of a render pass activate transform feedback to the same bound transform feedback buffers, a subpass dependency must: be included (either directly or via some intermediate subpasses) between them. endif::VK_EXT_transform_feedback[] ifdef::editing-notes[] [NOTE] .editing-note ==== The following two alleged implicit dependencies are practically no-ops, as the operations they describe are already guaranteed by semaphores and submission order (so they are almost entirely no-ops on their own). The *only* reason they exist is because it simplifies reasoning about where <> happen. Further rewrites of this chapter could potentially remove the need for these. ==== endif::editing-notes[] [[renderpass-implicit-dependencies]] If there is no subpass dependency from ename:VK_SUBPASS_EXTERNAL to the first subpass that uses an attachment, then an implicit subpass dependency exists from ename:VK_SUBPASS_EXTERNAL to the first subpass it is used in. The implicit subpass dependency only exists if there exists an automatic layout transition away from pname:initialLayout. The subpass dependency operates as if defined with the following parameters: [source,c] ~~~~ VkSubpassDependency implicitDependency = { .srcSubpass = VK_SUBPASS_EXTERNAL; .dstSubpass = firstSubpass; // First subpass attachment is used in ifdef::VK_KHR_synchronization2[] .srcStageMask = VK_PIPELINE_STAGE_NONE_KHR; endif::VK_KHR_synchronization2[] ifndef::VK_KHR_synchronization2[] .srcStageMask = VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT; endif::VK_KHR_synchronization2[] .dstStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT; .srcAccessMask = 0; .dstAccessMask = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT | VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT | VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT; .dependencyFlags = 0; }; ~~~~ Similarly, if there is no subpass dependency from the last subpass that uses an attachment to ename:VK_SUBPASS_EXTERNAL, then an implicit subpass dependency exists from the last subpass it is used in to ename:VK_SUBPASS_EXTERNAL. The implicit subpass dependency only exists if there exists an automatic layout transition into pname:finalLayout. The subpass dependency operates as if defined with the following parameters: [source,c] ~~~~ VkSubpassDependency implicitDependency = { .srcSubpass = lastSubpass; // Last subpass attachment is used in .dstSubpass = VK_SUBPASS_EXTERNAL; .srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT; ifdef::VK_KHR_synchronization2[] .dstStageMask = VK_PIPELINE_STAGE_NONE_KHR; endif::VK_KHR_synchronization2[] ifndef::VK_KHR_synchronization2[] .dstStageMask = VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT; endif::VK_KHR_synchronization2[] .srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT; .dstAccessMask = 0; .dependencyFlags = 0; }; ~~~~ [[renderpass-layout-transitions]] As subpasses may: overlap or execute out of order with regards to other subpasses unless a subpass dependency chain describes otherwise, the layout transitions required between subpasses cannot: be known to an application. Instead, an application provides the layout that each attachment must: be in at the start and end of a render pass, and the layout it must: be in during each subpass it is used in. The implementation then must: execute layout transitions between subpasses in order to guarantee that the images are in the layouts required by each subpass, and in the final layout at the end of the render pass. Automatic layout transitions apply to the entire image subresource attached to the framebuffer. ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] If the attachment view is a 2D or 2D array view of a 3D image, even if the attachment view only refers to a subset of the slices of the selected mip level of the 3D image, automatic layout transitions apply to the entire subresource referenced which is the entire mip level in this case. endif::VK_VERSION_1_1,VK_KHR_maintenance1[] Automatic layout transitions away from the layout used in a subpass happen-after the availability operations for all dependencies with that subpass as the pname:srcSubpass. Automatic layout transitions into the layout used in a subpass happen-before the visibility operations for all dependencies with that subpass as the pname:dstSubpass. Automatic layout transitions away from pname:initialLayout happen-after the availability operations for all dependencies with a pname:srcSubpass equal to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses the attachment that will be transitioned. For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, automatic layout transitions away from pname:initialLayout happen-after the availability operations for all dependencies with a pname:srcSubpass equal to ename:VK_SUBPASS_EXTERNAL, where pname:dstSubpass uses any aliased attachment. Automatic layout transitions into pname:finalLayout happen-before the visibility operations for all dependencies with a pname:dstSubpass equal to ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses the attachment that will be transitioned. For attachments created with ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, automatic layout transitions into pname:finalLayout happen-before the visibility operations for all dependencies with a pname:dstSubpass equal to ename:VK_SUBPASS_EXTERNAL, where pname:srcSubpass uses any aliased attachment. ifdef::VK_EXT_sample_locations[] The image layout of the depth aspect of a depth/stencil attachment referring to an image created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent on the last sample locations used to render to the attachment, thus automatic layout transitions use the sample locations state specified in slink:VkRenderPassSampleLocationsBeginInfoEXT. Automatic layout transitions of an attachment referring to a depth/stencil image created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT use the sample locations the image subresource range referenced by the attachment was last rendered with. If the current render pass does not use the attachment as a depth/stencil attachment in any subpass that happens-before, the automatic layout transition uses the sample locations state specified in the pname:sampleLocationsInfo member of the element of the sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pAttachmentInitialSampleLocations array for which the pname:attachmentIndex member equals the attachment index of the attachment, if one is specified. Otherwise, the automatic layout transition uses the sample locations state specified in the pname:sampleLocationsInfo member of the element of the sname:VkRenderPassSampleLocationsBeginInfoEXT::pname:pPostSubpassSampleLocations array for which the pname:subpassIndex member equals the index of the subpass that last used the attachment as a depth/stencil attachment, if one is specified. If no sample locations state has been specified for an automatic layout transition performed on an attachment referring to a depth/stencil image created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT the contents of the depth aspect of the depth/stencil attachment become undefined: as if the layout of the attachment was transitioned from the ename:VK_IMAGE_LAYOUT_UNDEFINED layout. endif::VK_EXT_sample_locations[] If two subpasses use the same attachment, and both subpasses use the attachment in a read-only layout, no subpass dependency needs to be specified between those subpasses. If an implementation treats those layouts separately, it must: insert an implicit subpass dependency between those subpasses to separate the uses in each layout. The subpass dependency operates as if defined with the following parameters: [source,c] ~~~~ // Used for input attachments VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT; VkAccessFlags inputAttachmentDstAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT; // Used for depth/stencil attachments VkPipelineStageFlags depthStencilAttachmentStages = VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT; VkAccessFlags depthStencilAttachmentDstAccess = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT; VkSubpassDependency implicitDependency = { .srcSubpass = firstSubpass; .dstSubpass = secondSubpass; .srcStageMask = inputAttachmentStages | depthStencilAttachmentStages; .dstStageMask = inputAttachmentStages | depthStencilAttachmentStages; .srcAccessMask = 0; .dstAccessMask = inputAttachmentDstAccess | depthStencilAttachmentDstAccess; .dependencyFlags = 0; }; ~~~~ [[renderpass-feedbackloop]] If a subpass uses the same attachment as both an input attachment and either a color attachment or a depth/stencil attachment, writes via the color or depth/stencil attachment are not automatically made visible to reads via the input attachment, causing a _feedback loop_, except in any of the following conditions: * If the color components or depth/stencil components read by the input attachment are mutually exclusive with the components written by the color or depth/stencil attachments, then there is no feedback loop. This requires the graphics pipelines used by the subpass to disable writes to color components that are read as inputs via the ifdef::VK_EXT_color_write_enable[] pname:colorWriteEnable or endif::VK_EXT_color_write_enable[] pname:colorWriteMask, and to disable writes to depth/stencil components that are read as inputs via pname:depthWriteEnable or pname:stencilTestEnable. * If the attachment is used as an input attachment and depth/stencil attachment only, and the depth/stencil attachment is not written to. Rendering within a subpass containing a feedback loop creates a <>, except in the following cases: * If a memory dependency is inserted between when the attachment is written and when it is subsequently read by later fragments. <> expressing a <> are the only way to achieve this, and one must: be inserted every time a fragment will read values at a particular sample (x, y, layer, sample) coordinate, if those values have been written since the most recent pipeline barrier; or since the start of the subpass, if there have been no pipeline barriers since the start of the subpass. ifdef::VK_ARM_rasterization_order_attachment_access[] * If the attachment is used as color and input attachment, and the pipeline performing the read was created with ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM included in the pname:flags member of the pname:pColorBlendState member of its slink:VkGraphicsPipelineCreateInfo. This creates a framebuffer-local memory dependency for each fragment generated by draw commands using this pipeline with the following properties: ** The first <> includes the ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage executed by all previous fragments (as defined by <>) in the corresponding <> including those generated by the same draw command. ** The second <> includes the ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT pipeline stage executed by the generated fragment. ** The first <> includes all writes to color attachments. ** The second <> includes all reads from input attachments. * If the attachment is used as depth/stencil and input attachment, and the pipeline performs a read of the depth aspect and was created with ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM included in the pname:flags member of the pname:pDepthStencilState member of its slink:VkGraphicsPipelineCreateInfo. This creates a memory dependency for each fragment generated by draw commands using this pipeline with the following properties: ** The first <> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed by all previous fragments (as defined by <>) in the corresponding <> including those generated by the same draw command. ** The second <> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed by the generated fragment. ** The first <> includes all writes to the depth aspect of depth/stencil attachments. ** The second <> includes all reads from the depth aspect of input attachments. * If the attachment is used as depth/stencil and input attachment, and the pipeline performs a read of the stencil aspect and was created with ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM included in the pname:flags member of the pname:pDepthStencilState member of its slink:VkGraphicsPipelineCreateInfo. This creates a memory dependency for each fragment generated by draw commands using this pipeline with the following properties: ** The first <> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed by all previous fragments (as defined by <>) in the corresponding <> including those generated by the same draw command. ** The second <> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed by the generated fragment. ** The first <> includes all writes to the stencil aspect of depth/stencil attachments. ** The second <> includes all reads from the stencil aspect of input attachments. endif::VK_ARM_rasterization_order_attachment_access[] [[attachment-type-imagelayout]] Attachments have requirements for a valid image layout depending on the usage * An attachment used as an input attachment must: be in the ifdef::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, endif::VK_KHR_shared_presentable_image[] ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, endif::VK_VERSION_1_1,VK_KHR_maintenance2[] ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_GENERAL layout. * An attachment used only as a color attachment must: be in the ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or ifdef::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or endif::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_GENERAL layout. * An attachment used as both an input attachment and a color attachment must: be in the ifdef::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or endif::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_GENERAL layout. * An attachment used only as a depth/stencil attachment must: be in the ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] ifdef::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, endif::VK_KHR_shared_presentable_image[] ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, endif::VK_VERSION_1_1,VK_KHR_maintenance2[] ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_GENERAL layout. * An attachment used as an input attachment and depth/stencil attachment must: be in the ifdef::VK_KHR_shared_presentable_image[] ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, endif::VK_KHR_shared_presentable_image[] ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, endif::VK_VERSION_1_1,VK_KHR_maintenance2[] ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_GENERAL layout. An attachment must: not be used as both a depth/stencil attachment and a color attachment. ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] A more extensible version of render pass creation is also defined below. [open,refpage='vkCreateRenderPass2',desc='Create a new render pass object',type='protos',alias='vkCreateRenderPass2KHR'] -- To create a render pass, call: ifdef::VK_VERSION_1_2[] include::{generated}/api/protos/vkCreateRenderPass2.txt[] endif::VK_VERSION_1_2[] ifdef::VK_VERSION_1_2+VK_KHR_create_renderpass2[or the equivalent command] ifdef::VK_KHR_create_renderpass2[] include::{generated}/api/protos/vkCreateRenderPass2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:device is the logical device that creates the render pass. * pname:pCreateInfo is a pointer to a slink:VkRenderPassCreateInfo2 structure describing the parameters of the render pass. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pRenderPass is a pointer to a slink:VkRenderPass handle in which the resulting render pass object is returned. This command is functionally identical to flink:vkCreateRenderPass, but includes extensible sub-structures that include pname:sType and pname:pNext parameters, allowing them to be more easily extended. include::{generated}/validity/protos/vkCreateRenderPass2.txt[] -- [open,refpage='VkRenderPassCreateInfo2',desc='Structure specifying parameters of a newly created render pass',type='structs',alias='VkRenderPassCreateInfo2KHR'] -- The sname:VkRenderPassCreateInfo2 structure is defined as: include::{generated}/api/structs/VkRenderPassCreateInfo2.txt[] ifdef::VK_KHR_create_renderpass2[] or the equivalent include::{generated}/api/structs/VkRenderPassCreateInfo2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is reserved for future use. * pname:attachmentCount is the number of attachments used by this render pass. * pname:pAttachments is a pointer to an array of pname:attachmentCount slink:VkAttachmentDescription2 structures describing the attachments used by the render pass. * pname:subpassCount is the number of subpasses to create. * pname:pSubpasses is a pointer to an array of pname:subpassCount slink:VkSubpassDescription2 structures describing each subpass. * pname:dependencyCount is the number of dependencies between pairs of subpasses. * pname:pDependencies is a pointer to an array of pname:dependencyCount slink:VkSubpassDependency2 structures describing dependencies between pairs of subpasses. * pname:correlatedViewMaskCount is the number of correlation masks. * pname:pCorrelatedViewMasks is a pointer to an array of view masks indicating sets of views that may: be more efficient to render concurrently. Parameters defined by this structure with the same name as those in slink:VkRenderPassCreateInfo have the identical effect to those parameters; the child structures are variants of those used in slink:VkRenderPassCreateInfo which add pname:sType and pname:pNext parameters, allowing them to be extended. If the slink:VkSubpassDescription2::pname:viewMask member of any element of pname:pSubpasses is not zero, _multiview_ functionality is considered to be enabled for this render pass. pname:correlatedViewMaskCount and pname:pCorrelatedViewMasks have the same effect as slink:VkRenderPassMultiviewCreateInfo::pname:correlationMaskCount and slink:VkRenderPassMultiviewCreateInfo::pname:pCorrelationMasks, respectively. .Valid Usage **** * [[VUID-VkRenderPassCreateInfo2-None-03049]] If any two subpasses operate on attachments with overlapping ranges of the same sname:VkDeviceMemory object, and at least one subpass writes to that area of sname:VkDeviceMemory, a subpass dependency must: be included (either directly or via some intermediate subpasses) between them * [[VUID-VkRenderPassCreateInfo2-attachment-03050]] If the pname:attachment member of any element of pname:pInputAttachments, pname:pColorAttachments, pname:pResolveAttachments or pname:pDepthStencilAttachment, or the attachment indexed by any element of pname:pPreserveAttachments in any given element of pname:pSubpasses is bound to a range of a sname:VkDeviceMemory object that overlaps with any other attachment in any subpass (including the same subpass), the sname:VkAttachmentDescription2 structures describing them must: include ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in pname:flags * [[VUID-VkRenderPassCreateInfo2-attachment-03051]] If the pname:attachment member of any element of pname:pInputAttachments, pname:pColorAttachments, pname:pResolveAttachments or pname:pDepthStencilAttachment, or any element of pname:pPreserveAttachments in any given element of pname:pSubpasses is not ename:VK_ATTACHMENT_UNUSED, then it must: be less than pname:attachmentCount ifdef::VK_EXT_fragment_density_map[] * [[VUID-VkRenderPassCreateInfo2-fragmentDensityMapAttachment-06472]] If the pNext chain includes a slink:VkRenderPassFragmentDensityMapCreateInfoEXT structure and the pname:fragmentDensityMapAttachment member is not ename:VK_ATTACHMENT_UNUSED, then pname:attachment must: be less than pname:attachmentCount endif::VK_EXT_fragment_density_map[] ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] * [[VUID-VkRenderPassCreateInfo2-pSubpasses-06473]] If the pname:pSubpasses pNext chain includes a slink:VkSubpassDescriptionDepthStencilResolve structure and the pname:pDepthStencilResolveAttachment member is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, then pname:attachment must: be less than pname:attachmentCount endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] * [[VUID-VkRenderPassCreateInfo2-pAttachments-02522]] For any member of pname:pAttachments with a pname:loadOp equal to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must: not specify a pname:layout equal to ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkRenderPassCreateInfo2-pAttachments-02523]] For any member of pname:pAttachments with a pname:stencilLoadOp equal to ename:VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must: not specify a pname:layout equal to ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkRenderPassCreateInfo2-pDependencies-03054]] For any element of pname:pDependencies, if the pname:srcSubpass is not ename:VK_SUBPASS_EXTERNAL, all stage flags included in the pname:srcStageMask member of that dependency must: be a pipeline stage supported by the <> identified by the pname:pipelineBindPoint member of the source subpass * [[VUID-VkRenderPassCreateInfo2-pDependencies-03055]] For any element of pname:pDependencies, if the pname:dstSubpass is not ename:VK_SUBPASS_EXTERNAL, all stage flags included in the pname:dstStageMask member of that dependency must: be a pipeline stage supported by the <> identified by the pname:pipelineBindPoint member of the destination subpass * [[VUID-VkRenderPassCreateInfo2-pCorrelatedViewMasks-03056]] The set of bits included in any element of pname:pCorrelatedViewMasks must: not overlap with the set of bits included in any other element of pname:pCorrelatedViewMasks * [[VUID-VkRenderPassCreateInfo2-viewMask-03057]] If the slink:VkSubpassDescription2::pname:viewMask member of all elements of pname:pSubpasses is `0`, pname:correlatedViewMaskCount must: be `0` * [[VUID-VkRenderPassCreateInfo2-viewMask-03058]] The slink:VkSubpassDescription2::pname:viewMask member of all elements of pname:pSubpasses must: either all be `0`, or all not be `0` * [[VUID-VkRenderPassCreateInfo2-viewMask-03059]] If the slink:VkSubpassDescription2::pname:viewMask member of all elements of pname:pSubpasses is `0`, the pname:dependencyFlags member of any element of pname:pDependencies must: not include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT * [[VUID-VkRenderPassCreateInfo2-pDependencies-03060]] For any element of pname:pDependencies where its pname:srcSubpass member equals its pname:dstSubpass member, if the pname:viewMask member of the corresponding element of pname:pSubpasses includes more than one bit, its pname:dependencyFlags member must: include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT * [[VUID-VkRenderPassCreateInfo2-attachment-02525]] If the pname:attachment member of any element of the pname:pInputAttachments member of any element of pname:pSubpasses is not ename:VK_ATTACHMENT_UNUSED, the pname:aspectMask member of that element of pname:pInputAttachments must: only include aspects that are present in images of the format specified by the element of pname:pAttachments specified by pname:attachment * [[VUID-VkRenderPassCreateInfo2-srcSubpass-02526]] The pname:srcSubpass member of each element of pname:pDependencies must: be less than pname:subpassCount * [[VUID-VkRenderPassCreateInfo2-dstSubpass-02527]] The pname:dstSubpass member of each element of pname:pDependencies must: be less than pname:subpassCount ifdef::VK_KHR_fragment_shading_rate[] * [[VUID-VkRenderPassCreateInfo2-pAttachments-04585]] If any element of pname:pAttachments is used as a fragment shading rate attachment in any subpass, it must: not be used as any other attachment in the render pass ifdef::VK_QCOM_render_pass_transform[] * [[VUID-VkRenderPassCreateInfo2-flags-04521]] If pname:flags includes ename:VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM, an element of pname:pSubpasses includes an instance of slink:VkFragmentShadingRateAttachmentInfoKHR in its pname:pNext chain, and the pname:pFragmentShadingRateAttachment member of that structure is not equal to `NULL`, the pname:attachment member of pname:pFragmentShadingRateAttachment must: be ename:VK_ATTACHMENT_UNUSED endif::VK_QCOM_render_pass_transform[] * [[VUID-VkRenderPassCreateInfo2-pAttachments-04586]] If any element of pname:pAttachments is used as a fragment shading rate attachment in any subpass, it must: have an image format whose <> contain ename:VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR endif::VK_KHR_fragment_shading_rate[] ifdef::VK_QCOM_render_pass_shader_resolve[] * [[VUID-VkRenderPassCreateInfo2-rasterizationSamples-04905]] If the pipeline is being created with fragment shader state, and the apiext:VK_QCOM_render_pass_shader_resolve extension is enabled, and if subpass has any input attachments, and if the subpass description contains ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then the sample count of the input attachments must: equal pname:rasterizationSamples * [[VUID-VkRenderPassCreateInfo2-sampleShadingEnable-04906]] If the pipeline is being created with fragment shader state, and the apiext:VK_QCOM_render_pass_shader_resolve extension is enabled, and if the subpass description contains ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then pname:sampleShadingEnable must: be false * [[VUID-VkRenderPassCreateInfo2-flags-04907]] If pname:flags includes ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pname:pResolveAttachments is not `NULL`, then each resolve attachment must: be ename:VK_ATTACHMENT_UNUSED * [[VUID-VkRenderPassCreateInfo2-flags-04908]] If pname:flags includes ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pname:pDepthStencilResolveAttachment is not `NULL`, then the depth/stencil resolve attachment must: be ename:VK_ATTACHMENT_UNUSED * [[VUID-VkRenderPassCreateInfo2-flags-04909]] If pname:flags includes ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass must: be the last subpass in a subpass dependency chain endif::VK_QCOM_render_pass_shader_resolve[] **** include::{generated}/validity/structs/VkRenderPassCreateInfo2.txt[] -- [open,refpage='VkAttachmentDescription2',desc='Structure specifying an attachment description',type='structs',alias='VkAttachmentDescription2KHR'] -- The sname:VkAttachmentDescription2 structure is defined as: include::{generated}/api/structs/VkAttachmentDescription2.txt[] ifdef::VK_KHR_create_renderpass2[] or the equivalent include::{generated}/api/structs/VkAttachmentDescription2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is a bitmask of elink:VkAttachmentDescriptionFlagBits specifying additional properties of the attachment. * pname:format is a elink:VkFormat value specifying the format of the image that will be used for the attachment. * pname:samples is a elink:VkSampleCountFlagBits value specifying the number of samples of the image. * pname:loadOp is a elink:VkAttachmentLoadOp value specifying how the contents of color and depth components of the attachment are treated at the beginning of the subpass where it is first used. * pname:storeOp is a elink:VkAttachmentStoreOp value specifying how the contents of color and depth components of the attachment are treated at the end of the subpass where it is last used. * pname:stencilLoadOp is a elink:VkAttachmentLoadOp value specifying how the contents of stencil components of the attachment are treated at the beginning of the subpass where it is first used. * pname:stencilStoreOp is a elink:VkAttachmentStoreOp value specifying how the contents of stencil components of the attachment are treated at the end of the last subpass where it is used. * pname:initialLayout is the layout the attachment image subresource will be in when a render pass instance begins. * pname:finalLayout is the layout the attachment image subresource will be transitioned to when a render pass instance ends. Parameters defined by this structure with the same name as those in slink:VkAttachmentDescription have the identical effect to those parameters. ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] If the <> feature is enabled, and pname:format is a depth/stencil format, pname:initialLayout and pname:finalLayout can: be set to a layout that only specifies the layout of the depth aspect. If the pname:pNext chain includes a slink:VkAttachmentDescriptionStencilLayout structure, then the pname:stencilInitialLayout and pname:stencilFinalLayout members specify the initial and final layouts of the stencil aspect of a depth/stencil format, and pname:initialLayout and pname:finalLayout only apply to the depth aspect. For depth-only formats, the slink:VkAttachmentDescriptionStencilLayout structure is ignored. For stencil-only formats, the initial and final layouts of the stencil aspect are taken from the slink:VkAttachmentDescriptionStencilLayout structure if present, or pname:initialLayout and pname:finalLayout if not present. If pname:format is a depth/stencil format, and either pname:initialLayout or pname:finalLayout does not specify a layout for the stencil aspect, then the application must: specify the initial and final layouts of the stencil aspect by including a slink:VkAttachmentDescriptionStencilLayout structure in the pname:pNext chain. endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] .Valid Usage **** * [[VUID-VkAttachmentDescription2-finalLayout-03061]] pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED * [[VUID-VkAttachmentDescription2-format-03294]] If pname:format is a color format, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03295]] If pname:format is a depth/stencil format, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03296]] If pname:format is a color format, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03297]] If pname:format is a depth/stencil format, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] * [[VUID-VkAttachmentDescription2-separateDepthStencilLayouts-03298]] If the <> feature is not enabled, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription2-separateDepthStencilLayouts-03299]] If the <> feature is not enabled, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03300]] If pname:format is a color format, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03301]] If pname:format is a color format, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03302]] If pname:format is a depth/stencil format which includes both depth and stencil aspects, and pname:initialLayout is ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pname:pNext chain must: include a slink:VkAttachmentDescriptionStencilLayout structure * [[VUID-VkAttachmentDescription2-format-03303]] If pname:format is a depth/stencil format which includes both depth and stencil aspects, and pname:finalLayout is ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pname:pNext chain must: include a slink:VkAttachmentDescriptionStencilLayout structure * [[VUID-VkAttachmentDescription2-format-03304]] If pname:format is a depth/stencil format which includes only the depth aspect, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03305]] If pname:format is a depth/stencil format which includes only the depth aspect, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03306]] If pname:format is a depth/stencil format which includes only the stencil aspect, pname:initialLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentDescription2-format-03307]] If pname:format is a depth/stencil format which includes only the stencil aspect, pname:finalLayout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] **** include::{generated}/validity/structs/VkAttachmentDescription2.txt[] -- ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] [open,refpage='VkAttachmentDescriptionStencilLayout',desc='Structure specifying an attachment description',type='structs',alias='VkAttachmentDescriptionStencilLayoutKHR'] -- The sname:VkAttachmentDescriptionStencilLayout structure is defined as: include::{generated}/api/structs/VkAttachmentDescriptionStencilLayout.txt[] ifdef::VK_KHR_separate_depth_stencil_layouts[] or the equivalent include::{generated}/api/structs/VkAttachmentDescriptionStencilLayoutKHR.txt[] endif::VK_KHR_separate_depth_stencil_layouts[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:stencilInitialLayout is the layout the stencil aspect of the attachment image subresource will be in when a render pass instance begins. * pname:stencilFinalLayout is the layout the stencil aspect of the attachment image subresource will be transitioned to when a render pass instance ends. .Valid Usage **** * [[VUID-VkAttachmentDescriptionStencilLayout-stencilInitialLayout-03308]] pname:stencilInitialLayout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-03309]] pname:stencilFinalLayout must: not be ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL * [[VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-03310]] pname:stencilFinalLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED **** include::{generated}/validity/structs/VkAttachmentDescriptionStencilLayout.txt[] -- endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] [open,refpage='VkSubpassDescription2',desc='Structure specifying a subpass description',type='structs',alias='VkSubpassDescription2KHR'] -- The sname:VkSubpassDescription2 structure is defined as: include::{generated}/api/structs/VkSubpassDescription2.txt[] ifdef::VK_KHR_create_renderpass2[] or the equivalent include::{generated}/api/structs/VkSubpassDescription2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is a bitmask of elink:VkSubpassDescriptionFlagBits specifying usage of the subpass. * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying the pipeline type supported for this subpass. * pname:viewMask is a bitfield of view indices describing which views rendering is broadcast to in this subpass, when multiview is enabled. * pname:inputAttachmentCount is the number of input attachments. * pname:pInputAttachments is a pointer to an array of slink:VkAttachmentReference2 structures defining the input attachments for this subpass and their layouts. * pname:colorAttachmentCount is the number of color attachments. * pname:pColorAttachments is a pointer to an array of pname:colorAttachmentCount slink:VkAttachmentReference2 structures defining the color attachments for this subpass and their layouts. * pname:pResolveAttachments is `NULL` or a pointer to an array of pname:colorAttachmentCount slink:VkAttachmentReference2 structures defining the resolve attachments for this subpass and their layouts. * pname:pDepthStencilAttachment is a pointer to a slink:VkAttachmentReference2 structure specifying the depth/stencil attachment for this subpass and its layout. * pname:preserveAttachmentCount is the number of preserved attachments. * pname:pPreserveAttachments is a pointer to an array of pname:preserveAttachmentCount render pass attachment indices identifying attachments that are not used by this subpass, but whose contents must: be preserved throughout the subpass. Parameters defined by this structure with the same name as those in slink:VkSubpassDescription have the identical effect to those parameters. pname:viewMask has the same effect for the described subpass as slink:VkRenderPassMultiviewCreateInfo::pname:pViewMasks has on each corresponding subpass. ifdef::VK_KHR_fragment_shading_rate[] If a slink:VkFragmentShadingRateAttachmentInfoKHR structure is included in the pname:pNext chain, pname:pFragmentShadingRateAttachment is not `NULL`, and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, the identified attachment defines a fragment shading rate attachment for that subpass. endif::VK_KHR_fragment_shading_rate[] .Valid Usage **** ifndef::VK_HUAWEI_subpass_shading[] * [[VUID-VkSubpassDescription2-pipelineBindPoint-03062]] pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS endif::VK_HUAWEI_subpass_shading[] ifdef::VK_HUAWEI_subpass_shading[] * [[VUID-VkSubpassDescription2-pipelineBindPoint-04953]] pname:pipelineBindPoint must: be ename:VK_PIPELINE_BIND_POINT_GRAPHICS or ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI endif::VK_HUAWEI_subpass_shading[] * [[VUID-VkSubpassDescription2-colorAttachmentCount-03063]] pname:colorAttachmentCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxColorAttachments * [[VUID-VkSubpassDescription2-loadOp-03064]] If the first use of an attachment in this render pass is as an input attachment, and the attachment is not also used as a color or depth/stencil attachment in the same subpass, then pname:loadOp must: not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR * [[VUID-VkSubpassDescription2-pResolveAttachments-03065]] If pname:pResolveAttachments is not `NULL`, for each resolve attachment that does not have the value ename:VK_ATTACHMENT_UNUSED, the corresponding color attachment must: not have the value ename:VK_ATTACHMENT_UNUSED * [[VUID-VkSubpassDescription2-pResolveAttachments-03066]] If pname:pResolveAttachments is not `NULL`, for each resolve attachment that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color attachment must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT * [[VUID-VkSubpassDescription2-pResolveAttachments-03067]] If pname:pResolveAttachments is not `NULL`, each resolve attachment that is not ename:VK_ATTACHMENT_UNUSED must: have a sample count of ename:VK_SAMPLE_COUNT_1_BIT * [[VUID-VkSubpassDescription2-pResolveAttachments-03068]] Any given element of pname:pResolveAttachments must: have the same elink:VkFormat as its corresponding color attachment * [[VUID-VkSubpassDescription2-pColorAttachments-03069]] All attachments in pname:pColorAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have the same sample count * [[VUID-VkSubpassDescription2-pInputAttachments-02897]] All attachments in pname:pInputAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain at least ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkSubpassDescription2-pColorAttachments-02898]] All attachments in pname:pColorAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT * [[VUID-VkSubpassDescription2-pResolveAttachments-02899]] All attachments in pname:pResolveAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT * [[VUID-VkSubpassDescription2-pDepthStencilAttachment-02900]] If pname:pDepthStencilAttachment is not `NULL` and the attachment is not ename:VK_ATTACHMENT_UNUSED then it must: have an image format whose <> contain ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT ifdef::VK_AMD_mixed_attachment_samples[] * [[VUID-VkSubpassDescription2-pColorAttachments-03070]] If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, all attachments in pname:pColorAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have a sample count that is smaller than or equal to the sample count of pname:pDepthStencilAttachment if it is not ename:VK_ATTACHMENT_UNUSED endif::VK_AMD_mixed_attachment_samples[] * [[VUID-VkSubpassDescription2-pDepthStencilAttachment-03071]] If neither the `apiext:VK_AMD_mixed_attachment_samples` nor the `apiext:VK_NV_framebuffer_mixed_samples` extensions are enabled, and if pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and any attachments in pname:pColorAttachments are not ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count * [[VUID-VkSubpassDescription2-attachment-03073]] Each element of pname:pPreserveAttachments must: not be ename:VK_ATTACHMENT_UNUSED * [[VUID-VkSubpassDescription2-pPreserveAttachments-03074]] Any given element of pname:pPreserveAttachments must: not also be an element of any other member of the subpass description * [[VUID-VkSubpassDescription2-layout-02528]] If any attachment is used by more than one slink:VkAttachmentReference2 member, then each use must: use the same pname:layout * [[VUID-VkSubpassDescription2-None-04439]] Attachments must: follow the <> based on the type of attachment it is being used as ifdef::VK_NVX_multiview_per_view_attributes[] * [[VUID-VkSubpassDescription2-flags-03076]] If pname:flags includes ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must: also include ename:VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX endif::VK_NVX_multiview_per_view_attributes[] * [[VUID-VkSubpassDescription2-attachment-02799]] If the pname:attachment member of any element of pname:pInputAttachments is not ename:VK_ATTACHMENT_UNUSED, then the pname:aspectMask member must: be a valid combination of elink:VkImageAspectFlagBits * [[VUID-VkSubpassDescription2-attachment-02800]] If the pname:attachment member of any element of pname:pInputAttachments is not ename:VK_ATTACHMENT_UNUSED, then the pname:aspectMask member must: not be `0` * [[VUID-VkSubpassDescription2-attachment-02801]] If the pname:attachment member of any element of pname:pInputAttachments is not ename:VK_ATTACHMENT_UNUSED, then the pname:aspectMask member must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT ifdef::VK_EXT_image_drm_format_modifier[] * [[VUID-VkSubpassDescription2-attachment-04563]] If the pname:attachment member of any element of pname:pInputAttachments is not ename:VK_ATTACHMENT_UNUSED, then the pname:aspectMask member must: not include `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ endif::VK_EXT_image_drm_format_modifier[] * [[VUID-VkSubpassDescription2-pDepthStencilAttachment-04440]] An attachment must: not be used in both pname:pDepthStencilAttachment and pname:pColorAttachments **** include::{generated}/validity/structs/VkSubpassDescription2.txt[] -- ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] [open,refpage='VkSubpassDescriptionDepthStencilResolve',desc='Structure specifying depth/stencil resolve operations for a subpass',type='structs',alias='VkSubpassDescriptionDepthStencilResolveKHR'] -- If the pname:pNext chain of sname:VkSubpassDescription2 includes a sname:VkSubpassDescriptionDepthStencilResolve structure, then that structure describes multisample resolve operations for the depth/stencil attachment in a subpass. The sname:VkSubpassDescriptionDepthStencilResolve structure is defined as: include::{generated}/api/structs/VkSubpassDescriptionDepthStencilResolve.txt[] ifdef::VK_KHR_depth_stencil_resolve[] or the equivalent include::{generated}/api/structs/VkSubpassDescriptionDepthStencilResolveKHR.txt[] endif::VK_KHR_depth_stencil_resolve[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:depthResolveMode is a elink:VkResolveModeFlagBits value describing the depth resolve mode. * pname:stencilResolveMode is a elink:VkResolveModeFlagBits value describing the stencil resolve mode. * pname:pDepthStencilResolveAttachment is `NULL` or a pointer to a slink:VkAttachmentReference2 structure defining the depth/stencil resolve attachment for this subpass and its layout. If pname:pDepthStencilResolveAttachment is `NULL`, or if its attachment index is ename:VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil resolve attachment will be used in the subpass. .Valid Usage **** * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03177]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, pname:pDepthStencilAttachment must: not be `NULL` or have the value ename:VK_ATTACHMENT_UNUSED * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03178]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, pname:depthResolveMode and pname:stencilResolveMode must: not both be ename:VK_RESOLVE_MODE_NONE * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03179]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, pname:pDepthStencilAttachment must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03180]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, pname:pDepthStencilResolveAttachment must: have a sample count of ename:VK_SAMPLE_COUNT_1_BIT * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-02651]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED then it must: have an image format whose <> contain ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03181]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED and elink:VkFormat of pname:pDepthStencilResolveAttachment has a depth component, then the elink:VkFormat of pname:pDepthStencilAttachment must: have a depth component with the same number of bits and numerical type * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03182]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, and elink:VkFormat of pname:pDepthStencilResolveAttachment has a stencil component, then the elink:VkFormat of pname:pDepthStencilAttachment must: have a stencil component with the same number of bits and numerical type * [[VUID-VkSubpassDescriptionDepthStencilResolve-depthResolveMode-03183]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED and the elink:VkFormat of pname:pDepthStencilResolveAttachment has a depth component, then the value of pname:depthResolveMode must: be one of the bits set in slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:supportedDepthResolveModes or ename:VK_RESOLVE_MODE_NONE * [[VUID-VkSubpassDescriptionDepthStencilResolve-stencilResolveMode-03184]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED and the elink:VkFormat of pname:pDepthStencilResolveAttachment has a stencil component, then the value of pname:stencilResolveMode must: be one of the bits set in slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:supportedStencilResolveModes or ename:VK_RESOLVE_MODE_NONE * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03185]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, the elink:VkFormat of pname:pDepthStencilResolveAttachment has both depth and stencil components, slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolve is ename:VK_FALSE, and slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolveNone is ename:VK_FALSE, then the values of pname:depthResolveMode and pname:stencilResolveMode must: be identical * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03186]] If pname:pDepthStencilResolveAttachment is not `NULL` and does not have the value ename:VK_ATTACHMENT_UNUSED, the elink:VkFormat of pname:pDepthStencilResolveAttachment has both depth and stencil components, slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolve is ename:VK_FALSE and slink:VkPhysicalDeviceDepthStencilResolveProperties::pname:independentResolveNone is ename:VK_TRUE, then the values of pname:depthResolveMode and pname:stencilResolveMode must: be identical or one of them must: be ename:VK_RESOLVE_MODE_NONE **** include::{generated}/validity/structs/VkSubpassDescriptionDepthStencilResolve.txt[] -- [open,refpage='VkResolveModeFlagBits',desc='Bitmask indicating supported depth and stencil resolve modes',type='enums',alias='VkResolveModeFlagBitsKHR'] -- Possible values of slink:VkSubpassDescriptionDepthStencilResolve::pname:depthResolveMode and pname:stencilResolveMode, specifying the depth and stencil resolve modes, are: include::{generated}/api/enums/VkResolveModeFlagBits.txt[] ifdef::VK_KHR_depth_stencil_resolve[] or the equivalent include::{generated}/api/enums/VkResolveModeFlagBitsKHR.txt[] endif::VK_KHR_depth_stencil_resolve[] * ename:VK_RESOLVE_MODE_NONE indicates that no resolve operation is done. * ename:VK_RESOLVE_MODE_SAMPLE_ZERO_BIT indicates that result of the resolve operation is equal to the value of sample 0. * ename:VK_RESOLVE_MODE_AVERAGE_BIT indicates that result of the resolve operation is the average of the sample values. * ename:VK_RESOLVE_MODE_MIN_BIT indicates that result of the resolve operation is the minimum of the sample values. * ename:VK_RESOLVE_MODE_MAX_BIT indicates that result of the resolve operation is the maximum of the sample values. -- [open,refpage='VkResolveModeFlags',desc='Bitmask of VkResolveModeFlagBits',type='flags',alias='VkResolveModeFlagsKHR'] -- include::{generated}/api/flags/VkResolveModeFlags.txt[] ifdef::VK_KHR_depth_stencil_resolve[] or the equivalent include::{generated}/api/flags/VkResolveModeFlagsKHR.txt[] endif::VK_KHR_depth_stencil_resolve[] tname:VkResolveModeFlags is a bitmask type for setting a mask of zero or more elink:VkResolveModeFlagBits. -- endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] ifdef::VK_KHR_fragment_shading_rate[] [open,refpage='VkFragmentShadingRateAttachmentInfoKHR',desc='Structure specifying a fragment shading rate attachment for a subpass',type='structs'] -- The sname:VkFragmentShadingRateAttachmentInfoKHR structure is defined as: include::{generated}/api/structs/VkFragmentShadingRateAttachmentInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:pFragmentShadingRateAttachment is `NULL` or a pointer to a slink:VkAttachmentReference2 structure defining the fragment shading rate attachment for this subpass. * pname:shadingRateAttachmentTexelSize specifies the size of the portion of the framebuffer corresponding to each texel in pname:pFragmentShadingRateAttachment. If no shading rate attachment is specified, or if this structure is not specified, the implementation behaves as if a valid shading rate attachment was specified with all texels specifying a single pixel per fragment. .Valid Usage **** * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04524]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, its pname:layout member must: be equal to ename:VK_IMAGE_LAYOUT_GENERAL or ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04525]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, pname:shadingRateAttachmentTexelSize.width must: be a power of two value * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04526]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, pname:shadingRateAttachmentTexelSize.width must: be less than or equal to <> * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04527]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, pname:shadingRateAttachmentTexelSize.width must: be greater than or equal to <> * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04528]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, pname:shadingRateAttachmentTexelSize.height must: be a power of two value * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04529]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, pname:shadingRateAttachmentTexelSize.height must: be less than or equal to <> * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04530]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, pname:shadingRateAttachmentTexelSize.height must: be greater than or equal to <> * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04531]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, the quotient of pname:shadingRateAttachmentTexelSize.width and pname:shadingRateAttachmentTexelSize.height must: be less than or equal to <> * [[VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04532]] If pname:pFragmentShadingRateAttachment is not `NULL` and its pname:attachment member is not ename:VK_ATTACHMENT_UNUSED, the quotient of pname:shadingRateAttachmentTexelSize.height and pname:shadingRateAttachmentTexelSize.width must: be less than or equal to <> **** include::{generated}/validity/structs/VkFragmentShadingRateAttachmentInfoKHR.txt[] -- endif::VK_KHR_fragment_shading_rate[] [open,refpage='VkAttachmentReference2',desc='Structure specifying an attachment reference',type='structs',alias='VkAttachmentReference2KHR'] -- The sname:VkAttachmentReference2 structure is defined as: include::{generated}/api/structs/VkAttachmentReference2.txt[] ifdef::VK_KHR_create_renderpass2[] or the equivalent include::{generated}/api/structs/VkAttachmentReference2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:attachment is either an integer value identifying an attachment at the corresponding index in slink:VkRenderPassCreateInfo2::pname:pAttachments, or ename:VK_ATTACHMENT_UNUSED to signify that this attachment is not used. * pname:layout is a elink:VkImageLayout value specifying the layout the attachment uses during the subpass. * pname:aspectMask is a mask of which aspect(s) can: be accessed within the specified subpass as an input attachment. Parameters defined by this structure with the same name as those in slink:VkAttachmentReference have the identical effect to those parameters. pname:aspectMask is ignored when this structure is used to describe anything other than an input attachment reference. ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] If the <> feature is enabled, and pname:attachment has a depth/stencil format, pname:layout can: be set to a layout that only specifies the layout of the depth aspect. If pname:layout only specifies the layout of the depth aspect of the attachment, the layout of the stencil aspect is specified by the pname:stencilLayout member of a slink:VkAttachmentReferenceStencilLayout structure included in the pname:pNext chain. Otherwise, pname:layout describes the layout for all relevant image aspects. endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] .Valid Usage **** * [[VUID-VkAttachmentReference2-layout-03077]] If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED, ename:VK_IMAGE_LAYOUT_PREINITIALIZED, or ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] * [[VUID-VkAttachmentReference2-separateDepthStencilLayouts-03313]] If the <> feature is not enabled, and pname:attachment is not ename:VK_ATTACHMENT_UNUSED, pname:layout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, * [[VUID-VkAttachmentReference2-attachment-04754]] If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, and the format of the referenced attachment is a color format, pname:layout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentReference2-attachment-04755]] If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, and the format of the referenced attachment is a depth/stencil format which includes both depth and stencil aspects, and pname:layout is ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pname:pNext chain must: include a slink:VkAttachmentReferenceStencilLayout structure * [[VUID-VkAttachmentReference2-attachment-04756]] If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, and the format of the referenced attachment is a depth/stencil format which includes only the depth aspect, pname:layout must: not be ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL * [[VUID-VkAttachmentReference2-attachment-04757]] If pname:attachment is not ename:VK_ATTACHMENT_UNUSED, and the format of the referenced attachment is a depth/stencil format which includes only the stencil aspect, pname:layout must: not be ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] **** include::{generated}/validity/structs/VkAttachmentReference2.txt[] -- ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] [open,refpage='VkAttachmentReferenceStencilLayout',desc='Structure specifying an attachment description',type='structs',alias='VkAttachmentReferenceStencilLayoutKHR'] -- The sname:VkAttachmentReferenceStencilLayout structure is defined as: include::{generated}/api/structs/VkAttachmentReferenceStencilLayout.txt[] ifdef::VK_KHR_separate_depth_stencil_layouts[] or the equivalent include::{generated}/api/structs/VkAttachmentReferenceStencilLayoutKHR.txt[] endif::VK_KHR_separate_depth_stencil_layouts[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:stencilLayout is a elink:VkImageLayout value specifying the layout the stencil aspect of the attachment uses during the subpass. .Valid Usage **** * [[VUID-VkAttachmentReferenceStencilLayout-stencilLayout-03318]] pname:stencilLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED, ename:VK_IMAGE_LAYOUT_PREINITIALIZED, ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR **** include::{generated}/validity/structs/VkAttachmentReferenceStencilLayout.txt[] -- endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] [open,refpage='VkSubpassDependency2',desc='Structure specifying a subpass dependency',type='structs',alias='VkSubpassDependency2KHR'] -- :refpage: VkSubpassDependency2 The sname:VkSubpassDependency2 structure is defined as: include::{generated}/api/structs/VkSubpassDependency2.txt[] ifdef::VK_KHR_create_renderpass2[] or the equivalent include::{generated}/api/structs/VkSubpassDependency2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:srcSubpass is the subpass index of the first subpass in the dependency, or ename:VK_SUBPASS_EXTERNAL. * pname:dstSubpass is the subpass index of the second subpass in the dependency, or ename:VK_SUBPASS_EXTERNAL. * pname:srcStageMask is a bitmask of elink:VkPipelineStageFlagBits specifying the <>. * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits specifying the <> * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a <>. * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a <>. * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits. * pname:viewOffset controls which views in the source subpass the views in the destination subpass depend on. Parameters defined by this structure with the same name as those in slink:VkSubpassDependency have the identical effect to those parameters. pname:viewOffset has the same effect for the described subpass dependency as slink:VkRenderPassMultiviewCreateInfo::pname:pViewOffsets has on each corresponding subpass dependency. ifdef::VK_KHR_synchronization2[] If a slink:VkMemoryBarrier2KHR structure is included in the pname:pNext chain, pname:srcStageMask, pname:dstStageMask, pname:srcAccessMask, and pname:dstAccessMask parameters are ignored. The synchronization and access scopes instead are defined by the parameters of slink:VkMemoryBarrier2KHR. endif::VK_KHR_synchronization2[] .Valid Usage **** :stageMaskName: srcStageMask include::{chapters}/commonvalidity/stage_mask_common.txt[] :stageMaskName: dstStageMask include::{chapters}/commonvalidity/stage_mask_common.txt[] * [[VUID-VkSubpassDependency2-srcSubpass-03084]] pname:srcSubpass must: be less than or equal to pname:dstSubpass, unless one of them is ename:VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies and ensure a valid execution order * [[VUID-VkSubpassDependency2-srcSubpass-03085]] pname:srcSubpass and pname:dstSubpass must: not both be equal to ename:VK_SUBPASS_EXTERNAL * [[VUID-VkSubpassDependency2-srcSubpass-03087]] If pname:srcSubpass is equal to pname:dstSubpass and not all of the stages in pname:srcStageMask and pname:dstStageMask are <>, the <> pipeline stage in pname:srcStageMask must: be <> than or equal to the <> pipeline stage in pname:dstStageMask * [[VUID-VkSubpassDependency2-srcAccessMask-03088]] Any access flag included in pname:srcAccessMask must: be supported by one of the pipeline stages in pname:srcStageMask, as specified in the <> * [[VUID-VkSubpassDependency2-dstAccessMask-03089]] Any access flag included in pname:dstAccessMask must: be supported by one of the pipeline stages in pname:dstStageMask, as specified in the <> * [[VUID-VkSubpassDependency2-dependencyFlags-03090]] If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, pname:srcSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL * [[VUID-VkSubpassDependency2-dependencyFlags-03091]] If pname:dependencyFlags includes ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, pname:dstSubpass must: not be equal to ename:VK_SUBPASS_EXTERNAL * [[VUID-VkSubpassDependency2-srcSubpass-02245]] If pname:srcSubpass equals pname:dstSubpass, and pname:srcStageMask and pname:dstStageMask both include a <>, then pname:dependencyFlags must: include ename:VK_DEPENDENCY_BY_REGION_BIT * [[VUID-VkSubpassDependency2-viewOffset-02530]] If pname:viewOffset is not equal to `0`, pname:srcSubpass must: not be equal to pname:dstSubpass * [[VUID-VkSubpassDependency2-dependencyFlags-03092]] If pname:dependencyFlags does not include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT, pname:viewOffset must: be `0` **** include::{generated}/validity/structs/VkSubpassDependency2.txt[] -- endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] [open,refpage='vkDestroyRenderPass',desc='Destroy a render pass object',type='protos'] -- To destroy a render pass, call: include::{generated}/api/protos/vkDestroyRenderPass.txt[] * pname:device is the logical device that destroys the render pass. * pname:renderPass is the handle of the render pass to destroy. * pname:pAllocator controls host memory allocation as described in the <> chapter. .Valid Usage **** * [[VUID-vkDestroyRenderPass-renderPass-00873]] All submitted commands that refer to pname:renderPass must: have completed execution * [[VUID-vkDestroyRenderPass-renderPass-00874]] If sname:VkAllocationCallbacks were provided when pname:renderPass was created, a compatible set of callbacks must: be provided here * [[VUID-vkDestroyRenderPass-renderPass-00875]] If no sname:VkAllocationCallbacks were provided when pname:renderPass was created, pname:pAllocator must: be `NULL` **** include::{generated}/validity/protos/vkDestroyRenderPass.txt[] -- [[renderpass-compatibility]] == Render Pass Compatibility Framebuffers and graphics pipelines are created based on a specific render pass object. They must: only be used with that render pass object, or one compatible with it. Two attachment references are compatible if they have matching format and sample count, or are both ename:VK_ATTACHMENT_UNUSED or the pointer that would contain the reference is `NULL`. Two arrays of attachment references are compatible if all corresponding pairs of attachments are compatible. If the arrays are of different lengths, attachment references not present in the smaller array are treated as ename:VK_ATTACHMENT_UNUSED. Two render passes are compatible if their corresponding color, input, resolve, and depth/stencil attachment references are compatible and if they are otherwise identical except for: * Initial and final image layout in attachment descriptions * Load and store operations in attachment descriptions * Image layout in attachment references As an additional special case, if two render passes have a single subpass, the resolve attachment reference ifdef::VK_KHR_depth_stencil_resolve[] and depth/stencil resolve mode endif::VK_KHR_depth_stencil_resolve[] compatibility requirements are ignored. A framebuffer is compatible with a render pass if it was created using the same render pass or a compatible render pass. == Framebuffers [open,refpage='VkFramebuffer',desc='Opaque handle to a framebuffer object',type='handles'] -- Render passes operate in conjunction with _framebuffers_. Framebuffers represent a collection of specific memory attachments that a render pass instance uses. Framebuffers are represented by sname:VkFramebuffer handles: include::{generated}/api/handles/VkFramebuffer.txt[] -- [open,refpage='vkCreateFramebuffer',desc='Create a new framebuffer object',type='protos'] -- To create a framebuffer, call: include::{generated}/api/protos/vkCreateFramebuffer.txt[] * pname:device is the logical device that creates the framebuffer. * pname:pCreateInfo is a pointer to a slink:VkFramebufferCreateInfo structure describing additional information about framebuffer creation. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pFramebuffer is a pointer to a slink:VkFramebuffer handle in which the resulting framebuffer object is returned. .Valid Usage **** * [[VUID-vkCreateFramebuffer-pCreateInfo-02777]] If pname:pCreateInfo->flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:attachmentCount is not `0`, each element of pname:pCreateInfo->pAttachments must: have been created on pname:device **** include::{generated}/validity/protos/vkCreateFramebuffer.txt[] -- [open,refpage='VkFramebufferCreateInfo',desc='Structure specifying parameters of a newly created framebuffer',type='structs'] -- The sname:VkFramebufferCreateInfo structure is defined as: include::{generated}/api/structs/VkFramebufferCreateInfo.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is a bitmask of elink:VkFramebufferCreateFlagBits * pname:renderPass is a render pass defining what render passes the framebuffer will be compatible with. See <> for details. * pname:attachmentCount is the number of attachments. * pname:pAttachments is a pointer to an array of slink:VkImageView handles, each of which will be used as the corresponding attachment in a render pass instance. ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, this parameter is ignored. endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] * pname:width, pname:height and pname:layers define the dimensions of the framebuffer. ifdef::VK_VERSION_1_1,VK_KHR_multiview[] If the render pass uses multiview, then pname:layers must: be one and each attachment requires a number of layers that is greater than the maximum bit index set in the view mask in the subpasses in which it is used. endif::VK_VERSION_1_1,VK_KHR_multiview[] Other than the exceptions listed below, applications must: ensure that all accesses to memory that backs image subresources used as attachments in a given render pass instance either happen-before the <> for those attachments, or happen-after the <> for those attachments. [[renderpass-attachment-nonattachment]] The exceptions to the general rule are: * For depth/stencil attachments, an aspect can: be used separately as attachment and non-attachment if both accesses are read-only. ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] * For depth/stencil attachments, each aspect can: be used separately as attachment and non-attachment as long as the non-attachment accesses are also via an image subresource in either the ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL layout or the ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL layout, and the attachment resource uses whichever of those two layouts the image accesses do not. endif::VK_VERSION_1_1,VK_KHR_maintenance2[] Use of non-attachment aspects in these cases is only well defined if the attachment is used in the subpass where the non-attachment access is being made, or the layout of the image subresource is constant throughout the entire render pass instance, including the pname:initialLayout and pname:finalLayout. [NOTE] .Note ==== ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] This restriction means endif::VK_VERSION_1_1,VK_KHR_maintenance2[] ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] These restrictions mean endif::VK_VERSION_1_1,VK_KHR_maintenance2[] that the render pass has full knowledge of all uses of all of the attachments, so that the implementation is able to make correct decisions about when and how to perform layout transitions, when to overlap execution of subpasses, etc. ==== [[renderpass-noattachments]] It is legal for a subpass to use no color or depth/stencil attachments, either because it has no attachment references or because all of them are ename:VK_ATTACHMENT_UNUSED. This kind of subpass can: use shader side effects such as image stores and atomics to produce an output. In this case, the subpass continues to use the pname:width, pname:height, and pname:layers of the framebuffer to define the dimensions of the rendering area, and the pname:rasterizationSamples from each pipeline's slink:VkPipelineMultisampleStateCreateInfo to define the number of samples used in rasterization; however, if slink:VkPhysicalDeviceFeatures::pname:variableMultisampleRate is ename:VK_FALSE, then all pipelines to be bound with the subpass must: have the same value for slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples. .Valid Usage **** * [[VUID-VkFramebufferCreateInfo-attachmentCount-00876]] If pname:renderpass is not dlink:VK_NULL_HANDLE, pname:attachmentCount must: be equal to the attachment count specified in pname:renderPass * [[VUID-VkFramebufferCreateInfo-flags-02778]] If pname:renderpass is not dlink:VK_NULL_HANDLE, pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:attachmentCount is not `0`, pname:pAttachments must: be a valid pointer to an array of pname:attachmentCount valid slink:VkImageView handles * [[VUID-VkFramebufferCreateInfo-pAttachments-00877]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is used as a color attachment or resolve attachment by pname:renderPass must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT * [[VUID-VkFramebufferCreateInfo-pAttachments-02633]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is used as a depth/stencil attachment by pname:renderPass must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] * [[VUID-VkFramebufferCreateInfo-pAttachments-02634]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is used as a depth/stencil resolve attachment by pname:renderPass must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] * [[VUID-VkFramebufferCreateInfo-pAttachments-00879]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderpass is not dlink:VK_NULL_HANDLE, pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is used as an input attachment by pname:renderPass must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT ifdef::VK_EXT_fragment_density_map[] * [[VUID-VkFramebufferCreateInfo-pAttachments-02552]] If pname:renderpass is not dlink:VK_NULL_HANDLE, each element of pname:pAttachments that is used as a fragment density map attachment by pname:renderPass must: not have been created with a pname:flags value including ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT * [[VUID-VkFramebufferCreateInfo-renderPass-02553]] If pname:renderpass is not dlink:VK_NULL_HANDLE, pname:renderPass has a fragment density map attachment, and <> is not enabled, each element of pname:pAttachments must: have been created with a pname:flags value including ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT unless that element is the fragment density map attachment endif::VK_EXT_fragment_density_map[] * [[VUID-VkFramebufferCreateInfo-pAttachments-00880]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments must: have been created with a elink:VkFormat value that matches the elink:VkFormat specified by the corresponding sname:VkAttachmentDescription in pname:renderPass * [[VUID-VkFramebufferCreateInfo-pAttachments-00881]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments must: have been created with a pname:samples value that matches the pname:samples value specified by the corresponding sname:VkAttachmentDescription in pname:renderPass * [[VUID-VkFramebufferCreateInfo-flags-04533]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is used as an input, color, resolve, or depth/stencil attachment by pname:renderPass must: have been created with a slink:VkImageCreateInfo::pname:width greater than or equal to pname:width * [[VUID-VkFramebufferCreateInfo-flags-04534]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is used as an input, color, resolve, or depth/stencil attachment by pname:renderPass must: have been created with a slink:VkImageCreateInfo::pname:height greater than or equal to pname:height * [[VUID-VkFramebufferCreateInfo-flags-04535]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is used as an input, color, resolve, or depth/stencil attachment by pname:renderPass must: have been created with a slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount greater than or equal to pname:layers ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-renderPass-04536]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderPass was specified with non-zero view masks, each element of pname:pAttachments that is used as an input, color, resolve, or depth/stencil attachment by pname:renderPass must: have a pname:layerCount greater than the index of the most significant bit set in any of those view masks endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_EXT_fragment_density_map[] ifndef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-pAttachments-02744]] If pname:renderpass is not dlink:VK_NULL_HANDLE, an element of pname:pAttachments that is referenced by pname:fragmentDensityMapAttachment must: have a pname:layerCount equal to `1` endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-renderPass-02746]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderPass was specified with non-zero view masks, each element of pname:pAttachments that is referenced by pname:fragmentDensityMapAttachment must: have a pname:layerCount equal to `1` or greater than the index of the most significant bit set in any of those view masks * [[VUID-VkFramebufferCreateInfo-renderPass-02747]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderPass was not specified with non-zero view masks, each element of pname:pAttachments that is referenced by pname:fragmentDensityMapAttachment must: have a pname:layerCount equal to `1` endif::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-pAttachments-02555]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pname:pAttachments that is referenced by pname:fragmentDensityMapAttachment must: have a width at least as large as latexmath:[\left\lceil{\frac{width}{maxFragmentDensityTexelSize_{width}}}\right\rceil] * [[VUID-VkFramebufferCreateInfo-pAttachments-02556]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pname:pAttachments that is referenced by pname:fragmentDensityMapAttachment must: have a height at least as large as latexmath:[\left\lceil{\frac{height}{maxFragmentDensityTexelSize_{height}}}\right\rceil] endif::VK_EXT_fragment_density_map[] ifdef::VK_KHR_fragment_shading_rate[] ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-flags-04537]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:renderPass was specified with non-zero view masks, each element of pname:pAttachments that is used as a <> by pname:renderPass must: have a pname:layerCount that is either `1`, or greater than the index of the most significant bit set in any of those view masks * [[VUID-VkFramebufferCreateInfo-flags-04538]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:renderPass was not specified with non-zero view masks, each element of pname:pAttachments that is used as a <> by pname:renderPass must: have a pname:layerCount that is either `1`, or greater than pname:layers endif::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-flags-04539]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pname:pAttachments that is used as a <> must: have a width at least as large as [eq]#{lceil}pname:width / code:texelWidth{rceil}#, where code:texelWidth is the largest value of pname:shadingRateAttachmentTexelSize.width in a slink:VkFragmentShadingRateAttachmentInfoKHR which references that attachment * [[VUID-VkFramebufferCreateInfo-flags-04540]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pname:pAttachments that is used as a <> must: have a height at least as large as [eq]#{lceil}pname:height / code:texelHeight{rceil}#, where code:texelHeight is the largest value of pname:shadingRateAttachmentTexelSize.height in a slink:VkFragmentShadingRateAttachmentInfoKHR which references that attachment endif::VK_KHR_fragment_shading_rate[] * [[VUID-VkFramebufferCreateInfo-pAttachments-00883]] If pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments must: only specify a single mip level * [[VUID-VkFramebufferCreateInfo-pAttachments-00884]] If pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments must: have been created with the identity swizzle * [[VUID-VkFramebufferCreateInfo-width-00885]] pname:width must: be greater than `0` * [[VUID-VkFramebufferCreateInfo-width-00886]] pname:width must: be less than or equal to <> * [[VUID-VkFramebufferCreateInfo-height-00887]] pname:height must: be greater than `0` * [[VUID-VkFramebufferCreateInfo-height-00888]] pname:height must: be less than or equal to <> * [[VUID-VkFramebufferCreateInfo-layers-00889]] pname:layers must: be greater than `0` * [[VUID-VkFramebufferCreateInfo-layers-00890]] pname:layers must: be less than or equal to <> ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-renderPass-02531]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:renderPass was specified with non-zero view masks, pname:layers must: be `1` endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] * [[VUID-VkFramebufferCreateInfo-pAttachments-00891]] If pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is a 2D or 2D array image view taken from a 3D image must: not be a depth/stencil format endif::VK_VERSION_1_1,VK_KHR_maintenance1[] ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] * [[VUID-VkFramebufferCreateInfo-flags-03189]] If the <> feature is not enabled, pname:flags must: not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT * [[VUID-VkFramebufferCreateInfo-flags-03190]] If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:pNext chain must: include a slink:VkFramebufferAttachmentsCreateInfo structure * [[VUID-VkFramebufferCreateInfo-flags-03191]] If pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:attachmentImageInfoCount member of a slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext chain must: be equal to either zero or pname:attachmentCount * [[VUID-VkFramebufferCreateInfo-flags-04541]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:width member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext chain that is used as an input, color, resolve or depth/stencil attachment in pname:renderPass must: be greater than or equal to pname:width * [[VUID-VkFramebufferCreateInfo-flags-04542]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:height member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext chain that is used as an input, color, resolve or depth/stencil attachment in pname:renderPass must: be greater than or equal to pname:height ifdef::VK_EXT_fragment_density_map[] * [[VUID-VkFramebufferCreateInfo-flags-03196]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:width member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext chain that is referenced by slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment in pname:renderPass must: be greater than or equal to latexmath:[\left\lceil{\frac{width}{maxFragmentDensityTexelSize_{width}}}\right\rceil] * [[VUID-VkFramebufferCreateInfo-flags-03197]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:height member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain that is referenced by slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment in pname:renderPass must: be greater than or equal to latexmath:[\left\lceil{\frac{height}{maxFragmentDensityTexelSize_{height}}}\right\rceil] endif::VK_EXT_fragment_density_map[] ifdef::VK_KHR_fragment_shading_rate[] * [[VUID-VkFramebufferCreateInfo-flags-04543]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:width member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext chain that is used as a <> must: be greater than or equal to [eq]#{lceil}pname:width / code:texelWidth{rceil}#, where code:texelWidth is the largest value of pname:shadingRateAttachmentTexelSize.width in a slink:VkFragmentShadingRateAttachmentInfoKHR which references that attachment * [[VUID-VkFramebufferCreateInfo-flags-04544]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:height member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext chain that is used as a <> must: be greater than or equal to [eq]#{lceil}pname:height / code:texelHeight{rceil}#, where code:texelHeight is the largest value of pname:shadingRateAttachmentTexelSize.height in a slink:VkFragmentShadingRateAttachmentInfoKHR which references that attachment * [[VUID-VkFramebufferCreateInfo-flags-04545]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:layerCount member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure in the pname:pNext chain that is used as a <> must: be either `1`, or greater than or equal to pname:layers * [[VUID-VkFramebufferCreateInfo-flags-04587]] If pname:renderpass is not dlink:VK_NULL_HANDLE, pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and pname:renderPass was specified with non-zero view masks, each element of pname:pAttachments that is used as a <> by pname:renderPass must: have a pname:layerCount that is either `1`, or greater than the index of the most significant bit set in any of those view masks endif::VK_KHR_fragment_shading_rate[] ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-renderPass-03198]] If pname:renderpass is not dlink:VK_NULL_HANDLE, multiview is enabled for pname:renderPass, and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:layerCount member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain used as an input, color, resolve, or depth/stencil attachment in pname:renderPass must: be greater than the maximum bit index set in the view mask in the subpasses in which it is used in pname:renderPass * [[VUID-VkFramebufferCreateInfo-renderPass-04546]] If pname:renderpass is not dlink:VK_NULL_HANDLE, multiview is not enabled for pname:renderPass, and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:layerCount member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain used as an input, color, resolve, or depth/stencil attachment in pname:renderPass must: be greater than or equal to pname:layers endif::VK_VERSION_1_1,VK_KHR_multiview[] ifndef::VK_VERSION_1_1+VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-flags-04547]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:layerCount member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain used as an input, color, resolve, or depth/stencil attachment in pname:pRenderPass must: be greater than or equal to pname:layers endif::VK_VERSION_1_1+VK_KHR_multiview[] * [[VUID-VkFramebufferCreateInfo-flags-03201]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain that refers to an attachment used as a color attachment or resolve attachment by pname:renderPass must: include ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT * [[VUID-VkFramebufferCreateInfo-flags-03202]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain that refers to an attachment used as a depth/stencil attachment by pname:renderPass must: include ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT ifdef::VK_KHR_depth_stencil_resolve[] * [[VUID-VkFramebufferCreateInfo-flags-03203]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain that refers to an attachment used as a depth/stencil resolve attachment by pname:renderPass must: include ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT endif::VK_KHR_depth_stencil_resolve[] * [[VUID-VkFramebufferCreateInfo-flags-03204]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain that refers to an attachment used as an input attachment by pname:renderPass must: include ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT * [[VUID-VkFramebufferCreateInfo-flags-03205]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, at least one element of the pname:pViewFormats member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain must: be equal to the corresponding value of slink:VkAttachmentDescription::pname:format used to create pname:renderPass endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] * [[VUID-VkFramebufferCreateInfo-flags-04113]] If pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments must: have been created with slink:VkImageViewCreateInfo::pname:viewType not equal to ename:VK_IMAGE_VIEW_TYPE_3D ifdef::VK_KHR_fragment_shading_rate[] * [[VUID-VkFramebufferCreateInfo-flags-04548]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags does not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pname:pAttachments that is used as a fragment shading rate attachment by pname:renderPass must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] * [[VUID-VkFramebufferCreateInfo-flags-04549]] If pname:renderpass is not dlink:VK_NULL_HANDLE and pname:flags includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:usage member of any element of the pname:pAttachmentImageInfos member of a slink:VkFramebufferAttachmentsCreateInfo structure included in the pname:pNext chain that refers to an attachment used as a fragment shading rate attachment by pname:renderPass must: include ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] endif::VK_KHR_fragment_shading_rate[] **** include::{generated}/validity/structs/VkFramebufferCreateInfo.txt[] -- ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] [open,refpage='VkFramebufferAttachmentsCreateInfo',desc='Structure specifying parameters of images that will be used with a framebuffer',type='structs',alias='VkFramebufferAttachmentsCreateInfo'] -- The sname:VkFramebufferAttachmentsCreateInfo structure is defined as: include::{generated}/api/structs/VkFramebufferAttachmentsCreateInfo.txt[] ifdef::VK_KHR_imageless_framebuffer[] or the equivalent include::{generated}/api/structs/VkFramebufferAttachmentsCreateInfoKHR.txt[] endif::VK_KHR_imageless_framebuffer[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:attachmentImageInfoCount is the number of attachments being described. * pname:pAttachmentImageInfos is a pointer to an array of slink:VkFramebufferAttachmentImageInfo structures, each structure describing a number of parameters of the corresponding attachment in a render pass instance. include::{generated}/validity/structs/VkFramebufferAttachmentsCreateInfo.txt[] -- [open,refpage='VkFramebufferAttachmentImageInfo',desc='Structure specifying parameters of an image that will be used with a framebuffer',type='structs',alias='VkFramebufferAttachmentImageInfoKHR'] -- The sname:VkFramebufferAttachmentImageInfo structure is defined as: include::{generated}/api/structs/VkFramebufferAttachmentImageInfo.txt[] ifdef::VK_KHR_imageless_framebuffer[] or the equivalent include::{generated}/api/structs/VkFramebufferAttachmentImageInfoKHR.txt[] endif::VK_KHR_imageless_framebuffer[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is a bitmask of elink:VkImageCreateFlagBits, matching the value of slink:VkImageCreateInfo::pname:flags used to create an image that will be used with this framebuffer. * pname:usage is a bitmask of elink:VkImageUsageFlagBits, matching the value of slink:VkImageCreateInfo::pname:usage used to create an image used with this framebuffer. * pname:width is the width of the image view used for rendering. * pname:height is the height of the image view used for rendering. * pname:layerCount is the number of array layers of the image view used for rendering. * pname:viewFormatCount is the number of entries in the pname:pViewFormats array, matching the value of slink:VkImageFormatListCreateInfo::pname:viewFormatCount used to create an image used with this framebuffer. * pname:pViewFormats is a pointer to an array of elink:VkFormat values specifying all of the formats which can: be used when creating views of the image, matching the value of slink:VkImageFormatListCreateInfo::pname:pViewFormats used to create an image used with this framebuffer. Images that can: be used with the framebuffer when beginning a render pass, as specified by slink:VkRenderPassAttachmentBeginInfo, must: be created with parameters that are identical to those specified here. include::{generated}/validity/structs/VkFramebufferAttachmentImageInfo.txt[] -- endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] [open,refpage='VkFramebufferCreateFlagBits',desc='Bitmask specifying framebuffer properties',type='enums'] -- Bits which can: be set in slink:VkFramebufferCreateInfo::pname:flags to specify options for framebuffers are: include::{generated}/api/enums/VkFramebufferCreateFlagBits.txt[] ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] * ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT specifies that image views are not specified, and only attachment compatibility information will be provided via a slink:VkFramebufferAttachmentImageInfo structure. endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] ifndef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] [NOTE] .Note ==== All bits for this type are defined by extensions, and none of those extensions are enabled in this build of the specification. ==== endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] -- [open,refpage='VkFramebufferCreateFlags',desc='Bitmask of VkFramebufferCreateFlagBits',type='flags'] -- include::{generated}/api/flags/VkFramebufferCreateFlags.txt[] tname:VkFramebufferCreateFlags is a bitmask type for setting a mask of zero or more elink:VkFramebufferCreateFlagBits. -- [open,refpage='vkDestroyFramebuffer',desc='Destroy a framebuffer object',type='protos'] -- To destroy a framebuffer, call: include::{generated}/api/protos/vkDestroyFramebuffer.txt[] * pname:device is the logical device that destroys the framebuffer. * pname:framebuffer is the handle of the framebuffer to destroy. * pname:pAllocator controls host memory allocation as described in the <> chapter. .Valid Usage **** * [[VUID-vkDestroyFramebuffer-framebuffer-00892]] All submitted commands that refer to pname:framebuffer must: have completed execution * [[VUID-vkDestroyFramebuffer-framebuffer-00893]] If sname:VkAllocationCallbacks were provided when pname:framebuffer was created, a compatible set of callbacks must: be provided here * [[VUID-vkDestroyFramebuffer-framebuffer-00894]] If no sname:VkAllocationCallbacks were provided when pname:framebuffer was created, pname:pAllocator must: be `NULL` **** include::{generated}/validity/protos/vkDestroyFramebuffer.txt[] -- [[renderpass-commands]] == Render Pass Commands An application records the commands for a render pass instance one subpass at a time, by beginning a render pass instance, iterating over the subpasses to record commands for that subpass, and then ending the render pass instance. [open,refpage='vkCmdBeginRenderPass',desc='Begin a new render pass',type='protos'] -- To begin a render pass instance, call: include::{generated}/api/protos/vkCmdBeginRenderPass.txt[] * pname:commandBuffer is the command buffer in which to record the command. * pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses. * pname:contents is a elink:VkSubpassContents value specifying how the commands in the first subpass will be provided. After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass. .Valid Usage **** * [[VUID-vkCmdBeginRenderPass-initialLayout-00895]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT // The VU below comes in an alternate version when the extension is // enabled. ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] * [[VUID-vkCmdBeginRenderPass-initialLayout-00896]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT endif::VK_VERSION_1_1,VK_KHR_maintenance2[] // The nested ifdefs are there in anticipation of the hoped-for day when the // VU extractor and validation layers can handle VU with imbedded // conditionals. They are commented out until then. ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] * [[VUID-vkCmdBeginRenderPass-initialLayout-01758]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is // ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, // endif::VK_VERSION_1_1,VK_KHR_maintenance2[] ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] * [[VUID-vkCmdBeginRenderPass-initialLayout-02842]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-vkCmdBeginRenderPass-stencilInitialLayout-02843]] If any of the pname:stencilInitialLayout or pname:stencilFinalLayout member of the sname:VkAttachmentDescriptionStencilLayout structures or the pname:stencilLayout member of the sname:VkAttachmentReferenceStencilLayout structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] endif::VK_VERSION_1_1,VK_KHR_maintenance2[] * [[VUID-vkCmdBeginRenderPass-initialLayout-00897]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_SAMPLED_BIT or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT * [[VUID-vkCmdBeginRenderPass-initialLayout-00898]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT * [[VUID-vkCmdBeginRenderPass-initialLayout-00899]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT * [[VUID-vkCmdBeginRenderPass-initialLayout-00900]] If the pname:initialLayout member of any of the sname:VkAttachmentDescription structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each such pname:initialLayout must: be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin * [[VUID-vkCmdBeginRenderPass-srcStageMask-06451]] The pname:srcStageMask members of any element of the pname:pDependencies member of slink:VkRenderPassCreateInfo used to create pname:renderPass must: be supported by the capabilities of the queue family identified by the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo used to create the command pool which pname:commandBuffer was allocated from * [[VUID-vkCmdBeginRenderPass-dstStageMask-06452]] The pname:dstStageMask members of any element of the pname:pDependencies member of slink:VkRenderPassCreateInfo used to create pname:renderPass must: be supported by the capabilities of the queue family identified by the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo used to create the command pool which pname:commandBuffer was allocated from * [[VUID-vkCmdBeginRenderPass-framebuffer-02532]] For any attachment in pname:framebuffer that is used by pname:renderPass and is bound to memory locations that are also bound to another attachment used by pname:renderPass, and if at least one of those uses causes either attachment to be written to, both attachments must: have had the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set **** include::{generated}/validity/protos/vkCmdBeginRenderPass.txt[] -- ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] [open,refpage='vkCmdBeginRenderPass2',desc='Begin a new render pass',type='protos',alias='vkCmdBeginRenderPass2KHR'] -- Alternatively to begin a render pass, call: ifdef::VK_VERSION_1_2[] include::{generated}/api/protos/vkCmdBeginRenderPass2.txt[] endif::VK_VERSION_1_2[] ifdef::VK_VERSION_1_2+VK_KHR_create_renderpass2[or the equivalent command] ifdef::VK_KHR_create_renderpass2[] include::{generated}/api/protos/vkCmdBeginRenderPass2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:commandBuffer is the command buffer in which to record the command. * pname:pRenderPassBegin is a pointer to a slink:VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses. * pname:pSubpassBeginInfo is a pointer to a slink:VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering. After beginning a render pass instance, the command buffer is ready to record the commands for the first subpass of that render pass. .Valid Usage **** * [[VUID-vkCmdBeginRenderPass2-framebuffer-02779]] Both the pname:framebuffer and pname:renderPass members of pname:pRenderPassBegin must: have been created on the same slink:VkDevice that pname:commandBuffer was allocated on * [[VUID-vkCmdBeginRenderPass2-initialLayout-03094]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT * [[VUID-vkCmdBeginRenderPass2-initialLayout-03096]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] * [[VUID-vkCmdBeginRenderPass2-initialLayout-02844]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-vkCmdBeginRenderPass2-stencilInitialLayout-02845]] If any of the pname:stencilInitialLayout or pname:stencilFinalLayout member of the sname:VkAttachmentDescriptionStencilLayout structures or the pname:stencilLayout member of the sname:VkAttachmentReferenceStencilLayout structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] * [[VUID-vkCmdBeginRenderPass2-initialLayout-03097]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_SAMPLED_BIT or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT * [[VUID-vkCmdBeginRenderPass2-initialLayout-03098]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT * [[VUID-vkCmdBeginRenderPass2-initialLayout-03099]] If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with a pname:usage value including ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT * [[VUID-vkCmdBeginRenderPass2-initialLayout-03100]] If the pname:initialLayout member of any of the sname:VkAttachmentDescription structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is not ename:VK_IMAGE_LAYOUT_UNDEFINED, then each such pname:initialLayout must: be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin * [[VUID-vkCmdBeginRenderPass2-srcStageMask-06453]] The pname:srcStageMask members of any element of the pname:pDependencies member of slink:VkRenderPassCreateInfo used to create pname:renderPass must: be supported by the capabilities of the queue family identified by the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo used to create the command pool which pname:commandBuffer was allocated from * [[VUID-vkCmdBeginRenderPass2-dstStageMask-06454]] The pname:dstStageMask members of any element of the pname:pDependencies member of slink:VkRenderPassCreateInfo used to create pname:renderPass must: be supported by the capabilities of the queue family identified by the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo used to create the command pool which pname:commandBuffer was allocated from * [[VUID-vkCmdBeginRenderPass2-framebuffer-02533]] For any attachment in pname:framebuffer that is used by pname:renderPass and is bound to memory locations that are also bound to another attachment used by pname:renderPass, and if at least one of those uses causes either attachment to be written to, both attachments must: have had the ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set **** include::{generated}/validity/protos/vkCmdBeginRenderPass2.txt[] -- endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] [open,refpage='VkRenderPassBeginInfo',desc='Structure specifying render pass begin information',type='structs'] -- The sname:VkRenderPassBeginInfo structure is defined as: include::{generated}/api/structs/VkRenderPassBeginInfo.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:renderPass is the render pass to begin an instance of. * pname:framebuffer is the framebuffer containing the attachments that are used with the render pass. * pname:renderArea is the render area that is affected by the render pass instance, and is described in more detail below. * pname:clearValueCount is the number of elements in pname:pClearValues. * pname:pClearValues is a pointer to an array of pname:clearValueCount slink:VkClearValue structures containing clear values for each attachment, if the attachment uses a pname:loadOp value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR or if the attachment has a depth/stencil format and uses a pname:stencilLoadOp value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR. The array is indexed by attachment number. Only elements corresponding to cleared attachments are used. Other elements of pname:pClearValues are ignored. pname:renderArea is the render area that is affected by the render pass instance. The effects of attachment load, store and multisample resolve operations are restricted to the pixels whose x and y coordinates fall within the render area on all attachments. The render area extends to all layers of pname:framebuffer. The application must: ensure (using scissor if necessary) that all rendering is contained within the render area. ifndef::VK_QCOM_render_pass_transform[] The render area must: be contained within the framebuffer dimensions. endif::VK_QCOM_render_pass_transform[] ifdef::VK_QCOM_render_pass_transform[] The render area, after any transform specified by slink:VkRenderPassTransformBeginInfoQCOM::pname:transform is applied, must: be contained within the framebuffer dimensions. endif::VK_QCOM_render_pass_transform[] ifdef::VK_QCOM_render_pass_transform[] If <> is enabled, then pname:renderArea must: equal the framebuffer pre-transformed dimensions. After pname:renderArea has been transformed by slink:VkRenderPassTransformBeginInfoQCOM::pname:transform, the resulting render area must: be equal to the framebuffer dimensions. endif::VK_QCOM_render_pass_transform[] ifdef::VK_HUAWEI_subpass_shading[] If <> is enabled, then pname:renderArea must: equal the framebuffer dimensions. endif::VK_HUAWEI_subpass_shading[] ifdef::VK_VERSION_1_1,VK_KHR_multiview[] When multiview is enabled, the resolve operation at the end of a subpass applies to all views in the view mask. endif::VK_VERSION_1_1,VK_KHR_multiview[] [NOTE] .Note ==== There may: be a performance cost for using a render area smaller than the framebuffer, unless it matches the render area granularity for the render pass. ==== .Valid Usage **** * [[VUID-VkRenderPassBeginInfo-clearValueCount-00902]] pname:clearValueCount must: be greater than the largest attachment index in pname:renderPass specifying a pname:loadOp (or pname:stencilLoadOp, if the attachment has a depth/stencil format) of ename:VK_ATTACHMENT_LOAD_OP_CLEAR * [[VUID-VkRenderPassBeginInfo-clearValueCount-04962]] If pname:clearValueCount is not `0`, pname:pClearValues must: be a valid pointer to an array of pname:clearValueCount slink:VkClearValue unions * [[VUID-VkRenderPassBeginInfo-renderPass-00904]] pname:renderPass must: be <> with the pname:renderPass member of the slink:VkFramebufferCreateInfo structure specified when creating pname:framebuffer ifndef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderPassBeginInfo-renderArea-02846]] pname:renderArea.offset.x must: be greater than or equal to 0 * [[VUID-VkRenderPassBeginInfo-renderArea-02847]] pname:renderArea.offset.y must: be greater than or equal to 0 * [[VUID-VkRenderPassBeginInfo-renderArea-02848]] [eq]#pname:renderArea.offset.x {plus} pname:renderArea.extent.width# must: be less than or equal to slink:VkFramebufferCreateInfo::pname:width the pname:framebuffer was created with * [[VUID-VkRenderPassBeginInfo-renderArea-02849]] [eq]#pname:renderArea.offset.y {plus} pname:renderArea.extent.height# must: be less than or equal to slink:VkFramebufferCreateInfo::pname:height the pname:framebuffer was created with endif::VK_VERSION_1_1,VK_KHR_device_group[] ifdef::VK_VERSION_1_1,VK_KHR_device_group[] * [[VUID-VkRenderPassBeginInfo-pNext-02850]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, pname:renderArea.offset.x must: be greater than or equal to 0 * [[VUID-VkRenderPassBeginInfo-pNext-02851]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, pname:renderArea.offset.y must: be greater than or equal to 0 * [[VUID-VkRenderPassBeginInfo-pNext-02852]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, [eq]#pname:renderArea.offset.x {plus} pname:renderArea.extent.width# must: be less than or equal to slink:VkFramebufferCreateInfo::pname:width the pname:framebuffer was created with * [[VUID-VkRenderPassBeginInfo-pNext-02853]] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, [eq]#pname:renderArea.offset.y {plus} pname:renderArea.extent.height# must: be less than or equal to slink:VkFramebufferCreateInfo::pname:height the pname:framebuffer was created with * [[VUID-VkRenderPassBeginInfo-pNext-02856]] If the pname:pNext chain contains slink:VkDeviceGroupRenderPassBeginInfo, [eq]#pname:offset.x {plus} pname:extent.width# of each element of pname:pDeviceRenderAreas must: be less than or equal to slink:VkFramebufferCreateInfo::pname:width the pname:framebuffer was created with * [[VUID-VkRenderPassBeginInfo-pNext-02857]] If the pname:pNext chain contains slink:VkDeviceGroupRenderPassBeginInfo, [eq]#pname:offset.y {plus} pname:extent.height# of each element of pname:pDeviceRenderAreas must: be less than or equal to slink:VkFramebufferCreateInfo::pname:height the pname:framebuffer was created with endif::VK_VERSION_1_1,VK_KHR_device_group[] ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] * [[VUID-VkRenderPassBeginInfo-framebuffer-03207]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that did not include ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and the pname:pNext chain includes a slink:VkRenderPassAttachmentBeginInfo structure, its pname:attachmentCount must: be zero * [[VUID-VkRenderPassBeginInfo-framebuffer-03208]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pname:attachmentCount of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be equal to the value of slink:VkFramebufferAttachmentsCreateInfo::pname:attachmentImageInfoCount used to create pname:framebuffer * [[VUID-VkRenderPassBeginInfo-framebuffer-02780]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: have been created on the same slink:VkDevice as pname:framebuffer and pname:renderPass * [[VUID-VkRenderPassBeginInfo-framebuffer-03209]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView of an image created with a value of slink:VkImageCreateInfo::pname:flags equal to the pname:flags member of the corresponding element of slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos used to create pname:framebuffer * [[VUID-VkRenderPassBeginInfo-framebuffer-04627]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView with <> equal to the pname:usage member of the corresponding element of slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos used to create pname:framebuffer * [[VUID-VkRenderPassBeginInfo-framebuffer-03211]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView with a width equal to the pname:width member of the corresponding element of slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos used to create pname:framebuffer * [[VUID-VkRenderPassBeginInfo-framebuffer-03212]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView with a height equal to the pname:height member of the corresponding element of slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos used to create pname:framebuffer * [[VUID-VkRenderPassBeginInfo-framebuffer-03213]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView of an image created with a value of slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount equal to the pname:layerCount member of the corresponding element of slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos used to create pname:framebuffer * [[VUID-VkRenderPassBeginInfo-framebuffer-03214]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView of an image created with a value of slink:VkImageFormatListCreateInfo::pname:viewFormatCount equal to the pname:viewFormatCount member of the corresponding element of slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos used to create pname:framebuffer * [[VUID-VkRenderPassBeginInfo-framebuffer-03215]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView of an image created with a set of elements in slink:VkImageFormatListCreateInfo::pname:pViewFormats equal to the set of elements in the pname:pViewFormats member of the corresponding element of slink:VkFramebufferAttachmentsCreateInfo::pname:pAttachmentImageInfos used to create pname:framebuffer * [[VUID-VkRenderPassBeginInfo-framebuffer-03216]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView of an image created with a value of slink:VkImageViewCreateInfo::pname:format equal to the corresponding value of slink:VkAttachmentDescription::pname:format in pname:renderPass * [[VUID-VkRenderPassBeginInfo-framebuffer-03217]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo structure included in the pname:pNext chain must: be a slink:VkImageView of an image created with a value of slink:VkImageCreateInfo::pname:samples equal to the corresponding value of slink:VkAttachmentDescription::pname:samples in pname:renderPass endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] ifdef::VK_QCOM_render_pass_transform[] * [[VUID-VkRenderPassBeginInfo-pNext-02869]] If the pname:pNext chain includes slink:VkRenderPassTransformBeginInfoQCOM, pname:renderArea.offset must: equal (0,0) * [[VUID-VkRenderPassBeginInfo-pNext-02870]] If the pname:pNext chain includes slink:VkRenderPassTransformBeginInfoQCOM, pname:renderArea.extent transformed by slink:VkRenderPassTransformBeginInfoQCOM::pname:transform must: equal the pname:framebuffer dimensions endif::VK_QCOM_render_pass_transform[] **** include::{generated}/validity/structs/VkRenderPassBeginInfo.txt[] -- ifdef::VK_EXT_sample_locations[] [open,refpage='VkRenderPassSampleLocationsBeginInfoEXT',desc='Structure specifying sample locations to use for the layout transition of custom sample locations compatible depth/stencil attachments',type='structs'] -- The image layout of the depth aspect of a depth/stencil attachment referring to an image created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent on the last sample locations used to render to the image subresource, thus preserving the contents of such depth/stencil attachments across subpass boundaries requires the application to specify these sample locations whenever a layout transition of the attachment may: occur. This information can: be provided by adding a sname:VkRenderPassSampleLocationsBeginInfoEXT structure to the pname:pNext chain of sname:VkRenderPassBeginInfo. The sname:VkRenderPassSampleLocationsBeginInfoEXT structure is defined as: include::{generated}/api/structs/VkRenderPassSampleLocationsBeginInfoEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:attachmentInitialSampleLocationsCount is the number of elements in the pname:pAttachmentInitialSampleLocations array. * pname:pAttachmentInitialSampleLocations is a pointer to an array of pname:attachmentInitialSampleLocationsCount slink:VkAttachmentSampleLocationsEXT structures specifying the attachment indices and their corresponding sample location state. Each element of pname:pAttachmentInitialSampleLocations can: specify the sample location state to use in the automatic layout transition performed to transition a depth/stencil attachment from the initial layout of the attachment to the image layout specified for the attachment in the first subpass using it. * pname:postSubpassSampleLocationsCount is the number of elements in the pname:pPostSubpassSampleLocations array. * pname:pPostSubpassSampleLocations is a pointer to an array of pname:postSubpassSampleLocationsCount slink:VkSubpassSampleLocationsEXT structures specifying the subpass indices and their corresponding sample location state. Each element of pname:pPostSubpassSampleLocations can: specify the sample location state to use in the automatic layout transition performed to transition the depth/stencil attachment used by the specified subpass to the image layout specified in a dependent subpass or to the final layout of the attachment in case the specified subpass is the last subpass using that attachment. In addition, if slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations is ename:VK_FALSE, each element of pname:pPostSubpassSampleLocations must: specify the sample location state that matches the sample locations used by all pipelines that will be bound to a command buffer during the specified subpass. If pname:variableSampleLocations is ename:VK_TRUE, the sample locations used for rasterization do not depend on pname:pPostSubpassSampleLocations. include::{generated}/validity/structs/VkRenderPassSampleLocationsBeginInfoEXT.txt[] -- [open,refpage='VkAttachmentSampleLocationsEXT',desc='Structure specifying the sample locations state to use in the initial layout transition of attachments',type='structs'] -- The sname:VkAttachmentSampleLocationsEXT structure is defined as: include::{generated}/api/structs/VkAttachmentSampleLocationsEXT.txt[] * pname:attachmentIndex is the index of the attachment for which the sample locations state is provided. * pname:sampleLocationsInfo is the sample locations state to use for the layout transition of the given attachment from the initial layout of the attachment to the image layout specified for the attachment in the first subpass using it. If the image referenced by the framebuffer attachment at index pname:attachmentIndex was not created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT then the values specified in pname:sampleLocationsInfo are ignored. .Valid Usage **** * [[VUID-VkAttachmentSampleLocationsEXT-attachmentIndex-01531]] pname:attachmentIndex must: be less than the pname:attachmentCount specified in slink:VkRenderPassCreateInfo the render pass specified by slink:VkRenderPassBeginInfo::pname:renderPass was created with **** include::{generated}/validity/structs/VkAttachmentSampleLocationsEXT.txt[] -- [open,refpage='VkSubpassSampleLocationsEXT',desc='Structure specifying the sample locations state to use for layout transitions of attachments performed after a given subpass',type='structs'] -- The sname:VkSubpassSampleLocationsEXT structure is defined as: include::{generated}/api/structs/VkSubpassSampleLocationsEXT.txt[] * pname:subpassIndex is the index of the subpass for which the sample locations state is provided. * pname:sampleLocationsInfo is the sample locations state to use for the layout transition of the depth/stencil attachment away from the image layout the attachment is used with in the subpass specified in pname:subpassIndex. If the image referenced by the depth/stencil attachment used in the subpass identified by pname:subpassIndex was not created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT or if the subpass does not use a depth/stencil attachment, and slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations is ename:VK_TRUE then the values specified in pname:sampleLocationsInfo are ignored. .Valid Usage **** * [[VUID-VkSubpassSampleLocationsEXT-subpassIndex-01532]] pname:subpassIndex must: be less than the pname:subpassCount specified in slink:VkRenderPassCreateInfo the render pass specified by slink:VkRenderPassBeginInfo::pname:renderPass was created with **** include::{generated}/validity/structs/VkSubpassSampleLocationsEXT.txt[] -- endif::VK_EXT_sample_locations[] ifdef::VK_QCOM_render_pass_transform[] [open,refpage='VkRenderPassTransformBeginInfoQCOM',desc='Structure describing transform parameters of a render pass instance',type='structs'] -- To begin a render pass instance with <> enabled, add the slink:VkRenderPassTransformBeginInfoQCOM to the pname:pNext chain of slink:VkRenderPassBeginInfo structure passed to the flink:vkCmdBeginRenderPass command specifying the render pass transform. The sname:VkRenderPassTransformBeginInfoQCOM structure is defined as: include::{generated}/api/structs/VkRenderPassTransformBeginInfoQCOM.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to rasterization. .Valid Usage **** * [[VUID-VkRenderPassTransformBeginInfoQCOM-transform-02871]] pname:transform must: be ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR * [[VUID-VkRenderPassTransformBeginInfoQCOM-flags-02872]] The pname:renderpass must: have been created with slink:VkRenderPassCreateInfo::pname:flags containing ename:VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM **** include::{generated}/validity/structs/VkRenderPassTransformBeginInfoQCOM.txt[] -- endif::VK_QCOM_render_pass_transform[] ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] [open,refpage='VkSubpassBeginInfo',desc='Structure specifying subpass begin information',type='structs',alias='VkSubpassBeginInfoKHR'] -- The sname:VkSubpassBeginInfo structure is defined as: include::{generated}/api/structs/VkSubpassBeginInfo.txt[] ifdef::VK_KHR_create_renderpass2[] or the equivalent include::{generated}/api/structs/VkSubpassBeginInfoKHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:contents is a elink:VkSubpassContents value specifying how the commands in the next subpass will be provided. include::{generated}/validity/structs/VkSubpassBeginInfo.txt[] -- endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] [open,refpage='VkSubpassContents',desc='Specify how commands in the first subpass of a render pass are provided',type='enums'] -- Possible values of flink:vkCmdBeginRenderPass::pname:contents, specifying how the commands in the first subpass will be provided, are: include::{generated}/api/enums/VkSubpassContents.txt[] * ename:VK_SUBPASS_CONTENTS_INLINE specifies that the contents of the subpass will be recorded inline in the primary command buffer, and secondary command buffers must: not be executed within the subpass. * ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS specifies that the contents are recorded in secondary command buffers that will be called from the primary command buffer, and flink:vkCmdExecuteCommands is the only valid command on the command buffer until flink:vkCmdNextSubpass or flink:vkCmdEndRenderPass. -- ifdef::VK_VERSION_1_1,VK_KHR_device_group[] [open,refpage='VkDeviceGroupRenderPassBeginInfo',desc='Set the initial device mask and render areas for a render pass instance',type='structs'] -- If the pname:pNext chain of slink:VkRenderPassBeginInfo ifdef::VK_KHR_dynamic_rendering[or slink:VkRenderingInfoKHR] includes a sname:VkDeviceGroupRenderPassBeginInfo structure, then that structure includes a device mask and set of render areas for the render pass instance. The sname:VkDeviceGroupRenderPassBeginInfo structure is defined as: include::{generated}/api/structs/VkDeviceGroupRenderPassBeginInfo.txt[] ifdef::VK_KHR_device_group[] or the equivalent include::{generated}/api/structs/VkDeviceGroupRenderPassBeginInfoKHR.txt[] endif::VK_KHR_device_group[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:deviceMask is the device mask for the render pass instance. * pname:deviceRenderAreaCount is the number of elements in the pname:pDeviceRenderAreas array. * pname:pDeviceRenderAreas is a pointer to an array of slink:VkRect2D structures defining the render area for each physical device. The pname:deviceMask serves several purposes. It is an upper bound on the set of physical devices that can: be used during the render pass instance, and the initial device mask when the render pass instance begins. In addition, commands transitioning to the next subpass in a render pass instance and commands ending the render pass instance, and, accordingly render pass attachment load, store, and resolve operations and subpass dependencies corresponding to the render pass instance, are executed on the physical devices included in the device mask provided here. If pname:deviceRenderAreaCount is not zero, then the elements of pname:pDeviceRenderAreas override the value of slink:VkRenderPassBeginInfo::pname:renderArea, and provide a render area specific to each physical device. These render areas serve the same purpose as slink:VkRenderPassBeginInfo::pname:renderArea, including controlling the region of attachments that are cleared by ename:VK_ATTACHMENT_LOAD_OP_CLEAR and that are resolved into resolve attachments. If this structure is not present, the render pass instance's device mask is the value of slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask. If this structure is not present or if pname:deviceRenderAreaCount is zero, slink:VkRenderPassBeginInfo::pname:renderArea is used for all physical devices. .Valid Usage **** * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00905]] pname:deviceMask must: be a valid device mask value * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00906]] pname:deviceMask must: not be zero * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00907]] pname:deviceMask must: be a subset of the command buffer's initial device mask * [[VUID-VkDeviceGroupRenderPassBeginInfo-deviceRenderAreaCount-00908]] pname:deviceRenderAreaCount must: either be zero or equal to the number of physical devices in the logical device * [[VUID-VkDeviceGroupRenderPassBeginInfo-offset-06166]] The pname:offset.x member of any element of pname:pDeviceRenderAreas must: be greater than or equal to 0 * [[VUID-VkDeviceGroupRenderPassBeginInfo-offset-06167]] The pname:offset.y member of any element of pname:pDeviceRenderAreas must: be greater than or equal to 0 * [[VUID-VkDeviceGroupRenderPassBeginInfo-offset-06168]] The sum of the pname:offset.x and pname:extent.width members of any element of pname:pDeviceRenderAreas must: be less than or equal to <> * [[VUID-VkDeviceGroupRenderPassBeginInfo-offset-06169]] The sum of the pname:offset.y and pname:extent.height members of any element of pname:pDeviceRenderAreas must: be less than or equal to <> **** include::{generated}/validity/structs/VkDeviceGroupRenderPassBeginInfo.txt[] -- endif::VK_VERSION_1_1,VK_KHR_device_group[] ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] [open,refpage='VkRenderPassAttachmentBeginInfo',desc='Structure specifying images to be used as framebuffer attachments',type='structs',alias='VkRenderPassAttachmentBeginInfoKHR'] -- The sname:VkRenderPassAttachmentBeginInfo structure is defined as: include::{generated}/api/structs/VkRenderPassAttachmentBeginInfo.txt[] ifdef::VK_KHR_imageless_framebuffer[] or the equivalent include::{generated}/api/structs/VkRenderPassAttachmentBeginInfoKHR.txt[] endif::VK_KHR_imageless_framebuffer[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:attachmentCount is the number of attachments. * pname:pAttachments is a pointer to an array of sname:VkImageView handles, each of which will be used as the corresponding attachment in the render pass instance. .Valid Usage **** * [[VUID-VkRenderPassAttachmentBeginInfo-pAttachments-03218]] Each element of pname:pAttachments must: only specify a single mip level * [[VUID-VkRenderPassAttachmentBeginInfo-pAttachments-03219]] Each element of pname:pAttachments must: have been created with the identity swizzle * [[VUID-VkRenderPassAttachmentBeginInfo-pAttachments-04114]] Each element of pname:pAttachments must: have been created with slink:VkImageViewCreateInfo::pname:viewType not equal to ename:VK_IMAGE_VIEW_TYPE_3D **** include::{generated}/validity/structs/VkRenderPassAttachmentBeginInfo.txt[] -- endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] [open,refpage='vkGetRenderAreaGranularity',desc='Returns the granularity for optimal render area',type='protos'] -- To query the render area granularity, call: include::{generated}/api/protos/vkGetRenderAreaGranularity.txt[] * pname:device is the logical device that owns the render pass. * pname:renderPass is a handle to a render pass. * pname:pGranularity is a pointer to a slink:VkExtent2D structure in which the granularity is returned. The conditions leading to an optimal pname:renderArea are: * the pname:offset.x member in pname:renderArea is a multiple of the pname:width member of the returned slink:VkExtent2D (the horizontal granularity). * the pname:offset.y member in pname:renderArea is a multiple of the pname:height member of the returned slink:VkExtent2D (the vertical granularity). * either the pname:extent.width member in pname:renderArea is a multiple of the horizontal granularity or pname:offset.x+pname:extent.width is equal to the pname:width of the pname:framebuffer in the slink:VkRenderPassBeginInfo. * either the pname:extent.height member in pname:renderArea is a multiple of the vertical granularity or pname:offset.y+pname:extent.height is equal to the pname:height of the pname:framebuffer in the slink:VkRenderPassBeginInfo. Subpass dependencies are not affected by the render area, and apply to the entire image subresources attached to the framebuffer as specified in the description of <>. Similarly, pipeline barriers are valid even if their effect extends outside the render area. include::{generated}/validity/protos/vkGetRenderAreaGranularity.txt[] -- [open,refpage='vkCmdNextSubpass',desc='Transition to the next subpass of a render pass',type='protos'] -- To transition to the next subpass in the render pass instance after recording the commands for a subpass, call: include::{generated}/api/protos/vkCmdNextSubpass.txt[] * pname:commandBuffer is the command buffer in which to record the command. * pname:contents specifies how the commands in the next subpass will be provided, in the same fashion as the corresponding parameter of flink:vkCmdBeginRenderPass. The subpass index for a render pass begins at zero when fname:vkCmdBeginRenderPass is recorded, and increments each time fname:vkCmdNextSubpass is recorded. Moving to the next subpass automatically performs any multisample resolve operations in the subpass being ended. End-of-subpass multisample resolves are treated as color attachment writes for the purposes of synchronization. ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] This applies to resolve operations for both color and depth/stencil attachments. endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] That is, they are considered to execute in the ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage and their writes are synchronized with ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. Synchronization between rendering within a subpass and any resolve operations at the end of the subpass occurs automatically, without need for explicit dependencies or pipeline barriers. However, if the resolve attachment is also used in a different subpass, an explicit dependency is needed. After transitioning to the next subpass, the application can: record the commands for that subpass. .Valid Usage **** * [[VUID-vkCmdNextSubpass-None-00909]] The current subpass index must: be less than the number of subpasses in the render pass minus one ifdef::VK_EXT_transform_feedback[] * [[VUID-vkCmdNextSubpass-None-02349]] This command must: not be recorded when transform feedback is active endif::VK_EXT_transform_feedback[] **** include::{generated}/validity/protos/vkCmdNextSubpass.txt[] -- ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] [open,refpage='vkCmdNextSubpass2',desc='Transition to the next subpass of a render pass',type='protos',alias='vkCmdNextSubpass2KHR'] -- To transition to the next subpass in the render pass instance after recording the commands for a subpass, call: ifdef::VK_VERSION_1_2[] include::{generated}/api/protos/vkCmdNextSubpass2.txt[] endif::VK_VERSION_1_2[] ifdef::VK_VERSION_1_2+VK_KHR_create_renderpass2[or the equivalent command] ifdef::VK_KHR_create_renderpass2[] include::{generated}/api/protos/vkCmdNextSubpass2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:commandBuffer is the command buffer in which to record the command. * pname:pSubpassBeginInfo is a pointer to a slink:VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering. * pname:pSubpassEndInfo is a pointer to a slink:VkSubpassEndInfo structure containing information about how the previous subpass will be ended. fname:vkCmdNextSubpass2 is semantically identical to flink:vkCmdNextSubpass, except that it is extensible, and that pname:contents is provided as part of an extensible structure instead of as a flat parameter. .Valid Usage **** * [[VUID-vkCmdNextSubpass2-None-03102]] The current subpass index must: be less than the number of subpasses in the render pass minus one ifdef::VK_EXT_transform_feedback[] * [[VUID-vkCmdNextSubpass2-None-02350]] This command must: not be recorded when transform feedback is active endif::VK_EXT_transform_feedback[] **** include::{generated}/validity/protos/vkCmdNextSubpass2.txt[] -- endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] [open,refpage='vkCmdEndRenderPass',desc='End the current render pass',type='protos'] -- To record a command to end a render pass instance after recording the commands for the last subpass, call: include::{generated}/api/protos/vkCmdEndRenderPass.txt[] * pname:commandBuffer is the command buffer in which to end the current render pass instance. Ending a render pass instance performs any multisample resolve operations on the final subpass. .Valid Usage **** * [[VUID-vkCmdEndRenderPass-None-00910]] The current subpass index must: be equal to the number of subpasses in the render pass minus one ifdef::VK_EXT_transform_feedback[] * [[VUID-vkCmdEndRenderPass-None-02351]] This command must: not be recorded when transform feedback is active endif::VK_EXT_transform_feedback[] ifdef::VK_KHR_dynamic_rendering[] * [[VUID-vkCmdEndRenderPass-None-06170]] The current render pass instance must: not have been begun with flink:vkCmdBeginRenderingKHR endif::VK_KHR_dynamic_rendering[] **** include::{generated}/validity/protos/vkCmdEndRenderPass.txt[] -- ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] [open,refpage='vkCmdEndRenderPass2',desc='End the current render pass',type='protos',alias='vkCmdEndRenderPass2KHR'] -- To record a command to end a render pass instance after recording the commands for the last subpass, call: ifdef::VK_VERSION_1_2[] include::{generated}/api/protos/vkCmdEndRenderPass2.txt[] endif::VK_VERSION_1_2[] ifdef::VK_VERSION_1_2+VK_KHR_create_renderpass2[or the equivalent command] ifdef::VK_KHR_create_renderpass2[] include::{generated}/api/protos/vkCmdEndRenderPass2KHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:commandBuffer is the command buffer in which to end the current render pass instance. * pname:pSubpassEndInfo is a pointer to a slink:VkSubpassEndInfo structure containing information about how the previous subpass will be ended. fname:vkCmdEndRenderPass2 is semantically identical to flink:vkCmdEndRenderPass, except that it is extensible. .Valid Usage **** * [[VUID-vkCmdEndRenderPass2-None-03103]] The current subpass index must: be equal to the number of subpasses in the render pass minus one ifdef::VK_EXT_transform_feedback[] * [[VUID-vkCmdEndRenderPass2-None-02352]] This command must: not be recorded when transform feedback is active endif::VK_EXT_transform_feedback[] ifdef::VK_KHR_dynamic_rendering[] * [[VUID-vkCmdEndRenderPass2-None-06171]] The current render pass instance must: not have been begun with flink:vkCmdBeginRenderingKHR endif::VK_KHR_dynamic_rendering[] **** include::{generated}/validity/protos/vkCmdEndRenderPass2.txt[] -- [open,refpage='VkSubpassEndInfo',desc='Structure specifying subpass end information',type='structs',alias='VkSubpassEndInfoKHR'] -- The sname:VkSubpassEndInfo structure is defined as: include::{generated}/api/structs/VkSubpassEndInfo.txt[] ifdef::VK_KHR_create_renderpass2[] or the equivalent include::{generated}/api/structs/VkSubpassEndInfoKHR.txt[] endif::VK_KHR_create_renderpass2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. include::{generated}/validity/structs/VkSubpassEndInfo.txt[] -- endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[]