Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

docs(perf): record the per-mode pipeline choice and what Windows and macOS still lack

Etienne Lescot39dafafd3bca
diff --git a/technical-documentation/engineering/rendering-performance.md b/technical-documentation/engineering/rendering-performance.md
index 3d581afe3..77db05db4 100644
--- a/technical-documentation/engineering/rendering-performance.md
+++ b/technical-documentation/engineering/rendering-performance.md
@@ -324,6 +324,8 @@ A third machine and a third pipeline: the Ryzen 5 7520U laptop of the reference
The three 3D models alone account for 48 → 168. They now compile into a second pipeline (`LAYER_MODELS`, prefixed to the source by `layer_source`), drawn only for the layers that use them; everything else goes through the flat one. Going further down to 32 VGPR measured no faster here — past ~20 waves the screen draw is bound by the memory it shares with the CPU decoder, not by latency hiding.
+**Which pipeline a layer takes is decided by its mode, at the draw** (`LayerCB::needs_models`, read by `draw_layer` in all three backends), not by the call site. The first version routed the three call sites known to draw a model and missed a fourth: a device frame's shadow is itself a mode-17 model (`device_shadow_cb` builds on `device_frame_cb`), and the flat pipeline drew nothing for it. D3D11 and Metal got the same split — `ps_main_models` compiled by `build.rs` with a `D3D_SHADER_MACRO`, a second Metal library with the macro prefixed — without being measured on either: the flat `ps_main` compiles to 40 KB of DXIL against 137 KB with the models (dxc 1.9).
+
The GPU time per frame, from per-pass timestamps (`TIMESTAMP_QUERY_INSIDE_PASSES`, throwaway instrumentation):
| draw | 1.11.0-rc.1 | 2.0 split pipelines | after the fixes below |
@@ -819,7 +821,7 @@ the bench runs on the reference machine.
## Known gaps
-- **The D3D11 and Metal layer shaders have the same shape as the WGSL one was**: one pixel shader, every mode, the 3D models included. Whether an AMD or Intel iGPU under Windows pays the same occupancy for it is unmeasured; the M1 shows no regression on 2.0, which says nothing about fxc's register allocation. [The Linux section](#the-linux-export-path--2026-10-02) has the method — the instruction and register counts first, then the export.
+- **The D3D11 and Metal layer shaders were split like the WGSL one without a measurement on either.** Whether an AMD or Intel iGPU under Windows paid the same occupancy for the models is unknown, and so is what the split buys there; the M1 showed no regression on 2.0, which says nothing about fxc's register allocation. [The Linux section](#the-linux-export-path--2026-10-02) has the method — the register counts first, then the export. The static-background cache and the scissored cursor-trail composite are Linux-only: the other two backends still redraw the wallpaper every frame and composite the trail over the whole output.
- **macOS export startup can cost 4 s, and nobody has reproduced it on demand.** Measured repeatedly at 4208–4502 ms between the CLI's `started` event and the first composed frame — 18 % of a 60 s export, 71 % of a 5 s one — then gone, on the same shipped binary, hours later (481 ms). It is not the compositor (init is 2.4 ms, runtime MSL compilation included), not the `<video>` metadata probes (13 ms and 6 ms), not the CLI prologue (24 ms total), and not the renderer entry point (measured at −0.1 %). It correlates with memory pressure on an 8 GiB machine — `387M unused / 2613M compressor` while it reproduced, `564M unused / 1837M compressor` after — which would fit faulting ~1.8 MB of module chunks out of a 274 MB `app.asar` while the compressor thrashes: seconds of wall clock, no CPU in either process, cost independent of the media. Untested. Recreating the pressure deliberately and watching it return is what would settle it, and then whether asar size is the lever.
- **10-bit and HEVC decode on macOS are unmeasured.** The export's decode predicate is `codec_id == H264 && format == YUV420P`, so both keep VideoToolbox untested. HEVC is the case most likely to invert the result, since its software decoder is materially more expensive. 10-bit needs work beyond the predicate first: `mac_frames::CpuFrames` converts to 8-bit NV12, so routing 10-bit through the software path would silently truncate — the predicate is currently what prevents that.
- **The macOS preview's decode backend has never been measured.** `DecodeIntent` splits preview from export precisely so the preview could keep the old arbitration; the export won on throughput, but the preview scrubs, where seek latency after `avcodec_flush_buffers` may matter more, and it shares the machine with the editor UI. Changing it without measuring it would be the same mistake the export change corrects.