x11-session-research/README.md

# x11-session-research

> **Status: PHASE 0 — motivation locked 2026-05-03.**
> See [`phase0_findings.md`](phase0_findings.md) §
> "Research question (LOCKED 2026-05-03)". Phase 1 still
> requires the four pre-question Phase 0 deliverables
> (state snapshot, X11 path inventory, browser-overlay-path
> inventory, **own** baseline anchor) before binding cells
> lock.

**Research question:** Does cutting out the KWin compositor
enable faster video display of Brave, chromium-fourier, and
Firefox — for full SW decoding, and for libva decoding (where
possible) — on PineTab2 RK3568?

The operator-supplied mechanism: hantro decodes to NV12;
rockchip-drm's overlay plane cannot accept NV12, so on Wayland
KWin must own the only NV12-capable plane (Primary, Plane 39)
for its compositor framebuffer, which forces a GL-composite
of every NV12 video buffer. X11 + non-compositing WM can give
the video region directly to Plane 39 (NV12 native) and put
the rest of the desktop on Plane 45 (RGB AFBC), avoiding the
forced GL-composite. **The campaign's load-bearing hypothesis
is that this plane-allocation freedom translates into
measurable browser-video speedup.**

The matrix is (3 browsers + mpv 0.41 as a reference X11-overlay
client) × 2 decode paths × 2 sessions = 16 cells (some N/A
where libva isn't supported). The mpv cells are run twice each
— once with `--vo=xv` (legacy XVideo overlay) and once with
`--vo=gpu --gpu-context=x11` (modern DRI3 + XPresent + Mesa GL).
See `phase0_findings.md` § "Experimental matrix" for the full
table and the rationale for mpv as reference baseline.

## Campaign-contained data discipline

**This campaign acquires all its own measurement data from
scratch in this session. Numbers, baselines, and verdict
thresholds from predecessor campaigns are NEVER imported as
binding cells, comparison targets, or success criteria.**

Predecessor campaigns are documented for *context* — what
question was asked, what file:line pointers stay valid for
source-reading, what tooling/state on ohm carries over. But
their *measurement numbers* (drop counts, perf percentages,
Δ_present medians, kwin %CPU values) **are reference history
only, not data this campaign relies on**.

The discipline lesson is concrete:
[`../kwin_overlay_subsurface/phase8_handover.md`](../kwin_overlay_subsurface/phase8_handover.md)
closed 2026-05-03 without patch because its Phase 1 binding
cells were anchored to a single historical measurement
(`ohm_gl_fix` Phase 0: cage = 7 drops total / 0 post-warmup).
That baseline was treated as a stable property of the
hardware × software stack and the campaign's whole phase
plan was built around closing the gap to it. When the same
condition was re-measured at N=3 in the closing session of
the campaign, none of the three reps reached 0 post-warmup
drops; the median was 26. The campaign's premise didn't
hold up to in-session replication, three weeks of phase
planning ended at Phase 8 close-out, and the lesson is now
[`feedback_replicate_baseline_first.md`](../kwin_overlay_subsurface/.claude/projects/-home-mfritsche-src-kwin-overlay-subsurface/memory/feedback_replicate_baseline_first.md)
in this session's memory.

This campaign acts on that lesson by stronger discipline:

- Every Phase 1 binding cell anchors to data acquired in
  this campaign's session.
- Predecessor *measurements* never appear in
  `metrics.csv`. Predecessor *file:line source-reads,
  protocol designs, parser scripts* may be referenced or
  re-used as durable substrate.
- The Phase 0 "A1 baseline" rep is not optional. It is the
  Wayland-with-KWin reference rep acquired at the start of
  this campaign, against which the X11 cells of the matrix
  will be compared. The predecessor's matching numbers are
  not used as a substitute even if they look identical.
- If a measurement instrument behaved one way in a
  predecessor campaign, that behavior is re-verified here
  before being relied on (see Phase 0 X11 measurement-tool
  inventory).

If a measurement in this campaign happens to match a
predecessor's number, that's a useful corroboration of
reproducibility — but it cannot substitute for in-session
acquisition.

## Predecessor campaigns

This campaign is the third in a chain on the same hardware
target:

1. [`../ohm_gl_fix/`](../ohm_gl_fix/) — closed 2026-05-02.
   Diagnosed and patched the Step 1 (`libva-v4l2-request`)
   and Step 2 (Chromium `WaylandBufferManagerHost`
   overlay-route) issues. Spun off the Wayland-compositor-
   path question into a separate campaign because that
   question had a different code surface, upstream, and
   reviewer culture.
2. [`../kwin_overlay_subsurface/`](../kwin_overlay_subsurface/)
   — closed 2026-05-03 without patch
   (`phase8_handover.md`). Diagnostic loop terminated at
   "Phase 0 cage = 0 post-warmup drops floor not
   reproducible at N=3" — the inherited baseline turned
   out to be N=1 historical and didn't replicate in-session.
3. **This campaign** (`x11-session-research`) — opened
   2026-05-03. Tests whether bypassing the KWin compositor
   via X11 + non-compositing WM avoids the forced
   NV12 → RGB GL-composite step the predecessor identified
   as a structural Wayland constraint on rockchip-drm.

Durable substrate from the predecessors that this campaign
*may* read (not import-as-data):

- `kwin_overlay_subsurface/phase2_source_findings.md` —
  KWin scanout-promotion archaeology (Plane 39 / Plane 45
  format/modifier table on rockchip-drm RK3568); Phase 2-prime
  Shape C source-read of `Display::dispatchEvents` and
  `TransactionFence` (Wayland-side, doesn't transfer to X11
  but illustrates the per-frame dispatch shape).
- `kwin_overlay_subsurface/phase3_protocol_prime.md` — the
  measurement-protocol structure (operator-vs-Claude split,
  pre-registered hypothesis, falsification table, evidence
  layout). The structural template is reusable. The specific
  numbers and threshold values **are not**.
- `kwin_overlay_subsurface/scripts/wayland_debug_to_csv.py` —
  parser for libwayland WAYLAND_DEBUG output. Useful for the
  Wayland cells of this campaign's matrix; an X11 equivalent
  is yet-to-build.

## Hardware target (same as predecessors)

ohm — PineTab2, Rockchip RK3568 (4× Cortex-A55, Mali-G52 MP2,
hantro G1/G2 VPU). Kernel `6.19.10-danctnix1-1-pinetab2`.
Mesa 26.0.5. Currently runs KDE Plasma 6.6.4 Wayland.

For an X11-session campaign, ohm needs an Xorg + non-compositing
WM install path verified. As of 2026-05-03, the only confirmed
display path on ohm is `startplasma-wayland`. Phase 0 inventory
will catalog what's installed, what'd need installing, and
what SDDM-advertised sessions exist.

## Carry-overs from predecessor (system state, not data)

Per `../kwin_overlay_subsurface/phase1_evidence/ohm_tooling_revert_log.md`:

- `qt6-base-fourier 1:6.11.0-3` installed.
- `kwin-fourier 1:6.6.4-3` installed.
- CPU governor pinned to `performance` (was `conservative`).
- Baloo permanently disabled
  (`Indexing-Enabled=false` in `~/.config/baloofilerc`).
- `drm-info 2.9.0-1` installed.

These were not reverted at the predecessor's close-out. This
campaign inherits them as **system state**, distinct from
**measurement data**. A different system state (e.g. a fresh
Plasma session, or the same packages but different uptime)
might produce different measurements; this is exactly why
in-session baseline acquisition matters.

## Non-upstreaming default

Inherited from the predecessors. Bug reports + MRs are
explicit operator-tasked decisions, not background process
steps.

## File map (will grow)

| File | What it is |
|---|---|
| `README.md` | This file. |
| `phase0_findings.md` | Locked motivation + experimental matrix + open questions before Phase 1. |
| `worklist.md` | Phase-by-phase task list. |
| `phase0_evidence/` (created when first run lands) | Phase 0 inventory + A1 baseline rep. |

## Repository

`ssh://gitea@git.reauktion.de:2222/marfrit/x11-session-research.git`
(public). Cloned/pushed via SSH on port 2222 per the home-infra
gitea convention.