Wayland layer-shell overlay (always-on-top over fullscreen games)

[raman78]

What & why

On Wayland the winit/eframe path cannot keep the metrics overlay above a full-screen game — the compositor simply won't honor always-on-top for a regular top-level. This PR renders the overlay through wlr-layer-shell on the dedicated overlay layer in a Wayland session, which is the reliable way to sit above fullscreen.

X11, Windows and macOS keep the existing always-on-top viewport, unchanged.

Note that on X11 this is only as good as the window manager's handling of _NET_WM_STATE_ABOVE: testing on KWin (via XWayland) the overlay window does appear, but it does not stay above a full-screen game. That is the pre-existing behaviour of this path and the reason the Wayland back end exists — the point of the runtime choice below is that an X11 session gets the same overlay it has today, rather than a button that silently does nothing.

Overlay

• Renders the overlay via a wlr-layer-shell surface in a Wayland session (smithay-client-toolkit + wgpu + egui), so it stays above fullscreen games.
• Draggable, with a click-through body so it doesn't steal game input.
• Remembers its position across restarts.
• Matches the main window's colors.
• Fixes for crashes when toggling the overlay off/on, closing it, and a 0×0 initial-size crash on Wayland (also proposed on its own in Fix the overlay crashing the program on Wayland #9).
• Architecture is documented in docs/OVERLAY.md.

Choosing the back end

Which back end is used is decided at runtime, not with #[cfg(target_os = "linux")]. A single Linux build has to serve both session types, and wlr-layer-shell is a Wayland protocol: in an X11 session there is nothing to connect to, and picking it there would leave the Overlay button doing nothing.

App::new only injects the shared wgpu handles when eframe's CreationContext reports a RawDisplayHandle::Wayland — the back end winit actually picked, rather than a guess — and having those handles is what OverlayInner::uses_layer_shell() asks about, so the two cannot disagree. A session without them falls back to the viewport. main.rs makes the same call one step earlier, before any window exists, the way winit does it, so an X11 session does not build a shared wgpu stack it will not use.

The selected back end is logged once at startup (overlay backend: ...).

Not included

The main-window geometry changes that used to be part of this PR (remembering the size, the redraw while resizing, the larger minimum size) had nothing to do with the overlay and are proposed separately in #8.

Notes

The Wayland/wgpu dependencies are Linux-only ([target.'cfg(target_os = "linux")'.dependencies]).

Verified on KDE: the layer-shell back end in a Wayland session, and the viewport back end in an X11 session (via env -u WAYLAND_DISPLAY).

Overlap with #8

Both this PR and #8 change the same lines of src/app/mod.rs and src/main.rs — this branch removes the window-geometry code that used to sit there, #8 adds its own version in the same place — so whichever of the two you merge first, the other will report a conflict.

Nothing for you to resolve: merge either one in any order and I will rebase the other branch and push, which updates its PR automatically. The two changes are independent in substance; only the text overlaps.

[raman78]

Pushed a revision addressing the feedback:

• Single wgpu stack. The app now creates one wgpu::Instance/adapter/device/queue at startup and hands it to eframe via WgpuSetup::Existing; the layer-shell overlay reuses the very same handles (injected through App::new → Overlay::set_gpu). No more second instance/device, and this also let me drop the old "keep the instance alive across show/hide" workaround that only existed to dodge a Vulkan teardown segfault on overlay close.

  One wrinkle worth noting: eframe 0.34's public RenderState exposes adapter/device/queue but not the instance (it's held privately in the Painter). So rather than grabbing eframe's instance after the fact, we create the instance ourselves and give it to eframe — WgpuSetup::Existing uses it verbatim for the main window, and we keep a clone for the overlay's surface. Same single instance either way.

• Module folder. The overlay moved into app::overlay, with the Linux layer-shell backend under overlay::layer_shell.

• While in there I also modernized some deprecated egui calls (Context::run/style, CentralPanel::show, SelectableLabel) and switched the overlay to adopt the main window's full Style instead of just its Visuals.

One thing I deliberately left out: proper HiDPI/fractional-scale handling for the overlay surface (it still renders at ppp = 1.0). I'm on a 1× display and didn't want to land scaling code I can't actually verify — happy to do it as a follow-up if you'd like it in this PR.

Let me know what else you'd like changed.

[raman78]

Narrowed this down to the overlay. The main-window geometry work that was bundled in here (remembering the window size, redrawing while resizing, and the larger minimum size) was unrelated to it and made this branch touch main.rs and the settings struct for reasons a reviewer of an overlay change should not have to care about. It now lives in #8, and the diff here no longer changes anything about the main window.

[raman78]

Follow-up: the back end is now picked per session rather than per target OS. As it stood, every Linux build went to wlr-layer-shell, which meant that in an X11 session the layer thread failed at Connection::connect_to_env, logged an error and exited, and the Overlay button did nothing — a regression against the always-on-top window those users have today. Both back ends are now compiled on Linux and the choice comes from the display handle eframe reports. Verified on KDE in both session types.