1Render Passes 2============= 3 4The Vulkan runtime code in Mesa provides several helpful utilities to make 5managing render passes easier. 6 7 8:ext:`VK_KHR_create_renderpass2` 9-------------------------------- 10 11It is strongly recommended that drivers implement 12:ext:`VK_KHR_create_renderpass2` directly and not bother implementing the 13old Vulkan 1.0 entrypoints. If a driver does not implement them, the 14following will be implemented in common code in terms of their 15:ext:`VK_KHR_create_renderpass2` counterparts: 16 17 - :c:func:`vkCreateRenderPass` 18 - :c:func:`vkCmdBeginRenderPass` 19 - :c:func:`vkCmdNextSubpass` 20 - :c:func:`vkCmdEndRenderPass` 21 22 23Common VkRenderPass implementation 24---------------------------------- 25 26The Vulkan runtime code in Mesa provides a common implementation of 27:c:type:`VkRenderPass` called :c:struct:`vk_render_pass` which drivers 28can optionally use. Unlike most Vulkan runtime structs, it's not really 29designed to be used as a base for a driver-specific struct. It does, 30however, contain all the information passed to 31:c:func:`vkCreateRenderPass2` so it can be used in a driver so long as 32that driver doesn't need to do any additional compilation at 33:c:func:`vkCreateRenderPass2` time. If a driver chooses to use 34:c:struct:`vk_render_pass`, the Vulkan runtime provides implementations 35of :c:func:`vkCreateRenderPass2` and :c:func:`vkDestroyRenderPass`. 36 37 38:ext:`VK_KHR_dynamic_rendering` 39------------------------------- 40 41For drivers which don't need to do subpass combining, it is recommended 42that they skip implementing render passes entirely and implement 43:ext:`VK_KHR_dynamic_rendering` instead. If they choose to do so, the runtime 44will provide the following, implemented in terms of 45:c:func:`vkCmdBeginRendering` and :c:func:`vkCmdEndRendering`: 46 47 - :c:func:`vkCmdBeginRenderPass2` 48 - :c:func:`vkCmdNextSubpass2` 49 - :c:func:`vkCmdEndRenderPass2` 50 51We also provide a no-op implementation of 52:c:func:`vkGetRenderAreaGranularity` which returns a render area 53granularity of 1x1. 54 55Drivers which wish to use the common render pass implementation in this way 56**must** also support a Mesa-specific pseudo-extension which optionally 57provides an initial image layout for each attachment at 58:c:func:`vkCmdBeginRendering` time. This is required for us to combine 59render pass clears with layout transitions, often from 60:c:enum:`VK_IMAGE_LAYOUT_UNDEFINED`. On at least Intel and AMD, 61combining these transitions with clears is important for performance. 62 63.. c:autostruct:: VkRenderingAttachmentInitialLayoutInfoMESA 64 :file: src/vulkan/runtime/vk_render_pass.h 65 :members: 66 67Because render passes and subpass indices are also passed into 68:c:func:`vkCmdCreateGraphicsPipelines` and 69:c:func:`vkCmdExecuteCommands` which we can't implement on the driver's 70behalf, we provide a couple of helpers for getting the render pass 71information in terms of the relevant :ext:`VK_KHR_dynamic_rendering`: 72 73.. c:autofunction:: vk_get_pipeline_rendering_create_info 74 :file: src/vulkan/runtime/vk_render_pass.h 75 76.. c:autofunction:: vk_get_command_buffer_inheritance_rendering_info 77 :file: src/vulkan/runtime/vk_render_pass.h 78 79Apart from handling layout transitions, the common render pass 80implementation mostly ignores input attachments. It is expected that the 81driver call :c:func:`nir_lower_input_attachments` to turn them into 82texturing operations. The driver **must** support texturing from an input 83attachment at the same time as rendering to it in order to support Vulkan 84subpass self-dependencies. ``VK_EXT_attachment_feedback_loop_layout`` provides 85information on when these self dependencies are present. 86 87vk_render_pass reference 88------------------------ 89 90The following is a reference for the :c:struct:`vk_render_pass` structure 91and its substructures. 92 93.. c:autostruct:: vk_render_pass 94 :file: src/vulkan/runtime/vk_render_pass.h 95 :members: 96 97.. c:autostruct:: vk_render_pass_attachment 98 :file: src/vulkan/runtime/vk_render_pass.h 99 :members: 100 101.. c:autostruct:: vk_subpass 102 :file: src/vulkan/runtime/vk_render_pass.h 103 :members: 104 105.. c:autostruct:: vk_subpass_attachment 106 :file: src/vulkan/runtime/vk_render_pass.h 107 :members: 108 109.. c:autostruct:: vk_subpass_dependency 110 :file: src/vulkan/runtime/vk_render_pass.h 111 :members: 112