punktfunk/docs/host-latency-plan.md

# Host latency & the GPU-contention collapse — analysis + prioritized plan

Scope: Windows + Linux GameStream/punktfunk1 hosts. Priority: **latency**, and specifically the
"saturating game starves the stream" headache:

> CS2 runs 400+ fps. Client requests 240. In an easy scene the client gets ~200; in a demanding
> (GPU-100%) scene it collapses to 40-50. Capping the game is **not** an acceptable fix.

This doc is the synthesis of a multi-agent investigation (deep read of our pipeline + the
[Apollo comparison](apollo-comparison.md) + external NVIDIA/streaming research) followed by an
**adversarial verification pass** — every candidate fix was attacked, against our actual code, to
separate real levers from placebo. The "Dropped / why" section exists so we don't re-propose the
placebos.

## Implementation status (2026-06-18)

- ✅ **Tier 2B — Linux scheduling hygiene**: landed. `boost_thread_priority` now nices the
  capture/encode + send threads on Linux (`setpriority`, best-effort) and its wrong gamescope
  doc-comment is fixed; CUDA context uses `CU_CTX_SCHED_BLOCKING_SYNC`; copies run on a per-thread
  highest-priority CUDA stream (`cuStreamCreateWithPriority`, graceful NULL-stream fallback) with a
  per-stream sync that no longer blocks on the other worker thread's work. Builds + clippy + fmt
  green. The stream-priority hint is **measure-then-keep** (NVIDIA Linux may ignore it).
- ✅ **Tier 3A — Windows session tuning**: landed (`session_tuning.rs`, raw C-ABI FFI, no-op off
  Windows). Each capture/encode/send thread now applies process-wide tuning once (1 ms timer,
  `DwmEnableMMCSS`, `HIGH_PRIORITY_CLASS`) and per-thread MMCSS "Games" + keep-display-awake. Wired
  into both the native (`boost_thread_priority`) and GameStream (`stream.rs`) paths. Linux no-op
  path builds green; the Windows path is validated by the Windows CI runner / on-box.
- ⏳ **Tier 2A — Linux NV12 convert**: specified to the code level (below) but **not landed** — it is
  a ~300-line, colour-correctness-critical change that cannot be A/B-validated on the headless dev
  VM (no display; the project has already been burned by the exact green-screen failure mode this
  risks — Steam-Deck `SEPARATE_LAYERS` bug). Execute + A/B it on a GPU box **with a display**.

---

## 0. Three corrections to the mental model (read first)

**(A) "Feed NVENC RGB so the ASIC does the colour-convert" is backwards.**
NVENC's encode core is YUV-native. RGB input makes the driver insert an **RGB→YUV CSC on the
SM/3D-compute cores** — the *exact* engine a game saturates. Windows already does the right thing:
`convert_to_yuv` runs the CSC on the dedicated **VIDEO engine** via `VideoProcessorBlt`
(`capture/dxgi.rs:1023,1063`), logged as "0% 3D". **Linux still feeds NVENC RGB**
(`encode/linux.rs:98 nvenc_input` → `RGBZ`/`BGRZ`; the `zerocopy/egl.rs:98` shader is a `.bgra`
*swizzle*, not a CSC), so it pays NVENC's internal CSC on the SM every frame. That is the single
biggest, clearly-fixable contention source on Linux, and Windows already eliminated it.

**(B) "More GPU priority so our frames get through" is already maxed on Windows, and hits a
hardware ceiling.** We ship `D3DKMTSetProcessSchedulingPriorityClass=HIGH(4)` +
`SetGPUThreadPriority(0x4000001E)` + `SetMaximumFrameLatency(1)` (`capture/dxgi.rs:160-263`). The
residual ~20 ms `lock_bitstream` wall (documented at `dxgi.rs:155`) is GPU **context-scheduling
latency**, bounded by **preemption granularity**: NVIDIA preempts *compute* at instruction level
(~0.1 ms) but *graphics* only at coarse draw/tile/DMA-buffer boundaries (milliseconds out under a
draw flood). No priority class preempts an in-flight game draw. So the winning strategy is **not
more priority** — it is (1) do **less work on the contended graphics/3D engine**, and (2) **overlap
the unavoidable per-frame scheduling wait across frames** to recover throughput.

