docs: the 4:4:4 story catches up with the code that ships it #87

Merged

enricobuehler merged 2 commits from worktree-docs-support-matrix-444 into main 2026-08-07 09:27:35 +00:00

Conversation 0 Commits 2 Files Changed 3

+61 -28

enricobuehler commented 2026-08-07 09:21:40 +00:00

Owner

Copy Link

Copy Source

The support matrix still told the pre-July story about full chroma. Reported from reading the page; every cell below was re-checked against the code that decides it.

Rebased onto #85 (FFmpeg is gone from the client), which changed two of my own claims — see "What the merge changed" below.

What was wrong

The desktop clients do ask for 4:4:4. clients/session/src/main.rs advertises VIDEO_CAP_444 whenever the Full chroma setting is on, with no client-side probe. The page said the switch "has no effect today" and that only the Apple client asks. Both stopped being true in 74863c96.

HDR and 4:4:4 compose on Windows. 9f72a3b6 gave the IDD-push capturer a packed 10-bit BT.2020 PQ RGB output, so NVENC encodes HEVC Main 4:4:4 10 and a session gets both. The matrix said they were "refused" together, and hdr.md still called PyroWave the only exception. Linux keeps the trade — handshake.rs resolves the bit depth back to 8 for a 4:4:4 session, so full chroma wins and the stream is SDR.

What the merge changed

Worth a look, because it moved the reasoning and not just the text:

• My note 4 justified the missing client-side probe with "every rung can display full chroma — swscale converts for the software rung". There is no swscale any more. The CPU floor is openh264 + rav1d, 4:2:0 8-bit by contract, with no HEVC at all — so it refuses a 4:4:4 stream rather than converting one. The client still advertises the bit unprobed (that part was right), but the honest reason is that full chroma is a hardware path — Vulkan RExt, NVIDIA today — and a box whose hardware 4:4:4 fails lands on note 2's codec reconnect, not on a downgraded picture. Note 13 repeated the same wrong premise and now names both halves of its warning.
• The C ABI is 17, not the 14 I read before the merge.

Why three cells become ⚠️ and not ✅

Both halves earn the caveat now: on the client it is hardware-only with no software floor; on the host it needs HEVC on an NVIDIA host, or PyroWave on any vendor. The notes say which, and point at the stats overlay's 4:4:4→4:2:0 tag — this is the one negotiation that fails loudly rather than quietly, so the "Four different kinds of yes" section now says so.

Android is genuinely ❌ — no setting, no cap bit, no 4:4:4 implementation at all. Left as it was.

Also in here

• C ABI version 13 → 17 (punktfunk-core/src/lib.rs).
• PyroWave's ≈8K 4:4:4 ceiling now has a note — the vendored rate controller packs its block index into 16 bits, and those modes are downgraded before the Welcome.
• The roadmap no longer calls Intel 4:4:4 a hardware limit. AMD's VCN genuinely can't; VAAPI just hasn't implemented it (vaapi.rs — "Deferred in v1"), which the matrix's own note 9 already said. The two pages contradicted each other.

Conflict resolution

#85 rewrote the Codecs column and notes 1–3 of the Client decode table while leaving note 4's stale 4:4:4 text alone. Theirs is kept in full — only the 4:4:4 column and note 4 are mine.

Spot-checked and left alone

Still accurate, so untouched: the Linux client clipboard stub, VAAPI declining 4:4:4, wire version 2, driver protocol 6 (accepts 3+), gamepad channel 3. client-settings.md, pyrowave.mdx and stats.md were already current — the staleness was concentrated in the matrix and hdr.md.

Verification

docs-site doesn't build standalone in this checkout (Footer.tsx and the API route import workspace packages that aren't installed locally; CI builds it against the registry), so this was checked structurally: a script confirming every superscript in all seven tables resolves to a note with no orphans — 0 problems, re-run after the merge — plus a full diff review. Docs-only; no code paths touched.

