Vulkan Logo

8. Render Pass

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.

To begin a render pass instance, call:

// Provided by VK_VERSION_1_3
void vkCmdBeginRendering(
    VkCommandBuffer                             commandBuffer,
    const VkRenderingInfo*                      pRenderingInfo);

or the equivalent command

// Provided by VK_KHR_dynamic_rendering
void vkCmdBeginRenderingKHR(
    VkCommandBuffer                             commandBuffer,
    const VkRenderingInfo*                      pRenderingInfo);
  • commandBuffer is the command buffer in which to record the command.

  • pRenderingInfo is a pointer to a VkRenderingInfo structure specifying details of the render pass instance to begin.

After beginning a render pass instance, the command buffer is ready to record draw commands.

If pRenderingInfo->flags includes VK_RENDERING_RESUMING_BIT then this render pass is resumed from a render pass instance that has been suspended earlier in submission order.

Valid Usage
  • VUID-vkCmdBeginRendering-dynamicRendering-06446
    The dynamicRendering feature must be enabled

  • VUID-vkCmdBeginRendering-commandBuffer-06068
    If commandBuffer is a secondary command buffer, pRenderingInfo->flags must not include VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT

Valid Usage (Implicit)
  • VUID-vkCmdBeginRendering-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBeginRendering-pRenderingInfo-parameter
    pRenderingInfo must be a valid pointer to a valid VkRenderingInfo structure

  • VUID-vkCmdBeginRendering-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBeginRendering-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBeginRendering-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBeginRendering-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Graphics

Action
State

The VkRenderingInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkRenderingInfo {
    VkStructureType                     sType;
    const void*                         pNext;
    VkRenderingFlags                    flags;
    VkRect2D                            renderArea;
    uint32_t                            layerCount;
    uint32_t                            viewMask;
    uint32_t                            colorAttachmentCount;
    const VkRenderingAttachmentInfo*    pColorAttachments;
    const VkRenderingAttachmentInfo*    pDepthAttachment;
    const VkRenderingAttachmentInfo*    pStencilAttachment;
} VkRenderingInfo;

or the equivalent

// Provided by VK_KHR_dynamic_rendering, VK_KHR_dynamic_rendering with VK_QCOM_tile_properties
typedef VkRenderingInfo VkRenderingInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkRenderingFlagBits.

  • renderArea is the render area that is affected by the render pass instance.

  • layerCount is the number of layers rendered to in each attachment when viewMask is 0.

  • viewMask is the view mask indicating the indices of attachment layers that will be rendered when it is not 0.

  • colorAttachmentCount is the number of elements in pColorAttachments.

  • pColorAttachments is a pointer to an array of colorAttachmentCount VkRenderingAttachmentInfo structures describing any color attachments used.

  • pDepthAttachment is a pointer to a VkRenderingAttachmentInfo structure describing a depth attachment.

  • pStencilAttachment is a pointer to a VkRenderingAttachmentInfo structure describing a stencil attachment.

If viewMask is not 0, multiview is enabled.

If there is an instance of VkDeviceGroupRenderPassBeginInfo included in the pNext chain and its deviceRenderAreaCount member is not 0, then renderArea is ignored, and the render area is defined per-device by that structure.

If multiview is enabled, and the multiviewPerViewRenderAreas feature is enabled, and there is an instance of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM included in the pNext chain with perViewRenderAreaCount not equal to 0, then the elements of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas override renderArea and define a render area for each view. In this case, renderArea must be set to an area at least as large as the union of all the per-view render areas.

Each element of the pColorAttachments array corresponds to an output location in the shader, i.e. if the shader declares an output variable decorated with a Location value of X, then it uses the attachment provided in pColorAttachments[X]. If the imageView member of any element of pColorAttachments is VK_NULL_HANDLE, writes to the corresponding location by a fragment are discarded.

Valid Usage
  • VUID-VkRenderingInfo-viewMask-06069
    If viewMask is 0, layerCount must not be 0

  • VUID-VkRenderingInfo-multisampledRenderToSingleSampled-06857
    If none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are enabled, imageView members of pDepthAttachment, pStencilAttachment, and elements of pColorAttachments that are not VK_NULL_HANDLE must have been created with the same sampleCount

  • VUID-VkRenderingInfo-None-08994
    If VkDeviceGroupRenderPassBeginInfo::deviceRenderAreaCount is 0, renderArea.extent.width must be greater than 0

  • VUID-VkRenderingInfo-None-08995
    If VkDeviceGroupRenderPassBeginInfo::deviceRenderAreaCount is 0, renderArea.extent.height must be greater than 0

  • VUID-VkRenderingInfo-imageView-06858
    If multisampled-render-to-single-sampled is enabled, then all attachments referenced by imageView members of pDepthAttachment, pStencilAttachment, and elements of pColorAttachments that are not VK_NULL_HANDLE must have a sample count that is either VK_SAMPLE_COUNT_1_BIT or equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

  • VUID-VkRenderingInfo-imageView-06859
    If multisampled-render-to-single-sampled is enabled, then all attachments referenced by imageView members of pDepthAttachment, pStencilAttachment, and elements of pColorAttachments that are not VK_NULL_HANDLE and have a sample count of VK_SAMPLE_COUNT_1_BIT must have been created with VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT in their VkImageCreateInfo::flags

  • VUID-VkRenderingInfo-pNext-06077
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.x must be greater than or equal to 0

  • VUID-VkRenderingInfo-pNext-06078
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.y must be greater than or equal to 0

  • VUID-VkRenderingInfo-pNext-07815
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, the sum of renderArea.extent.width and renderArea.offset.x must be less than or equal to maxFramebufferWidth

  • VUID-VkRenderingInfo-pNext-07816
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, the sum of renderArea.extent.height and renderArea.offset.y must be less than or equal to maxFramebufferHeight

  • VUID-VkRenderingInfo-pNext-06079
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, the width of the imageView member of any element of pColorAttachments, pDepthAttachment, or pStencilAttachment that is not VK_NULL_HANDLE must be greater than or equal to renderArea.offset.x + renderArea.extent.width

  • VUID-VkRenderingInfo-pNext-06080
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, the height of the imageView member of any element of pColorAttachments, pDepthAttachment, or pStencilAttachment that is not VK_NULL_HANDLE must be greater than or equal to renderArea.offset.y + renderArea.extent.height

  • VUID-VkRenderingInfo-pNext-06083
    If the pNext chain contains VkDeviceGroupRenderPassBeginInfo, the width of the imageView member of any element of pColorAttachments, pDepthAttachment, or pStencilAttachment that is not VK_NULL_HANDLE must be greater than or equal to the sum of the offset.x and extent.width members of each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-pNext-06084
    If the pNext chain contains VkDeviceGroupRenderPassBeginInfo, the height of the imageView member of any element of pColorAttachments, pDepthAttachment, or pStencilAttachment that is not VK_NULL_HANDLE must be greater than or equal to the sum of the offset.y and extent.height members of each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-pDepthAttachment-06085
    If neither pDepthAttachment or pStencilAttachment are NULL and the imageView member of either structure is not VK_NULL_HANDLE, the imageView member of each structure must be the same

  • VUID-VkRenderingInfo-pDepthAttachment-06086
    If neither pDepthAttachment or pStencilAttachment are NULL, and the resolveMode member of each is not VK_RESOLVE_MODE_NONE, the resolveImageView member of each structure must be the same

  • VUID-VkRenderingInfo-colorAttachmentCount-06087
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, that imageView must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-pDepthAttachment-06547
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->imageView must have been created with a format that includes a depth component

  • VUID-VkRenderingInfo-pDepthAttachment-06088
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->imageView must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-pStencilAttachment-06548
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->imageView must have been created with a format that includes a stencil aspect

  • VUID-VkRenderingInfo-pStencilAttachment-06089
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->imageView must have been created with a stencil usage including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkRenderingInfo-colorAttachmentCount-06090
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, the layout member of that element of pColorAttachments must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06091
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, if the resolveMode member of that element of pColorAttachments is not VK_RESOLVE_MODE_NONE, its resolveImageLayout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-06092
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->layout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-06093
    If pDepthAttachment is not NULL, pDepthAttachment->imageView is not VK_NULL_HANDLE, and pDepthAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pDepthAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-06094
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->layout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-06095
    If pStencilAttachment is not NULL, pStencilAttachment->imageView is not VK_NULL_HANDLE, and pStencilAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pStencilAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06096
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, the layout member of that element of pColorAttachments must not be VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06097
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, if the resolveMode member of that element of pColorAttachments is not VK_RESOLVE_MODE_NONE, its resolveImageLayout member must not be VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-06098
    If pDepthAttachment is not NULL, pDepthAttachment->imageView is not VK_NULL_HANDLE, and pDepthAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pDepthAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-06099
    If pStencilAttachment is not NULL, pStencilAttachment->imageView is not VK_NULL_HANDLE, and pStencilAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pStencilAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06100
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, the layout member of that element of pColorAttachments must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-colorAttachmentCount-06101
    If colorAttachmentCount is not 0 and the imageView member of an element of pColorAttachments is not VK_NULL_HANDLE, if the resolveMode member of that element of pColorAttachments is not VK_RESOLVE_MODE_NONE, its resolveImageLayout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-07732
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->layout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-07733
    If pDepthAttachment is not NULL, pDepthAttachment->imageView is not VK_NULL_HANDLE, and pDepthAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pDepthAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-07734
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->layout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pStencilAttachment-07735
    If pStencilAttachment is not NULL, pStencilAttachment->imageView is not VK_NULL_HANDLE, and pStencilAttachment->resolveMode is not VK_RESOLVE_MODE_NONE, pStencilAttachment->resolveImageLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkRenderingInfo-pDepthAttachment-06102
    If pDepthAttachment is not NULL and pDepthAttachment->imageView is not VK_NULL_HANDLE, pDepthAttachment->resolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedDepthResolveModes

  • VUID-VkRenderingInfo-pStencilAttachment-06103
    If pStencilAttachment is not NULL and pStencilAttachment->imageView is not VK_NULL_HANDLE, pStencilAttachment->resolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedStencilResolveModes

  • VUID-VkRenderingInfo-pDepthAttachment-06104
    If pDepthAttachment or pStencilAttachment are both not NULL, pDepthAttachment->imageView and pStencilAttachment->imageView are both not VK_NULL_HANDLE, and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone is VK_FALSE, the resolveMode of both structures must be the same value

  • VUID-VkRenderingInfo-pDepthAttachment-06105
    If pDepthAttachment or pStencilAttachment are both not NULL, pDepthAttachment->imageView and pStencilAttachment->imageView are both not VK_NULL_HANDLE, VkPhysicalDeviceDepthStencilResolveProperties::independentResolve is VK_FALSE, and the resolveMode of neither structure is VK_RESOLVE_MODE_NONE, the resolveMode of both structures must be the same value

  • VUID-VkRenderingInfo-colorAttachmentCount-06106
    colorAttachmentCount must be less than or equal to VkPhysicalDeviceLimits::maxColorAttachments

  • VUID-VkRenderingInfo-imageView-06107
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, and the fragmentDensityMapNonSubsampledImages feature is not enabled, valid imageView and resolveImageView members of pDepthAttachment, pStencilAttachment, and each element of pColorAttachments must be a VkImageView created with VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkRenderingInfo-imageView-06108
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, and viewMask is not 0, imageView must have a layerCount greater than or equal to the index of the most significant bit in viewMask

  • VUID-VkRenderingInfo-imageView-06109
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, and viewMask is 0, imageView must have a layerCount equal to 1

  • VUID-VkRenderingInfo-pNext-06112
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0 and the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a width greater than or equal to

  • VUID-VkRenderingInfo-pNext-06113
    If the pNext chain contains a VkDeviceGroupRenderPassBeginInfo structure, its deviceRenderAreaCount member is not 0, and the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a width greater than or equal to for each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-pNext-06114
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0 and the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a height greater than or equal to

  • VUID-VkRenderingInfo-pNext-06115
    If the pNext chain contains a VkDeviceGroupRenderPassBeginInfo structure, its deviceRenderAreaCount member is not 0, and the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a height greater than or equal to for each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-imageView-06116
    If the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain is not VK_NULL_HANDLE, it must not be equal to the imageView or resolveImageView member of pDepthAttachment, pStencilAttachment, or any element of pColorAttachments

  • VUID-VkRenderingInfo-pNext-06119
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0 and the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a width greater than or equal to

  • VUID-VkRenderingInfo-pNext-06120
    If the pNext chain contains a VkDeviceGroupRenderPassBeginInfo structure, its deviceRenderAreaCount member is not 0, and the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a width greater than or equal to for each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-pNext-06121
    If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0 and the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a height greater than or equal to

  • VUID-VkRenderingInfo-pNext-06122
    If the pNext chain contains a VkDeviceGroupRenderPassBeginInfo structure, its deviceRenderAreaCount member is not 0, and the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, imageView must have a height greater than or equal to for each element of pDeviceRenderAreas

  • VUID-VkRenderingInfo-layerCount-07817
    layerCount must be less than or equal to maxFramebufferLayers

  • VUID-VkRenderingInfo-imageView-06123
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, and viewMask is 0, imageView must have a layerCount that is either equal to 1 or greater than or equal to layerCount

  • VUID-VkRenderingInfo-imageView-06124
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, and viewMask is not 0, imageView must have a layerCount that either equal to 1 or greater than or equal to the index of the most significant bit in viewMask

  • VUID-VkRenderingInfo-imageView-06125
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, it must not be equal to the imageView or resolveImageView member of pDepthAttachment, pStencilAttachment, or any element of pColorAttachments

  • VUID-VkRenderingInfo-imageView-06126
    If the imageView member of a VkRenderingFragmentShadingRateAttachmentInfoKHR structure included in the pNext chain is not VK_NULL_HANDLE, it must not be equal to the imageView member of a VkRenderingFragmentDensityMapAttachmentInfoEXT structure included in the pNext chain

  • VUID-VkRenderingInfo-multiview-06127
    If the multiview feature is not enabled, viewMask must be 0

  • VUID-VkRenderingInfo-viewMask-06128
    The index of the most significant bit in viewMask must be less than maxMultiviewViewCount

  • VUID-VkRenderingInfo-perViewRenderAreaCount-07857
    If the perViewRenderAreaCount member of a VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure included in the pNext chain is not 0, then the multiviewPerViewRenderAreas feature must be enabled.

  • VUID-VkRenderingInfo-perViewRenderAreaCount-07858
    If the perViewRenderAreaCount member of a VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure included in the pNext chain is not 0, then renderArea must specify a render area that includes the union of all per view render areas.

  • VUID-VkRenderingInfo-None-09044
    Valid attachments specified by this structure must not be bound to memory locations that are bound to any other valid attachments specified by this structure

Valid Usage (Implicit)

Bits which can be set in VkRenderingInfo::flags describing additional properties of the render pass are:

// Provided by VK_VERSION_1_3
typedef enum VkRenderingFlagBits {
    VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT = 0x00000001,
    VK_RENDERING_SUSPENDING_BIT = 0x00000002,
    VK_RENDERING_RESUMING_BIT = 0x00000004,
  // Provided by VK_VERSION_1_3 with VK_EXT_legacy_dithering, VK_KHR_dynamic_rendering with VK_EXT_legacy_dithering
    VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000008,
    VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR = VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT,
    VK_RENDERING_SUSPENDING_BIT_KHR = VK_RENDERING_SUSPENDING_BIT,
    VK_RENDERING_RESUMING_BIT_KHR = VK_RENDERING_RESUMING_BIT,
} VkRenderingFlagBits;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingFlagBits VkRenderingFlagBitsKHR;
  • VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT specifies that draw calls for the render pass instance will be recorded in secondary command buffers.

  • VK_RENDERING_RESUMING_BIT specifies that the render pass instance is resuming an earlier suspended render pass instance.

  • VK_RENDERING_SUSPENDING_BIT specifies that the render pass instance will be suspended.

  • VK_RENDERING_ENABLE_LEGACY_DITHERING_BIT_EXT specifies that Legacy Dithering is enabled for the render pass instance.

The contents of pRenderingInfo must match between suspended render pass instances and the render pass instances that resume them, other than the presence or absence of the VK_RENDERING_RESUMING_BIT, VK_RENDERING_SUSPENDING_BIT, and VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT flags. No action or synchronization commands, or other render pass instances, are allowed between suspending and resuming render pass instances.

// Provided by VK_VERSION_1_3
typedef VkFlags VkRenderingFlags;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingFlags VkRenderingFlagsKHR;

VkRenderingFlags is a bitmask type for setting a mask of zero or more VkRenderingFlagBits.

The VkRenderingAttachmentInfo structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkRenderingAttachmentInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkImageView              imageView;
    VkImageLayout            imageLayout;
    VkResolveModeFlagBits    resolveMode;
    VkImageView              resolveImageView;
    VkImageLayout            resolveImageLayout;
    VkAttachmentLoadOp       loadOp;
    VkAttachmentStoreOp      storeOp;
    VkClearValue             clearValue;
} VkRenderingAttachmentInfo;

or the equivalent

// Provided by VK_KHR_dynamic_rendering
typedef VkRenderingAttachmentInfo VkRenderingAttachmentInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • imageView is the image view that will be used for rendering.

  • imageLayout is the layout that imageView will be in during rendering.

  • resolveMode is a VkResolveModeFlagBits value defining how multisampled data written to imageView will be resolved.

  • resolveImageView is an image view used to write resolved multisample data at the end of rendering.

  • resolveImageLayout is the layout that resolveImageView will be in during rendering.

  • loadOp is a VkAttachmentLoadOp value defining the load operation for the attachment.

  • storeOp is a VkAttachmentStoreOp value defining the store operation for the attachment.

  • clearValue is a VkClearValue structure defining values used to clear imageView when loadOp is VK_ATTACHMENT_LOAD_OP_CLEAR.

Values in imageView are loaded and stored according to the values of loadOp and storeOp, within the render area for each device specified in VkRenderingInfo. If imageView is VK_NULL_HANDLE, other members of this structure are ignored; writes to this attachment will be discarded, and no load, store, or multisample resolve operations will be performed.

If resolveMode is VK_RESOLVE_MODE_NONE, then resolveImageView is ignored. If resolveMode is not VK_RESOLVE_MODE_NONE, and resolveImageView is not VK_NULL_HANDLE, a render pass multisample resolve operation is defined for the attachment subresource.

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 VK_RENDERING_SUSPENDING_BIT_KHR flag.

Load operations are only performed at the beginning of a render pass instance that does not specify the 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-VkRenderingAttachmentInfo-imageView-06129
    If imageView is not VK_NULL_HANDLE and has a non-integer color format, resolveMode must be VK_RESOLVE_MODE_NONE or VK_RESOLVE_MODE_AVERAGE_BIT

  • VUID-VkRenderingAttachmentInfo-imageView-06130
    If imageView is not VK_NULL_HANDLE and has an integer color format, resolveMode must be VK_RESOLVE_MODE_NONE or VK_RESOLVE_MODE_SAMPLE_ZERO_BIT

  • VUID-VkRenderingAttachmentInfo-imageView-06861
    If imageView is not VK_NULL_HANDLE, resolveMode is not VK_RESOLVE_MODE_NONE, and the pNext chain of VkRenderingInfo does not includes a VkMultisampledRenderToSingleSampledInfoEXT structure with the multisampledRenderToSingleSampledEnable field equal to VK_TRUE, imageView must not have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkRenderingAttachmentInfo-imageView-06862
    If imageView is not VK_NULL_HANDLE, resolveMode is not VK_RESOLVE_MODE_NONE, and the pNext chain of VkRenderingInfo does not includes a VkMultisampledRenderToSingleSampledInfoEXT structure with the multisampledRenderToSingleSampledEnable field equal to VK_TRUE, resolveImageView must not be VK_NULL_HANDLE

  • VUID-VkRenderingAttachmentInfo-imageView-06863
    If imageView is not VK_NULL_HANDLE, resolveMode is not VK_RESOLVE_MODE_NONE, the pNext chain of VkRenderingInfo includes a VkMultisampledRenderToSingleSampledInfoEXT structure with the multisampledRenderToSingleSampledEnable field equal to VK_TRUE, and imageView has a sample count of VK_SAMPLE_COUNT_1_BIT, resolveImageView must be VK_NULL_HANDLE

  • VUID-VkRenderingAttachmentInfo-imageView-06864
    If imageView is not VK_NULL_HANDLE, resolveImageView is not VK_NULL_HANDLE, and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageView must have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkRenderingAttachmentInfo-imageView-06865
    If imageView is not VK_NULL_HANDLE, resolveImageView is not VK_NULL_HANDLE, and resolveMode is not VK_RESOLVE_MODE_NONE, imageView and resolveImageView must have the same VkFormat

  • VUID-VkRenderingAttachmentInfo-imageView-06135
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkRenderingAttachmentInfo-imageView-06136
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkRenderingAttachmentInfo-imageView-06137
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderingAttachmentInfo-imageView-06138
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV

  • VUID-VkRenderingAttachmentInfo-imageView-06139
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV

  • VUID-VkRenderingAttachmentInfo-imageView-06140
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT

  • VUID-VkRenderingAttachmentInfo-imageView-06141
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT

  • VUID-VkRenderingAttachmentInfo-imageView-06142
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkRenderingAttachmentInfo-imageView-06143
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkRenderingAttachmentInfo-imageView-06144
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkRenderingAttachmentInfo-imageView-06145
    If imageView is not VK_NULL_HANDLE, imageLayout must not be VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • VUID-VkRenderingAttachmentInfo-imageView-06146
    If imageView is not VK_NULL_HANDLE and resolveMode is not VK_RESOLVE_MODE_NONE, resolveImageLayout must not be VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

Valid Usage (Implicit)
  • VUID-VkRenderingAttachmentInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO

  • VUID-VkRenderingAttachmentInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkRenderingAttachmentInfo-imageView-parameter
    If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle

  • VUID-VkRenderingAttachmentInfo-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

  • VUID-VkRenderingAttachmentInfo-resolveMode-parameter
    If resolveMode is not 0, resolveMode must be a valid VkResolveModeFlagBits value

  • VUID-VkRenderingAttachmentInfo-resolveImageView-parameter
    If resolveImageView is not VK_NULL_HANDLE, resolveImageView must be a valid VkImageView handle

  • VUID-VkRenderingAttachmentInfo-resolveImageLayout-parameter
    resolveImageLayout must be a valid VkImageLayout value

  • VUID-VkRenderingAttachmentInfo-loadOp-parameter
    loadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkRenderingAttachmentInfo-storeOp-parameter
    storeOp must be a valid VkAttachmentStoreOp value

  • VUID-VkRenderingAttachmentInfo-clearValue-parameter
    clearValue must be a valid VkClearValue union

  • VUID-VkRenderingAttachmentInfo-commonparent
    Both of imageView, and resolveImageView that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkRenderingFragmentShadingRateAttachmentInfoKHR structure is defined as:

// Provided by VK_KHR_dynamic_rendering with VK_KHR_fragment_shading_rate
typedef struct VkRenderingFragmentShadingRateAttachmentInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkImageView        imageView;
    VkImageLayout      imageLayout;
    VkExtent2D         shadingRateAttachmentTexelSize;
} VkRenderingFragmentShadingRateAttachmentInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • imageView is the image view that will be used as a fragment shading rate attachment.

  • imageLayout is the layout that imageView will be in during rendering.

  • shadingRateAttachmentTexelSize specifies the number of pixels corresponding to each texel in imageView.

