| // Copyright 2015-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[renderpass]] |
| = Render Pass |
| |
| <<drawing, Draw commands>> 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 <<drawing,draw commands>>. |
| |
| 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 <<synchronization-submission-order, submission order>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdBeginRenderingKHR-dynamicRendering-06446]] |
| The <<features-dynamicRendering,pname:dynamicRendering>> 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 <<limits-maxFramebufferWidth, |
| pname:maxFramebufferWidth>> |
| * [[VUID-VkRenderingInfoKHR-renderArea-06074]] |
| The sum of pname:renderArea.offset.y and pname:renderArea.extent.height |
| must: be less than or equal to <<limits-maxFramebufferHeight, |
| pname:maxFramebufferHeight>> |
| * [[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-06081]] |
| If the pname:pNext chain contains |
| slink:VkDeviceGroupRenderPassBeginInfo, the pname:offset.x member of |
| each element of pname:pDeviceRenderAreas must: be greater than or equal |
| to 0 |
| * [[VUID-VkRenderingInfoKHR-pNext-06082]] |
| If the pname:pNext chain contains |
| slink:VkDeviceGroupRenderPassBeginInfo, the pname:offset.y member of |
| each element of pname:pDeviceRenderAreas must: be greater than or equal |
| to 0 |
| * [[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 |
| <<features-fragmentDensityMapNonSubsampledImages,non-subsample image |
| feature>> 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 <<features-multiview,pname:multiview>> 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 <<limits-maxMultiviewViewCount,pname:maxMultiviewViewCount>> |
| 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 that defines 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 |
| <<primsrast-fragment-shading-rate-attachment, fragment shading rate |
| attachment>>. |
| 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 <<limits-maxFragmentShadingRateAttachmentTexelSize, |
| pname:maxFragmentShadingRateAttachmentTexelSize.width>> |
| * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06151]] |
| If pname:imageView is not dlink:VK_NULL_HANDLE, |
| pname:shadingRateAttachmentTexelSize.width must: be greater than or |
| equal to <<limits-minFragmentShadingRateAttachmentTexelSize, |
| pname:minFragmentShadingRateAttachmentTexelSize.width>> |
| * [[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 <<limits-maxFragmentShadingRateAttachmentTexelSize, |
| pname:maxFragmentShadingRateAttachmentTexelSize.height>> |
| * [[VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06154]] |
| If pname:imageView is not dlink:VK_NULL_HANDLE, |
| pname:shadingRateAttachmentTexelSize.height must: be greater than or |
| equal to <<limits-minFragmentShadingRateAttachmentTexelSize, |
| pname:minFragmentShadingRateAttachmentTexelSize.height>> |
| * [[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 <<limits-maxFragmentShadingRateAttachmentTexelSizeAspectRatio, |
| pname:maxFragmentShadingRateAttachmentTexelSizeAspectRatio>> |
| * [[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 <<limits-maxFragmentShadingRateAttachmentTexelSizeAspectRatio, |
| pname:maxFragmentShadingRateAttachmentTexelSizeAspectRatio>> |
| **** |
| |
| 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 |
| <<synchronization-submission-order, submission order>>. |
| |
| .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's 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 <<synchronization-dependencies, execution |
| and memory dependencies>> 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 <<synchronization-submission-order, submission |
| order>> 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 <<synchronization-implicit, implicit ordering |
| guarantees>>. |
| |
| 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 <<renderpass-compatibility,Render Pass |
| Compatibility>>). |
| 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 <<synchronization-pipeline-stages-order, |
| pipeline order>>. |
| However for a given (x,y,layer,sample) sample location, certain per-sample |
| operations are performed in <<primsrast-order,rasterization order>>. |
| |
| [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 |
| <<memory-allocation, Memory Allocation>> 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, it must: be less than |
| pname:attachmentCount |
| * [[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 <<synchronization-pipeline-stages-types, pipeline>> |
| 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 <<synchronization-pipeline-stages-types, pipeline>> |
| 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 |
| <<vertexpostproc-renderpass-transform, render pass transform>>. |
| -- |
| 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 |
| <<features-multiview-gs,geometry shaders>> or |
| <<features-multiview-tess,tessellation shaders>>. |
| |
| [[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-02547]] |
| If pname:fragmentDensityMapAttachment is not ename:VK_ATTACHMENT_UNUSED, |
| pname:fragmentDensityMapAttachment must: be less than |
| sname:VkRenderPassCreateInfo::pname:attachmentCount |
| * [[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 <<fundamentals-numerics,Numeric |
| Representation and Computation>> and <<fundamentals-fixedconv, Fixed-Point |
| Data Conversions>>. |
| |
| [[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 |
| <<renderpass-feedbackloop, below>>. |
| |
| 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 <<features-separateDepthStencilLayouts, |
| pname:separateDepthStencilLayouts>> 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 <<features-separateDepthStencilLayouts, |
| pname:separateDepthStencilLayouts>> 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 <<vertexpostproc-renderpass-transform, render pass transform>>. |
| 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 <<framebuffer-color-write-enable,Color Write Enable>> 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 |
| <<potential-format-features, potential format features>> 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 |
| <<potential-format-features, potential format features>> 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 |
| <<potential-format-features, potential format features>> 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 |
| <<potential-format-features, potential format features>> 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 <<attachment-type-imagelayout, image |
| layout requirements>> 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-03342]] |
| If pname:flags includes |
| ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if |
| pname:pDepthStencilResolveAttachmentKHR is not `NULL`, then the |
| depth/stencil 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 |
| <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader |
| stage>>. |
| 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[] |
| |
| 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'] |
| -- |
| 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 <<synchronization-pipeline-stages-masks, source stage |
| mask>>. |
| * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits |
| specifying the <<synchronization-pipeline-stages-masks, destination |
| stage mask>> |
| * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a |
| <<synchronization-access-masks, source access mask>>. |
| * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a |
| <<synchronization-access-masks, destination access mask>>. |
| * pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits. |
| |
| If pname:srcSubpass is equal to pname:dstSubpass then the |
| slink:VkSubpassDependency describes a |
| <<synchronization-pipeline-barriers-subpass-self-dependencies, subpass |
| self-dependency>>, 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 |
| <<synchronization-dependencies-scopes, synchronization scope>> includes |
| commands that occur earlier in <<synchronization-submission-order,submission |
| order>> 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 |
| <<synchronization-pipeline-stages-masks, source stage mask>> specified by |
| pname:srcStageMask. |
| |
| If pname:dstSubpass is equal to ename:VK_SUBPASS_EXTERNAL, the second |
| <<synchronization-dependencies-scopes, synchronization scope>> includes |
| commands that occur later in <<synchronization-submission-order,submission |
| order>> 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 |
| <<synchronization-pipeline-stages-masks, destination stage mask>> specified |
| by pname:dstStageMask. |
| |
| The first <<synchronization-dependencies-access-scopes, access scope>> is |
| limited to accesses in the pipeline stages determined by the |
| <<synchronization-pipeline-stages-masks, source stage mask>> specified by |
| pname:srcStageMask. |
| It is also limited to access types in the <<synchronization-access-masks, |
| source access mask>> specified by pname:srcAccessMask. |
| |
| The second <<synchronization-dependencies-access-scopes, access scope>> is |
| limited to accesses in the pipeline stages determined by the |
| <<synchronization-pipeline-stages-masks, destination stage mask>> specified |
| by pname:dstStageMask. |
| It is also limited to access types in the <<synchronization-access-masks, |
| destination access mask>> specified by pname:dstAccessMask. |
| |
| The <<synchronization-dependencies-available-and-visible, availability and |
| visibility operations>> defined by a subpass dependency affect the execution |
| of <<renderpass-layout-transitions, image layout transitions>> 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 |
| **** |
| * [[VUID-VkSubpassDependency-srcStageMask-00860]] |
| If the <<features-geometryShader,geometry shaders>> feature is not |
| enabled, pname:srcStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT |
| * [[VUID-VkSubpassDependency-dstStageMask-00861]] |
| If the <<features-geometryShader,geometry shaders>> feature is not |
| enabled, pname:dstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT |
| * [[VUID-VkSubpassDependency-srcStageMask-00862]] |
| If the <<features-tessellationShader,tessellation shaders>> feature is |
| not enabled, pname:srcStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or |
| ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT |
| * [[VUID-VkSubpassDependency-dstStageMask-00863]] |
| If the <<features-tessellationShader,tessellation shaders>> feature is |
| not enabled, pname:dstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or |
| ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT |
| * [[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 |
| <<synchronization-framebuffer-regions,framebuffer-space stages>>, the |
| <<synchronization-pipeline-stages-order, logically latest>> pipeline |
| stage in pname:srcStageMask must: be |
| <<synchronization-pipeline-stages-order, logically earlier>> than or |
| equal to the <<synchronization-pipeline-stages-order, logically |
| earliest>> 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 |
| <<synchronization-access-types-supported, table of supported access |
| types>> |
| * [[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 |
| <<synchronization-access-types-supported, table of supported access |
| types>> |
| * [[VUID-VkSubpassDependency-srcSubpass-02243]] |
| If pname:srcSubpass equals pname:dstSubpass, and pname:srcStageMask and |
| pname:dstStageMask both include a |
| <<synchronization-framebuffer-regions,framebuffer-space stage>>, 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[] |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkSubpassDependency-srcStageMask-02099]] |
| If the <<features-meshShader,mesh shaders>> feature is not enabled, |
| pname:srcStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV |
| * [[VUID-VkSubpassDependency-srcStageMask-02100]] |
| If the <<features-taskShader,task shaders>> feature is not enabled, |
| pname:srcStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV |
| * [[VUID-VkSubpassDependency-dstStageMask-02101]] |
| If the <<features-meshShader,mesh shaders>> feature is not enabled, |
| pname:dstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV |
| * [[VUID-VkSubpassDependency-dstStageMask-02102]] |
| If the <<features-taskShader,task shaders>> feature is not enabled, |
| pname:dstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_KHR_synchronization2[] |
| * [[VUID-VkSubpassDependency-synchronization2-04984]] |
| If the <<features-synchronization2, pname:synchronization2>> feature is |
| not enabled, pname:srcStageMask must: not be `0` |
| * [[VUID-VkSubpassDependency-synchronization2-04985]] |
| If the <<features-synchronization2, pname:synchronization2>> feature is |
| not enabled, pname:dstStageMask must: not be `0` |
| endif::VK_KHR_synchronization2[] |
| ifndef::VK_KHR_synchronization2[] |
| * [[VUID-VkSubpassDependency-srcStageMask-04986]] |
| pname:srcStageMask must: not be `0` |
| * [[VUID-VkSubpassDependency-dstStageMask-04987]] |
| pname:dstStageMask must: not be `0` |
| endif::VK_KHR_synchronization2[] |
| **** |
| |
| 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 |
| <<renderpass-layout-transitions, automatic layout transitions>> 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 that contains a feedback loop creates a |
| <<memory-model-access-data-race, data race>>, 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. |
| <<synchronization-pipeline-barriers, Pipeline barriers>> expressing a |
| <<synchronization-pipeline-barriers-subpass-self-dependencies, subpass |
| self-dependency>> 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. |
| |
| [[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 |
| <<memory-allocation, Memory Allocation>> 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, it must: be less |
| than pname:attachmentCount |
| * [[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 <<synchronization-pipeline-stages-types, pipeline>> |
| 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 <<synchronization-pipeline-stages-types, pipeline>> |
| 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 |
| <<potential-format-features, potential format features>> 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:pDepthStencilResolveAttachmentKHR 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 <<features-separateDepthStencilLayouts, |
| pname:separateDepthStencilLayouts>> 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 <<features-separateDepthStencilLayouts, |
| pname:separateDepthStencilLayouts>> 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 <<features-separateDepthStencilLayouts, |
| pname:separateDepthStencilLayouts>> 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 |
| <<potential-format-features, potential format features>> 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 |
| <<potential-format-features, potential format features>> 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 |
| <<potential-format-features, potential format features>> 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 |
| <<potential-format-features, potential format features>> 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 <<attachment-type-imagelayout, image layout |
| requirements>> 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. |
| |
| .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 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 <<potential-format-features, potential format features>> contain |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03181]] |
| If the 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 the 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]] |
| 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]] |
| 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 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 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 |
| * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-04588]] |
| If the elink:VkFormat of pname:pDepthStencilResolveAttachment has a |
| depth component, pname:depthResolveMode must: be a valid |
| elink:VkResolveModeFlagBits value |
| * [[VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-04589]] |
| If the elink:VkFormat of pname:pDepthStencilResolveAttachment has a |
| stencil component, pname:stencilResolveMode must: be a valid |
| elink:VkResolveModeFlagBits value |
| **** |
| |
| 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 <<limits-maxFragmentShadingRateAttachmentTexelSize, |
| pname:maxFragmentShadingRateAttachmentTexelSize.width>> |
| * [[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 <<limits-minFragmentShadingRateAttachmentTexelSize, |
| pname:minFragmentShadingRateAttachmentTexelSize.width>> |
| * [[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 <<limits-maxFragmentShadingRateAttachmentTexelSize, |
| pname:maxFragmentShadingRateAttachmentTexelSize.height>> |
| * [[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 <<limits-minFragmentShadingRateAttachmentTexelSize, |
| pname:minFragmentShadingRateAttachmentTexelSize.height>> |
| * [[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 <<limits-maxFragmentShadingRateAttachmentTexelSizeAspectRatio, |
| pname:maxFragmentShadingRateAttachmentTexelSizeAspectRatio>> |
| * [[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 <<limits-maxFragmentShadingRateAttachmentTexelSizeAspectRatio, |
| pname:maxFragmentShadingRateAttachmentTexelSizeAspectRatio>> |
| **** |
| |
| 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 <<features-separateDepthStencilLayouts, |
| pname:separateDepthStencilLayouts>> 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 <<features-separateDepthStencilLayouts, |
| pname:separateDepthStencilLayouts>> 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'] |
| -- |
| 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 <<synchronization-pipeline-stages-masks, source stage |
| mask>>. |
| * pname:dstStageMask is a bitmask of elink:VkPipelineStageFlagBits |
| specifying the <<synchronization-pipeline-stages-masks, destination |
| stage mask>> |
| * pname:srcAccessMask is a bitmask of elink:VkAccessFlagBits specifying a |
| <<synchronization-access-masks, source access mask>>. |
| * pname:dstAccessMask is a bitmask of elink:VkAccessFlagBits specifying a |
| <<synchronization-access-masks, destination access mask>>. |
| * 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 |
| **** |
| * [[VUID-VkSubpassDependency2-srcStageMask-03080]] |
| If the <<features-geometryShader,geometry shaders>> feature is not |
| enabled, pname:srcStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT |
| * [[VUID-VkSubpassDependency2-dstStageMask-03081]] |
| If the <<features-geometryShader,geometry shaders>> feature is not |
| enabled, pname:dstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT |
| * [[VUID-VkSubpassDependency2-srcStageMask-03082]] |
| If the <<features-tessellationShader,tessellation shaders>> feature is |
| not enabled, pname:srcStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or |
| ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT |
| * [[VUID-VkSubpassDependency2-dstStageMask-03083]] |
| If the <<features-tessellationShader,tessellation shaders>> feature is |
| not enabled, pname:dstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or |
| ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT |
| * [[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 |
| <<synchronization-framebuffer-regions,framebuffer-space stages>>, the |
| <<synchronization-pipeline-stages-order, logically latest>> pipeline |
| stage in pname:srcStageMask must: be |
| <<synchronization-pipeline-stages-order, logically earlier>> than or |
| equal to the <<synchronization-pipeline-stages-order, logically |
| earliest>> 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 |
| <<synchronization-access-types-supported, table of supported access |
| types>> |
| * [[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 |
| <<synchronization-access-types-supported, table of supported access |
| types>> |
| * [[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 |
| <<synchronization-framebuffer-regions,framebuffer-space stage>>, 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` |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkSubpassDependency2-srcStageMask-02103]] |
| If the <<features-meshShader,mesh shaders>> feature is not enabled, |
| pname:srcStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV |
| * [[VUID-VkSubpassDependency2-srcStageMask-02104]] |
| If the <<features-taskShader,task shaders>> feature is not enabled, |
| pname:srcStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV |
| * [[VUID-VkSubpassDependency2-dstStageMask-02105]] |
| If the <<features-meshShader,mesh shaders>> feature is not enabled, |
| pname:dstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV |
| * [[VUID-VkSubpassDependency2-dstStageMask-02106]] |
| If the <<features-taskShader,task shaders>> feature is not enabled, |
| pname:dstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_KHR_synchronization2[] |
| * [[VUID-VkSubpassDependency2-synchronization2-04988]] |
| If the <<features-synchronization2, pname:synchronization2>> feature is |
| not enabled, pname:srcStageMask must: not be `0` |
| * [[VUID-VkSubpassDependency2-synchronization2-04989]] |
| If the <<features-synchronization2, pname:synchronization2>> feature is |
| not enabled, pname:dstStageMask must: not be `0` |
| endif::VK_KHR_synchronization2[] |
| ifndef::VK_KHR_synchronization2[] |
| * [[VUID-VkSubpassDependency2-srcStageMask-04990]] |
| pname:srcStageMask must: not be `0` |
| * [[VUID-VkSubpassDependency2-dstStageMask-04991]] |
| pname:dstStageMask must: not be `0` |
| endif::VK_KHR_synchronization2[] |
| **** |
| |
| 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 |
| <<memory-allocation, Memory Allocation>> 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 |
| <<memory-allocation, Memory Allocation>> 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 <<renderpass-compatibility,Render Pass Compatibility>> 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 |
| <<renderpass-load-store-ops, load operations>> for those attachments, or |
| happen-after the <<renderpass-load-store-ops, store operations>> 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 |
| <<features-fragmentDensityMapNonSubsampledImages,non-subsample image |
| feature>> 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 |
| <<primsrast-fragment-shading-rate-attachment,fragment shading rate |
| attachment>> 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 |
| <<primsrast-fragment-shading-rate-attachment,fragment shading rate |
| attachment>> 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 |
| <<primsrast-fragment-shading-rate-attachment, fragment shading rate |
| attachment>> 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 |
| <<primsrast-fragment-shading-rate-attachment, fragment shading rate |
| attachment>> 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 |
| <<limits-maxFramebufferWidth,pname:maxFramebufferWidth>> |
| * [[VUID-VkFramebufferCreateInfo-height-00887]] |
| pname:height must: be greater than `0` |
| * [[VUID-VkFramebufferCreateInfo-height-00888]] |
| pname:height must: be less than or equal to |
| <<limits-maxFramebufferHeight,pname:maxFramebufferHeight>> |
| * [[VUID-VkFramebufferCreateInfo-layers-00889]] |
| pname:layers must: be greater than `0` |
| * [[VUID-VkFramebufferCreateInfo-layers-00890]] |
| pname:layers must: be less than or equal to |
| <<limits-maxFramebufferLayers,pname:maxFramebufferLayers>> |
| 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 <<features-imagelessFramebuffer, imageless framebuffer>> 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 <<primsrast-fragment-shading-rate-attachment, |
| fragment shading rate attachment>> 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 <<primsrast-fragment-shading-rate-attachment, |
| fragment shading rate attachment>> 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 <<primsrast-fragment-shading-rate-attachment, |
| fragment shading rate attachment>> 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 <<primsrast-fragment-shading-rate-attachment,fragment |
| shading rate attachment>> 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 of which |
| describes 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 |
| <<memory-allocation, Memory Allocation>> 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-00901]] |
| The pname:srcStageMask and 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-03101]] |
| The pname:srcStageMask and 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 that contains 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 <<vertexpostproc-renderpass-transform, render pass transform>> 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 <<features-subpassShading, subpass shading>> 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 that specifies 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 <<renderpass-compatibility,compatible>> 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-02854]] |
| If the pname:pNext chain contains |
| slink:VkDeviceGroupRenderPassBeginInfo, the pname:offset.x member of |
| each element of pname:pDeviceRenderAreas must: be greater than or equal |
| to 0 |
| * [[VUID-VkRenderPassBeginInfo-pNext-02855]] |
| If the pname:pNext chain contains |
| slink:VkDeviceGroupRenderPassBeginInfo, the pname:offset.y member of |
| each element of pname:pDeviceRenderAreas must: be greater than or equal |
| to 0 |
| * [[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 <<resources-image-inherited-usage, an inherited usage>> 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 <<vertexpostproc-renderpass-transform, |
| render pass transform>> 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 |
| <<limits-maxFramebufferWidth, pname:maxFramebufferWidth>> |
| * [[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 |
| <<limits-maxFramebufferHeight, pname:maxFramebufferHeight>> |
| **** |
| |
| 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 <<renderpass-layout-transitions,automatic layout |
| transitions>>. |
| 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[] |