The support matrix still told the pre-July story about full chroma. Reported from reading the page; every cell below was re-checked against the code that decides it. **Rebased onto #85 (FFmpeg is gone from the client), which changed two of my own claims — see "What the merge changed" below.** ## What was wrong **The desktop clients do ask for 4:4:4.** `clients/session/src/main.rs` advertises `VIDEO_CAP_444` whenever the Full chroma setting is on, with no client-side probe. The page said the switch "has no effect today" and that only the Apple client asks. Both stopped being true in `74863c96`. **HDR and 4:4:4 compose on Windows.** `9f72a3b6` gave the IDD-push capturer a packed 10-bit BT.2020 PQ RGB output, so NVENC encodes HEVC Main 4:4:4 10 and a session gets both. The matrix said they were "refused" together, and `hdr.md` still called PyroWave the only exception. Linux keeps the trade — `handshake.rs` resolves the bit depth back to 8 for a 4:4:4 session, so full chroma wins and the stream is SDR. ## What the merge changed Worth a look, because it moved the *reasoning* and not just the text: - My note 4 justified the missing client-side probe with "every rung can display full chroma — swscale converts for the software rung". **There is no swscale any more.** The CPU floor is openh264 + rav1d, 4:2:0 8-bit by contract, with no HEVC at all — so it refuses a 4:4:4 stream rather than converting one. The client still advertises the bit unprobed (that part was right), but the honest reason is that full chroma is a *hardware* path — Vulkan RExt, NVIDIA today — and a box whose hardware 4:4:4 fails lands on note 2's codec reconnect, not on a downgraded picture. Note 13 repeated the same wrong premise and now names both halves of its warning. - **The C ABI is 17**, not the 14 I read before the merge. ## Why three cells become ⚠️ and not ✅ Both halves earn the caveat now: on the client it is hardware-only with no software floor; on the host it needs HEVC on an NVIDIA host, or PyroWave on any vendor. The notes say which, and point at the stats overlay's `4:4:4→4:2:0` tag — this is the one negotiation that fails loudly rather than quietly, so the "Four different kinds of yes" section now says so. **Android is genuinely ❌** — no setting, no cap bit, no 4:4:4 implementation at all. Left as it was. ## Also in here - **C ABI version 13 → 17** (`punktfunk-core/src/lib.rs`). - PyroWave's ≈8K 4:4:4 ceiling now has a note — the vendored rate controller packs its block index into 16 bits, and those modes are downgraded before the Welcome. - The roadmap no longer calls Intel 4:4:4 a hardware limit. AMD's VCN genuinely can't; VAAPI just hasn't implemented it (`vaapi.rs` — "Deferred in v1"), which the matrix's own note 9 already said. The two pages contradicted each other. ## Conflict resolution #85 rewrote the Codecs column and notes 1–3 of the Client decode table while leaving note 4's stale 4:4:4 text alone. **Theirs is kept in full** — only the 4:4:4 column and note 4 are mine. ## Spot-checked and left alone Still accurate, so untouched: the Linux client clipboard stub, VAAPI declining 4:4:4, wire version 2, driver protocol 6 (accepts 3+), gamepad channel 3. `client-settings.md`, `pyrowave.mdx` and `stats.md` were already current — the staleness was concentrated in the matrix and `hdr.md`. ## Verification `docs-site` doesn't build standalone in this checkout (`Footer.tsx` and the API route import workspace packages that aren't installed locally; CI builds it against the registry), so this was checked structurally: a script confirming every superscript in all seven tables resolves to a note with no orphans — 0 problems, re-run after the merge — plus a full diff review. Docs-only; no code paths touched.

enricobuehler added 1 commit 2026-08-07 09:21:42 +00:00

docs: the 4:4:4 story catches up with the code that ships it ... f1e7ec3535

The support matrix said the desktop clients' Full chroma switch "has no
effect today" and that only the Apple client asks for 4:4:4. Both stopped
being true in July: `clients/session/src/main.rs` advertises VIDEO_CAP_444
whenever the setting is on, deliberately with no client-side probe, because
every desktop decode rung can display full chroma — the Vulkan presenter
samples the 2-plane 4:4:4 pool formats and swscale converts for the software
rung. So Linux, Windows and Apple all ask; Android is the one that genuinely
doesn't implement it.

The other half was HDR. `9f72a3b6` gave the Windows IDD-push capturer a
packed 10-bit BT.2020 PQ RGB output, so NVENC encodes HEVC Main 4:4:4 10 and
the two compose — the matrix still said "4:4:4 and HDR together is refused",
and hdr.md still called PyroWave the only exception. Linux is the side that
keeps the trade: handshake.rs resolves the depth back to 8 for a 4:4:4
session, so full chroma wins and the stream is SDR.

Three cells move ❌ → ⚠️ rather than ✅ on purpose. The client half is
unconditional, but the host half is not: HEVC 4:4:4 means an NVIDIA host, or
PyroWave on any vendor. The notes say which, and point at the stats overlay's
`4:4:4→4:2:0` tag — this negotiation is the one that fails loudly.

Also: C ABI version 13 → 14; PyroWave's ≈8K 4:4:4 block-index ceiling now
has a note; and the roadmap no longer calls Intel 4:4:4 a hardware limit,
which the matrix and vaapi.rs both contradict — VCN can't, VAAPI hasn't.

Spot-checked and left alone as still accurate: the Linux client clipboard
stub, VAAPI declining 4:4:4, Android having no 4:4:4 at all, and the wire /
driver / gamepad-channel versions.

enricobuehler added 1 commit 2026-08-07 09:25:31 +00:00

Merge origin/main; 4:4:4 has no software floor, and the ABI is 17 ... 3a35773b70

Reconciling with #85 (FFmpeg is gone from the client). Two of my claims
were true against the pre-merge tree and false against this one.

Note 4 said the desktop clients need no 4:4:4 decode probe "because every
rung can display full chroma — swscale converts for the software rung".
There is no swscale any more. The CPU floor is openh264 + rav1d, it is
4:2:0 8-bit by contract and has no HEVC at all, so it refuses a 4:4:4
stream rather than converting one. The client still advertises the bit
unprobed, which was the point of the original fix, but the honest reason
is different: full chroma is a hardware path (Vulkan RExt, NVIDIA today),
and what catches a box whose hardware 4:4:4 fails is note 2's codec
reconnect, not a downgraded picture. Note 13 repeated the same wrong
premise and now names both halves of its warning.

The C ABI is 17, not the 14 I read before the merge.

Textual side of the conflict: #85 rewrote the Codecs column and notes 1-3
of the same table while leaving note 4's stale 4:4:4 text alone. Theirs
kept in full; only the 4:4:4 column and note 4 are mine.

enricobuehler merged commit c6b183450a into main 2026-08-07 09:27:35 +00:00

enricobuehler deleted branch worktree-docs-support-matrix-444 2026-08-07 09:27:42 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

FernandoMX enricobuehler (Enrico Bühler) kszlim nannku neoney sassycrown

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: unom/punktfunk#87