[with-developer]

Purpose

Issue #81 asks how long a decode takes while a client's display loop draws at the screen's refresh. This is the Mac's half; the iPhone's needs the phone.

Changes

• scripts/bench_app_on_mac.sh -display (and -short): a borderless window covers a screen while a CVDisplayLink and a CAMetalLayer draw the last decoded picture at the refresh. emberwave (Y, Cb, Cr textures and RGB) and HEVC (NV12) decode as frames arrive, each way without the loop and with a 60 and a 120 Hz loop in the same run. The report adds the time from a frame's arrival until the display presented it.
• The shared benchmark code gets a PictureSink type, a rate argument for FrameClock and entry points that decode a prepared HEVC stream paced with a sink. The iOS app's behaviour does not change; the shared files typecheck for the iOS Simulator, and scripts/bench_app_on_mac.sh -autorun passes.
• BENCHMARKS.md section "In a display loop, on the Mac", decision D72, and the READMEs' roadmap note.
• A review (Sonnet) of the first version led to a second commit: whole beats of the stream's drift against a 60 Hz loop, a black window in the rows without a loop, a guard that stops the run where the window never reaches the screen (a sleeping or locked screen), and a few counting fixes.

Result (two runs of the first version, M3 Max, 2026-11-06)

• Into the planes, emberwave decodes as quickly as or up to 0.8 ms quicker than HEVC into NV12 in the loop: 3.25 to 3.55 against 4.00 to 4.07 ms at 4K.
• The loop costs emberwave 0.2 to 0.5 ms and HEVC nothing; it does not keep the GPU's clock up.
• The time to the screen is 17 to 21 ms for every way and does not tell them apart.

Limits

• The runs were made with the first version. Its mean time to the screen at 60 Hz depends on the start phase by about 1 ms, and its rows without a loop ran with no window on the screen; BENCHMARKS.md says so. The decode times are not affected by the first. The runs are to be repeated with the changed program once the Mac's screen is unlocked (it was locked when this was finished).
• The stream arrives at 59.5 frames a second so that frames drift across the refreshes. The Mac's 60 Hz external monitor took no window, so the 60 Hz loop draws every second refresh of the 120 Hz screen. The Mac was not quiet (load average 4 to 7).

Testing

scripts/bench_app_on_mac.sh -display twice, in full, with the first version; -display -short while developing; scripts/bench_app_on_mac.sh -autorun after the last commit. CI builds the iOS app and runs -autorun; it never runs -display.

Refs #81