This structure can be included in the pNext chain of VkRenderingInfo to define a fragment shading rate attachment. If imageView is 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 imageView is not VK_NULL_HANDLE, layout must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06148
    If imageView is not VK_NULL_HANDLE, it must have been created with VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06149
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.width must be a power of two value

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06150
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.width

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06151
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.width must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.width

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06152
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.height must be a power of two value

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06153
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.height

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06154
    If imageView is not VK_NULL_HANDLE, shadingRateAttachmentTexelSize.height must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.height

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06155
    If imageView is not VK_NULL_HANDLE, the quotient of shadingRateAttachmentTexelSize.width and shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-06156
    If imageView is not VK_NULL_HANDLE, the quotient of shadingRateAttachmentTexelSize.height and shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

Valid Usage (Implicit)
  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageView-parameter
    If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle

  • VUID-VkRenderingFragmentShadingRateAttachmentInfoKHR-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

The VkRenderingFragmentDensityMapAttachmentInfoEXT structure is defined as:

// Provided by VK_KHR_dynamic_rendering with VK_EXT_fragment_density_map
typedef struct VkRenderingFragmentDensityMapAttachmentInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkImageView        imageView;
    VkImageLayout      imageLayout;
} VkRenderingFragmentDensityMapAttachmentInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • imageView is the image view that will be used as a fragment density map attachment.

  • imageLayout is the layout that imageView will be in during rendering.

This structure can be included in the pNext chain of VkRenderingInfo to define a fragment density map. If this structure is not included in the pNext chain, imageView is treated as VK_NULL_HANDLE.

Valid Usage
  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06157
    If imageView is not VK_NULL_HANDLE, layout must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06158
    If imageView is not VK_NULL_HANDLE, it must have been created with VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-06159
    If imageView is not VK_NULL_HANDLE, it must not have been created with VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-apiVersion-07908
    If VK_KHR_multiview is not enabled, VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, and imageView is not VK_NULL_HANDLE, it must have a layerCount equal to 1

Valid Usage (Implicit)
  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_INFO_EXT

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageView-parameter
    imageView must be a valid VkImageView handle

  • VUID-VkRenderingFragmentDensityMapAttachmentInfoEXT-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

To end a render pass instance, call:

// Provided by VK_VERSION_1_3
void vkCmdEndRendering(
    VkCommandBuffer                             commandBuffer);

or the equivalent command

// Provided by VK_KHR_dynamic_rendering
void vkCmdEndRenderingKHR(
    VkCommandBuffer                             commandBuffer);
  • commandBuffer is the command buffer in which to record the command.

If the value of pRenderingInfo->flags used to begin this render pass instance included VK_RENDERING_SUSPENDING_BIT, then this render pass is suspended and will be resumed later in submission order.

Valid Usage
  • VUID-vkCmdEndRendering-None-06161
    The current render pass instance must have been begun with vkCmdBeginRendering

  • VUID-vkCmdEndRendering-commandBuffer-06162
    The current render pass instance must have been begun in commandBuffer

  • VUID-vkCmdEndRendering-None-06781
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdEndRendering-None-06999
    If vkCmdBeginQuery* was called within the render pass, the corresponding vkCmdEndQuery* must have been called subsequently within the same subpass

Valid Usage (Implicit)
  • VUID-vkCmdEndRendering-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdEndRendering-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdEndRendering-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdEndRendering-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdEndRendering-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Inside

Outside

Graphics

Action
State

Note

For more complex rendering graphs, it is possible to pre-define a static render pass object, which as well as allowing draw commands, allows the definition of framebuffer-local dependencies between multiple subpasses. These objects have a lot of setup cost compared to vkCmdBeginRendering, but use of subpass dependencies can confer important performance benefits on some devices.

The VkTilePropertiesQCOM structure is defined as:

// Provided by VK_QCOM_tile_properties
typedef struct VkTilePropertiesQCOM {
    VkStructureType    sType;
    void*              pNext;
    VkExtent3D         tileSize;
    VkExtent2D         apronSize;
    VkOffset2D         origin;
} VkTilePropertiesQCOM;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • tileSize is the dimensions of a tile, with width and height describing the width and height of a tile in pixels, and depth corresponding to the number of slices the tile spans.

  • apronSize is the dimension of the apron.

  • origin is the top-left corner of the first tile in attachment space.

All tiles will be tightly packed around the first tile, with edges being multiples of tile width and/or height from the origin.

Note

Reported value for apronSize will be zero and its functionality will be described in a future extension.

Valid Usage (Implicit)
  • VUID-VkTilePropertiesQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_TILE_PROPERTIES_QCOM

  • VUID-VkTilePropertiesQCOM-pNext-pNext
    pNext must be NULL

To query the tile properties when using dynamic rendering, call:

// Provided by VK_QCOM_tile_properties
VkResult vkGetDynamicRenderingTilePropertiesQCOM(
    VkDevice                                    device,
    const VkRenderingInfo*                      pRenderingInfo,
    VkTilePropertiesQCOM*                       pProperties);
  • device is a logical device associated with the render pass.

  • pRenderingInfo is a pointer to the VkRenderingInfo structure specifying details of the render pass instance in dynamic rendering.

  • pProperties is a pointer to a VkTilePropertiesQCOM structure in which the properties are returned.

Valid Usage (Implicit)
  • VUID-vkGetDynamicRenderingTilePropertiesQCOM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDynamicRenderingTilePropertiesQCOM-pRenderingInfo-parameter
    pRenderingInfo must be a valid pointer to a valid VkRenderingInfo structure

  • VUID-vkGetDynamicRenderingTilePropertiesQCOM-pProperties-parameter
    pProperties must be a valid pointer to a VkTilePropertiesQCOM structure

Return Codes
Success
  • VK_SUCCESS

8.1. Render Pass Objects

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 VkRenderPass handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkRenderPass)

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.

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, perform shader resolve operations to color_attachments or depth/stencil_attachments, 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, depth/stencil resolve, fragment shading rate, or input attachment for that subpass (as determined by the pColorAttachments, pDepthStencilAttachment, pResolveAttachments, VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment, VkFragmentShadingRateAttachmentInfoKHR::pFragmentShadingRateAttachment->attachment, and pInputAttachments members of 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. 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 VkDevice.

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 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 submission order for commands recorded in the same subpass, and the vkCmdBeginRenderPass and vkCmdEndRenderPass commands that delimit the render pass - commands within other subpasses are not included. This affects most other 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 VkFramebuffer objects. Framebuffers are created with respect to a specific render pass that the framebuffer is compatible with (see 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 pipeline order. However for a given (x,y,layer,sample) sample location, certain per-sample operations are performed in rasterization order.

VK_ATTACHMENT_UNUSED is a constant indicating that a render pass attachment is not used.

#define VK_ATTACHMENT_UNUSED              (~0U)

8.2. Render Pass Creation

To create a render pass, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateRenderPass(
    VkDevice                                    device,
    const VkRenderPassCreateInfo*               pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkRenderPass*                               pRenderPass);
  • device is the logical device that creates the render pass.

  • pCreateInfo is a pointer to a VkRenderPassCreateInfo structure describing the parameters of the render pass.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pRenderPass is a pointer to a VkRenderPass handle in which the resulting render pass object is returned.

Valid Usage (Implicit)
  • VUID-vkCreateRenderPass-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateRenderPass-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkRenderPassCreateInfo structure

  • VUID-vkCreateRenderPass-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateRenderPass-pRenderPass-parameter
    pRenderPass must be a valid pointer to a VkRenderPass handle

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkRenderPassCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkRenderPassCreateInfo {
    VkStructureType                   sType;
    const void*                       pNext;
    VkRenderPassCreateFlags           flags;
    uint32_t                          attachmentCount;
    const VkAttachmentDescription*    pAttachments;
    uint32_t                          subpassCount;
    const VkSubpassDescription*       pSubpasses;
    uint32_t                          dependencyCount;
    const VkSubpassDependency*        pDependencies;
} VkRenderPassCreateInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkRenderPassCreateFlagBits

  • attachmentCount is the number of attachments used by this render pass.

  • pAttachments is a pointer to an array of attachmentCount VkAttachmentDescription structures describing the attachments used by the render pass.

  • subpassCount is the number of subpasses to create.

  • pSubpasses is a pointer to an array of subpassCount VkSubpassDescription structures describing each subpass.

  • dependencyCount is the number of memory dependencies between pairs of subpasses.

  • pDependencies is a pointer to an array of dependencyCount VkSubpassDependency structures describing dependencies between pairs of subpasses.

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 attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not VK_ATTACHMENT_UNUSED, then it must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo-fragmentDensityMapAttachment-06471
    If the pNext chain includes a VkRenderPassFragmentDensityMapCreateInfoEXT structure and the fragmentDensityMapAttachment member is not VK_ATTACHMENT_UNUSED, then attachment must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo-pAttachments-00836
    For any member of pAttachments with a loadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderPassCreateInfo-pAttachments-02511
    For any member of pAttachments with a stencilLoadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderPassCreateInfo-pAttachments-01566
    For any member of pAttachments with a loadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkRenderPassCreateInfo-pAttachments-01567
    For any member of pAttachments with a stencilLoadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderPassCreateInfo-pNext-01926
    If the pNext chain includes a VkRenderPassInputAttachmentAspectCreateInfo structure, the subpass member of each element of its pAspectReferences member must be less than subpassCount

  • VUID-VkRenderPassCreateInfo-pNext-01927
    If the pNext chain includes a VkRenderPassInputAttachmentAspectCreateInfo structure, the inputAttachmentIndex member of each element of its pAspectReferences member must be less than the value of inputAttachmentCount in the element of pSubpasses identified by its subpass member

  • VUID-VkRenderPassCreateInfo-pNext-01963
    If the pNext chain includes a VkRenderPassInputAttachmentAspectCreateInfo structure, for any element of the pInputAttachments member of any element of pSubpasses where the attachment member is not VK_ATTACHMENT_UNUSED, the aspectMask member of the corresponding element of VkRenderPassInputAttachmentAspectCreateInfo::pAspectReferences must only include aspects that are present in images of the format specified by the element of pAttachments at attachment

  • VUID-VkRenderPassCreateInfo-pNext-01928
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, and its subpassCount member is not zero, that member must be equal to the value of subpassCount

  • VUID-VkRenderPassCreateInfo-pNext-01929
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, if its dependencyCount member is not zero, it must be equal to dependencyCount

  • VUID-VkRenderPassCreateInfo-pNext-01930
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, for each non-zero element of pViewOffsets, the srcSubpass and dstSubpass members of pDependencies at the same index must not be equal

  • VUID-VkRenderPassCreateInfo-pNext-02512
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, for any element of pDependencies with a dependencyFlags member that does not include VK_DEPENDENCY_VIEW_LOCAL_BIT, the corresponding element of the pViewOffsets member of that VkRenderPassMultiviewCreateInfo instance must be 0

  • VUID-VkRenderPassCreateInfo-pNext-02513
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, elements of its pViewMasks member must either all be 0, or all not be 0

  • VUID-VkRenderPassCreateInfo-pNext-02514
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, and each element of its pViewMasks member is 0, the dependencyFlags member of each element of pDependencies must not include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-VkRenderPassCreateInfo-pNext-02515
    If the pNext chain includes a VkRenderPassMultiviewCreateInfo structure, and each element of its pViewMasks member is 0, its correlationMaskCount member must be 0

  • VUID-VkRenderPassCreateInfo-pDependencies-00837
    For any element of pDependencies, if the srcSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in the srcStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the source subpass

  • VUID-VkRenderPassCreateInfo-pDependencies-00838
    For any element of pDependencies, if the dstSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in the dstStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the destination subpass

  • VUID-VkRenderPassCreateInfo-pDependencies-06866
    For any element of pDependencies, if its srcSubpass is not VK_SUBPASS_EXTERNAL, it must be less than subpassCount

  • VUID-VkRenderPassCreateInfo-pDependencies-06867
    For any element of pDependencies, if its dstSubpass is not VK_SUBPASS_EXTERNAL, it must be less than subpassCount

Valid Usage (Implicit)
  • VUID-VkRenderPassCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO

  • VUID-VkRenderPassCreateInfo-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkRenderPassFragmentDensityMapCreateInfoEXT, VkRenderPassInputAttachmentAspectCreateInfo, or VkRenderPassMultiviewCreateInfo

  • VUID-VkRenderPassCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkRenderPassCreateInfo-flags-parameter
    flags must be a valid combination of VkRenderPassCreateFlagBits values

  • VUID-VkRenderPassCreateInfo-pAttachments-parameter
    If attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkAttachmentDescription structures

  • VUID-VkRenderPassCreateInfo-pSubpasses-parameter
    pSubpasses must be a valid pointer to an array of subpassCount valid VkSubpassDescription structures

  • VUID-VkRenderPassCreateInfo-pDependencies-parameter
    If dependencyCount is not 0, pDependencies must be a valid pointer to an array of dependencyCount valid VkSubpassDependency structures

  • VUID-VkRenderPassCreateInfo-subpassCount-arraylength
    subpassCount must be greater than 0

Bits which can be set in VkRenderPassCreateInfo::flags, describing additional properties of the render pass, are:

// Provided by VK_VERSION_1_0
typedef enum VkRenderPassCreateFlagBits {
  // Provided by VK_QCOM_render_pass_transform
    VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM = 0x00000002,
} VkRenderPassCreateFlagBits;
  • VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM specifies that the created render pass is compatible with render pass transform.

// Provided by VK_VERSION_1_0
typedef VkFlags VkRenderPassCreateFlags;

VkRenderPassCreateFlags is a bitmask type for setting a mask of zero or more VkRenderPassCreateFlagBits.

If the VkRenderPassCreateInfo::pNext chain includes a VkRenderPassMultiviewCreateInfo structure, then that structure includes an array of view masks, view offsets, and correlation masks for the render pass.

The VkRenderPassMultiviewCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkRenderPassMultiviewCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           subpassCount;
    const uint32_t*    pViewMasks;
    uint32_t           dependencyCount;
    const int32_t*     pViewOffsets;
    uint32_t           correlationMaskCount;
    const uint32_t*    pCorrelationMasks;
} VkRenderPassMultiviewCreateInfo;

or the equivalent

// Provided by VK_KHR_multiview
typedef VkRenderPassMultiviewCreateInfo VkRenderPassMultiviewCreateInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • subpassCount is zero or the number of subpasses in the render pass.

  • pViewMasks is a pointer to an array of 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 subpassCount is zero, each view mask is treated as zero.

  • dependencyCount is zero or the number of dependencies in the render pass.

  • pViewOffsets is a pointer to an array of dependencyCount view offsets, one for each dependency. If 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.

  • correlationMaskCount is zero or the number of correlation masks.

  • pCorrelationMasks is a pointer to an array of 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 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 mesh shaders, geometry shaders or tessellation shaders.

When multiview is enabled, the 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 (dstView) in the destination subpass depends on the view dstView + 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 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 vkCmdBeginRenderPass or 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.

A multiview subpass can declare that its shaders will write per-view attributes for all views in a single invocation, by setting the 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 PositionPerViewNV and ViewportMaskPerViewNV, respectively. If VK_NV_viewport_array2 is not supported and enabled, ViewportMaskPerViewNV must not be used. Values written to elements of PositionPerViewNV and ViewportMaskPerViewNV must not depend on the ViewIndex. The shader must also write to an output variable decorated with Position, and the value written to Position must equal the value written to PositionPerViewNV[ViewIndex]. Similarly, if ViewportMaskPerViewNV is written to then the shader must also write to an output variable decorated with ViewportMaskNV, and the value written to ViewportMaskNV must equal the value written to ViewportMaskPerViewNV[ViewIndex]. Implementations will either use values taken from Position and ViewportMaskNV and invoke the shader once for each view, or will use values taken from PositionPerViewNV and ViewportMaskPerViewNV and invoke the shader fewer times. The values written to Position and ViewportMaskNV must not depend on the values written to PositionPerViewNV and ViewportMaskPerViewNV, or vice versa (to allow compilers to eliminate the unused outputs). All attributes that do not have *PerViewNV counterparts must not depend on ViewIndex.

Per-view attributes are all-or-nothing for a subpass. That is, all pipelines compiled against a subpass that includes the 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. Position) outputs. Pipelines compiled against a subpass that does not include this bit must not include the *PerViewNV[] outputs in their interfaces.

Valid Usage
  • VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-00841
    Each view index must not be set in more than one element of pCorrelationMasks

  • VUID-VkRenderPassMultiviewCreateInfo-multiview-06555
    If the multiview feature is not enabled, each element of pViewMasks must be 0

  • VUID-VkRenderPassMultiviewCreateInfo-pViewMasks-06697
    The index of the most significant bit in each element of pViewMasks must be less than maxMultiviewViewCount

Valid Usage (Implicit)
  • VUID-VkRenderPassMultiviewCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO

  • VUID-VkRenderPassMultiviewCreateInfo-pViewMasks-parameter
    If subpassCount is not 0, pViewMasks must be a valid pointer to an array of subpassCount uint32_t values

  • VUID-VkRenderPassMultiviewCreateInfo-pViewOffsets-parameter
    If dependencyCount is not 0, pViewOffsets must be a valid pointer to an array of dependencyCount int32_t values

  • VUID-VkRenderPassMultiviewCreateInfo-pCorrelationMasks-parameter
    If correlationMaskCount is not 0, pCorrelationMasks must be a valid pointer to an array of correlationMaskCount uint32_t values

The VkMultiviewPerViewAttributesInfoNVX structure is defined as:

// Provided by VK_KHR_dynamic_rendering with VK_NVX_multiview_per_view_attributes
typedef struct VkMultiviewPerViewAttributesInfoNVX {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           perViewAttributes;
    VkBool32           perViewAttributesPositionXOnly;
} VkMultiviewPerViewAttributesInfoNVX;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • 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. Position) outputs.

  • 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 VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX or VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX in the subpass description flags, the per-attribute properties of the render pass instance must be specified by the VkMultiviewPerViewAttributesInfoNVX structure Include the VkMultiviewPerViewAttributesInfoNVX structure in the pNext chain of VkGraphicsPipelineCreateInfo when creating a graphics pipeline for dynamic rendering, VkRenderingInfo when starting a dynamic render pass instance, and VkCommandBufferInheritanceInfo when specifying the dynamic render pass instance parameters for secondary command buffers.

Valid Usage (Implicit)
  • VUID-VkMultiviewPerViewAttributesInfoNVX-sType-sType
    sType must be VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_ATTRIBUTES_INFO_NVX

If the VkRenderPassCreateInfo::pNext chain includes a VkRenderPassFragmentDensityMapCreateInfoEXT structure, then that structure includes a fragment density map attachment for the render pass.

The VkRenderPassFragmentDensityMapCreateInfoEXT structure is defined as:

// Provided by VK_EXT_fragment_density_map
typedef struct VkRenderPassFragmentDensityMapCreateInfoEXT {
    VkStructureType          sType;
    const void*              pNext;
    VkAttachmentReference    fragmentDensityMapAttachment;
} VkRenderPassFragmentDensityMapCreateInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • 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 flags:

  • VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT specifies that the fragment density map will be read by the device during VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT specifies that the fragment density map will be read by the host during vkEndCommandBuffer of the primary command buffer that the render pass is recorded into

  • Otherwise the fragment density map will be read by the host during vkCmdBeginRenderPass

The fragment density map may additionally be read by the device during VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT for any mode.

If this structure is not present, it is as if fragmentDensityMapAttachment was given as VK_ATTACHMENT_UNUSED.

Valid Usage
  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02548
    If fragmentDensityMapAttachment is not VK_ATTACHMENT_UNUSED, fragmentDensityMapAttachment must not be an element of VkSubpassDescription::pInputAttachments, VkSubpassDescription::pColorAttachments, VkSubpassDescription::pResolveAttachments, VkSubpassDescription::pDepthStencilAttachment, or VkSubpassDescription::pPreserveAttachments for any subpass

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02549
    If fragmentDensityMapAttachment is not VK_ATTACHMENT_UNUSED, layout must be equal to VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02550
    If fragmentDensityMapAttachment is not VK_ATTACHMENT_UNUSED, fragmentDensityMapAttachment must reference an attachment with a loadOp equal to VK_ATTACHMENT_LOAD_OP_LOAD or VK_ATTACHMENT_LOAD_OP_DONT_CARE

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-02551
    If fragmentDensityMapAttachment is not VK_ATTACHMENT_UNUSED, fragmentDensityMapAttachment must reference an attachment with a storeOp equal to VK_ATTACHMENT_STORE_OP_DONT_CARE

Valid Usage (Implicit)
  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT

  • VUID-VkRenderPassFragmentDensityMapCreateInfoEXT-fragmentDensityMapAttachment-parameter
    fragmentDensityMapAttachment must be a valid VkAttachmentReference structure

The VkAttachmentDescription structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkAttachmentDescription {
    VkAttachmentDescriptionFlags    flags;
    VkFormat                        format;
    VkSampleCountFlagBits           samples;
    VkAttachmentLoadOp              loadOp;
    VkAttachmentStoreOp             storeOp;
    VkAttachmentLoadOp              stencilLoadOp;
    VkAttachmentStoreOp             stencilStoreOp;
    VkImageLayout                   initialLayout;
    VkImageLayout                   finalLayout;
} VkAttachmentDescription;
  • flags is a bitmask of VkAttachmentDescriptionFlagBits specifying additional properties of the attachment.

  • format is a VkFormat value specifying the format of the image view that will be used for the attachment.

  • samples is a VkSampleCountFlagBits value specifying the number of samples of the image.

  • loadOp is a 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.

  • storeOp is a 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.

  • stencilLoadOp is a 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.

  • stencilStoreOp is a 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.

  • initialLayout is the layout the attachment image subresource will be in when a render pass instance begins.

  • finalLayout is the layout the attachment image subresource will be transitioned to when a render pass instance ends.

If the attachment uses a color format, then loadOp and storeOp are used, and stencilLoadOp and stencilStoreOp are ignored. If the format has depth and/or stencil components, loadOp and storeOp apply only to the depth data, while stencilLoadOp and stencilStoreOp define how the stencil data is handled. loadOp and stencilLoadOp define the load operations for the attachment. storeOp and stencilStoreOp define the store operations for the attachment. If an attachment is not used by any subpass, loadOp, storeOp, stencilStoreOp, and stencilLoadOp will be ignored for that attachment, and no load or store ops will be performed. However, any transition specified by initialLayout and finalLayout will still be executed.

If flags includes 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 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 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

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 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.

If a set of attachments alias each other, then all except the first to be used in the render pass must use an initialLayout of 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

Once an attachment needs the 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 VK_ATTACHMENT_LOAD_OP_CLEAR.

