Skip to content

LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.

Docs: GPU context re-creation, black windows after re-login fixed (0.8.1)

Federico Pereira7b294e7eac69
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a71c98f..e183e24 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,12 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),
name, "Chromium", in every language. The Dock tooltip and Linux app notifications use the same
short name; a real translation of the name (e.g. "Archivos") still shows, and a window without a
`.desktop` file is named after its app id. The window's own title bar keeps the title.
+- **Linux app windows are no longer black after the login screen or a lock.** With GPU
+ composition, coming back to the monitor creates a new GPU context, but each window's buffers were
+ still drawn with their textures from the old one: Chromium's window stayed black while its audio
+ kept playing. Imports now belong to one context and are made again, windows keep
+ their last frame while the session is off the monitor, and apps get the new dmabuf formats
+ ([docs/GPU.md](docs/GPU.md#when-the-gpu-context-is-re-created)).
## [0.8.0-beta] - 2026-10-18
diff --git a/docs/GPU.md b/docs/GPU.md
index 425e829..0736c43 100644
--- a/docs/GPU.md
+++ b/docs/GPU.md
@@ -69,6 +69,48 @@ direct scanout. The log says `gpu: GPU composition (renderer…)` or why not.
moving the mouse composites nothing. If the driver has no cursor plane, it's drawn as a quad
(`LORD_SW_CURSOR=1` forces it).
+## When the GPU context is re-created
+
+The EGL/GBM context does not live as long as the session. It is torn down and made again when the
+session leaves the monitor and comes back (login screen, lock, user switch: `SESSIONS.md`), when a
+remote viewer connects and leaves, when the displays change and when a frame fails. Every texture
+and EGLImage dies with its context, so:
+
+- **Each context has a generation** (`gpu_generation()`), and each `GpuTex` remembers its own.
+ A texture from an earlier context is *stale*: `gpu_draw` skips it, `gpu_tex_pixels` makes a new
+ one and `gpu_tex_free` only frees its memory (its GL name may already belong to a texture of the
+ new context, such as the UI's).
+- **dmabuf imports are cached per `wl_buffer` and per context** (`dm_tex` in `wl.c`): a buffer is
+ imported again the first time it is drawn in a new context. A failed import is remembered only
+ for that context.
+- **Going away** (`gpu_shutdown`): while the old context still works, the compositor reads back the
+ last frame of every window showing a dmabuf (`gpu_tex_read`) so the CPU path can keep drawing it,
+ and frees its textures. Off the GPU, linear dmabufs are mapped and copied as always; one the CPU
+ can't read (tiled) is held and the last good frame stays on screen. Buffers in a format the last
+ GPU context imported are still accepted while off the GPU.
+- **Coming back** (`gpu_init`): held buffers are imported again (no need to wait for the app's next
+ frame), shm textures are uploaded again and everything is repainted.
+- **Feedback:** if the format table or the device changed (GPU ↔ CPU), the `zwp_linux_dmabuf_feedback_v1`
+ objects are sent the new one, so apps reallocate buffers the new path can use.
+- **Direct scanout:** the buffers on the primary plane are released with the old context.
+
+Before 0.8.1 the cached imports and window textures were reused in the new context: after the
+login screen or a lock, Chromium's window (and other app windows, shm ones too) came back black.
+Test with `tests/gpu_cycle.sh` (needs a free card: stop `lordos.service` first; `build/seat-cycle`
+plays `lord-sessiond`'s part, lending the card and taking it back N times and saving what the CRTC
+shows). VM 119, virtio-gpu with llvmpipe (`LORD_GPU=1`), Chromium (`--ozone-platform=wayland`,
+which draws with shm there) and `dmabuf-client`, 10 and 20 cycles: Chromium keeps drawing every
+time it's shown again (before the fix it was black from the second time on), the session's fds
+stay flat (29) and RSS levels off at ~196 MB, as without the fix (llvmpipe's own memory);
+`LORD_GPU=0`, 5 cycles: 69 MB flat. The VM can't import a real GPU dmabuf (see "Untested"), so the
+re-import of an EGL-imported buffer was checked by reading the code path, not on screen;
+`gpu_tex_read` was checked against freshly uploaded textures (0 differing pixels).
+
+| | |
+|---|---|
+| ![before](gpu-relogin-before.png) | ![after](gpu-relogin-after.png) |
+| Before: Chromium black after the session came back to the monitor | After: still drawing after 10 off/on-monitor cycles |
+
## New protocols
| Protocol | Version | What it does |
diff --git a/docs/SESSIONS.md b/docs/SESSIONS.md
index 2b3d5ef..10f0234 100644
--- a/docs/SESSIONS.md
+++ b/docs/SESSIONS.md
@@ -207,6 +207,11 @@ after that the wait is 1, 2, 4… seconds, up to 5 minutes.
main process while live processes remained in the delegated tree ("Device or resource busy");
- autologin is applied only once per machine boot (`/run/lordos/autologin-done`), so a service
restart doesn't unlock a locked session.
+- **Linux app windows across a lock or a switch:** leaving the monitor tears the session's GPU
+ context down and coming back makes a new one. Every window is imported again in the new context
+ and, while the session is off the monitor, a window whose buffer the CPU can't read keeps its
+ last frame. Before 0.8.1, Chromium's window came back black (`GPU.md`, "When the GPU context is
+ re-created"; `tests/gpu_cycle.sh` repeats the off/on cycle).
In the SDK: `session.lock()`, `session.switchUser()` and `session.managed()`. The `default` and
`classic` themes show those items only if `managed()` is true.
diff --git a/docs/gpu-relogin-after.png b/docs/gpu-relogin-after.png
new file mode 100644
index 0000000..c91ce86
Binary files /dev/null and b/docs/gpu-relogin-after.png differ
diff --git a/docs/gpu-relogin-before.png b/docs/gpu-relogin-before.png
new file mode 100644
index 0000000..9a0c3ca
Binary files /dev/null and b/docs/gpu-relogin-before.png differ