Render Passes — The Mesa 3D Graphics Library latest documentation

# Render Passes

The Vulkan runtime code in Mesa provides several helpful utilities to make managing render passes easier.

## VK_KHR_create_renderpass2

It is strongly recommended that drivers implement VK_KHR_create_renderpass2 directly and not bother implementing the old Vulkan 1.0 entrypoints. If a driver does not implement them, the following will be implemented in common code in terms of their VK_KHR_create_renderpass2 counterparts:

> - `vkCreateRenderPass()`

> - `vkCmdBeginRenderPass()`

> - `vkCmdNextSubpass()`

> - `vkCmdEndRenderPass()`

## Common VkRenderPass implementation

The Vulkan runtime code in Mesa provides a common implementation of `VkRenderPass` called `vk_render_pass` which drivers can optionally use. Unlike most Vulkan runtime structs, it’s not really designed to be used as a base for a driver-specific struct. It does, however, contain all the information passed to `vkCreateRenderPass2()` so it can be used in a driver so long as that driver doesn’t need to do any additional compilation at `vkCreateRenderPass2()` time. If a driver chooses to use `vk_render_pass`, the Vulkan runtime provides implementations of `vkCreateRenderPass2()` and `vkDestroyRenderPass()`.

## VK_KHR_dynamic_rendering

For drivers which don’t need to do subpass combining, it is recommended that they skip implementing render passes entirely and implement VK_KHR_dynamic_rendering instead. If they choose to do so, the runtime will provide the following, implemented in terms of `vkCmdBeginRendering()` and `vkCmdEndRendering()`:

> - `vkCmdBeginRenderPass2()`

> - `vkCmdNextSubpass2()`

> - `vkCmdEndRenderPass2()`

We also provide a no-op implementation of `vkGetRenderAreaGranularity()` which returns a render area granularity of 1x1.

Drivers which wish to use the common render pass implementation in this way must also support a Mesa-specific pseudo-extension which optionally provides an initial image layout for each attachment at `vkCmdBeginRendering()` time. This is required for us to combine render pass clears with layout transitions, often from `VK_IMAGE_LAYOUT_UNDEFINED`. On at least Intel and AMD, combining these transitions with clears is important for performance.

struct VkRenderingAttachmentInitialLayoutInfoMESA

  Pseudo-extension struct that may be chained into VkRenderingAttachmentInfo to indicate an initial layout for the attachment. This is only allowed if all of the following conditions are met:

  > 1. VkRenderingAttachmentInfo::loadOp == LOAD_OP_CLEAR

  > 2. VkRenderingInfo::renderArea is the entire image view LOD

  > 3. For 3D image attachments, VkRenderingInfo::viewMask == 0 AND VkRenderingInfo::layerCount references the entire bound image view OR VkRenderingInfo::viewMask is dense (no holes) and references the entire bound image view. (2D and 2D array images have no such requirement.)

  If this struct is included in the pNext chain of a VkRenderingAttachmentInfo, the driver is responsible for transitioning the bound region of the image from VkRenderingAttachmentInitialLayoutInfoMESA::initialLayout to VkRenderingAttachmentInfo::imageLayout prior to rendering.

  VkImageLayout initialLayout

    Initial layout of the attachment

Because render passes and subpass indices are also passed into `vkCmdCreateGraphicsPipelines()` and `vkCmdExecuteCommands()` which we can’t implement on the driver’s behalf, we provide a couple of helpers for getting the render pass information in terms of the relevant VK_KHR_dynamic_rendering:

const VkPipelineRenderingCreateInfo *vk_get_pipeline_rendering_create_info(const VkGraphicsPipelineCreateInfo *info)

  Returns the VkPipelineRenderingCreateInfo for a graphics pipeline

  For render-pass-free drivers, this can be used in the implementation of vkCreateGraphicsPipelines to get the VkPipelineRenderingCreateInfo. If VkGraphicsPipelineCreateInfo::renderPass is not VK_NULL_HANDLE, it will return a representation of the specified subpass as a VkPipelineRenderingCreateInfo. If VkGraphicsPipelineCreateInfo::renderPass is VK_NULL_HANDLE and there is a VkPipelineRenderingCreateInfo in the pNext chain of VkGraphicsPipelineCreateInfo, it will return that.

  Parameters:

    - info – [in] One of the pCreateInfos from vkCreateGraphicsPipelines