Valid Usage
  • VUID-VkAttachmentDescription-format-06698
    format must not be VK_FORMAT_UNDEFINED

  • VUID-VkAttachmentDescription-format-06699
    If format includes a color or depth component and loadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription-finalLayout-00843
    finalLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkAttachmentDescription-format-03280
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03281
    If format is a depth/stencil format, initialLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription-format-03282
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03283
    If format is a depth/stencil format, finalLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription-format-06487
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription-format-06488
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription-separateDepthStencilLayouts-03284
    If the separateDepthStencilLayouts feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentDescription-separateDepthStencilLayouts-03285
    If the separateDepthStencilLayouts feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentDescription-format-03286
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03287
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-06906
    If format is a depth/stencil format which includes both depth and stencil components, initialLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-06907
    If format is a depth/stencil format which includes both depth and stencil components, finalLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03290
    If format is a depth/stencil format which includes only the depth component, initialLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03291
    If format is a depth/stencil format which includes only the depth component, finalLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-synchronization2-06908
    If the synchronization2 feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentDescription-synchronization2-06909
    If the synchronization2 feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentDescription-attachmentFeedbackLoopLayout-07309
    If the attachmentFeedbackLoopLayout feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentDescription-attachmentFeedbackLoopLayout-07310
    If the attachmentFeedbackLoopLayout feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentDescription-samples-08745
    samples must be a bit value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for the given format

  • VUID-VkAttachmentDescription-format-06700
    If format includes a stencil component and stencilLoadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription-format-03292
    If format is a depth/stencil format which includes only the stencil component, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-03293
    If format is a depth/stencil format which includes only the stencil component, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-06242
    If format is a depth/stencil format which includes both depth and stencil components, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription-format-06243
    If format is a depth/stencil format which includes both depth and stencil components, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

Valid Usage (Implicit)
  • VUID-VkAttachmentDescription-flags-parameter
    flags must be a valid combination of VkAttachmentDescriptionFlagBits values

  • VUID-VkAttachmentDescription-format-parameter
    format must be a valid VkFormat value

  • VUID-VkAttachmentDescription-samples-parameter
    samples must be a valid VkSampleCountFlagBits value

  • VUID-VkAttachmentDescription-loadOp-parameter
    loadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkAttachmentDescription-storeOp-parameter
    storeOp must be a valid VkAttachmentStoreOp value

  • VUID-VkAttachmentDescription-stencilLoadOp-parameter
    stencilLoadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkAttachmentDescription-stencilStoreOp-parameter
    stencilStoreOp must be a valid VkAttachmentStoreOp value

  • VUID-VkAttachmentDescription-initialLayout-parameter
    initialLayout must be a valid VkImageLayout value

  • VUID-VkAttachmentDescription-finalLayout-parameter
    finalLayout must be a valid VkImageLayout value

Bits which can be set in VkAttachmentDescription::flags, describing additional properties of the attachment, are:

// Provided by VK_VERSION_1_0
typedef enum VkAttachmentDescriptionFlagBits {
    VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT = 0x00000001,
} VkAttachmentDescriptionFlagBits;
  • VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT specifies that the attachment aliases the same device memory as other attachments.

// Provided by VK_VERSION_1_0
typedef VkFlags VkAttachmentDescriptionFlags;

VkAttachmentDescriptionFlags is a bitmask type for setting a mask of zero or more VkAttachmentDescriptionFlagBits.

The VkRenderPassInputAttachmentAspectCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkRenderPassInputAttachmentAspectCreateInfo {
    VkStructureType                            sType;
    const void*                                pNext;
    uint32_t                                   aspectReferenceCount;
    const VkInputAttachmentAspectReference*    pAspectReferences;
} VkRenderPassInputAttachmentAspectCreateInfo;

or the equivalent

// Provided by VK_KHR_maintenance2
typedef VkRenderPassInputAttachmentAspectCreateInfo VkRenderPassInputAttachmentAspectCreateInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • aspectReferenceCount is the number of elements in the pAspectReferences array.

  • pAspectReferences is a pointer to an array of aspectReferenceCount 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 VkRenderPassInputAttachmentAspectCreateInfo structure to the pNext chain of the VkRenderPassCreateInfo structure:

An application can access any aspect of an input attachment that does not have a specified aspect mask in the pAspectReferences array. Otherwise, an application must not access aspect(s) of an input attachment other than those in its specified aspect mask.

Valid Usage (Implicit)
  • VUID-VkRenderPassInputAttachmentAspectCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO

  • VUID-VkRenderPassInputAttachmentAspectCreateInfo-pAspectReferences-parameter
    pAspectReferences must be a valid pointer to an array of aspectReferenceCount valid VkInputAttachmentAspectReference structures

  • VUID-VkRenderPassInputAttachmentAspectCreateInfo-aspectReferenceCount-arraylength
    aspectReferenceCount must be greater than 0

The VkInputAttachmentAspectReference structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkInputAttachmentAspectReference {
    uint32_t              subpass;
    uint32_t              inputAttachmentIndex;
    VkImageAspectFlags    aspectMask;
} VkInputAttachmentAspectReference;

or the equivalent

// Provided by VK_KHR_maintenance2
typedef VkInputAttachmentAspectReference VkInputAttachmentAspectReferenceKHR;
  • subpass is an index into the pSubpasses array of the parent VkRenderPassCreateInfo structure.

  • inputAttachmentIndex is an index into the pInputAttachments of the specified subpass.

  • 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.

subpass and inputAttachmentIndex index into the render pass as:

pCreateInfo->pSubpasses[subpass].pInputAttachments[inputAttachmentIndex]
Valid Usage
  • VUID-VkInputAttachmentAspectReference-aspectMask-01964
    aspectMask must not include VK_IMAGE_ASPECT_METADATA_BIT

  • VUID-VkInputAttachmentAspectReference-aspectMask-02250
    aspectMask must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i

Valid Usage (Implicit)
  • VUID-VkInputAttachmentAspectReference-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-VkInputAttachmentAspectReference-aspectMask-requiredbitmask
    aspectMask must not be 0

The VkSubpassDescription structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSubpassDescription {
    VkSubpassDescriptionFlags       flags;
    VkPipelineBindPoint             pipelineBindPoint;
    uint32_t                        inputAttachmentCount;
    const VkAttachmentReference*    pInputAttachments;
    uint32_t                        colorAttachmentCount;
    const VkAttachmentReference*    pColorAttachments;
    const VkAttachmentReference*    pResolveAttachments;
    const VkAttachmentReference*    pDepthStencilAttachment;
    uint32_t                        preserveAttachmentCount;
    const uint32_t*                 pPreserveAttachments;
} VkSubpassDescription;
  • flags is a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying the pipeline type supported for this subpass.

  • inputAttachmentCount is the number of input attachments.

  • pInputAttachments is a pointer to an array of VkAttachmentReference structures defining the input attachments for this subpass and their layouts.

  • colorAttachmentCount is the number of color attachments.

  • pColorAttachments is a pointer to an array of colorAttachmentCount VkAttachmentReference structures defining the color attachments for this subpass and their layouts.

  • pResolveAttachments is NULL or a pointer to an array of colorAttachmentCount VkAttachmentReference structures defining the resolve attachments for this subpass and their layouts.

  • pDepthStencilAttachment is a pointer to a VkAttachmentReference structure specifying the depth/stencil attachment for this subpass and its layout.

  • preserveAttachmentCount is the number of preserved attachments.

  • pPreserveAttachments is a pointer to an array of 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 pInputAttachments array corresponds to an input attachment index in a fragment shader, i.e. if a shader declares an image variable decorated with a InputAttachmentIndex value of X, then it uses the attachment provided in pInputAttachments[X]. Input attachments must also be bound to the pipeline in a descriptor set. If the attachment member of any element of pInputAttachments is 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. Input attachments must not be used by any subpasses within a render pass that enables render pass transform.

Each element of the pColorAttachments array corresponds to an output location in the shader, i.e. if the shader declares an output variable decorated with a Location value of X, then it uses the attachment provided in pColorAttachments[X]. If the attachment member of any element of pColorAttachments is VK_ATTACHMENT_UNUSED, or if Color Write Enable has been disabled for the corresponding attachment index, then writes to the corresponding location by a fragment shader are discarded.

If flags does not include VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pResolveAttachments is not NULL, each of its elements corresponds to a color attachment (the element in pColorAttachments at the same index), and a multisample resolve operation is defined for each attachment unless the resolve attachment index is VK_ATTACHMENT_UNUSED.

Similarly, if flags does not include VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, it corresponds to the depth/stencil attachment in pDepthStencilAttachment, and multisample resolve operation for depth and stencil are defined by VkSubpassDescriptionDepthStencilResolve::depthResolveMode and VkSubpassDescriptionDepthStencilResolve::stencilResolveMode, respectively. If VkSubpassDescriptionDepthStencilResolve::depthResolveMode is VK_RESOLVE_MODE_NONE or the pDepthStencilResolveAttachment does not have a depth aspect, no resolve operation is performed for the depth attachment. If VkSubpassDescriptionDepthStencilResolve::stencilResolveMode is VK_RESOLVE_MODE_NONE or the pDepthStencilResolveAttachment does not have a stencil aspect, no resolve operation is performed for the stencil attachment.

If the image subresource range referenced by the depth/stencil attachment is created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT, then the multisample resolve operation uses the sample locations state specified in the sampleLocationsInfo member of the element of the VkRenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations for the subpass.

If pDepthStencilAttachment is NULL, or if its attachment index is 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 S1 that uses or preserves the attachment, and a subpass dependency from S1 to S.

  • The attachment is not used or preserved in subpass S.

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:

  • VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM is set.

  • The attachment is used as a color or depth/stencil in the subpass.

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 S1 if those subpasses use or preserve the attachment.

Valid Usage
  • VUID-VkSubpassDescription-attachment-06912
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06913
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06914
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06915
    If the attachment member of pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED, ts layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06916
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06917
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06918
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06919
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06920
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription-attachment-06921
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkSubpassDescription-attachment-06922
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription-attachment-06923
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription-pipelineBindPoint-04952
    pipelineBindPoint must be VK_PIPELINE_BIND_POINT_GRAPHICS or VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI

  • VUID-VkSubpassDescription-colorAttachmentCount-00845
    colorAttachmentCount must be less than or equal to VkPhysicalDeviceLimits::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 loadOp must not be VK_ATTACHMENT_LOAD_OP_CLEAR

  • VUID-VkSubpassDescription-pResolveAttachments-00847
    If pResolveAttachments is not NULL, for each resolve attachment that is not VK_ATTACHMENT_UNUSED, the corresponding color attachment must not be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-pResolveAttachments-00848
    If pResolveAttachments is not NULL, for each resolve attachment that is not VK_ATTACHMENT_UNUSED, the corresponding color attachment must not have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescription-pResolveAttachments-00849
    If pResolveAttachments is not NULL, each resolve attachment that is not VK_ATTACHMENT_UNUSED must have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescription-pResolveAttachments-00850
    If pResolveAttachments is not NULL, each resolve attachment that is not VK_ATTACHMENT_UNUSED must have the same VkFormat as its corresponding color attachment

  • VUID-VkSubpassDescription-pColorAttachments-06868
    If neither the VK_AMD_mixed_attachment_samples extension nor the VK_NV_framebuffer_mixed_samples extension is enabled, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have the same sample count

  • VUID-VkSubpassDescription-pInputAttachments-02647
    All attachments in pInputAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain at least VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescription-pColorAttachments-02648
    All attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkSubpassDescription-pResolveAttachments-02649
    All attachments in pResolveAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkSubpassDescription-pDepthStencilAttachment-02650
    If pDepthStencilAttachment is not NULL and the attachment is not VK_ATTACHMENT_UNUSED then it must have an image format whose potential format features contain VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescription-linearColorAttachment-06496
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pInputAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription-linearColorAttachment-06497
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription-linearColorAttachment-06498
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pResolveAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription-pColorAttachments-01506
    If the VK_AMD_mixed_attachment_samples extension is enabled, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have a sample count that is smaller than or equal to the sample count of pDepthStencilAttachment if it is not VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-pDepthStencilAttachment-01418
    If neither the VK_AMD_mixed_attachment_samples nor the VK_NV_framebuffer_mixed_samples extensions are enabled, and if pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED and any attachments in pColorAttachments are not VK_ATTACHMENT_UNUSED, they must have the same sample count

  • VUID-VkSubpassDescription-attachment-00853
    Each element of pPreserveAttachments must not be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-pPreserveAttachments-00854
    Each element of 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 VkAttachmentReference member, then each use must use the same layout

  • VUID-VkSubpassDescription-flags-00856
    If flags includes VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must also include VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX

  • VUID-VkSubpassDescription-flags-03341
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pResolveAttachments is not NULL, then each resolve attachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-flags-03343
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass must be the last subpass in a subpass dependency chain

  • VUID-VkSubpassDescription-pInputAttachments-02868
    If the render pass is created with VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM each of the elements of pInputAttachments must be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription-pDepthStencilAttachment-04438
    pDepthStencilAttachment and pColorAttachments must not contain references to the same attachment

Valid Usage (Implicit)
  • VUID-VkSubpassDescription-flags-parameter
    flags must be a valid combination of VkSubpassDescriptionFlagBits values

  • VUID-VkSubpassDescription-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-VkSubpassDescription-pInputAttachments-parameter
    If inputAttachmentCount is not 0, pInputAttachments must be a valid pointer to an array of inputAttachmentCount valid VkAttachmentReference structures

  • VUID-VkSubpassDescription-pColorAttachments-parameter
    If colorAttachmentCount is not 0, pColorAttachments must be a valid pointer to an array of colorAttachmentCount valid VkAttachmentReference structures

  • VUID-VkSubpassDescription-pResolveAttachments-parameter
    If colorAttachmentCount is not 0, and pResolveAttachments is not NULL, pResolveAttachments must be a valid pointer to an array of colorAttachmentCount valid VkAttachmentReference structures

  • VUID-VkSubpassDescription-pDepthStencilAttachment-parameter
    If pDepthStencilAttachment is not NULL, pDepthStencilAttachment must be a valid pointer to a valid VkAttachmentReference structure

  • VUID-VkSubpassDescription-pPreserveAttachments-parameter
    If preserveAttachmentCount is not 0, pPreserveAttachments must be a valid pointer to an array of preserveAttachmentCount uint32_t values

Bits which can be set in VkSubpassDescription::flags, specifying usage of the subpass, are:

// Provided by VK_VERSION_1_0
typedef enum VkSubpassDescriptionFlagBits {
  // Provided by VK_NVX_multiview_per_view_attributes
    VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX = 0x00000001,
  // Provided by VK_NVX_multiview_per_view_attributes
    VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX = 0x00000002,
  // Provided by VK_QCOM_render_pass_shader_resolve
    VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM = 0x00000004,
  // Provided by VK_QCOM_render_pass_shader_resolve
    VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM = 0x00000008,
  // Provided by VK_EXT_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT = 0x00000010,
  // Provided by VK_EXT_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT = 0x00000020,
  // Provided by VK_EXT_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT = 0x00000040,
  // Provided by VK_EXT_legacy_dithering
    VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT = 0x00000080,
  // Provided by VK_ARM_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT,
  // Provided by VK_ARM_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT,
  // Provided by VK_ARM_rasterization_order_attachment_access
    VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM = VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT,
} VkSubpassDescriptionFlagBits;
  • 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 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. Position) outputs.

  • 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.

  • 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.

  • VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM specifies that the subpass performs shader resolve operations.

  • VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_EXT specifies that this subpass supports pipelines created with VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT.

  • VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT specifies that this subpass supports pipelines created with VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT.

  • VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT specifies that this subpass supports pipelines created with VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT.

  • VK_SUBPASS_DESCRIPTION_ENABLE_LEGACY_DITHERING_BIT_EXT specifies that Legacy Dithering is enabled for this subpass.

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 beginning of a shader resolve subpass, any depth testing, stencil testing, or blending operation which sources these undefined values also has undefined result value.

// Provided by VK_VERSION_1_0
typedef VkFlags VkSubpassDescriptionFlags;

VkSubpassDescriptionFlags is a bitmask type for setting a mask of zero or more VkSubpassDescriptionFlagBits.

The VkAttachmentReference structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkAttachmentReference {
    uint32_t         attachment;
    VkImageLayout    layout;
} VkAttachmentReference;
  • attachment is either an integer value identifying an attachment at the corresponding index in VkRenderPassCreateInfo::pAttachments, or VK_ATTACHMENT_UNUSED to signify that this attachment is not used.

  • layout is a VkImageLayout value specifying the layout the attachment uses during the subpass.

Valid Usage
  • VUID-VkAttachmentReference-layout-03077
    If attachment is not VK_ATTACHMENT_UNUSED, layout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_PREINITIALIZED, or VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • VUID-VkAttachmentReference-separateDepthStencilLayouts-03313
    If the separateDepthStencilLayouts feature is not enabled, and attachment is not VK_ATTACHMENT_UNUSED, layout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentReference-synchronization2-06910
    If the synchronization2 feature is not enabled, layout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentReference-attachmentFeedbackLoopLayout-07311
    If the attachmentFeedbackLoopLayout feature is not enabled, layout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

Valid Usage (Implicit)
  • VUID-VkAttachmentReference-layout-parameter
    layout must be a valid VkImageLayout value

VK_SUBPASS_EXTERNAL is a special subpass index value expanding synchronization scope outside a subpass. It is described in more detail by VkSubpassDependency.

#define VK_SUBPASS_EXTERNAL               (~0U)

The VkSubpassDependency structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSubpassDependency {
    uint32_t                srcSubpass;
    uint32_t                dstSubpass;
    VkPipelineStageFlags    srcStageMask;
    VkPipelineStageFlags    dstStageMask;
    VkAccessFlags           srcAccessMask;
    VkAccessFlags           dstAccessMask;
    VkDependencyFlags       dependencyFlags;
} VkSubpassDependency;

If srcSubpass is equal to dstSubpass then the VkSubpassDependency does not directly define a dependency. Instead, it enables pipeline barriers to be used in a render pass instance within the identified subpass, where the scopes of one pipeline barrier must be a subset of those described by one subpass dependency. Subpass dependencies specified in this way that include framebuffer-space stages in the srcStageMask must only include framebuffer-space stages in dstStageMask, and must include VK_DEPENDENCY_BY_REGION_BIT. When a subpass dependency is specified in this way for a subpass that has more than one view in its view mask, its dependencyFlags must include VK_DEPENDENCY_VIEW_LOCAL_BIT.

If srcSubpass and dstSubpass are not equal, when a render pass instance which includes a subpass dependency is submitted to a queue, it defines a dependency between the subpasses identified by srcSubpass and dstSubpass.

If srcSubpass is equal to VK_SUBPASS_EXTERNAL, the first synchronization scope includes commands that occur earlier in submission order than the 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 srcSubpass and any load, store, or multisample resolve operations on attachments used in srcSubpass. In either case, the first synchronization scope is limited to operations on the pipeline stages determined by the source stage mask specified by srcStageMask.

If dstSubpass is equal to VK_SUBPASS_EXTERNAL, the second synchronization scope includes commands that occur later in submission order than the 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 dstSubpass and any load, store, and multisample resolve operations on attachments used in dstSubpass. In either case, the second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to accesses in the pipeline stages determined by the source stage mask specified by srcStageMask. It is also limited to access types in the source access mask specified by srcAccessMask.

The second access scope is limited to accesses in the pipeline stages determined by the destination stage mask specified by dstStageMask. It is also limited to access types in the destination access mask specified by dstAccessMask.

The availability and visibility operations defined by a subpass dependency affect the execution of image layout transitions within the render pass.

Note

