fix(linux): repair the PipeWire engine build, and advertise only decodable formats

[Tristan-Stoltz-ERC]

Two independent Linux-engine fixes, both small and self-contained. This replaces #183, which became structurally orphaned (details at the bottom) — apologies for the churn.

Related open PRs: #176 and #178 also touch the Linux frame/timestamp migration, and #169 proposes the RGBA handling below. This PR deliberately isolates the minimal compile repair plus the format-negotiation correction, without their broader or unrelated changes. Happy to rebase onto or defer to any of them if you'd rather take one of those first.

1. The Linux engine does not compile against the current frame enum

src/capturer/engine/linux/mod.rs still constructs the single-level Frame::RGBx(...) variants, but Frame now nests video variants under Frame::Video(VideoFrame::...). It also assigns an i64 PipeWire timestamp to display_time, which is a SystemTime.

Repaired to the two-level enum, with display_time = SystemTime::now().

On the timestamp, stated precisely — spa_meta_header.pts is a monotonic nanosecond count from an unspecified origin, so it cannot be represented directly as a SystemTime. SystemTime::now() is the minimal compile repair: it records when the callback processed the frame, not when the source captured it. That discards the source capture clock and its inter-frame timing, not merely sub-millisecond precision — callback delivery can be delayed or bursty.

This is deliberately weaker than the Windows engine, which anchors a SystemTime/performance-counter origin and derives each frame's display_time from the capture delta. Doing the same here needs a PTS origin to anchor against, which felt out of scope for a compile fix — but I'm glad to implement it, or expose pts as a separate field, if you'd prefer.

2. The engine advertises a format it cannot decode

The stream advertises RGB, RGBA, RGBx, BGRx; the callback handles RGB, RGBx, xBGR, BGRx. Two hand-maintained sets, disagreeing both ways:

• RGBA is advertised but has no decode arm — a compositor selecting it hits panic!("Unsupported frame format received") inside a PipeWire callback, for a format scap itself offered.
• xBGR has a decode arm but is never advertised, so it can never be negotiated.

This is independent of the compile repair and predates it.

RGBA is kept, not dropped

An earlier revision of this PR fixed the mismatch by removing RGBA from the advertised set. That was the wrong direction — RGBA is advertised for a reason. COSMIC negotiates RGBA where GNOME and KDE negotiate BGRx, which is precisely what #153 reported and what #169 proposes fixing. Removing it would either leave COSMIC without a compatible offer, or silently discard every frame if a portal supplied it anyway.

So RGBA keeps its place and gains a decode arm mapping onto RGBx — same byte order and width, differing only in whether the fourth byte is alpha or undefined padding. VideoFrame has no RGBA variant and scap doesn't currently expose alpha semantics, so this matches the mapping in #169.

SUPPORTED_VIDEO_FORMATS is now the authoritative advertisement set, pipewire_capturer's negotiation block destructures it rather than indexing (so growing it fails to compile at that callsite instead of silently under-advertising), and the dispatch moved into video_frame_for() -> Option<VideoFrame> so it can be checked without a live PipeWire stream.

What the tests guarantee — and what they don't

• advertised => decodable is enforced generally, for every entry, and each format's exact VideoFrame variant is pinned. A separate test asserts dimensions, timestamp and payload survive the dispatch unchanged for BGRx as a representative branch (all arms construct their frame identically).
• Growing the array cannot silently under-advertise — compiler-enforced via destructuring.
• decodable => advertised is not enforced generally. Adding an arm to video_frame_for without adding it to the array leaves that format unnegotiable. Quieter than a panic, but fix: Add handling for missing VideoFormat on Linux #153 shows "a compositor wants a format we don't offer" is a real failure, not a harmless one.

Closing that last direction would need a declarative table generating both the array and the dispatch. That seemed disproportionate at this size — happy to add it if you'd prefer.

Unsupported formats are rejected before the frame is copied

The unsupported-format path previously logged once per frame and copied the entire frame buffer before discarding it. So a portal delivering an undecodable format could emit dozens of lines per second indefinitely while also burning real memory bandwidth at high resolution.

The negotiated format is now checked against SUPPORTED_VIDEO_FORMATS before the to_vec(), and reported once per negotiated format (reset on renegotiation). The early exit requeues the PipeWire buffer exactly like the other early exits in that callback.

I've also stopped describing it as "unreachable by construction" — #153 is direct evidence that portal behaviour isn't a construction guarantee. It's a defensive fallback that reports rather than panicking, since this runs inside an FFI-driven callback where unwinding isn't something the C caller is prepared for.

Verification

• cargo test --lib: 7/7 pass; cargo fmt --check clean.
• Mutation-tested both directions of the regression, rather than only checking the happy path:
  • removing the RGBA decode arm (the original upstream bug) fails with advertised format VideoFormat::RGBA has no decode arm in video_frame_for;
  • removing RGBA from the advertised set (this PR's own earlier mistake) fails with RGBA decode support and RGBA advertisement must change together;
  • growing the array without updating the advertisement fails to compile: error[E0527]: pattern requires 5 elements but array has 6.
• Downstream-consumer evidence: this engine is compiled on every CI run of xenia-peer via a dedicated scap-backend job (lib + example + tests, --all-targets --no-run), and has been exercised live against a real KDE-Wayland session at 1920×1080.

Linux only. I have not compiled Windows or macOS and have deliberately not touched them here. I don't have a COSMIC system, so the RGBA path is reasoned from #153/#169 and unit-tested, not verified live — if a COSMIC user can confirm, that would be worth having.

Deliberately not included

Two further changes exist in a downstream fork but are not here, because they change observable behaviour and deserve separate review:

• bounded frame channel — the internal mpsc::channel() is unbounded and grows without limit under downstream backpressure (heaptrack measured ~1.44 GB of 1.47 GB in a 25.76 s repro). Converting to sync_channel + try_send changes delivery semantics cross-platform, and audio differs from stale video there.
• lifecycle/static-state hardening — the Linux backend's process-wide statics assume a single active capturer.

I'll submit those once I can show real Windows and macOS compilation evidence. I'd rather not hand you patches nobody has built.

I also noticed some pre-existing buffer-handling issues adjacent to this code (a n_datas < 1 early return that skips re-queueing, and a null-buffer path). They're outside this PR's scope and I haven't touched them — happy to open a separate issue if useful.

What happened to #183

#183 was opened from Luminous-Dynamics/scap, which left this repository's fork network at some point. GitHub closed it automatically when a later push forced it to recompute the comparison, and it can't be reopened (state cannot be changed. The repository may be missing relevant data). No review content was lost — #183 remains readable, and its discussion (thanks @tembo for the review there) informed this smaller resubmission.

This PR is from a genuine fork and deliberately narrower: the compile repair plus the negotiation correction, rather than the original 18-commit history.