diff --git a/docs/dev/bar-e2e.md b/docs/dev/bar-e2e.md index 4f38448c..b83ef1e0 100644 --- a/docs/dev/bar-e2e.md +++ b/docs/dev/bar-e2e.md @@ -25,51 +25,39 @@ macOS (see `docs/dev/macos-handcheck.md`). Not run when it was written (the guest was reserved): lint only (`py_compile`, `ruff`, the runner's 157 unit tests pass). -## The golden guest has no OpenGL 2.0 -The Windows gate (candidate 5) found that the bar cannot open a window in the golden guest: -eframe's default renderer is `egui_glow`, the guest has the basic display adapter and QXL and no -OpenGL driver, so Windows offers only the generic software OpenGL 1.1 of `opengl32.dll`, and the bar -exits at start with `Error: egui_glow: OpenGL: egui_glow requires opengl 2.0+` -(`komorebi-bar/src/windows/mod.rs`, the `run_native` error). The scenario therefore reports the -window, stays-alive and daemon-restart checks as `skipped: guest has no OpenGL 2.0` when, and only -when, the bar's own output says that (`extras/bar.py`, `classify`); any other early exit is a -failure. The schema equality, the configuration read, `komorebic state` and `stop --bar` stay real -checks. A skip is not a pass: the bar's runtime behaviour is unverified until the guest can draw. +## Renderers: glow first, wgpu when there is no OpenGL -### Getting rendering into the guest (analysis, nothing added) +The golden guest has no OpenGL 2.0 (the basic display adapter and QXL; Windows offers only the generic +OpenGL 1.1), and eframe's `egui_glow` refuses that: the first gate of the `bar` scenario saw +`Error: egui_glow: OpenGL: egui_glow requires opengl 2.0+` and the bar never opened a window. +Decision D-coord-14: the Windows bar tries glow as before and, only when glow cannot make its context +(`eframe::Error::OpenGL`, `Glutin` or `NoGlutinConfigs`), runs again with eframe's wgpu renderer, which +draws through Direct3D 12 and finds the software adapter WARP (Windows 11 ships it in the Basic Render +Driver) with no driver and no download (`run_with_fallback` in `komorebi-bar/src/windows/mod.rs`; the +`wgpu` feature of `eframe` is in the Windows-only table of `komorebi-bar/Cargo.toml`, the bar core and +the macOS bar do not have it). The bar logs `renderer: glow`, and on a fallback `renderer: glow failed +(...); trying wgpu`. With both features compiled eframe's default renderer is wgpu, so the first attempt +names `Renderer::Glow`: machines where glow works run exactly as before. -How the context is chosen: `komorebi-bar` uses `eframe` 0.33 with its default features, so only -the glow renderer is compiled (glutin + `egui_glow`); `NativeOptions` is left at its defaults on -Windows (the macOS bar sets its own), so the bar asks for a hardware OpenGL 2.0+ config through -glutin, falls back to the Windows generic GDI implementation (1.1) and `egui_glow` refuses it. +In the scenario: -1. Mesa llvmpipe `opengl32.dll` next to `komorebi-bar.exe` (the classic recipe: Mesa's - `opengl32.dll` takes over from the system one for that process). Not possible from this flake: - nixpkgs marks `pkgsCross.mingwW64.mesa` as an unsupported platform (`nix build --dry-run` refuses - it), and `nixpkgs` has no Windows `opengl32sw.dll` (that file ships with Qt) or ANGLE. Building - Mesa for mingw means porting its nix expression (swrast + llvm cross for mingw, a cross LLVM - build) and carrying a binary of unknown license status in the image: days of work, hours of - build, and the result is a third-party DLL in the test that real users do not run. -2. A wgpu renderer with the Windows software adapter. Windows 11 ships WARP, the software - Direct3D 12 rasteriser, in the Basic Render Driver, which the guest has; wgpu's DX12 backend - finds it as an adapter, no download. In `eframe` this is the `wgpu` feature plus - `NativeOptions { renderer: Renderer::Wgpu, .. }` (and `wgpu_options` with a fallback adapter if - it does not pick WARP by itself). The sources of the wgpu stack (wgpu 27, naga, wgpu-hal, - gpu-allocator, ash) are already in the local cargo registry because they are in `Cargo.lock` - as optional dependencies of eframe, so it should build offline. Proposal, smallest first: - in `komorebi-bar`'s `[target.'cfg(windows)'.dependencies]` ask for `eframe` with the `wgpu` - feature, and at start: try glow as now; if `run_native` fails with the OpenGL message, run again - with `Renderer::Wgpu` (the e2e then passes the window checks, and a user without OpenGL gets a - bar instead of an error). Cost: about 60 more crates in `Cargo.lock` that are compiled for - Windows only (cold build +3 to 5 minutes in CI, +8 to 12 MB in `komorebi-bar.exe`); a retry path - that needs `NativeOptions` to be built twice; a new, untested code path for real users (low - risk: it only runs where glow already failed). Without the fallback, a `KOMOREBI_BAR_RENDERER=wgpu` - switch the scenario sets would keep users on glow and cost the same dependencies. -3. ANGLE (EGL on Direct3D 11, itself on WARP) through `glutin`'s EGL support: needs - `libEGL.dll`/`libGLESv2.dll`, which are not in nix either. Rejected. +- the bar's window, stays-alive, daemon-restart and notify checks are real when either renderer opens the + window; the scenario prints which one drew it; +- only when both fail (the bar ends with `Error: glow: ...; wgpu: ...`) those checks are skipped, and the + skip line names both errors (`skip ...: guest cannot draw: glow: ...; wgpu: ...`); the schema, the + configuration read, `komorebic state` and `stop --bar` stay checks; any other early exit of the bar is a + failure; +- the bar is started with `RUST_LOG=info,wgpu_hal=debug,wgpu_core=warn` so `bar.out` keeps what wgpu says + about its adapters (read it first when the window does not appear). -Recommendation: 2, with the glow-then-wgpu fallback, as its own revision with the e2e `bar` -scenario as its gate (the window checks stop being skipped). Whether the guest's WARP accepts -wgpu's DX12 device (feature level, no HLSL compiler problem for egui's shaders) can only be -learned by running it; the first run should keep `RUST_LOG=wgpu_hal=debug` output in `bar.out`. +Cost, measured: 622 -> 664 distinct crate versions in the Windows bar's dependency tree (+42), one new +lock entry (`pollster` 0.4.0; the rest of the wgpu stack was already locked as optional dependencies of +eframe). Not measured here (no nix build was run): compile time and the size of `komorebi-bar.exe` +(estimate: a few minutes cold, 8 to 12 MB). + +Risks: WARP may not accept egui's Direct3D 12 device or the transparent surface the bar asks for +(`with_transparent(true)`; only the e2e gate can say); wgpu picks a hardware Vulkan/D3D12 adapter before +WARP when there is one, so on a machine with a GPU but broken OpenGL the bar now uses that adapter; a +second `run_native` on the same thread relies on eframe reusing its thread-local event loop (it does, by +design, for reopening windows).