From 00bc02f3c1abfc52ad2bc8800c74b6f46a1af18a Mon Sep 17 00:00:00 2001
From: Roman Stingler <roman.stingler@gmail.com>
Date: Fri, 3 Apr 2026 19:11:21 +0200
Subject: [PATCH] feat: add renderer backend config option

---
 src/config.rs                                 | 11 ++++++
 src/main.rs                                   | 26 +++++++++++++
 website/docs/configuration/main.md            | 38 +++++++++++++++++++
 website/docs/configuration/troubleshooting.md |  8 +++-
 4 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/src/config.rs b/src/config.rs
index d52285a7..4d811974 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -18,12 +18,22 @@ use tokio::time::sleep;
 
 pub const DEFAULT_CONFIG_FILE_PATH: &str = "~/.config/ashell/config.toml";
 
+#[derive(Deserialize, Copy, Clone, Debug, Default, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum RendererBackend {
+    #[default]
+    Auto,
+    Vulkan,
+    OpenGL,
+}
+
 #[derive(Deserialize, Clone, Debug)]
 #[serde(default)]
 pub struct Config {
     pub log_level: String,
     pub position: Position,
     pub layer: Layer,
+    pub renderer_backend: RendererBackend,
     pub outputs: Outputs,
     pub modules: Modules,
     #[serde(rename = "CustomModule")]
@@ -47,6 +57,7 @@ impl Default for Config {
             log_level: "warn".to_owned(),
             position: Position::default(),
             layer: Layer::default(),
+            renderer_backend: RendererBackend::default(),
             outputs: Outputs::default(),
             modules: Modules::default(),
             updates: None,
diff --git a/src/main.rs b/src/main.rs
index c6670f9e..eb2a5af9 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -87,6 +87,32 @@ async fn main() -> iced::Result {
 
     logger.set_new_spec(get_log_spec(&config.log_level));
 
+    // Set renderer backend BEFORE any wgpu/iced initialization
+    // Safe: we are single-threaded at this point, no other threads exist yet
+    if std::env::var("WGPU_BACKEND").is_err() {
+        match config.renderer_backend {
+            crate::config::RendererBackend::Vulkan => unsafe {
+                std::env::set_var("WGPU_BACKEND", "vulkan");
+            },
+            crate::config::RendererBackend::OpenGL => unsafe {
+                std::env::set_var("WGPU_BACKEND", "gl");
+            },
+            crate::config::RendererBackend::Auto => {
+                // Auto-detect: default proprietary NVIDIA driver to OpenGL for better stability
+                if std::env::var("__NV_PRIME_RENDER_OFFLOAD").is_ok()
+                    || std::env::var("__GLX_VENDOR_LIBRARY_NAME")
+                        .map(|v| v.contains("nvidia"))
+                        .unwrap_or(false)
+                {
+                    // Proprietary nvidia driver is loaded
+                    unsafe {
+                        std::env::set_var("WGPU_BACKEND", "gl");
+                    }
+                }
+            }
+        }
+    }
+
     let font = if let Some(font_name) = &config.appearance.font_name {
         Font::with_name(Box::leak(font_name.clone().into_boxed_str()))
     } else {
diff --git a/website/docs/configuration/main.md b/website/docs/configuration/main.md
index 4cfac040..5fdeb5e2 100644
--- a/website/docs/configuration/main.md
+++ b/website/docs/configuration/main.md
@@ -145,3 +145,41 @@ This is useful for keybind-based toggling or scripting.
 # Toggle ashell visibility
 kill -SIGUSR1 $(pidof ashell)
 ```
+
+## Renderer Backend
+
+Selects the graphics rendering backend to use.
+
+:::warning
+This configuration **requires** restarting Ashell to take effect.
+:::
+
+### Valid Options
+
+| Value | Description |
+|---|---|
+| `"auto"` | **(Default)** Automatically selects the best backend. Automatically uses OpenGL for proprietary NVIDIA driver users, Vulkan for all other hardware (AMD/Intel/nouveau). |
+| `"vulkan"` | Force use Vulkan renderer. |
+| `"opengl"` | Force use OpenGL renderer. |
+
+:::note Environment Variable Precedence
+If the `WGPU_BACKEND` environment variable is already set when starting ashell, this configuration option will be ignored entirely and the environment variable value will be used instead.
+:::
+
+### Examples
+
+```toml
+renderer_backend = "auto"
+```
+
+```toml
+renderer_backend = "vulkan"
+```
+
+```toml
+renderer_backend = "opengl"
+```
+
+:::tip NVIDIA Users
+Automatic mode will default to OpenGL for systems running the proprietary NVIDIA driver for best stability and performance. You can still explicitly select Vulkan if you prefer.
+:::
diff --git a/website/docs/configuration/troubleshooting.md b/website/docs/configuration/troubleshooting.md
index 8ee4639c..13c0d25c 100644
--- a/website/docs/configuration/troubleshooting.md
+++ b/website/docs/configuration/troubleshooting.md
@@ -12,7 +12,13 @@ Common issues and quick fixes for ashell.
 
 **Cause:** The default Vulkan backend may have compatibility issues with NVIDIA drivers.
 
-**Solution:** Force the use of OpenGL by setting the `WGPU_BACKEND` environment variable:
+**Solution 1 (Permanent):** Set renderer backend in your config.toml:
+
+```toml
+renderer_backend = "opengl"
+```
+
+**Solution 2 (Temporary):** Force the use of OpenGL by setting the `WGPU_BACKEND` environment variable:
 
 ```bash
 WGPU_BACKEND=gl ashell