feat(compositor): CPU backend — WARP render + software decode, surfaced to the user by EtienneLescot · Pull Request #162 · getopenscreen/openscreen

EtienneLescot · 2026-07-26T14:46:48Z

This PR outgrew its title. It opened as a scoping PR: retry D3D11CreateDevice with D3D_DRIVER_TYPE_WARP when hardware init fails. Measurement refuted that fix (below). What shipped instead is a full CPU backend — WARP for rendering, libavcodec for decoding, system-memory frames for encoding — selected automatically and never silently.

Summary

Render, decode and encode are three independent axes, and no software rasteriser on any platform also decodes video (WARP here, lavapipe/SwiftShader on Linux, nothing at all on macOS). A fallback needs all three answered, not one driver-type swap:

axis	hardware backend	CPU backend
render	D3D11 hardware	WARP
decode	D3D11VA (zero-copy)	libavcodec software → swscale → NV12 upload (`cpu_frames.rs`)
encode	`h264_amf` zero-copy	`h264_mf` / `libopenh264` via the existing `ExportCodec::candidates()`

The seam that keeps output identical: everything the compositor knows about a decoded frame is compositor::nv12_srvs() / compositor::tex_dims(), which read four fields — data[0] (NV12 texture), data[1] (array slice), width, height. Fill those and compositor.rs, every HLSL shader and the scene contract are untouched. A Metal or Vulkan port replaces d3d.rs + cpu_frames.rs and nothing else.

Why not the WARP retry this PR scoped

Measured on the reference machine (Ryzen 5 7520U + integrated Radeon, Windows 11):

probe	result
WARP + `D3D11_CREATE_DEVICE_VIDEO_SUPPORT`	`DXGI_ERROR_UNSUPPORTED` — device does not create
WARP without the flag	creates at FL 11_1, but `QueryInterface(ID3D11VideoDevice)` → `E_NOINTERFACE`, 0 decoder profiles
hardware, same call	20 decoder profiles

pipeline.rs hands the device to ffmpeg as the AVD3D11VADeviceContext, so preview and export decode every frame on it. A WARP device would produce zero frames — the retry would have converted a clear startup failure into an obscure ffmpeg one. Locked by crates/compositor/tests/warp_device_cannot_decode.rs: if that test ever fails, Windows gave WARP video capability and this design should be revisited.

The scoped questions, answered: WARP alone is acceptable for neither export nor preview; WGC capture stays hardware-only (see Known gaps); shader cost under WARP is fine except for two multi-tap loops (below).

What shipped

d3d.rs — Backend::{Hardware, Cpu}; create (hardware-strict, for tests/goldens), create_auto (production: hardware → CPU fallback), cached probe(), and diagnose() which re-probes minus VIDEO_SUPPORT to separate "this adapter has no video decoder" (RDP / VM / Basic Render Driver — a driver update fixes it) from "no FL 11_1 adapter at all" (structural). That distinction is what the logs and the UI surface.
cpu_frames.rs (new) — software decode → swscale → NV12 → upload into one owned dynamic texture → present an AVFrame carrying the 4 seam fields.
pipeline.rs — Decoder gains the CPU frame source; CPU export skips the encoder pool and VideoEncoder::send_composited() reads composed NV12 straight from the compositor (av_hwframe_transfer_data presupposes a D3D11 pool WARP cannot create — export died at enc hwdevice init before any encoder was tried).
live.rs / napi — the render thread's fatal error is stored and relayed as an Err on the next read_frame pull (~33 ms), instead of existing only as an eprintln! under a black canvas. Export uses create_auto.
Electron/TS — probeBackend() end to end (addon → service → IPC → useCompositorBackend() hook); the preview carries a small persistent CPU notice and the export dialog warns before the export starts. "none" (no addon at all: pure-web dev, jsdom) never warns — that is the normal state in development; only "cpu" is a degraded machine. Tested.
i18n — 13 locales: errors.previewCompositorUnavailable, cpuCompositor.{notice,exportWarning}.
Bench — --backend hardware|cpu, --preview, --export; writes a PPM per run so a backend composing black can't post a flattering fps.

Measurements (frozen fixture, C1–C8)