For non-attachment resources, the memory dependency expressed by subpass dependency is nearly identical to that of a VkMemoryBarrier (with matching srcAccessMask and dstAccessMask parameters) submitted as a part of a vkCmdPipelineBarrier (with matching srcStageMask and 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 VkImageMemoryBarrier defined similarly to the VkMemoryBarrier above, the queue family indices set to VK_QUEUE_FAMILY_IGNORED, and layouts as follows:

  • The equivalent to oldLayout is the attachment’s layout according to the subpass description for srcSubpass.

  • The equivalent to newLayout is the attachment’s layout according to the subpass description for dstSubpass.

Valid Usage
  • VUID-VkSubpassDependency-srcStageMask-04090
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubpassDependency-srcStageMask-04091
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubpassDependency-srcStageMask-04092
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-04093
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-04094
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-04095
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-04096
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubpassDependency-srcStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubpassDependency-srcStageMask-03937
    If the synchronization2 feature is not enabled, srcStageMask must not be 0

  • VUID-VkSubpassDependency-srcStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubpassDependency-dstStageMask-04090
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubpassDependency-dstStageMask-04091
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubpassDependency-dstStageMask-04092
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-04093
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-04094
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-04095
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-04096
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubpassDependency-dstStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubpassDependency-dstStageMask-03937
    If the synchronization2 feature is not enabled, dstStageMask must not be 0

  • VUID-VkSubpassDependency-dstStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubpassDependency-srcSubpass-00864
    srcSubpass must be less than or equal to dstSubpass, unless one of them is VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies and ensure a valid execution order

  • VUID-VkSubpassDependency-srcSubpass-00865
    srcSubpass and dstSubpass must not both be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency-srcSubpass-06809
    If srcSubpass is equal to dstSubpass and srcStageMask includes a framebuffer-space stage, dstStageMask must only contain framebuffer-space stages

  • VUID-VkSubpassDependency-srcAccessMask-00868
    Any access flag included in srcAccessMask must be supported by one of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-VkSubpassDependency-dstAccessMask-00869
    Any access flag included in dstAccessMask must be supported by one of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-VkSubpassDependency-srcSubpass-02243
    If srcSubpass equals dstSubpass, and srcStageMask and dstStageMask both include a framebuffer-space stage, then dependencyFlags must include VK_DEPENDENCY_BY_REGION_BIT

  • VUID-VkSubpassDependency-dependencyFlags-02520
    If dependencyFlags includes VK_DEPENDENCY_VIEW_LOCAL_BIT, srcSubpass must not be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency-dependencyFlags-02521
    If dependencyFlags includes VK_DEPENDENCY_VIEW_LOCAL_BIT, dstSubpass must not be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency-srcSubpass-00872
    If srcSubpass equals dstSubpass and that subpass has more than one bit set in the view mask, then dependencyFlags must include VK_DEPENDENCY_VIEW_LOCAL_BIT

Valid Usage (Implicit)
  • VUID-VkSubpassDependency-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-VkSubpassDependency-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-VkSubpassDependency-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkSubpassDependency-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkSubpassDependency-dependencyFlags-parameter
    dependencyFlags must be a valid combination of VkDependencyFlagBits values

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 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

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 N × 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.

The content of each view follows the description in attachment content behavior. In particular, if an attachment is preserved, all views within the attachment are preserved.

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.

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 automatic layout transitions happen. Further rewrites of this chapter could potentially remove the need for these.

If there is no subpass dependency from VK_SUBPASS_EXTERNAL to the first subpass that uses an attachment, then an implicit subpass dependency exists from 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 initialLayout. The subpass dependency operates as if defined with the following parameters:

VkSubpassDependency implicitDependency = {
    .srcSubpass = VK_SUBPASS_EXTERNAL,
    .dstSubpass = firstSubpass, // First subpass attachment is used in
    .srcStageMask = VK_PIPELINE_STAGE_NONE,
    .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 VK_SUBPASS_EXTERNAL, then an implicit subpass dependency exists from the last subpass it is used in to VK_SUBPASS_EXTERNAL. The implicit subpass dependency only exists if there exists an automatic layout transition into finalLayout. The subpass dependency operates as if defined with the following parameters:

VkSubpassDependency implicitDependency = {
    .srcSubpass = lastSubpass, // Last subpass attachment is used in
    .dstSubpass = VK_SUBPASS_EXTERNAL,
    .srcStageMask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
    .dstStageMask = VK_PIPELINE_STAGE_NONE,
    .srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT |
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
    .dstAccessMask = 0,
    .dependencyFlags = 0
};

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. If multiview is not enabled and the attachment is a view of a 1D or 2D image, the automatic layout transitions apply to the number of layers specified by VkFramebufferCreateInfo::layers. If multiview is enabled and the attachment is a view of a 1D or 2D image, the automatic layout transitions apply to the layers corresponding to views which are used by some subpass in the render pass, even if that subpass does not reference the given attachment. 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.

Automatic layout transitions away from the layout used in a subpass happen-after the availability operations for all dependencies with that subpass as the srcSubpass.

Automatic layout transitions into the layout used in a subpass happen-before the visibility operations for all dependencies with that subpass as the dstSubpass.

Automatic layout transitions away from initialLayout happen-after the availability operations for all dependencies with a srcSubpass equal to VK_SUBPASS_EXTERNAL, where dstSubpass uses the attachment that will be transitioned. For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, automatic layout transitions away from initialLayout happen-after the availability operations for all dependencies with a srcSubpass equal to VK_SUBPASS_EXTERNAL, where dstSubpass uses any aliased attachment.

Automatic layout transitions into finalLayout happen-before the visibility operations for all dependencies with a dstSubpass equal to VK_SUBPASS_EXTERNAL, where srcSubpass uses the attachment that will be transitioned. For attachments created with VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, automatic layout transitions into finalLayout happen-before the visibility operations for all dependencies with a dstSubpass equal to VK_SUBPASS_EXTERNAL, where srcSubpass uses any aliased attachment.

The image layout of the depth aspect of a depth/stencil attachment referring to an image created with 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 VkRenderPassSampleLocationsBeginInfoEXT.

Automatic layout transitions of an attachment referring to a depth/stencil image created with 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 sampleLocationsInfo member of the element of the VkRenderPassSampleLocationsBeginInfoEXT::pAttachmentInitialSampleLocations array for which the 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 sampleLocationsInfo member of the element of the VkRenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations array for which the 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 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 VK_IMAGE_LAYOUT_UNDEFINED layout.

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:

// 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;
};

A more extensible version of render pass creation is also defined below.

To create a render pass, call:

// Provided by VK_VERSION_1_2
VkResult vkCreateRenderPass2(
    VkDevice                                    device,
    const VkRenderPassCreateInfo2*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkRenderPass*                               pRenderPass);

or the equivalent command

// Provided by VK_KHR_create_renderpass2
VkResult vkCreateRenderPass2KHR(
    VkDevice                                    device,
    const VkRenderPassCreateInfo2*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkRenderPass*                               pRenderPass);
  • device is the logical device that creates the render pass.

  • pCreateInfo is a pointer to a VkRenderPassCreateInfo2 structure describing the parameters of the render pass.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pRenderPass is a pointer to a VkRenderPass handle in which the resulting render pass object is returned.

This command is functionally identical to vkCreateRenderPass, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage (Implicit)
  • VUID-vkCreateRenderPass2-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateRenderPass2-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkRenderPassCreateInfo2 structure

  • VUID-vkCreateRenderPass2-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateRenderPass2-pRenderPass-parameter
    pRenderPass must be a valid pointer to a VkRenderPass handle

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkRenderPassCreateInfo2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkRenderPassCreateInfo2 {
    VkStructureType                    sType;
    const void*                        pNext;
    VkRenderPassCreateFlags            flags;
    uint32_t                           attachmentCount;
    const VkAttachmentDescription2*    pAttachments;
    uint32_t                           subpassCount;
    const VkSubpassDescription2*       pSubpasses;
    uint32_t                           dependencyCount;
    const VkSubpassDependency2*        pDependencies;
    uint32_t                           correlatedViewMaskCount;
    const uint32_t*                    pCorrelatedViewMasks;
} VkRenderPassCreateInfo2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkRenderPassCreateInfo2 VkRenderPassCreateInfo2KHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • attachmentCount is the number of attachments used by this render pass.

  • pAttachments is a pointer to an array of attachmentCount VkAttachmentDescription2 structures describing the attachments used by the render pass.

  • subpassCount is the number of subpasses to create.

  • pSubpasses is a pointer to an array of subpassCount VkSubpassDescription2 structures describing each subpass.

  • dependencyCount is the number of dependencies between pairs of subpasses.

  • pDependencies is a pointer to an array of dependencyCount VkSubpassDependency2 structures describing dependencies between pairs of subpasses.

  • correlatedViewMaskCount is the number of correlation masks.

  • 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 VkRenderPassCreateInfo have the identical effect to those parameters; the child structures are variants of those used in VkRenderPassCreateInfo which add sType and pNext parameters, allowing them to be extended.

If the VkSubpassDescription2::viewMask member of any element of pSubpasses is not zero, multiview functionality is considered to be enabled for this render pass.

correlatedViewMaskCount and pCorrelatedViewMasks have the same effect as VkRenderPassMultiviewCreateInfo::correlationMaskCount and VkRenderPassMultiviewCreateInfo::pCorrelationMasks, respectively.

Valid Usage
  • VUID-VkRenderPassCreateInfo2-None-03049
    If any two subpasses operate on attachments with overlapping ranges of the same VkDeviceMemory object, and at least one subpass writes to that area of VkDeviceMemory, a subpass dependency must be included (either directly or via some intermediate subpasses) between them

  • VUID-VkRenderPassCreateInfo2-attachment-03050
    If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or the attachment indexed by any element of pPreserveAttachments in any element of pSubpasses is bound to a range of a VkDeviceMemory object that overlaps with any other attachment in any subpass (including the same subpass), the VkAttachmentDescription2 structures describing them must include VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT in flags

  • VUID-VkRenderPassCreateInfo2-attachment-03051
    If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not VK_ATTACHMENT_UNUSED, then it must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo2-fragmentDensityMapAttachment-06472
    If the pNext chain includes a VkRenderPassFragmentDensityMapCreateInfoEXT structure and the fragmentDensityMapAttachment member is not VK_ATTACHMENT_UNUSED, then attachment must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo2-pSubpasses-06473
    If the pSubpasses pNext chain includes a VkSubpassDescriptionDepthStencilResolve structure and the pDepthStencilResolveAttachment member is not NULL and does not have the value VK_ATTACHMENT_UNUSED, then attachment must be less than attachmentCount

  • VUID-VkRenderPassCreateInfo2-pAttachments-02522
    For any member of pAttachments with a loadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkRenderPassCreateInfo2-pAttachments-02523
    For any member of pAttachments with a stencilLoadOp equal to VK_ATTACHMENT_LOAD_OP_CLEAR, the first use of that attachment must not specify a layout equal to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkRenderPassCreateInfo2-pDependencies-03054
    For any element of pDependencies, if the srcSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in the srcStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the source subpass

  • VUID-VkRenderPassCreateInfo2-pDependencies-03055
    For any element of pDependencies, if the dstSubpass is not VK_SUBPASS_EXTERNAL, all stage flags included in the dstStageMask member of that dependency must be a pipeline stage supported by the pipeline identified by the pipelineBindPoint member of the destination subpass

  • VUID-VkRenderPassCreateInfo2-pCorrelatedViewMasks-03056
    The set of bits included in any element of pCorrelatedViewMasks must not overlap with the set of bits included in any other element of pCorrelatedViewMasks

  • VUID-VkRenderPassCreateInfo2-viewMask-03057
    If the VkSubpassDescription2::viewMask member of all elements of pSubpasses is 0, correlatedViewMaskCount must be 0

  • VUID-VkRenderPassCreateInfo2-viewMask-03058
    The VkSubpassDescription2::viewMask member of all elements of pSubpasses must either all be 0, or all not be 0

  • VUID-VkRenderPassCreateInfo2-viewMask-03059
    If the VkSubpassDescription2::viewMask member of all elements of pSubpasses is 0, the dependencyFlags member of any element of pDependencies must not include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-VkRenderPassCreateInfo2-pDependencies-03060
    For any element of pDependencies where its srcSubpass member equals its dstSubpass member, if the viewMask member of the corresponding element of pSubpasses includes more than one bit, its dependencyFlags member must include VK_DEPENDENCY_VIEW_LOCAL_BIT

  • VUID-VkRenderPassCreateInfo2-attachment-02525
    If the attachment member of any element of the pInputAttachments member of any element of pSubpasses is not VK_ATTACHMENT_UNUSED, the aspectMask member of that element of pInputAttachments must only include aspects that are present in images of the format specified by the element of pAttachments specified by attachment

  • VUID-VkRenderPassCreateInfo2-srcSubpass-02526
    The srcSubpass member of each element of pDependencies must be less than subpassCount

  • VUID-VkRenderPassCreateInfo2-dstSubpass-02527
    The dstSubpass member of each element of pDependencies must be less than subpassCount

  • VUID-VkRenderPassCreateInfo2-pAttachments-04585
    If any element of 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

  • VUID-VkRenderPassCreateInfo2-flags-04521
    If flags includes VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM, an element of pSubpasses includes an instance of VkFragmentShadingRateAttachmentInfoKHR in its pNext chain, and the pFragmentShadingRateAttachment member of that structure is not equal to NULL, the attachment member of pFragmentShadingRateAttachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkRenderPassCreateInfo2-pAttachments-04586
    If any element of pAttachments is used as a fragment shading rate attachment in any subpass, it must have an image format whose potential format features contain VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkRenderPassCreateInfo2-rasterizationSamples-04905
    If the pipeline is being created with fragment shader state, and the VK_QCOM_render_pass_shader_resolve extension is enabled, and if subpass has any input attachments, and if the subpass description contains VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then the sample count of the input attachments must equal rasterizationSamples

  • VUID-VkRenderPassCreateInfo2-sampleShadingEnable-04906
    If the pipeline is being created with fragment shader state, and the VK_QCOM_render_pass_shader_resolve extension is enabled, and if the subpass description contains VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then sampleShadingEnable must be false

  • VUID-VkRenderPassCreateInfo2-flags-04907
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pResolveAttachments is not NULL, then each resolve attachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkRenderPassCreateInfo2-flags-04908
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if pDepthStencilResolveAttachment is not NULL, then the depth/stencil resolve attachment must be VK_ATTACHMENT_UNUSED

  • VUID-VkRenderPassCreateInfo2-flags-04909
    If flags includes VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass must be the last subpass in a subpass dependency chain

  • VUID-VkRenderPassCreateInfo2-attachment-06244
    If the attachment member of the pDepthStencilAttachment member of an element of pSubpasses is not VK_ATTACHMENT_UNUSED, the layout member of that same structure is either VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, and the pNext chain of that structure does not include a VkAttachmentReferenceStencilLayout structure, then the element of pAttachments with an index equal to attachment must not have a format that includes both depth and stencil components

  • VUID-VkRenderPassCreateInfo2-attachment-06245
    If the attachment member of the pDepthStencilAttachment member of an element of pSubpasses is not VK_ATTACHMENT_UNUSED and the layout member of that same structure is either VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, then the element of pAttachments with an index equal to attachment must have a format that includes only a stencil component

  • VUID-VkRenderPassCreateInfo2-attachment-06246
    If the attachment member of the pDepthStencilAttachment member of an element of pSubpasses is not VK_ATTACHMENT_UNUSED and the layout member of that same structure is either VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, then the element of pAttachments with an index equal to attachment must not have a format that includes only a stencil component

Valid Usage (Implicit)
  • VUID-VkRenderPassCreateInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2

  • VUID-VkRenderPassCreateInfo2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkRenderPassCreationControlEXT, VkRenderPassCreationFeedbackCreateInfoEXT, or VkRenderPassFragmentDensityMapCreateInfoEXT

  • VUID-VkRenderPassCreateInfo2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkRenderPassCreateInfo2-flags-parameter
    flags must be a valid combination of VkRenderPassCreateFlagBits values

  • VUID-VkRenderPassCreateInfo2-pAttachments-parameter
    If attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkAttachmentDescription2 structures

  • VUID-VkRenderPassCreateInfo2-pSubpasses-parameter
    pSubpasses must be a valid pointer to an array of subpassCount valid VkSubpassDescription2 structures

  • VUID-VkRenderPassCreateInfo2-pDependencies-parameter
    If dependencyCount is not 0, pDependencies must be a valid pointer to an array of dependencyCount valid VkSubpassDependency2 structures

  • VUID-VkRenderPassCreateInfo2-pCorrelatedViewMasks-parameter
    If correlatedViewMaskCount is not 0, pCorrelatedViewMasks must be a valid pointer to an array of correlatedViewMaskCount uint32_t values

  • VUID-VkRenderPassCreateInfo2-subpassCount-arraylength
    subpassCount must be greater than 0

The VkAttachmentDescription2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkAttachmentDescription2 {
    VkStructureType                 sType;
    const void*                     pNext;
    VkAttachmentDescriptionFlags    flags;
    VkFormat                        format;
    VkSampleCountFlagBits           samples;
    VkAttachmentLoadOp              loadOp;
    VkAttachmentStoreOp             storeOp;
    VkAttachmentLoadOp              stencilLoadOp;
    VkAttachmentStoreOp             stencilStoreOp;
    VkImageLayout                   initialLayout;
    VkImageLayout                   finalLayout;
} VkAttachmentDescription2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkAttachmentDescription2 VkAttachmentDescription2KHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkAttachmentDescriptionFlagBits specifying additional properties of the attachment.

  • format is a VkFormat value specifying the format of the image that will be used for the attachment.

  • samples is a VkSampleCountFlagBits value specifying the number of samples of the image.

  • loadOp is a 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.

  • storeOp is a 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.

  • stencilLoadOp is a 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.

  • stencilStoreOp is a 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.

  • initialLayout is the layout the attachment image subresource will be in when a render pass instance begins.

  • 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 VkAttachmentDescription have the identical effect to those parameters.

If the separateDepthStencilLayouts feature is enabled, and format is a depth/stencil format, initialLayout and finalLayout can be set to a layout that only specifies the layout of the depth aspect.

If the pNext chain includes a VkAttachmentDescriptionStencilLayout structure, then the stencilInitialLayout and stencilFinalLayout members specify the initial and final layouts of the stencil aspect of a depth/stencil format, and initialLayout and finalLayout only apply to the depth aspect. For depth-only formats, the VkAttachmentDescriptionStencilLayout structure is ignored. For stencil-only formats, the initial and final layouts of the stencil aspect are taken from the VkAttachmentDescriptionStencilLayout structure if present, or initialLayout and finalLayout if not present.

If format is a depth/stencil format, and either initialLayout or 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 VkAttachmentDescriptionStencilLayout structure in the pNext chain.

Valid Usage
  • VUID-VkAttachmentDescription2-format-06698
    format must not be VK_FORMAT_UNDEFINED

  • VUID-VkAttachmentDescription2-format-06699
    If format includes a color or depth component and loadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription2-finalLayout-00843
    finalLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

  • VUID-VkAttachmentDescription2-format-03280
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03281
    If format is a depth/stencil format, initialLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03282
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03283
    If format is a depth/stencil format, finalLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06487
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06488
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescription2-separateDepthStencilLayouts-03284
    If the separateDepthStencilLayouts feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentDescription2-separateDepthStencilLayouts-03285
    If the separateDepthStencilLayouts feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentDescription2-format-03286
    If format is a color format, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03287
    If format is a color format, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06906
    If format is a depth/stencil format which includes both depth and stencil components, initialLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06907
    If format is a depth/stencil format which includes both depth and stencil components, finalLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03290
    If format is a depth/stencil format which includes only the depth component, initialLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-03291
    If format is a depth/stencil format which includes only the depth component, finalLayout must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-synchronization2-06908
    If the synchronization2 feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentDescription2-synchronization2-06909
    If the synchronization2 feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentDescription2-attachmentFeedbackLoopLayout-07309
    If the attachmentFeedbackLoopLayout feature is not enabled, initialLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentDescription2-attachmentFeedbackLoopLayout-07310
    If the attachmentFeedbackLoopLayout feature is not enabled, finalLayout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

  • VUID-VkAttachmentDescription2-samples-08745
    samples must be a bit value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for the given format

  • VUID-VkAttachmentDescription2-pNext-06704
    If the pNext chain does not include a VkAttachmentDescriptionStencilLayout structure, format includes a stencil component, and stencilLoadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then initialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription2-pNext-06705
    If the pNext chain does includes a VkAttachmentDescriptionStencilLayout structure, format includes a stencil component, and stencilLoadOp is VK_ATTACHMENT_LOAD_OP_LOAD, then VkAttachmentDescriptionStencilLayout::stencilInitialLayout must not be VK_IMAGE_LAYOUT_UNDEFINED

  • VUID-VkAttachmentDescription2-format-06249
    If format is a depth/stencil format which includes both depth and stencil components, and initialLayout is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pNext chain must include a VkAttachmentDescriptionStencilLayout structure

  • VUID-VkAttachmentDescription2-format-06250
    If format is a depth/stencil format which includes both depth and stencil components, and finalLayout is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, the pNext chain must include a VkAttachmentDescriptionStencilLayout structure

  • VUID-VkAttachmentDescription2-format-06247
    If the pNext chain does not include a VkAttachmentDescriptionStencilLayout structure and format only includes a stencil component, initialLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

  • VUID-VkAttachmentDescription2-format-06248
    If the pNext chain does not include a VkAttachmentDescriptionStencilLayout structure and format only includes a stencil component, finalLayout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

Valid Usage (Implicit)
  • VUID-VkAttachmentDescription2-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2

  • VUID-VkAttachmentDescription2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkAttachmentDescriptionStencilLayout

  • VUID-VkAttachmentDescription2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkAttachmentDescription2-flags-parameter
    flags must be a valid combination of VkAttachmentDescriptionFlagBits values

  • VUID-VkAttachmentDescription2-format-parameter
    format must be a valid VkFormat value

  • VUID-VkAttachmentDescription2-samples-parameter
    samples must be a valid VkSampleCountFlagBits value

  • VUID-VkAttachmentDescription2-loadOp-parameter
    loadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkAttachmentDescription2-storeOp-parameter
    storeOp must be a valid VkAttachmentStoreOp value

  • VUID-VkAttachmentDescription2-stencilLoadOp-parameter
    stencilLoadOp must be a valid VkAttachmentLoadOp value

  • VUID-VkAttachmentDescription2-stencilStoreOp-parameter
    stencilStoreOp must be a valid VkAttachmentStoreOp value

  • VUID-VkAttachmentDescription2-initialLayout-parameter
    initialLayout must be a valid VkImageLayout value

  • VUID-VkAttachmentDescription2-finalLayout-parameter
    finalLayout must be a valid VkImageLayout value

The VkAttachmentDescriptionStencilLayout structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkAttachmentDescriptionStencilLayout {
    VkStructureType    sType;
    void*              pNext;
    VkImageLayout      stencilInitialLayout;
    VkImageLayout      stencilFinalLayout;
} VkAttachmentDescriptionStencilLayout;

or the equivalent

// Provided by VK_KHR_separate_depth_stencil_layouts
typedef VkAttachmentDescriptionStencilLayout VkAttachmentDescriptionStencilLayoutKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stencilInitialLayout is the layout the stencil aspect of the attachment image subresource will be in when a render pass instance begins.

  • 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
    stencilInitialLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-03309
    stencilFinalLayout must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-03310
    stencilFinalLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

Valid Usage (Implicit)
  • VUID-VkAttachmentDescriptionStencilLayout-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_STENCIL_LAYOUT

  • VUID-VkAttachmentDescriptionStencilLayout-stencilInitialLayout-parameter
    stencilInitialLayout must be a valid VkImageLayout value

  • VUID-VkAttachmentDescriptionStencilLayout-stencilFinalLayout-parameter
    stencilFinalLayout must be a valid VkImageLayout value

The VkSubpassDescription2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassDescription2 {
    VkStructureType                  sType;
    const void*                      pNext;
    VkSubpassDescriptionFlags        flags;
    VkPipelineBindPoint              pipelineBindPoint;
    uint32_t                         viewMask;
    uint32_t                         inputAttachmentCount;
    const VkAttachmentReference2*    pInputAttachments;
    uint32_t                         colorAttachmentCount;
    const VkAttachmentReference2*    pColorAttachments;
    const VkAttachmentReference2*    pResolveAttachments;
    const VkAttachmentReference2*    pDepthStencilAttachment;
    uint32_t                         preserveAttachmentCount;
    const uint32_t*                  pPreserveAttachments;
} VkSubpassDescription2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkSubpassDescription2 VkSubpassDescription2KHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkSubpassDescriptionFlagBits specifying usage of the subpass.

  • pipelineBindPoint is a VkPipelineBindPoint value specifying the pipeline type supported for this subpass.

  • viewMask is a bitfield of view indices describing which views rendering is broadcast to in this subpass, when multiview is enabled.

  • inputAttachmentCount is the number of input attachments.

  • pInputAttachments is a pointer to an array of VkAttachmentReference2 structures defining the input attachments for this subpass and their layouts.

  • colorAttachmentCount is the number of color attachments.

  • pColorAttachments is a pointer to an array of colorAttachmentCount VkAttachmentReference2 structures defining the color attachments for this subpass and their layouts.

  • pResolveAttachments is NULL or a pointer to an array of colorAttachmentCount VkAttachmentReference2 structures defining the resolve attachments for this subpass and their layouts.

  • pDepthStencilAttachment is a pointer to a VkAttachmentReference2 structure specifying the depth/stencil attachment for this subpass and its layout.

  • preserveAttachmentCount is the number of preserved attachments.

  • pPreserveAttachments is a pointer to an array of 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 VkSubpassDescription have the identical effect to those parameters.

viewMask has the same effect for the described subpass as VkRenderPassMultiviewCreateInfo::pViewMasks has on each corresponding subpass.

If a VkFragmentShadingRateAttachmentInfoKHR structure is included in the pNext chain, pFragmentShadingRateAttachment is not NULL, and its attachment member is not VK_ATTACHMENT_UNUSED, the identified attachment defines a fragment shading rate attachment for that subpass.

Valid Usage
  • VUID-VkSubpassDescription2-attachment-06912
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06913
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06914
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06915
    If the attachment member of pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED, ts layout member must not be VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06916
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06917
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06918
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06919
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06920
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-attachment-06921
    If the attachment member of an element of pInputAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06922
    If the attachment member of an element of pColorAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06923
    If the attachment member of an element of pResolveAttachments is not VK_ATTACHMENT_UNUSED, its layout member must not be VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkSubpassDescription2-attachment-06251
    If the attachment member of pDepthStencilAttachment is not VK_ATTACHMENT_UNUSED and its pNext chain includes a VkAttachmentReferenceStencilLayout structure, the layout member of pDepthStencilAttachment must not be VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

  • VUID-VkSubpassDescription2-pipelineBindPoint-04953
    pipelineBindPoint must be VK_PIPELINE_BIND_POINT_GRAPHICS or VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI

  • VUID-VkSubpassDescription2-colorAttachmentCount-03063
    colorAttachmentCount must be less than or equal to VkPhysicalDeviceLimits::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 loadOp must not be VK_ATTACHMENT_LOAD_OP_CLEAR

  • VUID-VkSubpassDescription2-pResolveAttachments-03065
    If pResolveAttachments is not NULL, for each resolve attachment that does not have the value VK_ATTACHMENT_UNUSED, the corresponding color attachment must not have the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-pResolveAttachments-03066
    If pResolveAttachments is not NULL, for each resolve attachment that is not VK_ATTACHMENT_UNUSED, the corresponding color attachment must not have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescription2-pResolveAttachments-03067
    If pResolveAttachments is not NULL, each resolve attachment that is not VK_ATTACHMENT_UNUSED must have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescription2-pResolveAttachments-03068
    Each element of pResolveAttachments must have the same VkFormat as its corresponding color attachment

  • VUID-VkSubpassDescription2-multisampledRenderToSingleSampled-06869
    If none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are enabled, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have the same sample count

  • VUID-VkSubpassDescription2-pInputAttachments-02897
    All attachments in pInputAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain at least VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescription2-pColorAttachments-02898
    All attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkSubpassDescription2-pResolveAttachments-02899
    All attachments in pResolveAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkSubpassDescription2-pDepthStencilAttachment-02900
    If pDepthStencilAttachment is not NULL and the attachment is not VK_ATTACHMENT_UNUSED then it must have an image format whose potential format features contain VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescription2-linearColorAttachment-06499
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pInputAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription2-linearColorAttachment-06500
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription2-linearColorAttachment-06501
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, all attachments in pResolveAttachments that are not VK_ATTACHMENT_UNUSED must have image formats whose potential format features must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkSubpassDescription2-pColorAttachments-03070
    If the VK_AMD_mixed_attachment_samples extension is enabled, all attachments in pColorAttachments that are not VK_ATTACHMENT_UNUSED must have a sample count that is smaller than or equal to the sample count of pDepthStencilAttachment if it is not VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-pNext-06870
    If the pNext chain includes a VkMultisampledRenderToSingleSampledInfoEXT structure with multisampledRenderToSingleSampledEnable equal to VK_TRUE, then all attachments in pColorAttachments and pDepthStencilAttachment that are not VK_ATTACHMENT_UNUSED must have a sample count that is either VK_SAMPLE_COUNT_1_BIT or equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

  • VUID-VkSubpassDescription2-pNext-06871
    If the pNext chain includes a VkMultisampledRenderToSingleSampledInfoEXT structure with multisampledRenderToSingleSampledEnable equal to VK_TRUE, and pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a sample count of VK_SAMPLE_COUNT_1_BIT, the pNext chain must also include a VkSubpassDescriptionDepthStencilResolve structure with pDepthStencilResolveAttachment that is either NULL or has the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-multisampledRenderToSingleSampled-06872
    If none of the VK_AMD_mixed_attachment_samples extension, the VK_NV_framebuffer_mixed_samples extension, or the multisampledRenderToSingleSampled feature are enabled, all attachments in pDepthStencilAttachment or pColorAttachments that are not VK_ATTACHMENT_UNUSED must have the same sample count

  • VUID-VkSubpassDescription2-attachment-03073
    Each element of pPreserveAttachments must not be VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescription2-pPreserveAttachments-03074
    Each element of 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 VkAttachmentReference2 member, then each use must use the same layout

  • VUID-VkSubpassDescription2-flags-03076
    If flags includes VK_SUBPASS_DESCRIPTION_PER_VIEW_POSITION_X_ONLY_BIT_NVX, it must also include VK_SUBPASS_DESCRIPTION_PER_VIEW_ATTRIBUTES_BIT_NVX

  • VUID-VkSubpassDescription2-attachment-02799
    If the attachment member of any element of pInputAttachments is not VK_ATTACHMENT_UNUSED, then the aspectMask member must be a valid combination of VkImageAspectFlagBits

  • VUID-VkSubpassDescription2-attachment-02800
    If the attachment member of any element of pInputAttachments is not VK_ATTACHMENT_UNUSED, then the aspectMask member must not be 0

  • VUID-VkSubpassDescription2-attachment-02801
    If the attachment member of any element of pInputAttachments is not VK_ATTACHMENT_UNUSED, then the aspectMask member must not include VK_IMAGE_ASPECT_METADATA_BIT

  • VUID-VkSubpassDescription2-attachment-04563
    If the attachment member of any element of pInputAttachments is not VK_ATTACHMENT_UNUSED, then the aspectMask member must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i

  • VUID-VkSubpassDescription2-pDepthStencilAttachment-04440
    An attachment must not be used in both pDepthStencilAttachment and pColorAttachments

  • VUID-VkSubpassDescription2-multiview-06558
    If the multiview feature is not enabled, viewMask must be 0

  • VUID-VkSubpassDescription2-viewMask-06706
    The index of the most significant bit in viewMask must be less than maxMultiviewViewCount

Valid Usage (Implicit)
  • VUID-VkSubpassDescription2-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2

  • VUID-VkSubpassDescription2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkFragmentShadingRateAttachmentInfoKHR, VkMultisampledRenderToSingleSampledInfoEXT, VkRenderPassCreationControlEXT, VkRenderPassSubpassFeedbackCreateInfoEXT, or VkSubpassDescriptionDepthStencilResolve

  • VUID-VkSubpassDescription2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSubpassDescription2-flags-parameter
    flags must be a valid combination of VkSubpassDescriptionFlagBits values

  • VUID-VkSubpassDescription2-pipelineBindPoint-parameter
    pipelineBindPoint must be a valid VkPipelineBindPoint value

  • VUID-VkSubpassDescription2-pInputAttachments-parameter
    If inputAttachmentCount is not 0, pInputAttachments must be a valid pointer to an array of inputAttachmentCount valid VkAttachmentReference2 structures

  • VUID-VkSubpassDescription2-pColorAttachments-parameter
    If colorAttachmentCount is not 0, pColorAttachments must be a valid pointer to an array of colorAttachmentCount valid VkAttachmentReference2 structures

  • VUID-VkSubpassDescription2-pResolveAttachments-parameter
    If colorAttachmentCount is not 0, and pResolveAttachments is not NULL, pResolveAttachments must be a valid pointer to an array of colorAttachmentCount valid VkAttachmentReference2 structures

  • VUID-VkSubpassDescription2-pDepthStencilAttachment-parameter
    If pDepthStencilAttachment is not NULL, pDepthStencilAttachment must be a valid pointer to a valid VkAttachmentReference2 structure

  • VUID-VkSubpassDescription2-pPreserveAttachments-parameter
    If preserveAttachmentCount is not 0, pPreserveAttachments must be a valid pointer to an array of preserveAttachmentCount uint32_t values

The VkSubpassDescriptionDepthStencilResolve structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassDescriptionDepthStencilResolve {
    VkStructureType                  sType;
    const void*                      pNext;
    VkResolveModeFlagBits            depthResolveMode;
    VkResolveModeFlagBits            stencilResolveMode;
    const VkAttachmentReference2*    pDepthStencilResolveAttachment;
} VkSubpassDescriptionDepthStencilResolve;

or the equivalent

// Provided by VK_KHR_depth_stencil_resolve
typedef VkSubpassDescriptionDepthStencilResolve VkSubpassDescriptionDepthStencilResolveKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • depthResolveMode is a VkResolveModeFlagBits value describing the depth resolve mode.

  • stencilResolveMode is a VkResolveModeFlagBits value describing the stencil resolve mode.

  • pDepthStencilResolveAttachment is NULL or a pointer to a VkAttachmentReference2 structure defining the depth/stencil resolve attachment for this subpass and its layout.

If the pNext chain of VkSubpassDescription2 includes a VkSubpassDescriptionDepthStencilResolve structure, then that structure describes multisample resolve operations for the depth/stencil attachment in a subpass. If this structure is not included in the pNext chain of VkSubpassDescription2, or if it is and either pDepthStencilResolveAttachment is NULL or its attachment index is VK_ATTACHMENT_UNUSED, it indicates that no depth/stencil resolve attachment will be used in the subpass.

Valid Usage
  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03177
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, pDepthStencilAttachment must not be NULL or have the value VK_ATTACHMENT_UNUSED

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03179
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, pDepthStencilAttachment must not have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03180
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, pDepthStencilResolveAttachment must have a sample count of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-02651
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED then it must have an image format whose potential format features contain VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03181
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED and VkFormat of pDepthStencilResolveAttachment has a depth component, then the VkFormat of pDepthStencilAttachment must have a depth component with the same number of bits and numeric format

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03182
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, and VkFormat of pDepthStencilResolveAttachment has a stencil component, then the VkFormat of pDepthStencilAttachment must have a stencil component with the same number of bits and numeric format

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03178
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, depthResolveMode and stencilResolveMode must not both be VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-depthResolveMode-03183
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED and the VkFormat of pDepthStencilResolveAttachment has a depth component, then the value of depthResolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedDepthResolveModes or VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-stencilResolveMode-03184
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED and the VkFormat of pDepthStencilResolveAttachment has a stencil component, then the value of stencilResolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedStencilResolveModes or VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03185
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, the VkFormat of pDepthStencilResolveAttachment has both depth and stencil components, VkPhysicalDeviceDepthStencilResolveProperties::independentResolve is VK_FALSE, and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone is VK_FALSE, then the values of depthResolveMode and stencilResolveMode must be identical

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-03186
    If pDepthStencilResolveAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, the VkFormat of pDepthStencilResolveAttachment has both depth and stencil components, VkPhysicalDeviceDepthStencilResolveProperties::independentResolve is VK_FALSE and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone is VK_TRUE, then the values of depthResolveMode and stencilResolveMode must be identical or one of them must be VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06873
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure, the multisampledRenderToSingleSampledEnable field is VK_TRUE, and pDepthStencilAttachment is not NULL and does not have the value VK_ATTACHMENT_UNUSED, depthResolveMode and stencilResolveMode must not both be VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06874
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, and pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a VkFormat that has a depth component, then the value of depthResolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedDepthResolveModes or VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06875
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, and pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a VkFormat with a stencil component, then the value of stencilResolveMode must be one of the bits set in VkPhysicalDeviceDepthStencilResolveProperties::supportedStencilResolveModes or VK_RESOLVE_MODE_NONE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06876
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a VkFormat with both depth and stencil components, and both VkPhysicalDeviceDepthStencilResolveProperties::independentResolve and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone are VK_FALSE, then the values of depthResolveMode and stencilResolveMode must be identical

  • VUID-VkSubpassDescriptionDepthStencilResolve-pNext-06877
    If the pNext chain of VkSubpassDescription2 includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, pDepthStencilAttachment is not NULL, does not have the value VK_ATTACHMENT_UNUSED, and has a VkFormat with both depth and stencil components, VkPhysicalDeviceDepthStencilResolveProperties::independentResolve is VK_FALSE, and VkPhysicalDeviceDepthStencilResolveProperties::independentResolveNone is VK_TRUE, then the values of depthResolveMode and stencilResolveMode must be identical or one of them must be VK_RESOLVE_MODE_NONE

Valid Usage (Implicit)
  • VUID-VkSubpassDescriptionDepthStencilResolve-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_DEPTH_STENCIL_RESOLVE

  • VUID-VkSubpassDescriptionDepthStencilResolve-pDepthStencilResolveAttachment-parameter
    If pDepthStencilResolveAttachment is not NULL, pDepthStencilResolveAttachment must be a valid pointer to a valid VkAttachmentReference2 structure

The VkFragmentShadingRateAttachmentInfoKHR structure is defined as:

// Provided by VK_KHR_fragment_shading_rate
typedef struct VkFragmentShadingRateAttachmentInfoKHR {
    VkStructureType                  sType;
    const void*                      pNext;
    const VkAttachmentReference2*    pFragmentShadingRateAttachment;
    VkExtent2D                       shadingRateAttachmentTexelSize;
} VkFragmentShadingRateAttachmentInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pFragmentShadingRateAttachment is NULL or a pointer to a VkAttachmentReference2 structure defining the fragment shading rate attachment for this subpass.

  • shadingRateAttachmentTexelSize specifies the size of the portion of the framebuffer corresponding to each texel in 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 pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, its layout member must be equal to VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04525
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be a power of two value

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04526
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.width

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04527
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.width must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.width

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04528
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be a power of two value

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04529
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSize.height

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04530
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, shadingRateAttachmentTexelSize.height must be greater than or equal to minFragmentShadingRateAttachmentTexelSize.height

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04531
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, the quotient of shadingRateAttachmentTexelSize.width and shadingRateAttachmentTexelSize.height must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-04532
    If pFragmentShadingRateAttachment is not NULL and its attachment member is not VK_ATTACHMENT_UNUSED, the quotient of shadingRateAttachmentTexelSize.height and shadingRateAttachmentTexelSize.width must be less than or equal to maxFragmentShadingRateAttachmentTexelSizeAspectRatio

Valid Usage (Implicit)
  • VUID-VkFragmentShadingRateAttachmentInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR

  • VUID-VkFragmentShadingRateAttachmentInfoKHR-pFragmentShadingRateAttachment-parameter
    If pFragmentShadingRateAttachment is not NULL, pFragmentShadingRateAttachment must be a valid pointer to a valid VkAttachmentReference2 structure

If the pNext chain of VkSubpassDescription2 or VkRenderingInfo includes a VkMultisampledRenderToSingleSampledInfoEXT structure, then that structure describes how multisampled rendering is performed on single sampled attachments in that subpass.

The VkMultisampledRenderToSingleSampledInfoEXT structure is defined as:

// Provided by VK_EXT_multisampled_render_to_single_sampled
typedef struct VkMultisampledRenderToSingleSampledInfoEXT {
    VkStructureType          sType;
    const void*              pNext;
    VkBool32                 multisampledRenderToSingleSampledEnable;
    VkSampleCountFlagBits    rasterizationSamples;
} VkMultisampledRenderToSingleSampledInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • multisampledRenderToSingleSampledEnable controls whether multisampled rendering to single-sampled attachments is performed as described below.

  • rasterizationSamples is a VkSampleCountFlagBits specifying the number of samples used in rasterization.

Valid Usage
  • VUID-VkMultisampledRenderToSingleSampledInfoEXT-rasterizationSamples-06878
    The value of rasterizationSamples must not be VK_SAMPLE_COUNT_1_BIT

  • VUID-VkMultisampledRenderToSingleSampledInfoEXT-pNext-06880
    If added to the pNext chain of VkRenderingInfo, each imageView member of any element of VkRenderingInfo::pColorAttachments, VkRenderingInfo::pDepthAttachment, or VkRenderingInfo::pStencilAttachment that is not VK_NULL_HANDLE must have a format that supports the sample count specified in rasterizationSamples

Valid Usage (Implicit)
  • VUID-VkMultisampledRenderToSingleSampledInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_INFO_EXT

  • VUID-VkMultisampledRenderToSingleSampledInfoEXT-rasterizationSamples-parameter
    rasterizationSamples must be a valid VkSampleCountFlagBits value

If the pNext chain of VkSubpassDescription2 or VkRenderingInfo includes a VkMultisampledRenderToSingleSampledInfoEXT structure whose multisampledRenderToSingleSampledEnable field is VK_TRUE, the graphics pipelines must have VkGraphicsPipelineCreateInfo::rasterizationSamples equal to VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples, and the subpass attachments can have a sample count of VK_SAMPLE_COUNT_1_BIT. For attachments with a sample count of VK_SAMPLE_COUNT_1_BIT, multisampled rendering is performed to an intermediate multisampled image with VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples samples, implicitly allocated by the implementation for the duration of the subpass. For such attachments:

  • If loadOp equals to VK_ATTACHMENT_LOAD_OP_LOAD, samples of the implicit image are initialized by replicating the value from the corresponding pixel in the attachment.

  • If storeOp or stencilStoreOp is equal to VK_ATTACHMENT_STORE_OP_STORE, the implicit image is implicitly resolved prior to storage in the attachment.

Memory constraints due to high primitive counts may result in an implicit split of the subpass. This is the equivalent of partial rasterization of geometry in a render pass that ends in storeOp and stencilStoreOp equal to VK_ATTACHMENT_STORE_OP_STORE, followed by another render pass with loadOp and stencilLoadOp equal to VK_ATTACHMENT_LOAD_OP_LOAD with appropriate barriers in between. When VkMultisampledRenderToSingleSampledInfoEXT is used, the implementation is allowed to resolve attachments with a sample count of VK_SAMPLE_COUNT_1_BIT and lose multisampled data on such splits. The implementation may similarly split the render pass at subpass boundaries even if they use the same value for VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples.

The VkAttachmentReference2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkAttachmentReference2 {
    VkStructureType       sType;
    const void*           pNext;
    uint32_t              attachment;
    VkImageLayout         layout;
    VkImageAspectFlags    aspectMask;
} VkAttachmentReference2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkAttachmentReference2 VkAttachmentReference2KHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • attachment is either an integer value identifying an attachment at the corresponding index in VkRenderPassCreateInfo2::pAttachments, or VK_ATTACHMENT_UNUSED to signify that this attachment is not used.

  • layout is a VkImageLayout value specifying the layout the attachment uses during the subpass.

  • 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 VkAttachmentReference have the identical effect to those parameters.

aspectMask is ignored when this structure is used to describe anything other than an input attachment reference.

If the separateDepthStencilLayouts feature is enabled, and attachment has a depth/stencil format, layout can be set to a layout that only specifies the layout of the depth aspect.

If layout only specifies the layout of the depth aspect of the attachment, the layout of the stencil aspect is specified by the stencilLayout member of a VkAttachmentReferenceStencilLayout structure included in the pNext chain. Otherwise, layout describes the layout for all relevant image aspects.

Valid Usage
  • VUID-VkAttachmentReference2-layout-03077
    If attachment is not VK_ATTACHMENT_UNUSED, layout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_PREINITIALIZED, or VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

  • VUID-VkAttachmentReference2-separateDepthStencilLayouts-03313
    If the separateDepthStencilLayouts feature is not enabled, and attachment is not VK_ATTACHMENT_UNUSED, layout must not be VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,

  • VUID-VkAttachmentReference2-synchronization2-06910
    If the synchronization2 feature is not enabled, layout must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

  • VUID-VkAttachmentReference2-attachmentFeedbackLoopLayout-07311
    If the attachmentFeedbackLoopLayout feature is not enabled, layout must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

Valid Usage (Implicit)
  • VUID-VkAttachmentReference2-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2

  • VUID-VkAttachmentReference2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkAttachmentReferenceStencilLayout

  • VUID-VkAttachmentReference2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkAttachmentReference2-layout-parameter
    layout must be a valid VkImageLayout value

The VkAttachmentReferenceStencilLayout structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkAttachmentReferenceStencilLayout {
    VkStructureType    sType;
    void*              pNext;
    VkImageLayout      stencilLayout;
} VkAttachmentReferenceStencilLayout;

or the equivalent

// Provided by VK_KHR_separate_depth_stencil_layouts
typedef VkAttachmentReferenceStencilLayout VkAttachmentReferenceStencilLayoutKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stencilLayout is a VkImageLayout value specifying the layout the stencil aspect of the attachment uses during the subpass.

Valid Usage
  • VUID-VkAttachmentReferenceStencilLayout-stencilLayout-03318
    stencilLayout must not be VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_PREINITIALIZED, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

Valid Usage (Implicit)
  • VUID-VkAttachmentReferenceStencilLayout-sType-sType
    sType must be VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_STENCIL_LAYOUT

  • VUID-VkAttachmentReferenceStencilLayout-stencilLayout-parameter
    stencilLayout must be a valid VkImageLayout value

The VkSubpassDependency2 structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassDependency2 {
    VkStructureType         sType;
    const void*             pNext;
    uint32_t                srcSubpass;
    uint32_t                dstSubpass;
    VkPipelineStageFlags    srcStageMask;
    VkPipelineStageFlags    dstStageMask;
    VkAccessFlags           srcAccessMask;
    VkAccessFlags           dstAccessMask;
    VkDependencyFlags       dependencyFlags;
    int32_t                 viewOffset;
} VkSubpassDependency2;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkSubpassDependency2 VkSubpassDependency2KHR;

Parameters defined by this structure with the same name as those in VkSubpassDependency have the identical effect to those parameters.

viewOffset has the same effect for the described subpass dependency as VkRenderPassMultiviewCreateInfo::pViewOffsets has on each corresponding subpass dependency.

If a VkMemoryBarrier2 is included in the pNext chain, srcStageMask, dstStageMask, srcAccessMask, and dstAccessMask parameters are ignored. The synchronization and access scopes instead are defined by the parameters of VkMemoryBarrier2.

Valid Usage
  • VUID-VkSubpassDependency2-srcStageMask-04090
    If the geometryShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubpassDependency2-srcStageMask-04091
    If the tessellationShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubpassDependency2-srcStageMask-04092
    If the conditionalRendering feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-04093
    If the fragmentDensityMap feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-04094
    If the transformFeedback feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-04095
    If the meshShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-04096
    If the taskShader feature is not enabled, srcStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubpassDependency2-srcStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubpassDependency2-srcStageMask-03937
    If the synchronization2 feature is not enabled, srcStageMask must not be 0

  • VUID-VkSubpassDependency2-srcStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, srcStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubpassDependency2-dstStageMask-04090
    If the geometryShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-VkSubpassDependency2-dstStageMask-04091
    If the tessellationShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-VkSubpassDependency2-dstStageMask-04092
    If the conditionalRendering feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-04093
    If the fragmentDensityMap feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-04094
    If the transformFeedback feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-04095
    If the meshShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-04096
    If the taskShader feature is not enabled, dstStageMask must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-VkSubpassDependency2-dstStageMask-07318
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkSubpassDependency2-dstStageMask-03937
    If the synchronization2 feature is not enabled, dstStageMask must not be 0

  • VUID-VkSubpassDependency2-dstStageMask-07949
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, dstStageMask must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-VkSubpassDependency2-srcSubpass-03084
    srcSubpass must be less than or equal to dstSubpass, unless one of them is VK_SUBPASS_EXTERNAL, to avoid cyclic dependencies and ensure a valid execution order

  • VUID-VkSubpassDependency2-srcSubpass-03085
    srcSubpass and dstSubpass must not both be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency2-srcSubpass-06810
    If srcSubpass is equal to dstSubpass and srcStageMask includes a framebuffer-space stage, dstStageMask must only contain framebuffer-space stages

  • VUID-VkSubpassDependency2-srcAccessMask-03088
    Any access flag included in srcAccessMask must be supported by one of the pipeline stages in srcStageMask, as specified in the table of supported access types

  • VUID-VkSubpassDependency2-dstAccessMask-03089
    Any access flag included in dstAccessMask must be supported by one of the pipeline stages in dstStageMask, as specified in the table of supported access types

  • VUID-VkSubpassDependency2-dependencyFlags-03090
    If dependencyFlags includes VK_DEPENDENCY_VIEW_LOCAL_BIT, srcSubpass must not be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency2-dependencyFlags-03091
    If dependencyFlags includes VK_DEPENDENCY_VIEW_LOCAL_BIT, dstSubpass must not be equal to VK_SUBPASS_EXTERNAL

  • VUID-VkSubpassDependency2-srcSubpass-02245
    If srcSubpass equals dstSubpass, and srcStageMask and dstStageMask both include a framebuffer-space stage, then dependencyFlags must include VK_DEPENDENCY_BY_REGION_BIT

  • VUID-VkSubpassDependency2-viewOffset-02530
    If viewOffset is not equal to 0, srcSubpass must not be equal to dstSubpass

  • VUID-VkSubpassDependency2-dependencyFlags-03092
    If dependencyFlags does not include VK_DEPENDENCY_VIEW_LOCAL_BIT, viewOffset must be 0

Valid Usage (Implicit)
  • VUID-VkSubpassDependency2-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_DEPENDENCY_2

  • VUID-VkSubpassDependency2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkMemoryBarrier2

  • VUID-VkSubpassDependency2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSubpassDependency2-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-VkSubpassDependency2-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits values

  • VUID-VkSubpassDependency2-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkSubpassDependency2-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits values

  • VUID-VkSubpassDependency2-dependencyFlags-parameter
    dependencyFlags must be a valid combination of VkDependencyFlagBits values

To destroy a render pass, call:

// Provided by VK_VERSION_1_0
void vkDestroyRenderPass(
    VkDevice                                    device,
    VkRenderPass                                renderPass,
    const VkAllocationCallbacks*                pAllocator);
  • device is the logical device that destroys the render pass.

  • renderPass is the handle of the render pass to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage
  • VUID-vkDestroyRenderPass-renderPass-00873
    All submitted commands that refer to renderPass must have completed execution

  • VUID-vkDestroyRenderPass-renderPass-00874
    If VkAllocationCallbacks were provided when renderPass was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyRenderPass-renderPass-00875
    If no VkAllocationCallbacks were provided when renderPass was created, pAllocator must be NULL

Valid Usage (Implicit)
  • VUID-vkDestroyRenderPass-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyRenderPass-renderPass-parameter
    If renderPass is not VK_NULL_HANDLE, renderPass must be a valid VkRenderPass handle

  • VUID-vkDestroyRenderPass-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyRenderPass-renderPass-parent
    If renderPass is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to renderPass must be externally synchronized

8.3. 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 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 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 and depth/stencil resolve mode 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.

8.4. Framebuffers

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 VkFramebuffer handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkFramebuffer)

