docs(windows-rewrite): track the fullscreen-game capture bug as a related workstream

Cross-reference docs/windows-host-rewrite-game-capture-bug.md from the remediation tracker, with the intersections that matter for whoever implements it: Stage 1 builds on (doesn't duplicate) our C1 mid-/open-time fallback; the bug doc is written against pre-remediation main (a11b0dd) so its line refs are stale; Stage 2's new SharedHeader fields must update A's offset asserts (in lib.rs frame mod); Stage 0/S3 diagnostics need the driver log B3 gated off in release; S1/S2 is adjacent to E1. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 14:40:16 +00:00
parent 5d279f8886
commit dbab1f98ba
1 changed files with 32 additions and 0 deletions
@@ -88,6 +88,38 @@ driven by a human** (driver install + client connect).
 - **Push** to run the full CI matrix — the local host checks use `--features nvenc` only (no FFmpeg), so the
  `amf-qsv` encode path is unexercised locally; CI (`windows-host.yml`) covers it.
 ## Related workstream — fullscreen-game IDD-push capture bug (separate doc)
 A **separate, newly-found bug** (NOT an audit finding) in the same IDD-push subsystem, with its own staged
 fix plan: [`docs/windows-host-rewrite-game-capture-bug.md`](windows-host-rewrite-game-capture-bug.md).
 **Symptom:** launching a fullscreen game (Doom the Dark Ages) on an HDR IDD-push stream flashes the desktop,
 the game never shows, and reconnect = black screen + working audio. **Root cause:** the IDD-push ring is
 fixed format+size at session start; the driver silently drops every frame whose surface descriptor no longer
 matches (a game forces a mode-set); the host has no channel to learn the descriptor changed; and there is no
 mid-session fallback → 20 s `bail!`.
 **Intersections with this remediation — read before implementing:**
 - **Stage 1 builds on our C1 (`ed58365`); do not duplicate it.** C1 added an IDD-push→DDA fallback, but
  **open-time only** (driver never attaches). The game bug is **mid-session** (attached, then a game changes
  format/size). The bug doc's Stage 1 (a composing capturer that fails over mid-session) is the
  generalization — build it on C1's `open()`-returns-keepalive + bounded-attach infrastructure.
 - **The bug doc was written against pre-remediation `main` (`a11b0dd`).** Its line numbers and its claim
  "`capture.rs:348-356` … no fall-through" are **stale after our 9 commits** (C1 changed exactly that).
  Rebase on current `main` first.
 - **Stage 2 (new `SharedHeader` fields + `PROTOCOL_VERSION` bump)** must update the **`offset_of!`/size
  asserts added in A (`95dcef3`)** — they catch drift at compile time (the intended safety net). Note: those
  asserts live in the `frame` module of `crates/pf-vdisplay-proto/src/lib.rs` (the doc says `frame.rs`).
 - **Stage 0 / S3 diagnostics rely on the driver log**, which **B3 (`0a7ae5e`) gated off in release builds**
  (`debug_assertions || PFVD_DEBUG_LOG`). Enable it (`PFVD_DEBUG_LOG=1` or a debug build) for the repro.
 - **S1/S2 (driver swap-chain resilience)** is adjacent to **E1** (same `swap_chain_processor.rs`/
  `callbacks.rs`); coordinate so they don't conflict.
 - The bug doc's "doc-lag" note (`stage-pf-vdisplay.ps1` still names the old `vdisplay-driver/` tree) is part
  of our **G / M6** packaging cleanup.
 **Stages (detail in the bug doc):** Stage 0 diagnostics (S3) → Stage 1 mid-session fallback (P3, host-only,
 the user-visible fix) → Stage 2 adaptive ring (P1/P2; proto bump + driver re-vendor) → Stage 3 trim
 advertised modes → Stage S driver resilience (S1/S2). Tracked as GB0–GB3 in the task list.
 ## Verification
 The persistent validator is the **RTX box** `ssh "Enrico Bühler"@192.168.1.158` (ENRICOS-DESKTOP, RTX 4090,