docs(bar): the wgpu fallback, the scenario's new rules, cost and risks

docs/dev/bar-e2e.md: why the golden guest cannot use glow, how the bar falls
back to wgpu (WARP), what the scenario now counts as real and as a skip (both
renderers failing, naming both errors), the log level kept in bar.out, the
measured cost (622 -> 664 crate versions in the Windows bar tree, one new lock
entry; build time and exe size not measured) and the risks.

Verified: not applicable (docs). The checks of the stack: see the other
revisions.
This commit is contained in:
LGUG2Z committed 2026-11-05 15:03:26 -08:00
1 parent 0a315a61bc
commit d9da877134
1 file changed
+31 -43
+31 -43
View File
@@ -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).