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