fix(encode): NVENC split-frame encode never engaged for HDR — engage it, measured #83
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: unom/punktfunk#83
Reference in New Issue
Block a user
A field 4K60 HDR capture (RTX 4090, gamescope → direct-NVENC HEVC, ABR ~409 Mbps) spent 10.3 ms of a 16.67 ms frame budget in
encodewith the GPU's second NVENC engine idle. The path was clean — zero drops, 60.0 fps, zero-copy capture — so the encoder was simply never being split.Root cause: split engaged for exactly one shape — 8-bit above 950 Mpix/s. No HDR session ever split, on any GPU.
What was wrong
Five defects in
resolve_split_mode, two of them pure short-circuit accidents:codec, so an HEVC-Main10-on-Ada measurement vetoed AV1 10-bit, which has neither the constraint nor any measurement against it.NV_ENC_CAPS_NUM_ENCODER_ENGINESwas queried nowhere, so a 3-NVENC part ran 2-way and a 1-NVENC part paid a wasted session open.AUTOarm mean "never split" on the fleet's default config.What this changes
Use every engine the GPU has. The engine count is now probed and the widest split selected; >3 engines falls back to
AUTO_FORCEDsince the enum can only name three. Operator overrides are clamped — necessary because the driver honours an over-ask and silently encodes narrower:THREE_FORCEDon a 2-engine card was accepted and ran identically toTWO_FORCED, so the rejection fallback can't discover the ceiling.The 10-bit short circuit is gone, and the veto is codec-scoped.
Live split arbitration (opt-in,
PUNKTFUNK_NVENC_SPLIT_ARBITRATE=1): the encoder measures both arms on the running session and keeps the winner, caching the verdict per config. Prediction was impossible — the decision depends on bits/frame and an Automatic client's steady-state rate is unknown at open — so it measures instead. Zero extra IDRs, asserted on hardware.The HEVC sub-frame trade is priced. Forcing split gives up sub-frame readback, whose value is that the send overlaps the encode — a cost the encoder cannot see. The host now reports its paced-send spread and the encoder converts it into a handicap. A unit test runs identical encode numbers under a cheap and an expensive send and asserts the verdict reverses.
One split policy. The libav path had drifted (hard-coded 2-way, no depth rule); it now shares the resolver, which moved to
codec.rsso the featureless build can use it, with a parity test pinning the hand-written enum constants against the SDK.Measurements
The veto's founding datapoint does not reproduce. It rested on 5120×1440@240 Main10 on Ada being 2.7× slower split. Re-run at its own operating point:
Split wins everywhere, both architectures.
The bits/frame curve — no crossover. Previous measurements used driver-zeroed buffers, so rate control had nothing to code (~300 B/AU against an 833 KB quota) and only the pixel-proportional half was exercised. With real content:
Encode time scales 4.6 → 16.2 ms with bits/frame, and split wins at every point. At ~6.8 Mbit/frame these curves put single-engine 4K60 at 10–13 ms — against the field's 10.3 ms, so that number reads as real ASIC time rather than queue-depth inflation.
⚠ Content structure is a real term: the highest-bits/frame row encodes faster than the next one down on both boxes, because pure noise defeats motion estimation. bits/frame is a good axis, not a complete model.
Verification
Hardware across three platform × arch × driver combinations — Linux/CUDA Blackwell 610.57.04, Linux/CUDA Ada 610.43.03, Windows/D3D11 Ada 610.88 — with the in-place switch accepted and zero IDRs on all three.
.21: clippy-D warningsclean with and without the nvenc feature, 65 unit tests, 25/25 NVENC on-hardware..181,.158: on-hardware suites green..133+.158: Windows clippy-D warningsclean.Notes for review
RUSTFLAGS='-L native=C:\Users\Public\nvenc -l nvencodeapi'— previously believed impossible, and it unblocks Windows on-hardware testing generally. Test-local only; production dlopens NVENC by design.dead_codetrap bit five times here, every one caught by running a Windows build rather than by reasoning. Worth a look at any shared-module item added for one platform's caller.Two on-hardware spikes answering the gate on the split-encode engagement program (design/nvenc-split-encode-engagement-implementation-plan.md). S1a `nvenc_cuda_split_reconfigure_in_place`: can splitEncodeMode change via nvEncReconfigureEncoder with resetEncoder=0, without an IDR? Our "reconfigure must present the SAME init params as the open" rule (windows/nvenc.rs:620) is our own invariant and had never been tested against a driver. It reports rather than asserts the verdict -- both outcomes are legitimate findings -- and only asserts what would invalidate the measurement (session live, engines >= 2, the arms actually differ). Sub-frame is pinned off so the driver can't reject for the wrong reason (HEVC forced-split and sub-frame are mutually unsupported). S1b `nvenc_cuda_split_reconfigure_takes_effect`: the other half -- a driver that accepts the parameter and quietly ignores it looks identical to one that honours it. Three legs at 4K (fresh DISABLE / fresh TWO_FORCED / DISABLE->TWO in place); if C tracks B and not A, the switch is real. RESULT on .21 (RTX 5070 Ti, GB203 Blackwell, driver 610.57.04): NV_ENC_CAPS_NUM_ENCODER_ENGINES = 2 S1a: accepted, ZERO IDRs, both directions. S1b: A fresh DISABLE 5054 us/frame, B fresh TWO_FORCED 2453, C switched in place 2419 -- |C-B|=34 vs |C-A|=2635. It takes effect, and split is a clean ~2x at 4K. Two limits, both recorded in the test docs rather than the commit only. The frames come out at 427 B/AU against an 833 KB CBR quota: the driver hands back zeroed VRAM, so the rotated buffers are identical and rate control skip-codes everything. So this measures the PIXEL-proportional half of the cost only -- the bits/frame regime the field case lives in is untested here, and the test prints an explicit INCONCLUSIVE-on-content line when it detects that. And this is Blackwell 8-bit; the Ada Main10 question is untouched. Verified on .21: clippy -p pf-encode --features nvenc --all-targets -D warnings clean, both spikes green, cargo fmt --all --check clean.The fix S1 unlocked. Rather than predict the right split mode at open — which cannot work, because the decision depends on bits/frame and an Automatic client's steady-state bitrate is unknown at open (ABR climbs in place afterwards) — the encoder now measures both arms on the live session and keeps the winner. S1 proved nvEncReconfigureEncoder takes a changed splitEncodeMode with resetEncoder=0, emits no IDR, and actually applies it, so the experiment is invisible on the wire. Deliberately measures instead of modelling: hard-coded per-arch constants are exactly how the rule this replaces went wrong (one 5120x1440@240 Ada datapoint generalised into a fleet-wide 10-bit veto). A measurement tracks driver updates for free. `SplitArbiter` (pure state machine, unit-tested without a GPU): measure incumbent -> switch -> SETTLE -> measure challenger -> keep the winner, else switch back. Verdicts cache per (gpu, codec, mode, depth, chroma) so later sessions open straight into the winning arm; the key is CeilingKey minus split_mode, since the split mode is the thing being decided. ⚠ SETTLE_FRAMES=16 is load-bearing, not padding: split-encode does not reach steady state on the first frame (a FRESH TWO_FORCED session measured early-half 3280us vs late-half 1996), so judging an arm right after switching reads the transient — intermittently, which would then be cached. A unit test feeds exactly that transient and asserts the arbiter still sees the steady state. Safety gates, all correctness conditions rather than preferences: opt-in (PUNKTFUNK_NVENC_SPLIT_ARBITRATE=1) while it earns trust; an operator PUNKTFUNK_SPLIT_ENCODE pin always wins; skip if a verdict is already cached; sync depth-1 only (async_rt.is_none(), same gate chunked poll uses — under pipelined retrieve the submit->AU span includes queue depth and the comparison is noise); needs >=2 engines; never H.264. ⚠ And the one that bounds this increment: NO SUB-FRAME TRADE. For HEVC, forcing split gives up sub-frame readback, which costs send/encode overlap the ENCODER CANNOT SEE — it measures encode time only, so it would reliably prefer split and silently make end-to-end latency worse. So arbitration runs only where nothing is traded: sub-frame already off, or AV1 (both features legal). Pricing that trade needs the host's send cost and is the next work package. Challenger choice tests the question worth asking — anything not already the widest forced split is challenged BY the widest ("are we leaving engines idle?"). The naive "challenge whatever we are not" spent the experiment re-proving that splitting beats not-splitting, while parking the session on the slow arm to do it, because 4K60 sits on the fallthrough AUTO. ⚠ Every new nvenc_core item is linux-gated: the arbiter is wired into the Linux backend only for now and nvenc_core compiles on Windows too. Caught by the .133 check, not by reasoning — the first cut failed Windows clippy with 12 dead_code errors, the exact item-level trap this file already carries a scar from. Verified .21: clippy --features nvenc --all-targets -D warnings clean, 62 unit tests (4 new arbiter tests), 23/23 NVENC on-hardware green including a new end-to-end convergence test asserting ZERO extra IDRs and a cached verdict. Verified .133: Windows clippy -D warnings clean, zero dead_code. fmt clean.WP0's real deliverable, and the hole every previous measurement in this programme had. All prior timings ran against driver-zeroed buffers, so rate control had nothing to code (~300 B/AU against an 833 KB quota) and only the PIXEL-proportional half of the encode cost was ever exercised -- while the 4K60 HDR field report was a BITS/FRAME problem at 6.8 Mbit/frame. Adds `pf_zerocopy::cuda::write_plane_from_host`, the exact mirror of the existing read_plane_to_host. No new loader entry was needed: cuMemcpy2DAsync_v2 was already in the table and CUDA_MEMCPY2D just needed the reverse memory types. Linux-only by construction (pf-zerocopy's `imp` is cfg'd to linux). ⚠ Two harness mistakes found and fixed by looking at bytes/AU rather than trusting the knob: - Pure per-pixel noise is INCOMPRESSIBLE, so a low bitrate target does not produce low bits/frame -- it OVERSHOOTS. At a nominal 50 Mbps the encoder emitted 719 KB/AU against a 104 KB quota, and the three lowest rows of the first sweep all sat at the same ~5.7 Mbit/frame. Sweeping nominal bitrate measures nothing. - So the sweep moves CONTENT DETAIL (block size) instead, and the x-axis is the bits/frame the encoder ACTUALLY produced, never the one requested. 4K60 HEVC 8-bit, real content, single-engine vs forced-2: bits/frame Ada 4090 Blackwell 5070 Ti 0.2-0.3 Mb 4567 -> 2381 1.92x 5549 -> 3552 1.56x ~1.1-1.2 Mb 5060 -> 2626 1.93x 5867 -> 4082 1.44x ~3.3 Mb 8478 -> 4455 1.90x 9286 -> 5862 1.58x ~9.6 Mb 16237 -> 8114 2.00x 16435 -> 9275 1.77x RESULTS. (1) Encode time scales strongly with bits/frame -- 4.6 ms to 16.2 ms across the range on Ada -- confirming the hypothesis' core claim. (2) There is NO CROSSOVER: split wins at every point on both architectures (Ada ~1.9-2.0x and notably flat, Blackwell 1.44-1.77x). So the arbitration's encode-side answer is essentially always "split", which makes the sub-frame handicap the only decision that actually matters -- exactly the part already built and unit-pinned. (3) It corroborates the field capture: at ~6.8 Mbit/frame these curves put single-engine 4K60 around 10-13 ms, and the field report was 10.3 ms on a 4090. That reads as real ASIC time, not the retrieve-queue inflation it might have been. ⚠ Caveat the data itself shows: cost is NOT monotonic in bits/frame alone. The 1px row lands at the HIGHEST bits/frame yet encodes FASTER than the 4px row on both boxes (Ada 10148 vs 16237 us) -- pure noise defeats motion estimation, which gives up early, where semi-structured content makes it search hard. Content structure is a real term, so "bits/frame" is a good axis but not a complete cost model. Verified .21: clippy -D warnings clean (pf-encode + pf-zerocopy), 64 unit tests, 25/25 NVENC on-hardware. Curves run on both Ada and Blackwell. fmt clean.The libav NVENC path carried its own inline copy of the split decision and had already drifted from the direct-SDK selector: it hard-coded a 2-way split regardless of engine count, and had no depth rule at all. That is the drift the shared resolver was extracted to prevent, and the copy quietly reintroduced it. Routing it through `resolve_split_mode` needed the policy to MOVE. `nvenc_core` is gated on `feature = "nvenc"`, but the libav path is precisely the build where that feature is OFF (`PUNKTFUNK_NVENC_DIRECT=0`, and the featureless packages -- the packaging gap this project has been bitten by before). So resolve_split_mode / max_forced_split_mode / clamp_to_engines, plus a new `forced_split_width`, now live in `codec.rs`, which is always compiled and already owned SPLIT_FORCE_PIXEL_RATE. That means the NV_ENC_SPLIT_ENCODE_MODE values had to be hand-written as plain constants, since the SDK enum does not exist without the feature. They are therefore pinned: `nvenc_split_constants_match_the_sdk` (feature-gated, the only place both are visible at once) asserts all five against the real enum, so the copies cannot rot. ⚠ Only the FORCED outcomes are actionable on the libav side -- libavcodec's `split_encode_mode` AVOption is its own vocabulary and our DISABLE is the NVENC enum's 15, which would be meaningless there. DISABLE/AUTO both map to "leave the option unset", which is exactly today's behaviour (unset = the driver's auto). `engines = 0` ("not probed") maps to 2-way, preserving what that site always did; a 3-NVENC part gets the wider split only on the direct-SDK path, which is the one that actually probes. ⚠⚠ VERIFICATION GAP: .133 went down mid-change (no ping), so the WINDOWS leg is UNVERIFIED. This matters more than usual -- the Windows backend imported resolve_split_mode from nvenc_core and that import had to move too, which a grep caught rather than a compiler. Re-run before trusting it: cargo clippy -p pf-encode --features nvenc --all-targets -- -D warnings Verified .21: clippy -D warnings clean BOTH with and without the nvenc feature (the featureless build is the whole point of the move) and with nvenc,vulkan-encode; 65 unit tests incl. the new constant-parity test; 25/25 NVENC on-hardware; punktfunk-host clippy clean. fmt clean.Everything the split-encode programme rests on had been proven only on Linux/CUDA. The Windows backend drives NV_ENC_DEVICE_TYPE_DIRECTX, so none of it transferred by assumption -- and if the driver refused an in-place split change there, Windows arbitration would simply not be buildable. RESULT on the RTX Windows box (RTX 4090 / AD102, driver 610.88, D3D11): engines=2, latched by query_caps (WP1.1's probe, validated on Windows hardware rather than inferred from Linux) DISABLE -> TWO_FORCED via nvEncReconfigureEncoder, resetEncoder=0: ACCEPTED, ZERO IDRs, and the reverse likewise. So the foundation now holds across three platform x arch x driver combinations: Linux/CUDA Blackwell 610.57.04, Linux/CUDA Ada 610.43.03, Windows/D3D11 Ada 610.88. ⭐ UNBLOCKS ALL FUTURE WINDOWS ON-HARDWARE TESTING. pf-encode's nvenc test binaries were believed unlinkable on Windows ("NvEncodeAPICreateInstance unresolved", recorded as pre-existing and worked around by only ever running clippy there). They link fine given the SDK import library: RUSTFLAGS='-L native=C:\Users\Public\nvenc -l nvencodeapi' `-L` alone is not enough -- without a `-l` nothing pulls the archive in, which is why the earlier attempt still failed. ⚠ This is TEST-BINARY-LOCAL and must stay that way: production deliberately dlopens NVENC rather than link-loading it, and an unconditional link-load is the known crash class on non-NVIDIA Windows hosts. ⚠ Box note: the RTX Windows box answers on .158, not the .173 in its memory entry, and `Administrator@` there resets the connection right after SSH2_MSG_SERVICE_ACCEPT in a way that reads like the host being down -- the working login is "Enrico Bühler"@192.168.1.158.