rt(vk): make render passes the default, and dynamic rendering not.

This is technically a breaking change for the C API, but it doesn't break ABI.
If someone complains there is a migration guide anyways...

README.md

@@ -14,21 +14,19 @@ librashader (*/ˈli:brəʃeɪdɚ/*) is a preprocessor, compiler, and runtime for
 For end-users, librashader is available from the [Open Build Service](https://software.opensuse.org//download.html?project=home%3Achyyran%3Alibrashader&package=librashader) for a variety of Linux distributions and platforms. Windows users can grab the latest DLL from [GitHub Releases](https://github.com/SnowflakePowered/librashader/releases).
 
 ## Supported Render APIs
-librashader supports OpenGL 3, OpenGL 4.6, Vulkan, Direct3D 11, and Direct3D 12.  Metal and WebGPU
+librashader supports all modern graphics runtimes, including wgpu, Vulkan, OpenGL 3.3+ and 4.6 (with DSA), 
-are not currently supported (but pull-requests are welcome). librashader does not support legacy render
+Direct3D 11, Direct3D 12, and Metal. librashader does not support legacy render
 APIs such as older versions of OpenGL, or legacy versions of Direct3D.
 
 | **API**     | **Status** | **`librashader` feature** |
-|-------------|------------|---------------------------|
+|-------------|-----------|---------------------------|
 | OpenGL 3.3+ | ✔         | `gl`                      |
 | OpenGL 4.6  | ✔         | `gl`                      |
 | Vulkan      | ✔         | `vk`                      |
 | Direct3D 11 | ✔         | `d3d11`                   |
 | Direct3D 12 | ✔         | `d3d12`                   |
+| Metal       | ✔         | `metal`                   |
 | wgpu        | ✔         | `wgpu`                    |
-| Metal       | ❌         |                           |
-
-✔ = Render API is supported — ❌ Render API is not supported
 
 ## Usage
 
@@ -158,9 +156,9 @@ Please report an issue if you run into a shader that works in RetroArch, but not
   * Should work on OpenGL 4.5 but this is not guaranteed. The OpenGL 4.6 runtime may eventually switch to using `ARB_spirv_extensions` for loading shaders, and this will not be marked as a breaking change.
   * The OpenGL 4.6 runtime uses Direct State Access to minimize changes to the OpenGL state. For GPUs released within the last 5 years, this may improve performance.
 * Vulkan
-  * The Vulkan runtime uses [`VK_KHR_dynamic_rendering`](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_dynamic_rendering.html) by default.
+  * The Vulkan runtime can use [`VK_KHR_dynamic_rendering`](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_dynamic_rendering.html).
-    This extension must be enabled at device creation. Explicit render passes can be used by configuring filter chain options, but may have reduced performance 
+    This extension must be enabled at device creation. 
-    compared to dynamic rendering.
+    Dynamic rendering may have improved performance when enabled, and supported by the host hardware.
   * Allocations within the runtime are done through [gpu-allocator](https://github.com/Traverse-Research/gpu-allocator) rather than handled manually.
 * Direct3D 11
   * Framebuffer copies are done via `ID3D11DeviceContext::CopySubresourceRegion` rather than a CPU conversion + copy.
@@ -170,6 +168,8 @@ Please report an issue if you run into a shader that works in RetroArch, but not
   * For maximum compatibility with shaders, a shader compile pipeline based on [`spirv-to-dxil`](https://github.com/SnowflakePowered/spirv-to-dxil-rs) is used, with the SPIRV-Cross HLSL pipeline used as a fallback. 
     This brings shader compatibility beyond what the RetroArch Direct3D 12 driver provides. The HLSL pipeline fallback may be removed in the future as `spirv-to-dxil` improves.
   * The Direct3D 12 runtime requires `dxil.dll` and `dxcompiler.dll` from the [DirectX Shader Compiler](https://github.com/microsoft/DirectXShaderCompiler).
+* Metal
+  * The Metal runtime uses the same VBOs as the other non-OpenGL runtimes as well as the identity matrix MVP for intermediate passes. RetroArch's Metal driver uses only the final VBO.
 
 Most, if not all shader presets should work fine on librashader. The runtime specific differences should not affect the output,
 and are more a heads-up for integrating librashader into your project.

librashader-capi/src/runtime/vk/filter_chain.rs

@@ -119,9 +119,10 @@ pub struct filter_chain_vk_opt_t {
     pub frames_in_flight: u32,
     /// Whether or not to explicitly disable mipmap generation regardless of shader preset settings.
     pub force_no_mipmaps: bool,
-    /// Use explicit render pass objects It is recommended if possible to use dynamic rendering,
+    /// Use dynamic rendering over explicit render pass objects.
+    /// It is recommended if possible to use dynamic rendering,
     /// because render-pass mode will create new framebuffers per pass.
-    pub use_render_pass: bool,
+    pub use_dynamic_rendering: bool,
     /// Disable the shader object cache. Shaders will be
     /// recompiled rather than loaded from the cache.
     pub disable_cache: bool,
@@ -129,7 +130,7 @@ pub struct filter_chain_vk_opt_t {
 
 config_struct! {
     impl FilterChainOptions => filter_chain_vk_opt_t {
-        0 => [frames_in_flight, force_no_mipmaps, use_render_pass, disable_cache];
+        0 => [frames_in_flight, force_no_mipmaps, use_dynamic_rendering, disable_cache];
     }
 }
 

librashader-runtime-vk/src/filter_chain.rs

@@ -346,7 +346,7 @@ impl FilterChainVulkan {
             passes,
             &semantics,
             frames_in_flight,
-            options.map_or(false, |o| o.use_render_pass),
+            options.map_or(false, |o| o.use_dynamic_rendering),
             disable_cache,
         )?;
 
@@ -412,7 +412,7 @@ impl FilterChainVulkan {
         passes: Vec<ShaderPassMeta>,
         semantics: &ShaderSemantics,
         frames_in_flight: u32,
-        use_render_pass: bool,
+        use_dynamic_rendering: bool,
         disable_cache: bool,
     ) -> error::Result<Box<[FilterPass]>> {
         let frames_in_flight = std::cmp::max(1, frames_in_flight);
@@ -440,7 +440,7 @@ impl FilterChainVulkan {
 
                 let uniform_bindings = reflection.meta.create_binding_map(|param| param.offset());
 
-                let render_pass_format = if !use_render_pass {
+                let render_pass_format = if use_dynamic_rendering {
                     vk::Format::UNDEFINED
                 } else if let Some(format) = config.get_format_override() {
                     format.into()

librashader-runtime-vk/src/options.rs

@@ -11,9 +11,10 @@ pub struct FilterChainOptionsVulkan {
     pub frames_in_flight: u32,
     /// Whether or not to explicitly disable mipmap generation regardless of shader preset settings.
     pub force_no_mipmaps: bool,
-    /// Use explicit render pass objects It is recommended if possible to use dynamic rendering,
+    /// Use dynamic rendering instead of explicit render pass objects.
+    /// It is recommended if possible to use dynamic rendering,
     /// because render-pass mode will create new framebuffers per pass.
-    pub use_render_pass: bool,
+    pub use_dynamic_rendering: bool,
     /// Disable the shader object cache. Shaders will be
     /// recompiled rather than loaded from the cache.
     pub disable_cache: bool,

librashader-runtime-vk/tests/triangle.rs

@@ -19,7 +19,7 @@ fn triangle_vk() {
             Some(&FilterChainOptionsVulkan {
                 frames_in_flight: 3,
                 force_no_mipmaps: false,
-                use_render_pass: true,
+                use_dynamic_rendering: true,
                 disable_cache: true,
             }),
         )

librashader/src/lib.rs

@@ -15,15 +15,15 @@
 //! called with appropriate input and output parameters to draw a frame with the shader effect applied.
 //!
 //! ## Runtimes
-//! Currently available runtimes are wgpu, Vulkan, OpenGL 3.3+ and 4.6 (with DSA), Direct3D 11, and Direct3D 12.
+//! librashader supports all modern graphics runtimes, including wgpu, Vulkan, OpenGL 3.3+ and 4.6 (with DSA),
-//!
+//! Direct3D 11, Direct3D 12, and Metal.
-//! The Vulkan runtime requires [`VK_KHR_dynamic_rendering`](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_dynamic_rendering.html)
-//! by default, unless [`FilterChainOptions::use_render_pass`](crate::runtime::vk::FilterChainOptions) is explicitly set. Note that dynamic rendering
-//! will bring the best performance.
 //!
 //! The Direct3D 12 runtime requires support for [render passes](https://learn.microsoft.com/en-us/windows/win32/direct3d12/direct3d-12-render-passes), which
 //! have been available since Windows 10, version 1809.
 //!
+//! The Vulkan runtime can use [`VK_KHR_dynamic_rendering`](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_dynamic_rendering.html)
+//! for improved performance, if the underlying hardware supports it.
+//!
 //! wgpu support is not available in the librashader C API.
 //!
 //! | **API**     | **Status** | **`librashader` feature** |
@@ -34,7 +34,7 @@
 //! | Direct3D 11  | ✔        | `d3d11`                 |
 //! | Direct3D 12  | ✔        | `d3d12`                 |
 //! | wgpu        | ✔        |  `wgpu`                 |
-//! | Metal       | ❌        |                         |
+//! | Metal       | ✔        |  `metal`                |
 //!
 //! ## C API
 //! For documentation on the librashader C API, see [librashader-capi](https://docs.rs/librashader-capi/latest/librashader_capi/),