**(C) A chunk of the collapse is upstream of our encoder — no encode/priority fix can beat it.**
DXGI Desktop Duplication *and* WGC both capture **from the DWM compositor**, so captured fps is
hard-ceilinged at the **compose rate**, never the game's 400 fps. Under saturation the *compositor
itself* is scheduled late → composes fewer unique frames → we starve even though NVENC is idle. And
borderless/fullscreen games on **Independent/Direct Flip** present straight to scanout, *bypassing
DWM*, so capture sees ~half the frames (this is the "200 not 240"). The host already paces at
`target_fps` and **re-encodes held frames**, so *transmitted* fps stays ~240 while *unique* fps
collapses. **This must be measured before blaming encode.**

> Net: Windows is already near best-in-class (priority + video-engine CSC + encode|send split all
> shipped); its remaining wins are narrow and partly a hardware/compositor ceiling. **Linux is the
> least-hardened host and holds most of the headroom.**

---

## Tier 0 — Diagnose first (cheap, decisive, do before writing code)

Everything below is gated on knowing *which* bucket the collapse is in. We already have the tooling.

1. **Run the workload with `PUNKTFUNK_PERF=1` and read `uniq` vs `fps`.** The `uniq` counter
   (genuinely-new captured frames vs re-encoded holds) already exists
   (`gamestream/stream.rs:332-336,403`; `wgc_helper.rs:122-183`). Under CS2 at GPU-100%:
   - **`fps`≈240 but `uniq`→40-50** ⇒ the *source/compositor* only produced 40-50 unique frames.
     No encode/priority/cadence fix on our side exceeds that — it is the game's effective
     present-to-compose rate at 100% GPU. The lever there is **reducing our own per-frame GPU
     steal** (Tier 2) so the game keeps more headroom, plus the cadence work (Tier 1A).
   - **both `fps` and `uniq`→40-50** ⇒ our capture→convert→encode round-trip is being starved (the
     `lock_bitstream` scheduling stall). The Tier 1/2 contention levers apply directly.
2. **Confirm the game's flip mode on Windows.** If the game is on Independent/Direct Flip (MPO),
   capture is bypassing DWM and seeing half the frames. We already have `capture/composed_flip.rs`
   — verify ForceComposedFlip is actually engaged on the game path, and watch `cap_us`.
3. Capture `cap_us` / `enc_us` / `pace_us` p50/p99 alongside, to localise the stall.

Run this on the real-GPU boxes (RTX 4090 Windows host; a Linux NVIDIA box with a real game). This
headless dev VM cannot reproduce the contention.

---

## Tier 1 — The two under-weighted, cross-platform levers (confirmed by research, not yet done)

### 1A. Capture-source / compose-rate cadence (where "200 not 240" actually lives)
The capture ceiling is the compositor's compose rate, and under load the compositor gets starved.
Levers, in order:
- **Force Composed Flip on Windows** for the game path (defeat MPO/flip-metering frame loss).
  Machinery exists (`composed_flip.rs`); confirm it engages and measure the unique-frame delta.
- **Opt-in "double-refresh" virtual output**: create the per-session virtual output at ~2× the
  client's rate to break the game-present-vs-compose beat (community-validated; cheap for us since
  we already mint arbitrary-mode virtual outputs). Gate **off** by default and **never** on the
  gamescope/SudoVDA game-attach path (no DWM beat there; it just adds compose work to the saturated
  engine). `PUNKTFUNK_OUTPUT_HZ_MULTIPLIER`.
- **Reflex / render-queue=0 style headroom** (non-capping): documented as the substitute for an fps
  cap — removes render-queue backpressure so the compositor/capture get scheduled. Investigate what
  we can influence from the host side.

Risk: the double-refresh trick can be a net regression under saturation (doubles compose + our
capture work on the saturated engine) — measure (Tier 0) before shipping it on by default.

