From aec1562e4a17c10fa132fb8f14af5c4fd93d71ec Mon Sep 17 00:00:00 2001 From: FractalEncrypt <59615752+FractalEncrypt@users.noreply.github.com> Date: Tue, 3 Nov 2026 09:48:59 -0500 Subject: [PATCH] fix(windows): start on OpenGL when Direct3D 12 can't create the UI pipeline (#1081) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The launcher built its window once, on wgpu's first-choice backend, and exited with code 1 when that backend couldn't create `egui_pipeline`. Nothing appeared on screen, so it looked like the launcher had never started at all: on Direct3D 12 some drivers refuse that pipeline (#111, #1081), and a 32-bit build refuses it on every Direct3D 12 adapter even where the 64-bit build of the same commit draws fine. `StartupBackends` now tries the fallback backend after a start that couldn't create its renderer. The fallback is OpenGL everywhere it exists (Metal is macOS's only backend, so there is nothing to fall back to there). `WGPU_BACKEND` still names the one backend a start uses, and a window that failed for another reason — no event loop, no display — is not retried, so its error isn't buried. Reproduced with the shipped `windows-x86` 0.14.0 binary and with a local i686 build: `egui_pipeline` fails in `ID3D12Device2::CreatePipelineState` with E_INVALIDARG (0x80070057) on the RTX 4080 SUPER and on the AMD integrated GPU, in both debug and release, while the x86_64 build of the same commit starts on Direct3D 12. With this change the 32-bit build logs the failure and opens its window on OpenGL. The 32-bit Direct3D 12 failure itself is still open: it is below this repository, in wgpu's Direct3D 12 pipeline creation. Part of #1081, not all of it: the issue also asks for a readable error naming the backend when every backend fails. That needs a new user-facing string and its row in every `complete_menus` catalog, so it stays open rather than closing here. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- apps/artcraft-launcher/src/main.rs | 186 +++++++++++++++++++++++++---- 1 file changed, 165 insertions(+), 21 deletions(-) diff --git a/apps/artcraft-launcher/src/main.rs b/apps/artcraft-launcher/src/main.rs index 7df41274..ba4c34cc 100644 --- a/apps/artcraft-launcher/src/main.rs +++ b/apps/artcraft-launcher/src/main.rs @@ -125,6 +125,10 @@ fn main() -> ExitCode { launcher.start(settings, &waker); window = launcher.tray.is_none(); } + // A renderer that can't start on the first-choice backend is tried again on the next one + // (`StartupBackends`), so a graphics driver that fails the UI pipeline doesn't end the + // launcher before its window appears. + let mut backends = StartupBackends::new(eframe::wgpu::Backends::from_env().is_some()); // One pass per window: where a window can't hide, closing to the tray ends its pass and the // launcher carries on without one until the window is asked for again. loop { @@ -133,7 +137,7 @@ fn main() -> ExitCode { let (waker, launcher) = (waker.clone(), &mut launcher); eframe::run_native( "ArtCraft Launcher", - native_options(hidden), + native_options(hidden, backends.current()), Box::new(move |cc| { launcher.open(cc, &waker); Ok(Box::new(Shell::new(cc, launcher, hidden))) @@ -142,6 +146,10 @@ fn main() -> ExitCode { }; waker.set_window(None); if let Err(e) = result { + if let Some(next) = backends.after_failure(&e) { + log::warn!("the window didn't start: {e}; trying {next:?} instead"); + continue; + } log::error!("{e}"); return ExitCode::FAILURE; } @@ -158,12 +166,13 @@ fn main() -> ExitCode { } /// The native window and renderer setup. `hidden` only sets the initial visibility; the shell -/// shows the window after a tray start. Non-macOS windows are undecorated because the header -/// draws the title bar, while macOS keeps its bundle icon and hides the system title. Window -/// state persists to the portable-aware settings path, system font fallback is off so the -/// deliberate bundled faces stay in charge, and wgpu limits are clamped to the adapter so a -/// short adapter cannot fail device creation. -fn native_options(hidden: bool) -> eframe::NativeOptions { +/// shows the window after a tray start. `backends` overrides wgpu's backend list for this attempt +/// (`StartupBackends`). Non-macOS windows are undecorated because the header draws the title bar, +/// while macOS keeps its bundle icon and hides the system title. Window state persists to the +/// portable-aware settings path, system font fallback is off so the deliberate bundled faces stay +/// in charge, and wgpu limits are clamped to the adapter so a short adapter cannot fail device +/// creation. +fn native_options(hidden: bool, backends: Option) -> eframe::NativeOptions { let icon = eframe::icon_data::from_png_bytes(include_bytes!("../../../assets/app-icon/hicolor/256x256/apps/ai.storyteller.artcraft-launcher.png")).ok(); let mut viewport = egui::ViewportBuilder::default() @@ -192,7 +201,7 @@ fn native_options(hidden: bool) -> eframe::NativeOptions { viewport, persist_window: true, persistence_path: settings_file::path(APP_ID), - wgpu_options: within_adapter_limits(wgpu_options()), + wgpu_options: within_adapter_limits(wgpu_options(backends)), // The launcher's typography is deliberate (its bundled Latin and monochrome emoji faces // plus, for a CJK language, the one system face read by `theme`). eframe's system-font // provider would enumerate and select fonts asynchronously, changing which face draws Han @@ -224,6 +233,74 @@ fn fit_limits(requested: eframe::wgpu::Limits, adapter: &eframe::wgpu::Limits) - requested.or_worse_values_from(adapter) } +/// The backends a start tries for its window, in order, before it gives up. +/// +/// The first attempt uses wgpu's own backend list. If the renderer can't be created on it — the +/// driver refuses the UI pipeline — the next attempt uses [`fallback_backends`] instead. Without +/// this the launcher exits before its window appears and looks like it never started at all: +/// Direct3D 12 fails to create `egui_pipeline` on some drivers (#111, #1081), and a 32-bit build +/// fails it on every Direct3D 12 adapter even where the 64-bit build of the same commit draws +/// fine (reproduced here: `windows-x86` from v0.14.0 on Windows 10 22H2, NVIDIA 32.0.16.1742 and +/// the AMD integrated GPU alike). +/// +/// `WGPU_BACKEND` is the user's own choice, so a start that names one tries that alone. +struct StartupBackends { + /// What to try next, in order. An entry of `None` means wgpu's own backend list. + remaining: Vec>, +} + +impl StartupBackends { + /// The plan for a start, where `named_by_env` says `WGPU_BACKEND` picked the backend itself. + fn new(named_by_env: bool) -> Self { + Self { remaining: startup_plan(named_by_env) } + } + + /// The backends to start with, or `None` for wgpu's own list. + fn current(&self) -> Option { + self.remaining.first().copied().flatten() + } + + /// The backends to try after `error` ended the attempt, or `None` when there is nothing left + /// to try and the launcher should report the failure and exit. + fn after_failure(&mut self, error: &eframe::Error) -> Option { + // Only a renderer that couldn't be created is worth another backend. A window that failed + // for another reason — no event loop, no display — fails the same way on all of them, and + // retrying would only hide the first error. + if !matches!(error, eframe::Error::Wgpu(_)) { + self.remaining.clear(); + return None; + } + if !self.remaining.is_empty() { + self.remaining.remove(0); + } + self.current() + } +} + +/// [`StartupBackends`]' order: wgpu's own list, then the fallback. +fn startup_plan(named_by_env: bool) -> Vec> { + match (named_by_env, fallback_backends()) { + (true, _) | (false, None) => vec![None], + (false, Some(fallback)) => vec![None, Some(fallback)], + } +} + +/// The backend a start falls back to when wgpu's own list can't create the UI pipeline, if the +/// platform has one to offer. +#[cfg(target_os = "macos")] +fn fallback_backends() -> Option { + // Metal is the only backend macOS has; a Metal failure has no second backend to fall back to. + None +} + +/// OpenGL, which draws the launcher everywhere else: it needs no vendor ICDs and no overlay +/// layers, and on Windows it is already the launcher's second choice (`wgpu_options`). Vulkan is +/// deliberately not tried, for the reason given there. +#[cfg(not(target_os = "macos"))] +fn fallback_backends() -> Option { + Some(eframe::wgpu::Backends::GL) +} + /// wgpu's backend list. On Windows that is Direct3D 12 with GL as the fallback, not Vulkan: /// Vulkan goes through vendor ICDs and third-party overlay layers, and on hybrid AMD laptops whose /// integrated and discrete GPUs run different driver packages (common on OEM machines, where the @@ -236,17 +313,16 @@ fn fit_limits(requested: eframe::wgpu::Limits, adapter: &eframe::wgpu::Limits) - /// the window is then stretched over it vertically by the compositor, blurring every horizontal /// edge and line of text. `WGPU_DX12_PRESENTATION_SYSTEM` still overrides it. #[cfg(windows)] -fn wgpu_options() -> eframe::WgpuConfiguration { +fn wgpu_options(backends: Option) -> eframe::WgpuConfiguration { use eframe::wgpu::{Backends, Dx12Compiler, Dx12SwapchainKind, PowerPreference}; let mut config = eframe::WgpuConfiguration::default(); pin_dx12_compiler(&mut config, Dx12Compiler::from_env()); if let eframe::egui_wgpu::WgpuSetup::CreateNew(setup) = &mut config.wgpu_setup { setup.instance_descriptor.backend_options.dx12.presentation_system = Dx12SwapchainKind::from_env().unwrap_or(Dx12SwapchainKind::DxgiFromVisual); - if let Some(backends) = Backends::from_env() { - setup.instance_descriptor.backends = backends; - } else { - setup.instance_descriptor.backends = Backends::DX12 | Backends::GL; + let named = Backends::from_env(); + setup.instance_descriptor.backends = named.or(backends).unwrap_or(Backends::DX12 | Backends::GL); + if named.is_none() { let integrated = setup.power_preference == PowerPreference::LowPower; setup.native_adapter_selector = Some(Arc::new(move |adapters, surface| { adapters @@ -304,10 +380,13 @@ fn adapter_rank(backend: eframe::wgpu::Backend, device_type: eframe::wgpu::Devic /// software rasterizer only wins when nothing else can draw. `WGPU_POWER_PREF` (`low`, `high` or /// `none`) still overrides it, and then wgpu picks the adapter itself. #[cfg(not(any(windows, target_os = "macos")))] -fn wgpu_options() -> eframe::WgpuConfiguration { +fn wgpu_options(backends: Option) -> eframe::WgpuConfiguration { use eframe::wgpu::{DeviceType, PowerPreference}; let mut config = eframe::WgpuConfiguration::default(); if let eframe::egui_wgpu::WgpuSetup::CreateNew(setup) = &mut config.wgpu_setup { + if let Some(backends) = backends { + setup.instance_descriptor.backends = backends; + } if let Some(preference) = PowerPreference::from_env() { setup.power_preference = preference; } else { @@ -328,13 +407,16 @@ fn wgpu_options() -> eframe::WgpuConfiguration { /// Returns wgpu's defaults, except that Intel Macs skip the indirect-call validation shaders /// ([`skips_indirect_validation`]). #[cfg(target_os = "macos")] -fn wgpu_options() -> eframe::WgpuConfiguration { +fn wgpu_options(backends: Option) -> eframe::WgpuConfiguration { use eframe::wgpu::InstanceFlags; let mut config = eframe::WgpuConfiguration::default(); - if let eframe::egui_wgpu::WgpuSetup::CreateNew(setup) = &mut config.wgpu_setup - && skips_indirect_validation(std::env::consts::OS, cfg!(target_arch = "x86_64")) - { - setup.instance_descriptor.flags = setup.instance_descriptor.flags.difference(InstanceFlags::VALIDATION_INDIRECT_CALL).with_env(); + if let eframe::egui_wgpu::WgpuSetup::CreateNew(setup) = &mut config.wgpu_setup { + if let Some(backends) = backends { + setup.instance_descriptor.backends = backends; + } + if skips_indirect_validation(std::env::consts::OS, cfg!(target_arch = "x86_64")) { + setup.instance_descriptor.flags = setup.instance_descriptor.flags.difference(InstanceFlags::VALIDATION_INDIRECT_CALL).with_env(); + } } config } @@ -1170,6 +1252,68 @@ mod tests { assert!(!shell.launcher.closed_to_tray); } + #[test] + fn a_renderer_that_cannot_start_is_retried_on_the_fallback() { + // What eframe returns when the driver refuses the UI pipeline (#111, #1081). + let failure = || eframe::Error::Wgpu(eframe::egui_wgpu::WgpuError::NoSurfaceFormatsAvailable); + let mut backends = StartupBackends::new(false); + assert_eq!(backends.current(), None, "the first attempt uses wgpu's own backend list"); + match fallback_backends() { + Some(fallback) => { + assert_eq!(backends.after_failure(&failure()), Some(fallback)); + // The fallback is the last try: a driver that fails it too ends the launcher. + assert_eq!(backends.after_failure(&failure()), None); + } + // Metal is the only backend macOS has. + None => assert_eq!(backends.after_failure(&failure()), None), + } + } + + #[test] + fn a_start_that_names_a_backend_is_not_overruled() { + // `WGPU_BACKEND` is the user's own choice, so a failure on it ends the start. + assert_eq!(startup_plan(true), vec![None]); + let mut backends = StartupBackends::new(true); + let failure = eframe::Error::Wgpu(eframe::egui_wgpu::WgpuError::NoSurfaceFormatsAvailable); + assert_eq!(backends.after_failure(&failure), None); + } + + #[test] + fn a_window_that_fails_for_another_reason_is_not_retried() { + // No event loop, no display: every backend fails the same way, and retrying would only + // bury the first error. + let mut backends = StartupBackends::new(false); + let error = eframe::Error::AppCreation(Box::new(std::io::Error::other("no window"))); + assert_eq!(backends.after_failure(&error), None); + } + + #[cfg(not(target_os = "macos"))] + #[test] + fn the_fallback_backend_is_opengl() { + // Direct3D 12 and Vulkan both fail the UI pipeline on drivers where OpenGL draws fine + // (#111, #1081), and Vulkan is deliberately not a Windows backend (see `wgpu_options`). + assert_eq!(fallback_backends(), Some(eframe::wgpu::Backends::GL)); + } + + #[cfg(windows)] + #[test] + fn a_fallback_attempt_starts_only_that_backend() { + use eframe::egui_wgpu::WgpuSetup; + fn backends(config: eframe::WgpuConfiguration) -> eframe::wgpu::Backends { + match config.wgpu_setup { + WgpuSetup::CreateNew(setup) => setup.instance_descriptor.backends, + WgpuSetup::Existing(_) => panic!("the launcher creates its own wgpu instance"), + } + } + if eframe::wgpu::Backends::from_env().is_some() { + // `WGPU_BACKEND` outranks the fallback, and `a_start_that_names_a_backend_is_not_overruled` + // covers that it is then the only attempt. + return; + } + assert_eq!(backends(wgpu_options(None)), eframe::wgpu::Backends::DX12 | eframe::wgpu::Backends::GL); + assert_eq!(backends(wgpu_options(Some(eframe::wgpu::Backends::GL))), eframe::wgpu::Backends::GL); + } + #[test] fn intel_macs_skip_the_indirect_validation_shaders() { // Metal's compiler fails on them on Intel Iris Macs, losing the device (#344). @@ -1191,7 +1335,7 @@ mod tests { WgpuSetup::Existing(_) => panic!("the launcher creates its own wgpu instance"), } } - let launcher = flags(wgpu_options()); + let launcher = flags(wgpu_options(None)); if !cfg!(target_arch = "x86_64") { // Apple silicon keeps wgpu's flags. assert_eq!(launcher, flags(eframe::WgpuConfiguration::default())); @@ -1255,7 +1399,7 @@ mod tests { #[test] fn linux_draws_on_the_desktops_gpu_unless_told_otherwise() { use eframe::wgpu::PowerPreference; - let config = wgpu_options(); + let config = wgpu_options(None); let eframe::egui_wgpu::WgpuSetup::CreateNew(setup) = &config.wgpu_setup else { panic!("the launcher creates its own wgpu instance"); };