Iso render — hardware vs CPU, same frame, all 6,220,800 channels: 93–95 % bit-identical, max deviation 3/255, mean levels matching (neither frame is blank). Every effect layer survives the backend swap; the residual is rasteriser/FP difference, so cross-backend goldens need a tolerance, not an exact baseline.
Preview — C1–C3 hold ~30 fps on WARP; C4+ sit at 6–9 fps. Two multi-tap sampling loops own the whole gap: background blur +4.53 ms hardware vs +75.43 ms WARP (17×), motion blur +2.30 vs +52.65 (23×). Everything else is within ~2.2× of the GPU.
Export (360 frames) — hardware 88.2 fps (h264_amf zero-copy); CPU backend 4.8 fps (h264_mf); CPU forced libopenh264 4.6 fps. All decode clean under ffmpeg -f null -.
⚠️ Caveats: the absolutes need a re-run on a quiet machine (4 of 16 rows blew the <15 % spread gate with background processes live; the layer attribution is robust). And h264_mf winning on the CPU backend is a local artefact — Media Foundation picks its MFT independently of our device, so on a machine that has a GPU it still reaches hardware; OPENSCREEN_EXPORT_ENCODER=libopenh264 exercises the real last resort.

Product decisions

No WARP-only retry — refuted by measurement.
No effect degradation on the CPU path — ~8 fps is what the shipped 1.7.0 preview delivered; disabling blur/motion-blur would trade away the iso property. Slow and correct beats fast and wrong, in preview and export.
Fallback is automatic but never silent — create_auto + probeBackend() + notices.

Known gaps (not fixed here)

WGC capture fallback is unreachable on a host that fails D3D. is-native-windows-capture-available checks only the Windows build and helper-on-disk — never D3D. A host whose helper fails createD3DDevice gets available: true, commits to native, and startNativeWindowsRecordingIfAvailable rethrows instead of returning false, so the getDisplayMedia fallback is never reached. Not a one-line return false: the webcam preview stream has been deliberately released by then, so falling through would silently record screen-only. Fix = re-acquire the stream on the fallback route, or make the probe truthful (helper reports D3D capability before the renderer commits).
Preview effect policy deliberately absent — cfg.bg_blur / cfg.mblur_n are the levers if frame rate ever becomes the complaint.

Related issue

n/a — scoping PR that grew into the implementation.

Type of change

Feature
Performance

Release impact

Minor

Desktop impact

Windows

Testing

1153 vitest + 81 Rust tests pass (--lib --tests; the 13 Rust doctest failures and the tsconfig.test.json errors are pre-existing on the base branch, verified by stashing).
crates/compositor/tests/warp_device_cannot_decode.rs pins the WARP probe results above.
Verified through the real addon (not mocks): probeBackend() returns "hardware" on a GPU machine and stays cached; CPU-backend export produces a file that decodes clean end to end.
Preview/export numbers from poc-d3d --cfg C1..C8 --backend {hardware,cpu} --frames 300 --repeat 3 on the frozen fixture (360 frames, 1920×1080 + 1920×1032, Constrained Baseline 60 fps); each run also writes a PPM frame for pixel inspection.

coderabbitai · 2026-07-26T14:46:55Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 95bdf0cd-d37b-4a79-a4c5-0a424be6b29f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/d3d-warp-fallback

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

…and mark

…e only editor

…mpty timeline

…s and snapping - feat(ai-edition): multi-session chat history + multi-clip timeline with drag-drop - feat(ai-edition): timeline interaction P0 — clip resize/delete/duplicate, region drag, Edit Clip dialog - feat(ai-edition): timeline viewport spine — pan/zoom/reorder (T01-T09) - feat(ai-edition): timeline lanes, navigator strip, Place-skip mode (T10-T18) - feat(ai-edition): timeline polish — scrub preview, resequence, snap guides (T19-T25)

…ompaction

…r pipeline into the preview

…set regeneration

… and manual compaction

…nline

…kip-range model

…nd move the transport into the timeline

…nment, then CTranslate2

…ise its build

…e thinking on/off