To create a framebuffer, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateFramebuffer(
    VkDevice                                    device,
    const VkFramebufferCreateInfo*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkFramebuffer*                              pFramebuffer);
  • device is the logical device that creates the framebuffer.

  • pCreateInfo is a pointer to a VkFramebufferCreateInfo structure describing additional information about framebuffer creation.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pFramebuffer is a pointer to a VkFramebuffer handle in which the resulting framebuffer object is returned.

Valid Usage
  • VUID-vkCreateFramebuffer-pCreateInfo-02777
    If pCreateInfo->flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and attachmentCount is not 0, each element of pCreateInfo->pAttachments must have been created on device

Valid Usage (Implicit)
  • VUID-vkCreateFramebuffer-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateFramebuffer-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkFramebufferCreateInfo structure

  • VUID-vkCreateFramebuffer-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateFramebuffer-pFramebuffer-parameter
    pFramebuffer must be a valid pointer to a VkFramebuffer handle

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkFramebufferCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkFramebufferCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkFramebufferCreateFlags    flags;
    VkRenderPass                renderPass;
    uint32_t                    attachmentCount;
    const VkImageView*          pAttachments;
    uint32_t                    width;
    uint32_t                    height;
    uint32_t                    layers;
} VkFramebufferCreateInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkFramebufferCreateFlagBits

  • renderPass is a render pass defining what render passes the framebuffer will be compatible with. See Render Pass Compatibility for details.

  • attachmentCount is the number of attachments.

  • pAttachments is a pointer to an array of VkImageView handles, each of which will be used as the corresponding attachment in a render pass instance. If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, this parameter is ignored.

  • width, height and layers define the dimensions of the framebuffer. If the render pass uses multiview, then 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.

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 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 width, height, and layers of the framebuffer to define the dimensions of the rendering area, and the rasterizationSamples from each pipeline’s VkPipelineMultisampleStateCreateInfo to define the number of samples used in rasterization; however, if VkPhysicalDeviceFeatures::variableMultisampleRate is VK_FALSE, then all pipelines to be bound with the subpass must have the same value for VkPipelineMultisampleStateCreateInfo::rasterizationSamples. In all such cases, rasterizationSamples must be a bit value that is set in VkPhysicalDeviceLimits::framebufferNoAttachmentsSampleCounts.

