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:
VkRenderingAttachmentInfo::loadOp == LOAD_OP_CLEAR
VkRenderingInfo::renderArea is the entire image view LOD
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
-
bool is_multiview¶
-
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.
-
VkFormat format¶
-
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.
-
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.
-
uint32_t attachment_count¶
-
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
-
uint32_t attachment¶
-
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
-
VkDependencyFlags flags¶