### 1B. Pin GPU power / clock state for the session (kills the per-frame downclock tax)
NVIDIA's adaptive P-state downclocks between our small bursty frames and pays a ramp every frame —
a hidden latency tax, *most visible in easy scenes* (the ~200-should-be-240 case). Sunshine ships
this as `nvenc_latency_over_power` and calls it decisive. **Neither host does it.**
- **Windows**: NvAPI **per-application DRS profile** `PREFERRED_PSTATE = PREFER_MAX` scoped to our
  exe (not a global override). Load `nvapi64.dll` dynamically; treat `NvAPI_Initialize` failure as
  "no NVIDIA, skip" (covers AMD/Intel + the WARP dev VM). **Crash-safe undo is mandatory**: write
  an undo record to `%ProgramData%\punktfunk\` *before* applying and revert a stale profile on next
  startup — a crash must not leave the user's control panel modified.
- **Linux**: prefer the **root-free** path — disable the CUDA "Force P2 State" downclock that
  context creation triggers (env/per-context), and `nvidia-smi -pm 1` (persistence) where
  permitted. `nvmlDeviceSetGpuLockedClocks` needs root/CAP_SYS_ADMIN (our host runs as a normal
  user → silent no-op) and is brittle across SKUs; if used, query `nvmlDeviceGetMaxClockInfo`, lock
  to *that*, and restore on teardown **and** via a SIGTERM/panic handler.
- Gate behind `PUNKTFUNK_PIN_CLOCKS`; **default OFF on battery / Steam Deck** (thermal/power caps
  make pinning actively harmful there).

Impact: reliable, modest p99 / easy-scene win on both OSes. Does **not** fix the saturated-scene
collapse (at 100% util the clock is already maxed). Low cost.

---

## Tier 2 — Linux work-deletion + scheduling hygiene (the biggest in-our-control headroom)

### 2A. Produce **NV12/P010** on Linux and feed it to NVENC native (delete the SM-side CSC)
The strictly-correct version (verified): **extend the existing GL de-tile blit
(`zerocopy/egl.rs`) to emit NV12** instead of swizzled BGRx — multi-render-target (GL_R8 luma
full-res + GL_RG8 chroma half-res, or two passes) applying an **explicit BT.709 limited-range
matrix matching the Windows `VideoConverter`** (`dxgi.rs:957`) so hosts look identical — then
register `NV_ENC_BUFFER_FORMAT_NV12` with the encoder (teach `encode/linux.rs:98 nvenc_input` an
NV12 case; `CudaHw sw_format` → `AV_PIX_FMT_NV12`).
- Net: today = GL swizzle (3D) **+** NVENC-internal CSC (SM); after = GL CSC (3D, ~same cost as the
  swizzle it replaces) **+ zero NVENC CSC**. Removes one whole CSC pass and removes it from the SM.
- **Do *not* implement this as a standalone CUDA convert kernel on the tiled path** — CUDA can't
  sample a tiled NVIDIA surface (`cuGraphicsEGLRegisterImage` is Tegra-only, `egl.rs:6-12`), so it
  would still need the GL detile, *and* a CUDA kernel runs on the same saturated SM. The CUDA-kernel
  route is only clean on the **LINEAR/Vulkan-bridge (gamescope)** path, where it doubles as the NV12
  producer; do it there if/when that path needs it.
- Pitfalls: pervasive 4-byte-pixel assumptions break with NV12 — `cuda.rs` hardcodes
  `WidthInBytes = width*4` (`:363,392,499`), `BufferPool`/`alloc_pitched` assume 4 B/px, GL dst is
  `GL_RGBA8`; all need a plane-aware NV12 variant (luma W·H + chroma W·H/2, two-plane copy) or you
  get the Steam-Deck green-screen class of bug. The HDR/10-bit path needs P010, not NV12.
- Impact: real, **modest, compounding** — a few ms of per-frame GPU time and a shorter time-slice
  need, which stacks with cadence + power-pin. **Not** a standalone cure for the 240→40 collapse
  (external "47→100 fps" numbers are other people's non-zero-copy pipelines; don't promise them).
  Medium cost. Gate behind a `PUNKTFUNK_*` env and A/B `cap→encoded` p50 + the CS2 fps floor.

### 2B. Linux scheduling hygiene (cheap; the priority bits are "measure-then-keep")
Consolidates the genuine parts of several candidates. Mostly unambiguous cleanups + opt-in
priority:
- **Arm the Linux `boost_thread_priority` no-op** (`punktfunk1.rs:1856` cfg branch): best-effort
  `libc::setpriority(PRIO_PROCESS, 0, -10/-5)` on the calling thread (tid 0 = self), log-and-continue
  on EPERM. **Do not** default to SCHED_RR/FIFO (can starve the compositor and the game's render
  thread — the user refuses to add game frame-time); offer it only behind `PUNKTFUNK_SCHED_RR=1`.
  **Fix the wrong doc-comment** at `punktfunk1.rs:1834-1835` ("the Linux host caps the game via
  gamescope, so its threads aren't starved") — false for the uncapped/NVIDIA-direct path.
- **Set CUDA context scheduling deliberately**: `cuCtxCreate` flag `CU_CTX_SCHED_BLOCKING_SYNC` on
  this shared VM (frees a core vs the default AUTO/SPIN) — a CPU-efficiency fix, not throughput.
- **High-priority CUDA stream + EGL context priority** (the missing analogue of the Windows
  hardening): `cuStreamCreateWithPriority(highest from cuCtxGetStreamPriorityRange)` for our copies;
  request `EGL_IMG_context_priority HIGH` (try `EGL_NV_context_priority_realtime`) at
  `egl.rs:332`. **Caveat, load-bearing**: these are intra-process *hints* and NVIDIA's Linux driver
  has been reported to **ignore** context priority (driver 545: high- vs low-priority EGL contexts
  measured identical) and to **deny** realtime Vulkan queues. Implement with graceful fallback,
  gate behind env, and **measure on driver 595** — do not architect around it or credit it before
  measurement.

> Explicitly **not** doing on Linux: Vulkan `VK_EXT_global_priority` as "the" lever (it only touches
> the minority gamescope/LINEAR copy, not the convert; likely a silent no-op on consumer NVIDIA).
> Replacing `cuCtxSynchronize` with a per-stream event chain for *contention* reasons (it's
> per-context, never waited on the game's separate context — a non-fix; keep the full sync where it
> guards dmabuf recycle, `egl.rs:491`).

---

## Tier 3 — Windows parity polish (Windows is already strong)

- **3A. Host-process session tuning (we have *zero* today — verified):** `NtSetTimerResolution(0.5ms)`
  / `timeBeginPeriod(1)` (default 15.6 ms granularity blocks precise pacing), `DwmEnableMMCSS(true)`,
  `SetPriorityClass(HIGH_PRIORITY_CLASS)`, MMCSS-register the capture/encode threads ("Games"/"Pro
  Audio"), `SetThreadExecutionState(ES_CONTINUOUS|ES_DISPLAY_REQUIRED)`. All revert on stop.
  Foundational for any precise frame pacing and the encode|send split. Low cost, low risk.
  (`gamestream/stream.rs` start/stop; Apollo's `streaming_will_start`/`_stopped`.)
- **3B. Auto-gated REALTIME D3DKMT class** instead of fixed HIGH (the realtime opt-in already exists
  at `dxgi.rs:199-207`): probe HAGS (`D3DKMTQueryAdapterInfo` `HwSchEnabled`) **and** VRAM headroom
  (`IDXGIAdapter3::QueryVideoMemoryInfo`, continuously), allow REALTIME(5) only when safe (HAGS off,
  or HAGS on + VRAM comfortably below budget), downgrade to HIGH the moment VRAM pressure rises —
  Sunshine's actual gate avoids the HAGS+near-full-VRAM NVENC freeze/crash. Marginal (one scheduling
  rung, same preemption ceiling), so rank it as cheap parity, not a fix.
- **3C. Cheap experiment — `VideoProcessorBlt` directly from the DDA surface** (skip the same-format
  `gpu_copy` at `dxgi.rs:2375`), then `ReleaseFrame`, *iff* it doesn't re-serialize `AcquireNextFrame`
  (the existing decouple-copy was measured 40-200 fps vs ~60 fps, but that note predates confirming
  the Blt is on the video engine). One-line source-texture change; benchmark only. Do **not** build a
  D3D11↔D3D12 copy-queue offload — the convert is already off-3D, the remaining copy is intra-VRAM
  (~5% 3D, no PCIe), not worth the interop rebuild.
- **3D. Async NVENC + off-thread retrieve — measure-gated, uncertain.** Today retrieve
  (`lock_bitstream`) runs **inline on the submit thread** (`nvenc.rs:524-558`), which is *why*
  `depth>1` was measured to regress (`wgc_helper.rs:111-114`). The NVENC guide mandates submit/retrieve
  on separate threads with completion events + a deep surface pool; doing that *could* let per-frame
  scheduling waits **overlap across frames** and recover *throughput* — at a per-frame *latency* cost
  (depth × frame time). This is the one place the research and our own prior measurement disagree, so
  it is **strictly measure-first**, and it forecloses slice output (`reportSliceOffsets` needs
  `enableEncodeAsync=0`). Treat as a structural experiment, not a committed win.

---

## Tier 4 — Deferred 2nd-order latency (not contention fixes; do after Tiers 0-2)

- **GL2 — Intra-refresh for RFI/recovery** (`enableIntraRefresh` + recovery-point SEI) instead of a
  forced full-IDR: spreads a moving intra band across N frames, killing the 20-40× keyframe size
  spike and the VBV-overshoot drops it causes. Preconditions (infinite GOP, P-only) already met.
  Medium; needs all 4 clients to trust the recovery-point SEI and stop demanding IDRs. Real p99 win,
  orthogonal to the collapse.
- **GL1 + GL6 — Sub-frame slice output + per-slice paced send** (the roadmap's "~2-4 ms lever"):
  `enableSubFrameWrite` + `sliceMode` + transmit each slice as it completes. **Big**: needs the
  direct NVENC SDK on Linux (libavcodec emits whole AUs) **and** a per-slice wire/FEC redesign in
  `punktfunk-core` (today `PacketHeader`/`Packetizer`/reassembler are whole-AU; per-slice FEC blocks
  wreck Leopard efficiency) **and** client slice-granular submit. Gate on
  `NV_ENC_CAPS_SUPPORT_SUBFRAME_READBACK` (often absent on consumer GeForce). The paced-send half is
  **already shipped** (`stream.rs spawn_sender`, `punktfunk1.rs paced_submit`) — don't re-implement.

---

## Dropped / why (so we don't re-propose placebo)

| Candidate | Verdict | Why |
|---|---|---|
| Feed NVENC ARGB to "offload CSC to ASIC" | ✗ backwards | RGB input forces CSC onto the SM; YUV-native is correct (see §0A). |
| Replace `cuCtxSynchronize` with per-stream event chain *for contention* | ✗ | `cuCtxSynchronize` is per-context, never waited on the game's separate process; single null stream = no overlap to win. Keep the full sync where it guards dmabuf recycle. |
| Vulkan `VK_EXT_global_priority` as the Linux priority lever | ✗ | Touches only the minority gamescope/LINEAR `vkCmdCopyBuffer`, not the convert; consumer NVIDIA denies realtime / ignores it. Retarget to CUDA/EGL priority. |
| Async NVENC as a *throughput/collapse* fix | ✗ (→ measure-gated 3D) | Async is CPU-thread-only (NVIDIA guide); Apollo's own PR #3629 measured no gain; our `depth>1` regressed; Linux-impossible. Kept only as the structural pipelining experiment (§3D). |
| D3D12 copy-queue offload of the DDA copy | ✗ | Convert already off-3D; remaining copy is intra-VRAM ~5%, no PCIe — not worth a D3D11↔D3D12 interop rebuild. |
| Empty-frame (`LastPresentTime==0`) skip | ✗ for this | Static desktop already coalesced via WAIT_TIMEOUT; under a 400 fps game there are no empty frames to skip. |
| GL5 — set ULL RC knobs explicitly | ✗ (audit only) | ULL preset already sets `zeroReorderDelay=1`, lookahead/multipass/AQ off; ffmpeg defaults match + we set `bf=0`. Only `lowDelayKeyFrameScale=1` is non-redundant → fold into GL2 (Windows SDK path only). |
| GL3 — true ref-frame invalidation | ✗ for this | No lost-range protocol signal (both control planes collapse to a bool/unit); libavcodec exposes no `nvEncInvalidateRefFrames`; deeper DPB adds per-frame cost. Revisit only as loss-recovery robustness. |
| GL4 — move input injection off the ENet thread | ✗ for this | CPU-side, orthogonal to GPU contention; the blocking case is a once-per-UAC desktop switch. Demote to control-plane robustness. |
| SCHED_RR/FIFO by default (Linux) | ✗ default | Can preempt the compositor + the game's render thread → adds game frame-time the user refuses. Opt-in only. |

---

## Recommended order of attack

1. **Tier 0 diagnose** on the real boxes — settles whether the collapse is source-ceiling or
   pipeline-starvation, and whether flip-bypass is halving capture.
2. **Tier 2A (Linux NV12)** + **Tier 2B (Linux scheduling hygiene)** — the largest in-our-control
   headroom; Linux is the least-hardened host.
3. **Tier 1B (clock/power pin)** both OSes — cheap, fixes the easy-scene 200-vs-240, crash-safe undo.
4. **Tier 1A (cadence/flip)** — gated on Tier 0 (this is where a big chunk of the collapse may live).
5. **Tier 3 (Windows polish)** — session tuning is the clear win; the rest is parity.
6. **Tier 4** — only after the contention work; intra-refresh first, slice pipelining last.

Honest expectation: with the work-deletion + cadence + power-pin levers stacked, the easy-scene gap
closes and the saturated floor rises, but a residual ceiling remains — at 100% GPU the game
physically cannot also render the game *and* compose 240 unique frames, and WDDM/NVIDIA preemption
granularity caps how far priority can claw back. Report that ceiling honestly rather than chasing it
with encoder micro-optimisations.