const VkCommandBufferInheritanceRenderingInfo *vk_get_command_buffer_inheritance_rendering_info(VkCommandBufferLevel level, const VkCommandBufferBeginInfo *pBeginInfo)

  Returns the VkCommandBufferInheritanceRenderingInfo for secondary command buffer execution

  For render-pass-free drivers, this can be used in the implementation of vkCmdExecuteCommands to get the VkCommandBufferInheritanceRenderingInfo. If VkCommandBufferInheritanceInfo::renderPass is not VK_NULL_HANDLE, it will return a representation of the specified subpass as a VkCommandBufferInheritanceRenderingInfo. If VkCommandBufferInheritanceInfo::renderPass is not VK_NULL_HANDLE and there is a VkCommandBufferInheritanceRenderingInfo in the pNext chain of VkCommandBufferBeginInfo, it will return that.

  Parameters:

    - level – [in] The nesting level of this command buffer

    - pBeginInfo – [in] The pBeginInfo from vkBeginCommandBuffer

Apart from handling layout transitions, the common render pass implementation mostly ignores input attachments. It is expected that the driver call `nir_lower_input_attachments()` to turn them into texturing operations. The driver must support texturing from an input attachment at the same time as rendering to it in order to support Vulkan subpass self-dependencies. `VK_EXT_attachment_feedback_loop_layout` provides information on when these self dependencies are present.

## vk_render_pass reference

The following is a reference for the `vk_render_pass` structure and its substructures.

struct vk_render_pass
  bool is_multiview

    True if this render pass uses multiview

    This is true if all subpasses have viewMask != 0.

  uint32_t view_mask

    Views used by this render pass or 1 for non-multiview

  uint32_t attachment_count

    VkRenderPassCreateInfo2::attachmentCount

  struct vk_render_pass_attachment *attachments

    VkRenderPassCreateInfo2::pAttachments

  uint32_t subpass_count

    VkRenderPassCreateInfo2::subpassCount

  struct vk_subpass *subpasses

    VkRenderPassCreateInfo2::subpasses

  uint32_t dependency_count

    VkRenderPassCreateInfo2::dependencyCount

  VkAttachmentReference fragment_density_map

    VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment

  struct vk_subpass_dependency *dependencies

    VkRenderPassCreateInfo2::pDependencies

struct vk_render_pass_attachment
  VkFormat format

    VkAttachmentDescription2::format

  VkImageAspectFlags aspects

    Aspects contained in format

  uint32_t samples

    VkAttachmentDescription2::samples

  uint32_t view_mask

    Views in which this attachment is used, 0 for unused

    For non-multiview, this will be 1 if the attachment is used.

  VkAttachmentLoadOp load_op

    VkAttachmentDescription2::loadOp

  VkAttachmentStoreOp store_op

    VkAttachmentDescription2::storeOp

  VkAttachmentLoadOp stencil_load_op

    VkAttachmentDescription2::stencilLoadOp

  VkAttachmentStoreOp stencil_store_op

    VkAttachmentDescription2::stencilStoreOp

  VkImageLayout initial_layout

    VkAttachmentDescription2::initialLayout

  VkImageLayout final_layout

    VkAttachmentDescription2::finalLayout

  VkImageLayout initial_stencil_layout

    VkAttachmentDescriptionStencilLayout::stencilInitialLayout

    If VK_KHR_separate_depth_stencil_layouts is not used, this will be initial_layout if format contains stencil and VK_IMAGE_LAYOUT_UNDEFINED otherwise.

  VkImageLayout final_stencil_layout

    VkAttachmentDescriptionStencilLayout::stencilFinalLayout

    If VK_KHR_separate_depth_stencil_layouts is not used, this will be final_layout if format contains stencil and VK_IMAGE_LAYOUT_UNDEFINED otherwise.