Valid Usage
  • VUID-VkFramebufferCreateInfo-attachmentCount-00876
    attachmentCount must be equal to the attachment count specified in renderPass

  • VUID-VkFramebufferCreateInfo-flags-02778
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT and attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkImageView handles

  • VUID-VkFramebufferCreateInfo-pAttachments-00877
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as a color attachment or resolve attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-pAttachments-02633
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as a depth/stencil attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-pAttachments-02634
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as a depth/stencil resolve attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-pAttachments-00879
    If renderpass is not VK_NULL_HANDLE, flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as an input attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-pAttachments-02552
    Each element of pAttachments that is used as a fragment density map attachment by renderPass must not have been created with a flags value including VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkFramebufferCreateInfo-renderPass-02553
    If renderPass has a fragment density map attachment and the fragmentDensityMapNonSubsampledImages feature is not enabled, each element of pAttachments must have been created with a flags value including VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT unless that element is the fragment density map attachment

  • VUID-VkFramebufferCreateInfo-renderPass-06502
    If renderPass was created with fragment density map offsets other than (0,0), each element of pAttachments must have been created with a flags value including VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM

  • VUID-VkFramebufferCreateInfo-pAttachments-00880
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must have been created with a VkFormat value that matches the VkFormat specified by the corresponding VkAttachmentDescription in renderPass

  • VUID-VkFramebufferCreateInfo-pAttachments-00881
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must have been created with a samples value that matches the samples value specified by the corresponding VkAttachmentDescription in renderPass

  • VUID-VkFramebufferCreateInfo-flags-04533
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as an input, color, resolve, or depth/stencil attachment by renderPass must have been created with a VkImageCreateInfo::extent.width greater than or equal to width

  • VUID-VkFramebufferCreateInfo-flags-04534
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as an input, color, resolve, or depth/stencil attachment by renderPass must have been created with a VkImageCreateInfo::extent.height greater than or equal to height

  • VUID-VkFramebufferCreateInfo-flags-04535
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as an input, color, resolve, or depth/stencil attachment by renderPass must have been created with a VkImageViewCreateInfo::subresourceRange.layerCount greater than or equal to layers

  • VUID-VkFramebufferCreateInfo-renderPass-04536
    If renderPass was specified with non-zero view masks, each element of pAttachments that is used as an input, color, resolve, or depth/stencil attachment by renderPass must have a layerCount greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-renderPass-02746
    If renderPass was specified with non-zero view masks, each element of pAttachments that is referenced by fragmentDensityMapAttachment must have a 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 renderPass was specified with all view masks equal to zero, each element of pAttachments that is referenced by fragmentDensityMapAttachment must have a layerCount equal to 1

  • VUID-VkFramebufferCreateInfo-pAttachments-02555
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pAttachments that is referenced by fragmentDensityMapAttachment must have a width at least as large as

  • VUID-VkFramebufferCreateInfo-pAttachments-02556
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pAttachments that is referenced by fragmentDensityMapAttachment must have a height at least as large as

  • VUID-VkFramebufferCreateInfo-flags-04537
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and renderPass was specified with non-zero view masks, each element of pAttachments that is used as a fragment shading rate attachment by renderPass must have a 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 flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and renderPass was not specified with non-zero view masks, each element of pAttachments that is used as a fragment shading rate attachment by renderPass must have a layerCount that is either 1, or greater than layers

  • VUID-VkFramebufferCreateInfo-renderPass-08921
    If renderPass was specified with non-zero view masks, each element of pAttachments that is used as a fragment shading rate attachment must have a layerCount equal to 1 or greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-flags-04539
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pAttachments that is used as a fragment shading rate attachment must have a width at least as large as width / texelWidth, where texelWidth is the largest value of shadingRateAttachmentTexelSize.width in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

  • VUID-VkFramebufferCreateInfo-flags-04540
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, an element of pAttachments that is used as a fragment shading rate attachment must have a height at least as large as height / texelHeight, where texelHeight is the largest value of shadingRateAttachmentTexelSize.height in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

  • VUID-VkFramebufferCreateInfo-pAttachments-00883
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must only specify a single mip level

  • VUID-VkFramebufferCreateInfo-pAttachments-00884
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must have been created with the identity swizzle

  • VUID-VkFramebufferCreateInfo-width-00885
    width must be greater than 0

  • VUID-VkFramebufferCreateInfo-width-00886
    width must be less than or equal to maxFramebufferWidth

  • VUID-VkFramebufferCreateInfo-height-00887
    height must be greater than 0

  • VUID-VkFramebufferCreateInfo-height-00888
    height must be less than or equal to maxFramebufferHeight

  • VUID-VkFramebufferCreateInfo-layers-00889
    layers must be greater than 0

  • VUID-VkFramebufferCreateInfo-layers-00890
    layers must be less than or equal to maxFramebufferLayers

  • VUID-VkFramebufferCreateInfo-renderPass-02531
    If renderPass was specified with non-zero view masks, layers must be 1

  • VUID-VkFramebufferCreateInfo-pAttachments-00891
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is a 2D or 2D array image view taken from a 3D image must not be a depth/stencil format

  • VUID-VkFramebufferCreateInfo-flags-03189
    If the imagelessFramebuffer feature is not enabled, flags must not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT

  • VUID-VkFramebufferCreateInfo-flags-03190
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the pNext chain must include a VkFramebufferAttachmentsCreateInfo structure

  • VUID-VkFramebufferCreateInfo-flags-03191
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the attachmentImageInfoCount member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain must be equal to either zero or attachmentCount

  • VUID-VkFramebufferCreateInfo-flags-04541
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the width member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as an input, color, resolve or depth/stencil attachment in renderPass must be greater than or equal to width

  • VUID-VkFramebufferCreateInfo-flags-04542
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the height member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as an input, color, resolve or depth/stencil attachment in renderPass must be greater than or equal to height

  • VUID-VkFramebufferCreateInfo-flags-03196
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the width member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment in renderPass must be greater than or equal to

  • VUID-VkFramebufferCreateInfo-flags-03197
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the height member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment in renderPass must be greater than or equal to

  • VUID-VkFramebufferCreateInfo-flags-04543
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the width member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as a fragment shading rate attachment must be greater than or equal to width / texelWidth, where texelWidth is the largest value of shadingRateAttachmentTexelSize.width in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

  • VUID-VkFramebufferCreateInfo-flags-04544
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the height member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as a fragment shading rate attachment must be greater than or equal to height / texelHeight, where texelHeight is the largest value of shadingRateAttachmentTexelSize.height in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

  • VUID-VkFramebufferCreateInfo-flags-04545
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the layerCount member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure in the pNext chain that is used as a fragment shading rate attachment must be either 1, or greater than or equal to layers

  • VUID-VkFramebufferCreateInfo-flags-04587
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT and renderPass was specified with non-zero view masks, each element of pAttachments that is used as a fragment shading rate attachment by renderPass must have a layerCount that is either 1, or greater than the index of the most significant bit set in any of those view masks

  • VUID-VkFramebufferCreateInfo-renderPass-03198
    If multiview is enabled for renderPass and flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the layerCount member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain used as an input, color, resolve, or depth/stencil attachment in renderPass must be greater than the maximum bit index set in the view mask in the subpasses in which it is used in renderPass

  • VUID-VkFramebufferCreateInfo-renderPass-04546
    If multiview is not enabled for renderPass and flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the layerCount member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain used as an input, color, resolve, or depth/stencil attachment in renderPass must be greater than or equal to layers

  • VUID-VkFramebufferCreateInfo-flags-03201
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as a color attachment or resolve attachment by renderPass must include VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-flags-03202
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as a depth/stencil attachment by renderPass must include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-flags-03203
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as a depth/stencil resolve attachment by renderPass must include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-flags-03204
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as an input attachment by renderPass must include VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-VkFramebufferCreateInfo-flags-03205
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, at least one element of the pViewFormats member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain must be equal to the corresponding value of VkAttachmentDescription::format used to create renderPass

  • VUID-VkFramebufferCreateInfo-flags-04113
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments must have been created with VkImageViewCreateInfo::viewType not equal to VK_IMAGE_VIEW_TYPE_3D

  • VUID-VkFramebufferCreateInfo-flags-04548
    If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of pAttachments that is used as a fragment shading rate attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkFramebufferCreateInfo-flags-04549
    If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, the usage member of any element of the pAttachmentImageInfos member of a VkFramebufferAttachmentsCreateInfo structure included in the pNext chain that refers to an attachment used as a fragment shading rate attachment by renderPass must include VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-VkFramebufferCreateInfo-samples-06881
    If multisampled-render-to-single-sampled is enabled for any subpass, all color, depth/stencil and input attachments used in that subpass which have VkAttachmentDescription::samples or VkAttachmentDescription2::samples equal to VK_SAMPLE_COUNT_1_BIT must have been created with VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT in their VkImageCreateInfo::flags

  • VUID-VkFramebufferCreateInfo-samples-07009
    If multisampled-render-to-single-sampled is enabled for any subpass, all color, depth/stencil and input attachments used in that subpass which have VkAttachmentDescription::samples or VkAttachmentDescription2::samples equal to VK_SAMPLE_COUNT_1_BIT must have a format that supports the sample count specified in VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

Valid Usage (Implicit)
  • VUID-VkFramebufferCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO

  • VUID-VkFramebufferCreateInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkFramebufferAttachmentsCreateInfo

  • VUID-VkFramebufferCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkFramebufferCreateInfo-flags-parameter
    flags must be a valid combination of VkFramebufferCreateFlagBits values

  • VUID-VkFramebufferCreateInfo-renderPass-parameter
    renderPass must be a valid VkRenderPass handle

  • VUID-VkFramebufferCreateInfo-commonparent
    Both of renderPass, and the elements of pAttachments that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkFramebufferAttachmentsCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkFramebufferAttachmentsCreateInfo {
    VkStructureType                            sType;
    const void*                                pNext;
    uint32_t                                   attachmentImageInfoCount;
    const VkFramebufferAttachmentImageInfo*    pAttachmentImageInfos;
} VkFramebufferAttachmentsCreateInfo;

or the equivalent

// Provided by VK_KHR_imageless_framebuffer
typedef VkFramebufferAttachmentsCreateInfo VkFramebufferAttachmentsCreateInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • attachmentImageInfoCount is the number of attachments being described.

  • pAttachmentImageInfos is a pointer to an array of VkFramebufferAttachmentImageInfo structures, each structure describing a number of parameters of the corresponding attachment in a render pass instance.

Valid Usage (Implicit)
  • VUID-VkFramebufferAttachmentsCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENTS_CREATE_INFO

  • VUID-VkFramebufferAttachmentsCreateInfo-pAttachmentImageInfos-parameter
    If attachmentImageInfoCount is not 0, pAttachmentImageInfos must be a valid pointer to an array of attachmentImageInfoCount valid VkFramebufferAttachmentImageInfo structures

The VkFramebufferAttachmentImageInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkFramebufferAttachmentImageInfo {
    VkStructureType       sType;
    const void*           pNext;
    VkImageCreateFlags    flags;
    VkImageUsageFlags     usage;
    uint32_t              width;
    uint32_t              height;
    uint32_t              layerCount;
    uint32_t              viewFormatCount;
    const VkFormat*       pViewFormats;
} VkFramebufferAttachmentImageInfo;

or the equivalent

// Provided by VK_KHR_imageless_framebuffer
typedef VkFramebufferAttachmentImageInfo VkFramebufferAttachmentImageInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkImageCreateFlagBits, matching the value of VkImageCreateInfo::flags used to create an image that will be used with this framebuffer.

  • usage is a bitmask of VkImageUsageFlagBits, matching the value of VkImageCreateInfo::usage used to create an image used with this framebuffer.

  • width is the width of the image view used for rendering.

  • height is the height of the image view used for rendering.

  • layerCount is the number of array layers of the image view used for rendering.

  • viewFormatCount is the number of entries in the pViewFormats array, matching the value of VkImageFormatListCreateInfo::viewFormatCount used to create an image used with this framebuffer.

  • pViewFormats is a pointer to an array of VkFormat values specifying all of the formats which can be used when creating views of the image, matching the value of VkImageFormatListCreateInfo::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 VkRenderPassAttachmentBeginInfo, must be created with parameters that are identical to those specified here.

Valid Usage (Implicit)
  • VUID-VkFramebufferAttachmentImageInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_FRAMEBUFFER_ATTACHMENT_IMAGE_INFO

  • VUID-VkFramebufferAttachmentImageInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkFramebufferAttachmentImageInfo-flags-parameter
    flags must be a valid combination of VkImageCreateFlagBits values

  • VUID-VkFramebufferAttachmentImageInfo-usage-parameter
    usage must be a valid combination of VkImageUsageFlagBits values

  • VUID-VkFramebufferAttachmentImageInfo-usage-requiredbitmask
    usage must not be 0

  • VUID-VkFramebufferAttachmentImageInfo-pViewFormats-parameter
    If viewFormatCount is not 0, pViewFormats must be a valid pointer to an array of viewFormatCount valid VkFormat values

Bits which can be set in VkFramebufferCreateInfo::flags, specifying options for framebuffers, are:

// Provided by VK_VERSION_1_0
typedef enum VkFramebufferCreateFlagBits {
  // Provided by VK_VERSION_1_2
    VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT = 0x00000001,
  // Provided by VK_KHR_imageless_framebuffer
    VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR = VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT,
} VkFramebufferCreateFlagBits;
  • VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT specifies that image views are not specified, and only attachment compatibility information will be provided via a VkFramebufferAttachmentImageInfo structure.

// Provided by VK_VERSION_1_0
typedef VkFlags VkFramebufferCreateFlags;

VkFramebufferCreateFlags is a bitmask type for setting a mask of zero or more VkFramebufferCreateFlagBits.

To destroy a framebuffer, call:

// Provided by VK_VERSION_1_0
void vkDestroyFramebuffer(
    VkDevice                                    device,
    VkFramebuffer                               framebuffer,
    const VkAllocationCallbacks*                pAllocator);
  • device is the logical device that destroys the framebuffer.

  • framebuffer is the handle of the framebuffer to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage
  • VUID-vkDestroyFramebuffer-framebuffer-00892
    All submitted commands that refer to framebuffer must have completed execution

  • VUID-vkDestroyFramebuffer-framebuffer-00893
    If VkAllocationCallbacks were provided when framebuffer was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyFramebuffer-framebuffer-00894
    If no VkAllocationCallbacks were provided when framebuffer was created, pAllocator must be NULL

Valid Usage (Implicit)
  • VUID-vkDestroyFramebuffer-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyFramebuffer-framebuffer-parameter
    If framebuffer is not VK_NULL_HANDLE, framebuffer must be a valid VkFramebuffer handle

  • VUID-vkDestroyFramebuffer-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyFramebuffer-framebuffer-parent
    If framebuffer is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to framebuffer must be externally synchronized

8.5. Render Pass Load Operations

Render pass load operations define the initial values of an attachment during a render pass instance.

Load operations for attachments with a depth/stencil format execute in the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage. Load operations for attachments with a color format execute in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. The load operation for each sample in an attachment happens-before any recorded command which accesses the sample in that render pass instance via that attachment or an alias.

Note

Because load operations always happen first, external synchronization with attachment access only needs to synchronize the load operations with previous commands; not the operations within the render pass instance. This does not apply when using VK_ATTACHMENT_LOAD_OP_NONE_EXT.

Load operations only update values within the defined render area for the render pass instance. However, any writes performed by a load operation (as defined by its access masks) to a given attachment may read and write back any memory locations within the image subresource bound for that attachment. For depth/stencil images, writes to one aspect may also result in read-modify-write operations for the other aspect. If the subresource is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout, implementations must not access pixels outside of the render area.

Note

As entire subresources could be accessed by load operations, applications cannot safely access values outside of the render area during a render pass instance when a load operation that modifies values is used.

Load operations that can be used for a render pass are:

// Provided by VK_VERSION_1_0
typedef enum VkAttachmentLoadOp {
    VK_ATTACHMENT_LOAD_OP_LOAD = 0,
    VK_ATTACHMENT_LOAD_OP_CLEAR = 1,
    VK_ATTACHMENT_LOAD_OP_DONT_CARE = 2,
  // Provided by VK_EXT_load_store_op_none
    VK_ATTACHMENT_LOAD_OP_NONE_EXT = 1000400000,
} VkAttachmentLoadOp;
  • VK_ATTACHMENT_LOAD_OP_LOAD specifies that the previous contents of the image within the render area will be preserved as the initial values. For attachments with a depth/stencil format, this uses the access type VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_READ_BIT.

  • 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 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • 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 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • VK_ATTACHMENT_LOAD_OP_NONE_EXT specifies that the previous contents of the image will be undefined inside the render pass. No access type is used as the image is not accessed.

During a render pass instance, input and 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 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 storeOp. Conversions occur as described in Numeric Representation and Computation and Fixed-Point Data Conversions.

8.6. Render Pass Store Operations

Render pass store operations define how values written to an attachment during a render pass instance are stored to memory.

Store operations for attachments with a depth/stencil format execute in the VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage. Store operations for attachments with a color format execute in the 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 via that attachment or an alias.

Note

Because store operations always happen after other accesses in a render pass instance, external synchronization with attachment access in an earlier render pass only needs to synchronize with the store operations; not the operations within the render pass instance. This does not apply when using VK_ATTACHMENT_STORE_OP_NONE.

Store operations only update values within the defined render area for the render pass instance. However, any writes performed by a store operation (as defined by its access masks) to a given attachment may read and write back any memory locations within the image subresource bound for that attachment. For depth/stencil images writes to one aspect may also result in read-modify-write operations for the other aspect. If the subresource is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout, implementations must not access pixels outside of the render area.

Note

As entire subresources could be accessed by store operations, applications cannot safely access values outside of the render area via aliased resources during a render pass instance when a store operation that modifies values is used.

Possible values of VkAttachmentDescription::storeOp and stencilStoreOp, specifying how the contents of the attachment are treated, are:

// Provided by VK_VERSION_1_0
typedef enum VkAttachmentStoreOp {
    VK_ATTACHMENT_STORE_OP_STORE = 0,
    VK_ATTACHMENT_STORE_OP_DONT_CARE = 1,
  // Provided by VK_VERSION_1_3
    VK_ATTACHMENT_STORE_OP_NONE = 1000301000,
  // Provided by VK_KHR_dynamic_rendering
    VK_ATTACHMENT_STORE_OP_NONE_KHR = VK_ATTACHMENT_STORE_OP_NONE,
  // Provided by VK_QCOM_render_pass_store_ops
    VK_ATTACHMENT_STORE_OP_NONE_QCOM = VK_ATTACHMENT_STORE_OP_NONE,
  // Provided by VK_EXT_load_store_op_none
    VK_ATTACHMENT_STORE_OP_NONE_EXT = VK_ATTACHMENT_STORE_OP_NONE,
} VkAttachmentStoreOp;
  • 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 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • 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 VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. For attachments with a color format, this uses the access type VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.

  • VK_ATTACHMENT_STORE_OP_NONE specifies the contents within the render area are not accessed by the store operation as long as no values are written to the attachment during the render pass. If values are written during the render pass, this behaves identically to VK_ATTACHMENT_STORE_OP_DONT_CARE and with matching access semantics.