…atch the v4 design - feat(ai-edition): refactor editor to OpenScreen Editor v4 (Media/Edit/Rec) - style(ai-edition): flatten timeline region pills to v4 design - style(ai-edition): match v4 timeline navigator to design - style(ai-edition): align v4 timeline clip cards + ruler to design - fix(ai-edition): hide timeline lane watermark when lane has regions - style(ai-edition): float clip label as v4 blur chip over waveform - docs(ai-edition): add v4 design-parity + import audit notes

…start offset

…ounded in the editor

…dding

…d add LLM effect tools

Branch off the CPU-backend seam established by PR #162 and split the compositor crate into per-platform directories. Windows behaviour is byte-identical (81 tests pass) and the macOS stubs that follow this commit in the stack expose the same public surface (Backend, Gpu, Compositor, Decoder, VideoEncoder, ExportCodec, ClipSource, LiveParams, LayerCB...) and Err from every operation. Renames + cfg dispatch: - crates/compositor/src/d3d_windows.rs (from d3d.rs) - crates/compositor/src/cpu_frames_windows.rs (from cpu_frames.rs) - crates/compositor/src/compositor_windows.rs (from compositor.rs) - crates/compositor/src/pipeline_windows.rs (from pipeline.rs) - crates/compositor/src/text_windows.rs (from text.rs) - crates/compositor/wrapper_windows.h (from wrapper.h) lib.rs cfg-dispatches 'd3d', 'cpu_frames', 'compositor', 'text' across the per-platform modules so call-sites stay portable. live.rs: Win32 harness (run_standalone, host_proc, wide, client_size) moved into a #[cfg(windows)] pub mod standalone_harness with a #[cfg(target_os = "macos")] no-op stub for run_standalone (poc-d3d is dev-only on Windows). Cargo.toml: macOS deps (metal, objc, block, core-foundation) added under [target.cfg(target_os = macos).dependencies]; windows dep gated to cfg(windows). compositor-view-napi mirrors the gate. crates/.cargo/config.toml: target-specific env block for macOS (LIBCLANG_PATH not needed, MAC_FFMPEG_DIR falls back via build.rs). build.rs: selects wrapper_windows.h vs wrapper_macos.h on CARGO_CFG_TARGET_OS, sets bindgen --target=aarch64-apple-darwin + -isysroot on macOS, finds MAC_FFMPEG_DIR or vendored thirdparty/ffmpeg-n8.1.2-macos64-lgpl-shared. Stacked on feat/d3d-warp-fallback (PR #162).

…ing back to WARP PR #162 scoped a WARP retry for the compositor's D3D11 device. Measured, WARP cannot serve this pipeline at all -- and not for the expected reason (speed): - WARP + D3D11_CREATE_DEVICE_VIDEO_SUPPORT does not create. It returns DXGI_ERROR_UNSUPPORTED (0x887A0004). - Drop the flag and WARP creates at FL 11_1, but QueryInterface for ID3D11VideoDevice returns E_NOINTERFACE -- zero decoder profiles. pipeline.rs hands Gpu's device to ffmpeg as the AVD3D11VADeviceContext, so preview and export decode every frame on it. A WARP device would produce none: the retry would only convert a clear startup failure into an obscure ffmpeg one. crates/compositor/tests/warp_device_cannot_decode.rs pins both measurements and fails if Windows ever changes them. So there is no fallback, and the answer to "WARP for export or preview only?" is neither. What the compositor does instead is fail in a way the user can act on: - Gpu::create re-probes on the failure path (same call, minus VIDEO_SUPPORT) to tell "this adapter has no video decoder" -- the RDP / VM case -- apart from "no FL 11_1 adapter at all", and says which, plus what to do. Export gets this for free: ExportDialog already renders the native message. - That message now reaches the preview too. create_view returns an id long before the render thread can die, so the failure existed only as an eprintln! and the user just saw a black canvas. The thread stores its fatal error in live::Shared, read_frame relays it as an Err on the next pull (~33 ms), and NativeCompositorOverlay renders it in place of the canvas. The WGC capture helper stays hardware-only on purpose: it requests no VIDEO_SUPPORT so a WARP device would be creatable there, but recording on a host whose compositor cannot start only produces footage the user can neither edit nor export.