struct vk_subpass
  uint32_t attachment_count

    Count of all attachments referenced by this subpass

  struct vk_subpass_attachment *attachments

    Array of all attachments referenced by this subpass

  uint32_t input_count

    VkSubpassDescription2::inputAttachmentCount

  struct vk_subpass_attachment *input_attachments

    VkSubpassDescription2::pInputAttachments

  uint32_t color_count

    VkSubpassDescription2::colorAttachmentCount

  struct vk_subpass_attachment *color_attachments

    VkSubpassDescription2::pColorAttachments

  uint32_t color_resolve_count

    VkSubpassDescription2::colorAttachmentCount or zero

  struct vk_subpass_attachment *color_resolve_attachments

    VkSubpassDescription2::pResolveAttachments

  struct vk_subpass_attachment *depth_stencil_attachment

    VkSubpassDescription2::pDepthStencilAttachment

  struct vk_subpass_attachment *depth_stencil_resolve_attachment

    VkSubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment

  struct vk_subpass_attachment *fragment_shading_rate_attachment

    VkFragmentShadingRateAttachmentInfoKHR::pFragmentShadingRateAttachment

  uint32_t view_mask

    VkSubpassDescription2::viewMask or 1 for non-multiview

    For all view masks in the vk_render_pass data structure, we use a mask of 1 for non-multiview instead of a mask of 0. To determine if the render pass is multiview or not, see vk_render_pass::is_multiview.

  VkResolveModeFlagBits depth_resolve_mode

    VkSubpassDescriptionDepthStencilResolve::depthResolveMode

  VkResolveModeFlagBits stencil_resolve_mode

    VkSubpassDescriptionDepthStencilResolve::stencilResolveMode

  VkExtent2D fragment_shading_rate_attachment_texel_size

    VkFragmentShadingRateAttachmentInfoKHR::shadingRateAttachmentTexelSize

  VkPipelineCreateFlagBits2KHR pipeline_flags

    Extra VkPipelineCreateFlags for this subpass

  VkAttachmentSampleCountInfoAMD sample_count_info_amd

    VkAttachmentSampleCountInfoAMD for this subpass

    This is in the pNext chain of pipeline_info and inheritance_info.

  struct [anonymous]

    VkRenderingInputAttachmentIndexInfo for this subpass

    This is in the pNext chain of pipeline_info and inheritance_info.

    Also returned by vk_get_pipeline_rendering_ial_info() if VkGraphicsPipelineCreateInfo::renderPass != VK_NULL_HANDLE.

  VkPipelineRenderingCreateInfo pipeline_info

    VkPipelineRenderingCreateInfo for this subpass

    Returned by vk_get_pipeline_rendering_create_info() if VkGraphicsPipelineCreateInfo::renderPass != VK_NULL_HANDLE.

  VkCommandBufferInheritanceRenderingInfo inheritance_info

    VkCommandBufferInheritanceRenderingInfo for this subpass

    Returned by vk_get_command_buffer_inheritance_rendering_info() if VkCommandBufferInheritanceInfo::renderPass != VK_NULL_HANDLE.

  VkMultisampledRenderToSingleSampledInfoEXT mrtss

    VkMultisampledRenderToSingleSampledInfoEXT for this subpass

  bool legacy_dithering_enabled

    True if legacy dithering is enabled for this subpass.

struct vk_subpass_attachment
  uint32_t attachment

    VkAttachmentReference2::attachment

  VkImageAspectFlags aspects

    Aspects referenced by this attachment

    For an input attachment, this is VkAttachmentReference2::aspectMask. For all others, it’s equal to the vk_render_pass_attachment::aspects.

  VkImageUsageFlagBits usage

    Usage for this attachment

    This is a single VK_IMAGE_USAGE_* describing the usage of this subpass attachment. Resolve attachments are VK_IMAGE_USAGE_TRANSFER_DST_BIT.

  VkImageLayout layout

    VkAttachmentReference2::layout

  VkImageLayout stencil_layout

    VkAttachmentReferenceStencilLayout::stencilLayout

    If VK_KHR_separate_depth_stencil_layouts is not used, this will be layout if the attachment contains stencil and VK_IMAGE_LAYOUT_UNDEFINED otherwise.

  uint32_t last_subpass

    A per-view mask for if this is the last use of this attachment

    If the same render pass attachment is used multiple ways within a subpass, corresponding last_subpass bits will be set in all of them. For the non-multiview case, only the first bit is used.

  struct vk_subpass_attachment *resolve

    Resolve attachment, if any

struct vk_subpass_dependency
  VkDependencyFlags flags

    VkSubpassDependency2::dependencyFlags

  uint32_t src_subpass

    VkSubpassDependency2::srcSubpass

  uint32_t dst_subpass

    VkSubpassDependency2::dstSubpass

  VkPipelineStageFlags2 src_stage_mask

    VkSubpassDependency2::srcStageMask

  VkPipelineStageFlags2 dst_stage_mask

    VkSubpassDependency2::dstStageMask

  VkAccessFlags2 src_access_mask

    VkSubpassDependency2::srcAccessMask

  VkAccessFlags2 dst_access_mask

    VkSubpassDependency2::dstAccessMask

  int32_t view_offset

    VkSubpassDependency2::viewOffset