Note

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.

8.7. Render Pass Multisample Resolve Operations

Render pass multisample resolve operations combine sample values from a single pixel in a multisample attachment and store the result to the corresponding pixel in a single sample attachment.

Multisample resolve operations for attachments execute in the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. A final resolve operation for all pixels in the render area happens-after any recorded command which writes a pixel via the multisample attachment to be resolved or an explicit alias of it in the subpass that it is specified. Any single sample attachment specified for use in a multisample resolve operation may have its contents modified at any point once rendering begins for the render pass instance. Reads from the multisample attachment can be synchronized with VK_ACCESS_COLOR_ATTACHMENT_READ_BIT. Access to the single sample attachment can be synchronized with VK_ACCESS_COLOR_ATTACHMENT_READ_BIT and VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. These pipeline stage and access types are used whether the attachments are color or depth/stencil attachments.

When using render pass objects, a subpass dependency specified with the above pipeline stages and access flags will ensure synchronization with multisample resolve operations for any attachments that were last accessed by that subpass. This allows later subpasses to read resolved values as input attachments.

Resolve operations only update values within the defined render area for the render pass instance. However, any writes performed by a resolve operation (as defined by its access masks) to a given attachment may read and write back any memory locations within the image subresource bound for that attachment. For depth/stencil images writes to one aspect may also result in read-modify-write operations for the other aspect. If the subresource is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout, implementations must not access pixels outside of the render area.

Note

As entire subresources could be accessed by multisample resolve operations, applications cannot safely access values outside of the render area via aliased resources during a render pass instance when a multisample resolve operation is performed.

Multisample values in a multisample attachment are combined according to the resolve mode used:

// Provided by VK_VERSION_1_2
typedef enum VkResolveModeFlagBits {
    VK_RESOLVE_MODE_NONE = 0,
    VK_RESOLVE_MODE_SAMPLE_ZERO_BIT = 0x00000001,
    VK_RESOLVE_MODE_AVERAGE_BIT = 0x00000002,
    VK_RESOLVE_MODE_MIN_BIT = 0x00000004,
    VK_RESOLVE_MODE_MAX_BIT = 0x00000008,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_NONE_KHR = VK_RESOLVE_MODE_NONE,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_SAMPLE_ZERO_BIT_KHR = VK_RESOLVE_MODE_SAMPLE_ZERO_BIT,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_AVERAGE_BIT_KHR = VK_RESOLVE_MODE_AVERAGE_BIT,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_MIN_BIT_KHR = VK_RESOLVE_MODE_MIN_BIT,
  // Provided by VK_KHR_depth_stencil_resolve
    VK_RESOLVE_MODE_MAX_BIT_KHR = VK_RESOLVE_MODE_MAX_BIT,
} VkResolveModeFlagBits;

or the equivalent

// Provided by VK_KHR_depth_stencil_resolve
typedef VkResolveModeFlagBits VkResolveModeFlagBitsKHR;
  • VK_RESOLVE_MODE_NONE indicates that no resolve operation is done.

  • VK_RESOLVE_MODE_SAMPLE_ZERO_BIT indicates that result of the resolve operation is equal to the value of sample 0.

  • VK_RESOLVE_MODE_AVERAGE_BIT indicates that result of the resolve operation is the average of the sample values.

  • VK_RESOLVE_MODE_MIN_BIT indicates that result of the resolve operation is the minimum of the sample values.

  • VK_RESOLVE_MODE_MAX_BIT indicates that result of the resolve operation is the maximum of the sample values.

When no resolve mode is specified, VK_RESOLVE_MODE_AVERAGE_BIT is used.

// Provided by VK_VERSION_1_2
typedef VkFlags VkResolveModeFlags;

or the equivalent

// Provided by VK_KHR_depth_stencil_resolve
typedef VkResolveModeFlags VkResolveModeFlagsKHR;

VkResolveModeFlags is a bitmask type for setting a mask of zero or more VkResolveModeFlagBits.

8.8. 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.

To begin a render pass instance, call:

// Provided by VK_VERSION_1_0
void vkCmdBeginRenderPass(
    VkCommandBuffer                             commandBuffer,
    const VkRenderPassBeginInfo*                pRenderPassBegin,
    VkSubpassContents                           contents);
  • commandBuffer is the command buffer in which to record the command.

  • pRenderPassBegin is a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses.

  • contents is a 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 initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-01758
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-02842
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-stencilInitialLayout-02843
    If any of the stencilInitialLayout or stencilFinalLayout member of the VkAttachmentDescriptionStencilLayout structures or the stencilLayout member of the VkAttachmentReferenceStencilLayout structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-00897
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-00898
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_TRANSFER_SRC_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-00899
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_TRANSFER_DST_BIT

  • VUID-vkCmdBeginRenderPass-initialLayout-00900
    If the initialLayout member of any of the VkAttachmentDescription structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is not VK_IMAGE_LAYOUT_UNDEFINED, then each such initialLayout must be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the framebuffer member of pRenderPassBegin

  • VUID-vkCmdBeginRenderPass-srcStageMask-06451
    The srcStageMask members of any element of the pDependencies member of VkRenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the VkCommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from

  • VUID-vkCmdBeginRenderPass-dstStageMask-06452
    The dstStageMask members of any element of the pDependencies member of VkRenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the VkCommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from

  • VUID-vkCmdBeginRenderPass-framebuffer-02532
    For any attachment in framebuffer that is used by renderPass and is bound to memory locations that are also bound to another attachment used by renderPass, and if at least one of those uses causes either attachment to be written to, both attachments must have had the VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set

  • VUID-vkCmdBeginRenderPass-framebuffer-09045
    If any attachments specified in framebuffer are used by renderPass and are bound to overlapping memory locations, there must be only one that is used as a color attachment, depth/stencil, or resolve attachment in any subpass

  • VUID-vkCmdBeginRenderPass-initialLayout-07000
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including either the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT and either the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or VK_IMAGE_USAGE_SAMPLED_BIT usage bits

  • VUID-vkCmdBeginRenderPass-initialLayout-07001
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit

Valid Usage (Implicit)
  • VUID-vkCmdBeginRenderPass-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBeginRenderPass-pRenderPassBegin-parameter
    pRenderPassBegin must be a valid pointer to a valid VkRenderPassBeginInfo structure

  • VUID-vkCmdBeginRenderPass-contents-parameter
    contents must be a valid VkSubpassContents value

  • VUID-vkCmdBeginRenderPass-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBeginRenderPass-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBeginRenderPass-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBeginRenderPass-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBeginRenderPass-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Outside

Outside

Graphics

Action
State
Synchronization

Alternatively to begin a render pass, call:

// Provided by VK_VERSION_1_2
void vkCmdBeginRenderPass2(
    VkCommandBuffer                             commandBuffer,
    const VkRenderPassBeginInfo*                pRenderPassBegin,
    const VkSubpassBeginInfo*                   pSubpassBeginInfo);

or the equivalent command

// Provided by VK_KHR_create_renderpass2
void vkCmdBeginRenderPass2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkRenderPassBeginInfo*                pRenderPassBegin,
    const VkSubpassBeginInfo*                   pSubpassBeginInfo);
  • commandBuffer is the command buffer in which to record the command.

  • pRenderPassBegin is a pointer to a VkRenderPassBeginInfo structure specifying the render pass to begin an instance of, and the framebuffer the instance uses.

  • pSubpassBeginInfo is a pointer to a 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 framebuffer and renderPass members of pRenderPassBegin must have been created on the same VkDevice that commandBuffer was allocated on

  • VUID-vkCmdBeginRenderPass2-initialLayout-03094
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03096
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-02844
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-stencilInitialLayout-02845
    If any of the stencilInitialLayout or stencilFinalLayout member of the VkAttachmentDescriptionStencilLayout structures or the stencilLayout member of the VkAttachmentReferenceStencilLayout structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL, or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03097
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03098
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_TRANSFER_SRC_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03099
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including VK_IMAGE_USAGE_TRANSFER_DST_BIT

  • VUID-vkCmdBeginRenderPass2-initialLayout-03100
    If the initialLayout member of any of the VkAttachmentDescription structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is not VK_IMAGE_LAYOUT_UNDEFINED, then each such initialLayout must be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the framebuffer member of pRenderPassBegin

  • VUID-vkCmdBeginRenderPass2-srcStageMask-06453
    The srcStageMask members of any element of the pDependencies member of VkRenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the VkCommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from

  • VUID-vkCmdBeginRenderPass2-dstStageMask-06454
    The dstStageMask members of any element of the pDependencies member of VkRenderPassCreateInfo used to create renderPass must be supported by the capabilities of the queue family identified by the queueFamilyIndex member of the VkCommandPoolCreateInfo used to create the command pool which commandBuffer was allocated from

  • VUID-vkCmdBeginRenderPass2-framebuffer-02533
    For any attachment in framebuffer that is used by renderPass and is bound to memory locations that are also bound to another attachment used by renderPass, and if at least one of those uses causes either attachment to be written to, both attachments must have had the VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT set

  • VUID-vkCmdBeginRenderPass2-framebuffer-09046
    If any attachments specified in framebuffer are used by renderPass and are bound to overlapping memory locations, there must be only one that is used as a color attachment, depth/stencil, or resolve attachment in any subpass

  • VUID-vkCmdBeginRenderPass2-initialLayout-07002
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value including either the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT and either the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or VK_IMAGE_USAGE_SAMPLED_BIT usage bits

  • VUID-vkCmdBeginRenderPass2-initialLayout-07003
    If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then the corresponding attachment image view of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with a usage value the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit

Valid Usage (Implicit)
  • VUID-vkCmdBeginRenderPass2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBeginRenderPass2-pRenderPassBegin-parameter
    pRenderPassBegin must be a valid pointer to a valid VkRenderPassBeginInfo structure

  • VUID-vkCmdBeginRenderPass2-pSubpassBeginInfo-parameter
    pSubpassBeginInfo must be a valid pointer to a valid VkSubpassBeginInfo structure

  • VUID-vkCmdBeginRenderPass2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBeginRenderPass2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBeginRenderPass2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBeginRenderPass2-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBeginRenderPass2-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Outside

Outside

Graphics

Action
State
Synchronization

The VkRenderPassBeginInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkRenderPassBeginInfo {
    VkStructureType        sType;
    const void*            pNext;
    VkRenderPass           renderPass;
    VkFramebuffer          framebuffer;
    VkRect2D               renderArea;
    uint32_t               clearValueCount;
    const VkClearValue*    pClearValues;
} VkRenderPassBeginInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • renderPass is the render pass to begin an instance of.

  • framebuffer is the framebuffer containing the attachments that are used with the render pass.

  • renderArea is the render area that is affected by the render pass instance, and is described in more detail below.

  • clearValueCount is the number of elements in pClearValues.

  • pClearValues is a pointer to an array of clearValueCount VkClearValue structures containing clear values for each attachment, if the attachment uses a loadOp value of VK_ATTACHMENT_LOAD_OP_CLEAR or if the attachment has a depth/stencil format and uses a stencilLoadOp value of VK_ATTACHMENT_LOAD_OP_CLEAR. The array is indexed by attachment number. Only elements corresponding to cleared attachments are used. Other elements of pClearValues are ignored.

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 framebuffer. The application must ensure (using scissor if necessary) that all rendering is contained within the render area. The render area, after any transform specified by VkRenderPassTransformBeginInfoQCOM::transform is applied, must be contained within the framebuffer dimensions.

If render pass transform is enabled, then renderArea must equal the framebuffer pre-transformed dimensions. After renderArea has been transformed by VkRenderPassTransformBeginInfoQCOM::transform, the resulting render area must be equal to the framebuffer dimensions.

If multiview is enabled in renderPass, and multiviewPerViewRenderAreas feature is enabled, and there is an instance of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM included in the pNext chain with perViewRenderAreaCount not equal to 0, then the elements of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas override renderArea and define a render area for each view. In this case, renderArea must be set to an area at least as large as the union of all the per-view render areas.

If the subpassShading feature is enabled, then renderArea must equal the framebuffer dimensions.

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
Valid Usage (Implicit)

The image layout of the depth aspect of a depth/stencil attachment referring to an image created with 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 VkRenderPassSampleLocationsBeginInfoEXT structure to the pNext chain of VkRenderPassBeginInfo.

The VkRenderPassSampleLocationsBeginInfoEXT structure is defined as:

// Provided by VK_EXT_sample_locations
typedef struct VkRenderPassSampleLocationsBeginInfoEXT {
    VkStructureType                          sType;
    const void*                              pNext;
    uint32_t                                 attachmentInitialSampleLocationsCount;
    const VkAttachmentSampleLocationsEXT*    pAttachmentInitialSampleLocations;
    uint32_t                                 postSubpassSampleLocationsCount;
    const VkSubpassSampleLocationsEXT*       pPostSubpassSampleLocations;
} VkRenderPassSampleLocationsBeginInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • attachmentInitialSampleLocationsCount is the number of elements in the pAttachmentInitialSampleLocations array.

  • pAttachmentInitialSampleLocations is a pointer to an array of attachmentInitialSampleLocationsCount VkAttachmentSampleLocationsEXT structures specifying the attachment indices and their corresponding sample location state. Each element of 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.

  • postSubpassSampleLocationsCount is the number of elements in the pPostSubpassSampleLocations array.

  • pPostSubpassSampleLocations is a pointer to an array of postSubpassSampleLocationsCount VkSubpassSampleLocationsEXT structures specifying the subpass indices and their corresponding sample location state. Each element of 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 VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations is VK_FALSE, each element of 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 variableSampleLocations is VK_TRUE, the sample locations used for rasterization do not depend on pPostSubpassSampleLocations.

Valid Usage (Implicit)
  • VUID-VkRenderPassSampleLocationsBeginInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT

  • VUID-VkRenderPassSampleLocationsBeginInfoEXT-pAttachmentInitialSampleLocations-parameter
    If attachmentInitialSampleLocationsCount is not 0, pAttachmentInitialSampleLocations must be a valid pointer to an array of attachmentInitialSampleLocationsCount valid VkAttachmentSampleLocationsEXT structures

  • VUID-VkRenderPassSampleLocationsBeginInfoEXT-pPostSubpassSampleLocations-parameter
    If postSubpassSampleLocationsCount is not 0, pPostSubpassSampleLocations must be a valid pointer to an array of postSubpassSampleLocationsCount valid VkSubpassSampleLocationsEXT structures

The VkAttachmentSampleLocationsEXT structure is defined as:

// Provided by VK_EXT_sample_locations
typedef struct VkAttachmentSampleLocationsEXT {
    uint32_t                    attachmentIndex;
    VkSampleLocationsInfoEXT    sampleLocationsInfo;
} VkAttachmentSampleLocationsEXT;
  • attachmentIndex is the index of the attachment for which the sample locations state is provided.

  • 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 attachmentIndex was not created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT then the values specified in sampleLocationsInfo are ignored.

Valid Usage
  • VUID-VkAttachmentSampleLocationsEXT-attachmentIndex-01531
    attachmentIndex must be less than the attachmentCount specified in VkRenderPassCreateInfo the render pass specified by VkRenderPassBeginInfo::renderPass was created with

Valid Usage (Implicit)
  • VUID-VkAttachmentSampleLocationsEXT-sampleLocationsInfo-parameter
    sampleLocationsInfo must be a valid VkSampleLocationsInfoEXT structure

The VkSubpassSampleLocationsEXT structure is defined as:

// Provided by VK_EXT_sample_locations
typedef struct VkSubpassSampleLocationsEXT {
    uint32_t                    subpassIndex;
    VkSampleLocationsInfoEXT    sampleLocationsInfo;
} VkSubpassSampleLocationsEXT;
  • subpassIndex is the index of the subpass for which the sample locations state is provided.

  • 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 subpassIndex.

If the image referenced by the depth/stencil attachment used in the subpass identified by subpassIndex was not created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT or if the subpass does not use a depth/stencil attachment, and VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations is VK_TRUE then the values specified in sampleLocationsInfo are ignored.

Valid Usage
  • VUID-VkSubpassSampleLocationsEXT-subpassIndex-01532
    subpassIndex must be less than the subpassCount specified in VkRenderPassCreateInfo the render pass specified by VkRenderPassBeginInfo::renderPass was created with

Valid Usage (Implicit)
  • VUID-VkSubpassSampleLocationsEXT-sampleLocationsInfo-parameter
    sampleLocationsInfo must be a valid VkSampleLocationsInfoEXT structure

To begin a render pass instance with render pass transform enabled, add the VkRenderPassTransformBeginInfoQCOM to the pNext chain of VkRenderPassBeginInfo structure passed to the vkCmdBeginRenderPass command specifying the render pass transform.

The VkRenderPassTransformBeginInfoQCOM structure is defined as:

// Provided by VK_QCOM_render_pass_transform
typedef struct VkRenderPassTransformBeginInfoQCOM {
    VkStructureType                  sType;
    void*                            pNext;
    VkSurfaceTransformFlagBitsKHR    transform;
} VkRenderPassTransformBeginInfoQCOM;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • transform is a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied to rasterization.

Valid Usage
  • VUID-VkRenderPassTransformBeginInfoQCOM-transform-02871
    transform must be VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR

  • VUID-VkRenderPassTransformBeginInfoQCOM-flags-02872
    The renderpass must have been created with VkRenderPassCreateInfo::flags containing VK_RENDER_PASS_CREATE_TRANSFORM_BIT_QCOM

Valid Usage (Implicit)
  • VUID-VkRenderPassTransformBeginInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_TRANSFORM_BEGIN_INFO_QCOM

The VkSubpassBeginInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassBeginInfo {
    VkStructureType      sType;
    const void*          pNext;
    VkSubpassContents    contents;
} VkSubpassBeginInfo;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkSubpassBeginInfo VkSubpassBeginInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • contents is a VkSubpassContents value specifying how the commands in the next subpass will be provided.

Valid Usage (Implicit)
  • VUID-VkSubpassBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_BEGIN_INFO

  • VUID-VkSubpassBeginInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkSubpassBeginInfo-contents-parameter
    contents must be a valid VkSubpassContents value

Possible values of vkCmdBeginRenderPass::contents, specifying how the commands in the first subpass will be provided, are:

// Provided by VK_VERSION_1_0
typedef enum VkSubpassContents {
    VK_SUBPASS_CONTENTS_INLINE = 0,
    VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS = 1,
} VkSubpassContents;
  • 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.

  • 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 vkCmdExecuteCommands is the only valid command in the command buffer until vkCmdNextSubpass or vkCmdEndRenderPass.

If the pNext chain of VkRenderPassBeginInfo or VkRenderingInfo includes a VkDeviceGroupRenderPassBeginInfo structure, then that structure includes a device mask and set of render areas for the render pass instance.

The VkDeviceGroupRenderPassBeginInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkDeviceGroupRenderPassBeginInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           deviceMask;
    uint32_t           deviceRenderAreaCount;
    const VkRect2D*    pDeviceRenderAreas;
} VkDeviceGroupRenderPassBeginInfo;

or the equivalent

// Provided by VK_KHR_device_group
typedef VkDeviceGroupRenderPassBeginInfo VkDeviceGroupRenderPassBeginInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceMask is the device mask for the render pass instance.

  • deviceRenderAreaCount is the number of elements in the pDeviceRenderAreas array.

  • pDeviceRenderAreas is a pointer to an array of VkRect2D structures defining the render area for each physical device.

The 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 load, store, and multisample 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 deviceRenderAreaCount is not zero, then the elements of pDeviceRenderAreas override the value of VkRenderPassBeginInfo::renderArea, and provide a render area specific to each physical device. These render areas serve the same purpose as VkRenderPassBeginInfo::renderArea, including controlling the region of attachments that are cleared by 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 VkDeviceGroupCommandBufferBeginInfo::deviceMask. If this structure is not present or if deviceRenderAreaCount is zero, VkRenderPassBeginInfo::renderArea is used for all physical devices.

Valid Usage
  • VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00905
    deviceMask must be a valid device mask value

  • VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00906
    deviceMask must not be zero

  • VUID-VkDeviceGroupRenderPassBeginInfo-deviceMask-00907
    deviceMask must be a subset of the command buffer’s initial device mask

  • VUID-VkDeviceGroupRenderPassBeginInfo-deviceRenderAreaCount-00908
    deviceRenderAreaCount must either be zero or equal to the number of physical devices in the logical device

  • VUID-VkDeviceGroupRenderPassBeginInfo-offset-06166
    The offset.x member of any element of pDeviceRenderAreas must be greater than or equal to 0

  • VUID-VkDeviceGroupRenderPassBeginInfo-offset-06167
    The offset.y member of any element of pDeviceRenderAreas must be greater than or equal to 0

  • VUID-VkDeviceGroupRenderPassBeginInfo-offset-06168
    The sum of the offset.x and extent.width members of any element of pDeviceRenderAreas must be less than or equal to maxFramebufferWidth

  • VUID-VkDeviceGroupRenderPassBeginInfo-offset-06169
    The sum of the offset.y and extent.height members of any element of pDeviceRenderAreas must be less than or equal to maxFramebufferHeight

  • VUID-VkDeviceGroupRenderPassBeginInfo-extent-08998
    The extent.width member of any element of pDeviceRenderAreas must be greater than 0

  • VUID-VkDeviceGroupRenderPassBeginInfo-extent-08999
    The extent.height member of any element of pDeviceRenderAreas must be greater than 0

Valid Usage (Implicit)
  • VUID-VkDeviceGroupRenderPassBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO

  • VUID-VkDeviceGroupRenderPassBeginInfo-pDeviceRenderAreas-parameter
    If deviceRenderAreaCount is not 0, pDeviceRenderAreas must be a valid pointer to an array of deviceRenderAreaCount VkRect2D structures

The VkRenderPassAttachmentBeginInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkRenderPassAttachmentBeginInfo {
    VkStructureType       sType;
    const void*           pNext;
    uint32_t              attachmentCount;
    const VkImageView*    pAttachments;
} VkRenderPassAttachmentBeginInfo;

or the equivalent

// Provided by VK_KHR_imageless_framebuffer
typedef VkRenderPassAttachmentBeginInfo VkRenderPassAttachmentBeginInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • attachmentCount is the number of attachments.

  • pAttachments is a pointer to an array of 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 pAttachments must only specify a single mip level

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-03219
    Each element of pAttachments must have been created with the identity swizzle

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-04114
    Each element of pAttachments must have been created with VkImageViewCreateInfo::viewType not equal to VK_IMAGE_VIEW_TYPE_3D

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-07010
    If multisampled-render-to-single-sampled is enabled for any subpass, all element of pAttachments which have a sample count equal to VK_SAMPLE_COUNT_1_BIT must have a format that supports the sample count specified in VkMultisampledRenderToSingleSampledInfoEXT::rasterizationSamples

Valid Usage (Implicit)
  • VUID-VkRenderPassAttachmentBeginInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_ATTACHMENT_BEGIN_INFO

  • VUID-VkRenderPassAttachmentBeginInfo-pAttachments-parameter
    If attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkImageView handles

If a render pass instance enables multiview and if the <features-multiview-per-view-render-areas,multiviewPerViewRenderAreas>> feature is enabled, the VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure can be included in the pNext chain of VkRenderPassBeginInfo or VkRenderingInfo

The VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure is defined as:

// Provided by VK_QCOM_multiview_per_view_render_areas
typedef struct VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           perViewRenderAreaCount;
    const VkRect2D*    pPerViewRenderAreas;
} VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • perViewRenderAreaCount is the number of elements in the pPerViewRenderAreas array.

  • pPerViewRenderAreas is a pointer to an array of VkRect2D structures defining the render area for each view.

If perViewRenderAreaCount is not zero, then the elements of pPerViewRenderAreas override the value of VkRenderPassBeginInfo::renderArea or VkRenderingInfo::renderArea and define per-view render areas for the individual views of a multiview render pass. The render area for the view with view index i is specified by pPerViewRenderAreas[i].

The per-view render areas define per-view regions of attachments that are loaded, stored, and resolved according to the loadOp, storeOp, and resolveMode values of the render pass instance. When per-view render areas are defined, the value of VkRenderPassBeginInfo::renderArea or VkRenderingInfo::renderArea must be set to a render area that includes the union of all per-view render areas, may be used by the implementation for optimizations, but does not affect loads, stores, or resolves.

If this structure is present and if perViewRenderAreaCount is not zero, then perViewRenderAreaCount must be at least least one greater than the most significant bit set in any any element of VkRenderPassMultiviewCreateInfo::pViewMasks. or VkRenderingInfo::viewMask

If this structure is not present or if perViewRenderAreaCount is zero, VkRenderPassBeginInfo::renderArea or VkRenderingInfo::renderArea is used for all views.

Valid Usage
  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-offset-07861
    The offset.x member of any element of pPerViewRenderAreas must be greater than or equal to 0

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-offset-07862
    The offset.y member of any element of pPerViewRenderAreas must be greater than or equal to 0

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-offset-07863
    The sum of the offset.x and extent.width members of any element of pPerViewRenderAreas must be less than or equal to maxFramebufferWidth

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-offset-07864
    The sum of the offset.y and extent.height members of any element of pPerViewRenderAreas must be less than or equal to maxFramebufferHeight

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-pNext-07865
    If this structure is in the pNext chain of VkRenderPassBeginInfo and if the render pass object included an element in VkRenderPassMultiviewCreateInfo::pViewMasks that set bit n, then perViewRenderAreaCount must be at least equal to n+1.

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-pNext-07866
    If this structure is in the pNext chain of VkRenderingInfo and if VkRenderingInfo::viewMask set bit n, then perViewRenderAreaCount must be at least equal to n+1.

Valid Usage (Implicit)
  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_MULTIVIEW_PER_VIEW_RENDER_AREAS_RENDER_PASS_BEGIN_INFO_QCOM

  • VUID-VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM-pPerViewRenderAreas-parameter
    If perViewRenderAreaCount is not 0, pPerViewRenderAreas must be a valid pointer to an array of perViewRenderAreaCount VkRect2D structures

To query the render area granularity, call:

// Provided by VK_VERSION_1_0
void vkGetRenderAreaGranularity(
    VkDevice                                    device,
    VkRenderPass                                renderPass,
    VkExtent2D*                                 pGranularity);
  • device is the logical device that owns the render pass.

  • renderPass is a handle to a render pass.

  • pGranularity is a pointer to a VkExtent2D structure in which the granularity is returned.

The conditions leading to an optimal renderArea are:

  • the offset.x member in renderArea is a multiple of the width member of the returned VkExtent2D (the horizontal granularity).

  • the offset.y member in renderArea is a multiple of the height member of the returned VkExtent2D (the vertical granularity).

  • either the extent.width member in renderArea is a multiple of the horizontal granularity or offset.x+extent.width is equal to the width of the framebuffer in the VkRenderPassBeginInfo.

  • either the extent.height member in renderArea is a multiple of the vertical granularity or offset.y+extent.height is equal to the height of the framebuffer in the 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 automatic layout transitions. Similarly, pipeline barriers are valid even if their effect extends outside the render area.

Valid Usage (Implicit)
  • VUID-vkGetRenderAreaGranularity-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRenderAreaGranularity-renderPass-parameter
    renderPass must be a valid VkRenderPass handle

  • VUID-vkGetRenderAreaGranularity-pGranularity-parameter
    pGranularity must be a valid pointer to a VkExtent2D structure

  • VUID-vkGetRenderAreaGranularity-renderPass-parent
    renderPass must have been created, allocated, or retrieved from device

To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:

// Provided by VK_VERSION_1_0
void vkCmdNextSubpass(
    VkCommandBuffer                             commandBuffer,
    VkSubpassContents                           contents);
  • commandBuffer is the command buffer in which to record the command.

  • contents specifies how the commands in the next subpass will be provided, in the same fashion as the corresponding parameter of vkCmdBeginRenderPass.

The subpass index for a render pass begins at zero when vkCmdBeginRenderPass is recorded, and increments each time vkCmdNextSubpass is recorded.

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

  • VUID-vkCmdNextSubpass-None-02349
    This command must not be recorded when transform feedback is active

Valid Usage (Implicit)
  • VUID-vkCmdNextSubpass-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdNextSubpass-contents-parameter
    contents must be a valid VkSubpassContents value

  • VUID-vkCmdNextSubpass-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdNextSubpass-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdNextSubpass-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdNextSubpass-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdNextSubpass-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Inside

Outside

Graphics

Action
State
Synchronization

To transition to the next subpass in the render pass instance after recording the commands for a subpass, call:

// Provided by VK_VERSION_1_2
void vkCmdNextSubpass2(
    VkCommandBuffer                             commandBuffer,
    const VkSubpassBeginInfo*                   pSubpassBeginInfo,
    const VkSubpassEndInfo*                     pSubpassEndInfo);

or the equivalent command

// Provided by VK_KHR_create_renderpass2
void vkCmdNextSubpass2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkSubpassBeginInfo*                   pSubpassBeginInfo,
    const VkSubpassEndInfo*                     pSubpassEndInfo);
  • commandBuffer is the command buffer in which to record the command.

  • pSubpassBeginInfo is a pointer to a VkSubpassBeginInfo structure containing information about the subpass which is about to begin rendering.

  • pSubpassEndInfo is a pointer to a VkSubpassEndInfo structure containing information about how the previous subpass will be ended.

vkCmdNextSubpass2 is semantically identical to vkCmdNextSubpass, except that it is extensible, and that 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

  • VUID-vkCmdNextSubpass2-None-02350
    This command must not be recorded when transform feedback is active

Valid Usage (Implicit)
  • VUID-vkCmdNextSubpass2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdNextSubpass2-pSubpassBeginInfo-parameter
    pSubpassBeginInfo must be a valid pointer to a valid VkSubpassBeginInfo structure

  • VUID-vkCmdNextSubpass2-pSubpassEndInfo-parameter
    pSubpassEndInfo must be a valid pointer to a valid VkSubpassEndInfo structure

  • VUID-vkCmdNextSubpass2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdNextSubpass2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdNextSubpass2-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdNextSubpass2-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdNextSubpass2-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Inside

Outside

Graphics

Action
State
Synchronization

To record a command to end a render pass instance after recording the commands for the last subpass, call:

// Provided by VK_VERSION_1_0
void vkCmdEndRenderPass(
    VkCommandBuffer                             commandBuffer);
  • 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

  • VUID-vkCmdEndRenderPass-None-02351
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdEndRenderPass-None-06170
    The current render pass instance must not have been begun with vkCmdBeginRendering

  • VUID-vkCmdEndRenderPass-None-07004
    If vkCmdBeginQuery* was called within a subpass of the render pass, the corresponding vkCmdEndQuery* must have been called subsequently within the same subpass

Valid Usage (Implicit)
  • VUID-vkCmdEndRenderPass-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdEndRenderPass-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdEndRenderPass-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdEndRenderPass-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdEndRenderPass-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdEndRenderPass-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Inside

Outside

Graphics

Action
State
Synchronization

To record a command to end a render pass instance after recording the commands for the last subpass, call:

// Provided by VK_VERSION_1_2
void vkCmdEndRenderPass2(
    VkCommandBuffer                             commandBuffer,
    const VkSubpassEndInfo*                     pSubpassEndInfo);

or the equivalent command

// Provided by VK_KHR_create_renderpass2
void vkCmdEndRenderPass2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkSubpassEndInfo*                     pSubpassEndInfo);
  • commandBuffer is the command buffer in which to end the current render pass instance.

  • pSubpassEndInfo is a pointer to a VkSubpassEndInfo structure containing information about how the last subpass will be ended.

vkCmdEndRenderPass2 is semantically identical to 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

  • VUID-vkCmdEndRenderPass2-None-02352
    This command must not be recorded when transform feedback is active

  • VUID-vkCmdEndRenderPass2-None-06171
    The current render pass instance must not have been begun with vkCmdBeginRendering

  • VUID-vkCmdEndRenderPass2-None-07005
    If vkCmdBeginQuery* was called within a subpass of the render pass, the corresponding vkCmdEndQuery* must have been called subsequently within the same subpass

Valid Usage (Implicit)
  • VUID-vkCmdEndRenderPass2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdEndRenderPass2-pSubpassEndInfo-parameter
    pSubpassEndInfo must be a valid pointer to a valid VkSubpassEndInfo structure

  • VUID-vkCmdEndRenderPass2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdEndRenderPass2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdEndRenderPass2-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdEndRenderPass2-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdEndRenderPass2-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Inside

Outside

Graphics

Action
State
Synchronization

The VkSubpassEndInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkSubpassEndInfo {
    VkStructureType    sType;
    const void*        pNext;
} VkSubpassEndInfo;

or the equivalent

// Provided by VK_KHR_create_renderpass2
typedef VkSubpassEndInfo VkSubpassEndInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

Valid Usage (Implicit)
  • VUID-VkSubpassEndInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_END_INFO

  • VUID-VkSubpassEndInfo-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkSubpassFragmentDensityMapOffsetEndInfoQCOM

  • VUID-VkSubpassEndInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

If the VkSubpassEndInfo::pNext chain includes a VkSubpassFragmentDensityMapOffsetEndInfoQCOM structure, then that structure includes an array of fragment density map offsets per layer for the render pass.

The VkSubpassFragmentDensityMapOffsetEndInfoQCOM structure is defined as:

// Provided by VK_QCOM_fragment_density_map_offset
typedef struct VkSubpassFragmentDensityMapOffsetEndInfoQCOM {
    VkStructureType      sType;
    const void*          pNext;
    uint32_t             fragmentDensityOffsetCount;
    const VkOffset2D*    pFragmentDensityOffsets;
} VkSubpassFragmentDensityMapOffsetEndInfoQCOM;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • fragmentDensityOffsetCount is the number of offsets being specified.

  • pFragmentDensityOffsets is a pointer to an array of VkOffset2D structs, each of which describes the offset per layer.

The array elements are given per layer as defined by Fetch Density Value, where index = layer. Each (x,y) offset is in framebuffer pixels and shifts the fetch of the fragment density map by that amount. Offsets can be positive or negative.

Offset values specified for any subpass that is not the last subpass in the render pass are ignored. If the VkSubpassEndInfo::pNext chain for the last subpass of a render pass does not include VkSubpassFragmentDensityMapOffsetEndInfoQCOM, or if fragmentDensityOffsetCount is zero, then the offset (0,0) is used for Fetch Density Value.

Valid Usage
  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-fragmentDensityMapOffsets-06503
    If the fragmentDensityMapOffsets feature is not enabled or fragment density map is not enabled in the render pass, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-fragmentDensityMapAttachment-06504
    If VkSubpassDescription::fragmentDensityMapAttachment is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pDepthStencilAttachment-06505
    If VkSubpassDescription::pDepthStencilAttachment is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pInputAttachments-06506
    If any element of VkSubpassDescription::pInputAttachments is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pColorAttachments-06507
    If any element of VkSubpassDescription::pColorAttachments is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pResolveAttachments-06508
    If any element of VkSubpassDescription::pResolveAttachments is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pPreserveAttachments-06509
    If any element of VkSubpassDescription::pPreserveAttachments is not is not VK_ATTACHMENT_UNUSED and was not created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM, fragmentDensityOffsetCount must equal 0

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-fragmentDensityOffsetCount-06510
    If fragmentDensityOffsetCount is not 0 and multiview is enabled for the render pass, fragmentDensityOffsetCount must equal the layerCount that was specified in creating the fragment density map attachment view

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-fragmentDensityOffsetCount-06511
    If fragmentDensityOffsetCount is not 0 and multiview is not enabled for the render pass, fragmentDensityOffsetCount must equal 1

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-x-06512
    The x component of each element of pFragmentDensityOffsets must be an integer multiple of fragmentDensityOffsetGranularity.width

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-y-06513
    The y component of each element of pFragmentDensityOffsets must be an integer multiple of fragmentDensityOffsetGranularity.height

Valid Usage (Implicit)
  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_SUBPASS_FRAGMENT_DENSITY_MAP_OFFSET_END_INFO_QCOM

  • VUID-VkSubpassFragmentDensityMapOffsetEndInfoQCOM-pFragmentDensityOffsets-parameter
    If fragmentDensityOffsetCount is not 0, pFragmentDensityOffsets must be a valid pointer to an array of fragmentDensityOffsetCount VkOffset2D structures

8.9. Render Pass Creation Feedback

A VkRenderPassCreationControlEXT structure can be included in the pNext chain of VkRenderPassCreateInfo2 or pNext chain of VkSubpassDescription2. The VkRenderPassCreationControlEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationControlEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           disallowMerging;
} VkRenderPassCreationControlEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • disallowMerging is a boolean value indicating whether subpass merging will be disabled.

If a VkRenderPassCreationControlEXT structure is included in the pNext chain of VkRenderPassCreateInfo2 and its value of disallowMerging is VK_TRUE, the implementation will disable subpass merging for the entire render pass. If a VkRenderPassCreationControlEXT structure is included in the pNext chain of VkSubpassDescription2 and its value of disallowMerging is VK_TRUE, the implementation will disable merging the described subpass with previous subpasses in the render pass.

Valid Usage (Implicit)
  • VUID-VkRenderPassCreationControlEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_CONTROL_EXT

To obtain feedback about the creation of a render pass, include a VkRenderPassCreationFeedbackCreateInfoEXT structure in the pNext chain of VkRenderPassCreateInfo2. The VkRenderPassCreationFeedbackCreateInfoEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationFeedbackCreateInfoEXT {
    VkStructureType                         sType;
    const void*                             pNext;
    VkRenderPassCreationFeedbackInfoEXT*    pRenderPassFeedback;
} VkRenderPassCreationFeedbackCreateInfoEXT;
Valid Usage (Implicit)
  • VUID-VkRenderPassCreationFeedbackCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_CREATION_FEEDBACK_CREATE_INFO_EXT

  • VUID-VkRenderPassCreationFeedbackCreateInfoEXT-pRenderPassFeedback-parameter
    pRenderPassFeedback must be a valid pointer to a VkRenderPassCreationFeedbackInfoEXT structure

The VkRenderPassCreationFeedbackInfoEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassCreationFeedbackInfoEXT {
    uint32_t    postMergeSubpassCount;
} VkRenderPassCreationFeedbackInfoEXT;
  • postMergeSubpassCount is the subpass count after merge.

Feedback about the creation of a subpass can be obtained by including a VkRenderPassSubpassFeedbackCreateInfoEXT structure in the pNext chain of VkSubpassDescription2. VkRenderPassSubpassFeedbackCreateInfoEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassSubpassFeedbackCreateInfoEXT {
    VkStructureType                        sType;
    const void*                            pNext;
    VkRenderPassSubpassFeedbackInfoEXT*    pSubpassFeedback;
} VkRenderPassSubpassFeedbackCreateInfoEXT;
Valid Usage (Implicit)
  • VUID-VkRenderPassSubpassFeedbackCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_RENDER_PASS_SUBPASS_FEEDBACK_CREATE_INFO_EXT

  • VUID-VkRenderPassSubpassFeedbackCreateInfoEXT-pSubpassFeedback-parameter
    pSubpassFeedback must be a valid pointer to a VkRenderPassSubpassFeedbackInfoEXT structure

The VkRenderPassSubpassFeedbackInfoEXT structure is defined as:

// Provided by VK_EXT_subpass_merge_feedback
typedef struct VkRenderPassSubpassFeedbackInfoEXT {
    VkSubpassMergeStatusEXT    subpassMergeStatus;
    char                       description[VK_MAX_DESCRIPTION_SIZE];
    uint32_t                   postMergeIndex;
} VkRenderPassSubpassFeedbackInfoEXT;
  • subpassMergeStatus is a VkSubpassMergeStatusEXT value specifying information about whether the subpass is merged with previous subpass and the reason why it is not merged.

  • description is an array of VK_MAX_DESCRIPTION_SIZE char containing a null-terminated UTF-8 string which provides additional details.

  • postMergeIndex is the subpass index after the subpass merging.

Possible values of VkRenderPassSubpassFeedbackInfoEXT:subpassMergeStatus are:

// Provided by VK_EXT_subpass_merge_feedback
typedef enum VkSubpassMergeStatusEXT {
    VK_SUBPASS_MERGE_STATUS_MERGED_EXT = 0,
    VK_SUBPASS_MERGE_STATUS_DISALLOWED_EXT = 1,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SIDE_EFFECTS_EXT = 2,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SAMPLES_MISMATCH_EXT = 3,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_VIEWS_MISMATCH_EXT = 4,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_ALIASING_EXT = 5,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPENDENCIES_EXT = 6,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INCOMPATIBLE_INPUT_ATTACHMENT_EXT = 7,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_TOO_MANY_ATTACHMENTS_EXT = 8,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INSUFFICIENT_STORAGE_EXT = 9,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPTH_STENCIL_COUNT_EXT = 10,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_RESOLVE_ATTACHMENT_REUSE_EXT = 11,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SINGLE_SUBPASS_EXT = 12,
    VK_SUBPASS_MERGE_STATUS_NOT_MERGED_UNSPECIFIED_EXT = 13,
} VkSubpassMergeStatusEXT;
  • VK_SUBPASS_MERGE_STATUS_MERGED_EXT specifies the subpass is merged with a previous subpass.

  • VK_SUBPASS_MERGE_STATUS_DISALLOWED_EXT specifies the subpass is disallowed to merge with previous subpass. If the render pass does not allow subpass merging, then all subpass statuses are set to this value. If a subpass description does not allow subpass merging, then only that subpass’s status is set to this value.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SIDE_EFFECTS_EXT specifies the subpass is not merged because it contains side effects.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SAMPLES_MISMATCH_EXT specifies the subpass is not merged because sample count is not compatible with previous subpass.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_VIEWS_MISMATCH_EXT specifies the subpass is not merged because view masks do not match with previous subpass.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_ALIASING_EXT specifies the subpass is not merged because of attachments aliasing between them.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPENDENCIES_EXT specifies the subpass is not merged because subpass dependencies do not allow merging.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INCOMPATIBLE_INPUT_ATTACHMENT_EXT specifies the subpass is not merged because input attachment is not a color attachment from previous subpass or the formats are incompatible.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_TOO_MANY_ATTACHMENTS_EXT specifies the subpass is not merged because of too many attachments.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_INSUFFICIENT_STORAGE_EXT specifies the subpass is not merged because of insufficient memory.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_DEPTH_STENCIL_COUNT_EXT specifies the subpass is not merged because of too many depth/stencil attachments.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_RESOLVE_ATTACHMENT_REUSE_EXT specifies the subpass is not merged because a resolve attachment is reused as an input attachment in a subsequent subpass.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_SINGLE_SUBPASS_EXT specifies the subpass is not merged because the render pass has only one subpass.

  • VK_SUBPASS_MERGE_STATUS_NOT_MERGED_UNSPECIFIED_EXT specifies other reasons why subpass is not merged. It is also the recommended default value that should be reported when a subpass is not merged and when no other value is appropriate.

8.10. Common Render Pass Data Races (Informative)

Due to the complexity of how rendering is performed, there are several ways an application can accidentally introduce a data race, usually by doing something that may seem benign but actually cannot be supported. This section indicates a number of the more common cases as guidelines to help avoid them.

8.10.1. Sampling from a read-only attachment

Vulkan includes read-only layouts for depth/stencil images, that allow the images to be both read during a render pass for the purposes of depth/stencil tests, and read as a non-attachment.

However, because VK_ATTACHMENT_STORE_OP_STORE and VK_ATTACHMENT_STORE_OP_DONT_CARE may perform write operations, even if no recorded command writes to an attachment, reading from an image while also using it as an attachment with these store operations can result in a data race. If the reads from the non-attachment are performed in a fragment shader where the accessed samples match those covered by the fragment shader, no data race will occur as store operations are guaranteed to operate after fragment shader execution for the set of samples the fragment covers. Notably, input attachments can also be used for this case. Reading other samples or in any other shader stage can result in unexpected behavior due to the potential for a data race, and validation errors should be generated for doing so. In practice, many applications have shipped reading samples outside of the covered fragment without any observable issue, but there is no guarantee that this will always work, and it is not advisable to rely on this in new or re-worked code bases. As VK_ATTACHMENT_STORE_OP_NONE is guaranteed to perform no writes, applications wishing to read an image as both an attachment and a non-attachment should make use of this store operation, coupled with a load operation that also performs no writes.

8.10.2. Non-overlapping access between resources

When relying on non-overlapping accesses between attachments and other resources, it is important to note that load and store operations have fairly wide alignment requirements - potentially affecting entire subresources and adjacent depth/stencil aspects. This makes it invalid to access a non-attachment subresource that is simultaneously being used as an attachment where either access performs a write operation.

The only exception to this is if a subresource is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT image layout, in which case the overlap is defined to occur at a per-pixel granularity, and applications can read data from pixels outside the render area without introducing a data race.

8.10.3. Depth/stencil and input attachments

When rendering to only the depth OR stencil aspect of an image, an input attachment accessing the other aspect will not cause a data race only under very specific conditions. To avoid a data race, the aspect not being written must be in a read-only layout, and writes to it must be disabled in the draw state. For example, to read from stencil while writing depth, the attachment must be in VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL (or equivalent), and the stencil write mask must be set to 0. Similarly to read from depth while writing stencil, the attachment must be in VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL (or equivalent), and depth write enable must be set to VK_FALSE.

8.10.4. Synchronization Options

There are several synchronization options available to synchronize between accesses to resources within a render pass. Some of the options are outlined below:

  • A VkSubpassDependency in a render pass object can synchronize attachment writes and multisample resolve operations from a prior subpass for subsequent input attachment reads.

  • A vkCmdPipelineBarrier inside a subpass can synchronize prior attachment writes in the subpass with subsequent input attachment reads.

  • A vkCmdPipelineBarrier inside a subpass can synchronize prior attachment writes in the subpass with subsequent non-attachment reads if the attachment is in the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT image layout.

  • If a subresource is used as a color and input attachment, and the pipeline performing the read was created with VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT

  • If a subresource is used as a depth and input attachment, and the pipeline performing the read was created with VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT

  • If a subresource is used as a stencil and input attachment, and the pipeline performing the read was created with VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT

  • If a subresource is used as two separate non-attachment resources, writes to a pixel or individual sample in a fragment shader can be synchronized with access to the same pixel or sample in another fragment shader by using one of the fragment interlock execution modes.