diff --git a/docs/roadmap.md b/docs/roadmap.md index 6b3e18f..cf27e3b 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -2,9 +2,14 @@ Decided 2026-06-10 (research-grounded; see commit history). Sequence: **KDE reliability → client compositor options → mic passthrough → Bazzite COPR RPM (then -bootc) → touch → full UHID DualSense → iOS.** +bootc) → touch → full UHID DualSense → iOS** (+ Windows host, scoped & deferred). -## 1. Reliable headless KDE/compositor spawning *(in progress)* +**Done (2026-06-10):** #1 KDE reliability (Phase 1 + 2), #2 compositor options (full stack incl. +macOS client), #4 mic passthrough — all on `main`, live-validated. #3 Bazzite packaging written +(`packaging/`); the COPR/bootc build is operator-run. Remaining: #5 touch → UHID DualSense, #6 iOS, +and a Windows host (`docs/windows-host.md`). + +## 1. Reliable headless KDE/compositor spawning ✅ *(done — Phase 1 + 2)* Startup is a chain of timing-sensitive handoffs with no readiness checks — each is a blind `sleep`, one-shot timeout, or silent fire-and-forget that fails into a black screen. @@ -23,17 +28,21 @@ Startup is a chain of timing-sensitive handoffs with no readiness checks — eac - **Phase 3 (L):** supervised systemd user session (kwin + portal + host) with the readiness probe as an `ExecStartPost` gate, `Restart=on-failure`. -## 2. Offer available compositors in the client *(M)* +## 2. Offer available compositors in the client ✅ *(done)* Host enumerates which backends are actually available (binary present + version OK: gamescope ≥3.16.22, KWin ≥6.5.6, gnome-shell, sway), advertises the list in the punktfunk/1 Welcome + a mgmt-API field; client sends its pick in the Hello; host honors it per session. Picker in the Apple client + web console. -## 3. Bazzite / install on other devices *(decision: COPR RPM → bootc)* +## 3. Bazzite / install on other devices ✅ *(packaging written — `packaging/`)* Bazzite already ships gamescope + PipeWire + the NVIDIA driver (incl. `libnvidia-encode`); it's Fedora-atomic and the community installs Sunshine via COPR rpm-ostree — the analog. +Written: `packaging/rpm/punktfunk.spec` (builds the host from source), `packaging/bootc/Containerfile` +(`FROM bazzite-nvidia`), `packaging/bazzite/host.env` (gamescope default), `packaging/copr/` + +`packaging/README.md`. The build itself is operator-run (COPR / a Fedora toolbox; not buildable on +the Ubuntu dev box). `LICENSE-{MIT,APACHE}` added to match the declared dual license. - **M-Bazzite-1:** a **COPR RPM** (primary) — binary + `60-punktfunk.rules` (→ `/usr/lib/udev/rules.d`) + systemd `--user` unit + `host.env.example`; `Requires` the @@ -45,7 +54,7 @@ it's Fedora-atomic and the community installs Sunshine via COPR rpm-ostree — t - Flatpak only later as an explicitly-degraded convenience build (sandbox fights zero-copy NVENC/dmabuf/uinput). -## 4. Mic passthrough — client mic → host input device *(S+M)* +## 4. Mic passthrough — client mic → host input device ✅ *(done — host side)* The exact mirror of the host→client desktop-audio path. A PipeWire virtual source apps can select = a `pw_stream` with `Direction::Output` + `media.class=Audio/Source`. @@ -75,3 +84,15 @@ select = a `pw_stream` with `Direction::Output` + `media.class=Audio/Source`. PunktfunkKit is already platform-shared; iOS needs the `UIViewRepresentable` presenter twin + touch capture (#5) + UI. tvOS later. + +## 7. Windows as a host *(scoped & deferred — `docs/windows-host.md`)* + +Architecturally an "add a backend" job, not a parallel port: `punktfunk-core` (protocol/FEC/ +crypto/C-ABI) + QUIC + GameStream + mgmt + the `m3`/pipeline orchestration are all platform-agnostic +and already `cfg`-isolated (~95% reuse). New `#[cfg(windows)]` backends behind the existing traits: +capture (DXGI Desktop Duplication), encode (Media Foundation / NVENC-SDK with a D3D11 context), +input (SendInput + ViGEm), audio (WASAPI loopback + a virtual mic). **The blocker** is the +virtual-display feature — no user-mode Windows API; it needs a signed kernel-mode **IDD** driver +(XL). Recommended start: **Phase 0** — a "basic Windows host" capturing an existing monitor (no +virtual display), proving the whole stack with the smallest surface. Deferred because it's large and +unbuildable on the Linux dev box; the trait boundaries are already in the right places. diff --git a/docs/windows-host.md b/docs/windows-host.md new file mode 100644 index 0000000..166a812 --- /dev/null +++ b/docs/windows-host.md @@ -0,0 +1,68 @@ +# Windows as a host — feasibility & scoping + +**Status: scoped, deferred.** A Windows host is architecturally an *"add a backend"* job, not a +parallel port — but it is a **large** implementation effort across five GPU/driver subsystems, and +the project's headline feature (a per-client *virtual* output at the client's exact mode) has **no +user-mode Windows API**: it needs a signed kernel-mode Indirect Display Driver (IDD). This doc +records what it takes so the work can be picked up deliberately later. + +(Grounded in a 4-agent read of the host crate, 2026-06-10.) + +## What's already done for us + +punktfunk is cleanly layered. **~95% of the codebase is platform-agnostic and reuses verbatim:** + +| Reusable as-is | Why | +|---|---| +| `punktfunk-core` (protocol, FEC, crypto, session, transport, **C ABI**) | Zero platform deps — no `cfg(linux)` anywhere; the C ABI is already cross-platform | +| QUIC control plane (`quic.rs`, pairing, mode negotiation) | quinn + tokio are portable | +| GameStream P1.1 (mDNS, serverinfo, pairing, RTSP, ENet) — *except* `stream.rs`/`audio.rs` | pure wire logic | +| Management REST API (`mgmt.rs`) + OpenAPI | axum/tokio, portable | +| Pipeline + `m3.rs` orchestration | trait-generic — calls `capturer.next_frame()`, `encoder.submit/poll()`; **needs zero changes** | +| The **trait boundaries** themselves: `Capturer`, `Encoder`, `VirtualDisplay`, `InputInjector`, `AudioCapturer`, `VirtualMic` | platform-neutral signatures; Linux deps are already isolated under `[target.'cfg(target_os="linux")'.dependencies]` | + +So a Windows host is **new `#[cfg(target_os = "windows")]` backend modules behind the existing +traits** — the per-frame path, protocol, and control plane don't move. No architectural refactor is +required; the boundaries are already in the right places. + +## What a Windows host needs (new code) + +Each row is a Linux backend that needs a Windows sibling. Effort is the *implementation* effort; +all reuse the existing trait. + +| Subsystem | Linux today | Windows equivalent | Effort | Notes | +|---|---|---|---|---| +| **Capture** | xdg ScreenCast portal → PipeWire (dmabuf) | **DXGI Desktop Duplication** (or Windows.Graphics.Capture) → D3D11 texture | M | DXGI gives a GPU `B8G8R8A8` texture directly | +| **Virtual display** | KWin/Mutter/Sway/gamescope protocols | **Indirect Display Driver (IDD)** — kernel UMDF mini-driver | **XL** | ⚠️ **the blocker**: no user-mode API; C++ driver + **code signing** (test-sign or WHQL). Fallback: capture an existing monitor (loses the native-resolution feature) or a borderless window | +| **Encode** | `ffmpeg-next` NVENC, CUDA hwframes | Media Foundation H.264/HEVC/AV1, **or** NVENC SDK direct with a D3D11 device context (`AVD3D11VADeviceContext`) | M–L | `encode.rs` AU/codec logic + NVENC option strings are portable; only the hwdevice + frame-pool glue swaps | +| **Zero-copy bridge** | dmabuf → EGL/Vulkan → CUDA | D3D11 texture → NVENC (shared texture / `cudaImportExternalMemory` + D3D12 fence) | M | **optional** — a portable CPU-copy path already exists, so v1 can skip this | +| **Input (ptr/kbd)** | libei (RemoteDesktop portal) / wlr protocols | **SendInput** (`keybd_event`/`mouse_event`) | S | the VK→evdev table just becomes VK→`VIRTUAL_KEY` (already Win32-native) | +| **Input (gamepads)** | uinput X-Box-360 pad + FF rumble | **ViGEm** (Virtual Gamepad Emulation) + HID reports | M | rumble back-channel maps to ViGEm notifications | +| **Audio capture** | PipeWire sink-monitor | **WASAPI loopback** (`IAudioCaptureClient`) | S–M | also produces interleaved f32 — same `AudioCapturer` contract | +| **Virtual mic** | PipeWire `Audio/Source` | virtual audio device (VB-Cable-style WDM driver) or WASAPI render-to-fake-device | M | needs a driver or a bundled 3rd-party cable | +| **`sendmmsg` batching** | `gamestream/stream.rs` | already has a `cfg(not(linux))` per-packet fallback | — | nothing to do | + +**Rough total: ~2,000–4,000 LOC of new Rust** (+ a C++ IDD driver if the virtual-display feature is +kept), spread over capture/encode/vdisplay/input/audio. Every reader rated the overall effort +**large**; the input+audio layer alone is *medium*. + +## Recommended phasing (when picked up) + +1. **Phase 0 — "basic Windows host" (no virtual display).** Capture an *existing* monitor (DXGI + Desktop Duplication) → Media Foundation/NVENC encode → SendInput + WASAPI loopback. This proves + the whole stack on Windows with the smallest surface, reusing all of core/QUIC/GameStream/mgmt. + It loses the per-client native-resolution output but is a working Windows host quickly. +2. **Phase 1 — input + audio parity.** ViGEm gamepads + rumble; WASAPI virtual mic; D3D11→NVENC + zero-copy. +3. **Phase 2 — the virtual display (IDD).** The XL piece: a signed Indirect Display Driver that + surfaces a client-sized monitor, captured via DXGI. This restores punktfunk's differentiator on + Windows. Gated on solving driver signing/distribution. + +## Why it's deferred (not started now) + +- It's **large**, and the virtual-display blocker (IDD) is a kernel driver + signing problem + outside Rust — not "somewhat manageable" as a side effort. +- None of it is **buildable or testable on the Linux dev box** — it would be unvalidated code. + +The architecture is ready whenever the work is scheduled; this doc + the clean trait boundaries are +the down payment. Start at **Phase 0** for the fastest path to a working Windows host.