PR #162's CPU backend commit (13e1a31) was applied on top of the GIF refactor that extracted `walk_composited_timeline` for the GIF path. The conflict resolution put the WARP branching inside the timeline walker, which doesn't have `out_w`/`out_h`/`out`/`params` -- those are MP4-specific. This commit moves the encoder creation back into `run_multi_inner` (where `out_w`/`out_h`/`out`/`params` are in scope) and adds the `if software_frames { ... } else { ... }` branching in the per-frame `on_frame` closure. Also fixes the unclosed `run_gif_bench` delimiter from the conflict resolution and adapts the call site to `export_gif`'s new signature (`(clips, out_path, gpu, comp, cfg, params, progress)` -- the GIF refactor moved from `(screen, webcam, cursor, out_path, params, dither)` to the slice-2 MP4-shaped signature).

Branch off the CPU-backend seam established by PR #162 and split the compositor crate into per-platform directories. Windows behaviour is byte-identical (81 tests pass) and the macOS stubs that follow this commit in the stack expose the same public surface (Backend, Gpu, Compositor, Decoder, VideoEncoder, ExportCodec, ClipSource, LiveParams, LayerCB...) and Err from every operation. Renames + cfg dispatch: - crates/compositor/src/d3d_windows.rs (from d3d.rs) - crates/compositor/src/cpu_frames_windows.rs (from cpu_frames.rs) - crates/compositor/src/compositor_windows.rs (from compositor.rs) - crates/compositor/src/pipeline_windows.rs (from pipeline.rs) - crates/compositor/src/text_windows.rs (from text.rs) - crates/compositor/wrapper_windows.h (from wrapper.h) lib.rs cfg-dispatches 'd3d', 'cpu_frames', 'compositor', 'text' across the per-platform modules so call-sites stay portable. live.rs: Win32 harness (run_standalone, host_proc, wide, client_size) moved into a #[cfg(windows)] pub mod standalone_harness with a dev-only on Windows). Cargo.toml: macOS deps (metal, objc, block, core-foundation) added under [target.cfg(target_os = macos).dependencies]; windows dep gated to cfg(windows). compositor-view-napi mirrors the gate. crates/.cargo/config.toml: target-specific env block for macOS (LIBCLANG_PATH not needed, MAC_FFMPEG_DIR falls back via build.rs). build.rs: selects wrapper_windows.h vs wrapper_macos.h on CARGO_CFG_TARGET_OS, sets bindgen --target=aarch64-apple-darwin + -isysroot on macOS, finds MAC_FFMPEG_DIR or vendored thirdparty/ffmpeg-n8.1.2-macos64-lgpl-shared. Stacked on feat/d3d-warp-fallback (PR #162).

"ISO with D3D" was an assertion. This makes the part of it that CAN be measured into a failing test, and says plainly what the rest is worth. The two backends cannot run on the same machine, so iso cannot be established by comparing two rendered images. What can be — and what is the layer where divergence actually happened on this branch — is the geometry: `plan_frame` is literally the same code on both sides, so its 15 outputs must be bit-identical. `plan_frame_is_pinned_bit_for_bit` pins them for a scene that exercises padding, crop, a displaced PiP camera, corner radii and the zoom, comparing with `to_bits()` rather than an epsilon. It runs in BOTH CI jobs — `rust-macos-compositor-check` and `rust-windows-compositor-check`. If the two platforms ever compute different placements, one of them goes red. That is the guarantee that was being claimed and never held: `webcam_shape_code` returned "rounded" on Windows and "rectangle" on macOS for months, and `LiveParams::default()` disagreed on two more fields, precisely because nothing compared them. What this test does NOT cover, and must not be read as covering: rasterisation. D3D11 and Metal will never be bit-identical — PR #162 measured 93-95 % of channels identical with a max deviation of 3/255 between two backends on the SAME machine, and that is the floor, not the target. Shader parity is held separately, by `shaders.metal` and `shaders.hlsl` having been diffed line by line across all 14 modes; nine divergences came out of that pass, three of them live. The expected values are measured from this code, not chosen. A drift is a divergence to explain, not a tolerance to loosen.