[with-developer]

Purpose

Say roughly what a decode or an encode costs on devices we cannot measure, without asking for the user's phone each time (#159).

Summary

• scripts/perf_model.py (standard library only) fits time = fixed + per_pixel x megapixels for decode to planes, decode to RGB and encode on the M3 Max, from the C API runs of release 0.11.0 (2026-10-26 and 2026-10-27), and scales the per-pixel term by memory bandwidth for other chips. --markdown prints the table, --write BENCHMARKS.md fills it between the file's markers.
• BENCHMARKS.md gains "Estimates for other devices": the table, marked as estimated and kept apart from the measured tables, with its basis, its check and its limits.
• ARCHITECTURE.md records the choice as D71.

What the numbers say

• The lines are straight within 0.04 ms at every size. Fixed costs are alike on the two devices (0.2 to 0.5 ms).
• The iPhone 17's per-pixel cost is 5.2 to 5.6 times the M3 Max's, against a bandwidth ratio of 5.9.
• Checked against the iPhone 17's own measurements, the model reads 6 to 8 % high for decoding to planes, 7 to 9 % for RGB and 11 to 16 % for encoding, always above. The table says it is no better than 15 %.
• Paced decoding (60 frames a second) is not modelled; it stays measured (bench: decode latency inside a client's display loop #81).

How to test

python3 -I scripts/perf_model.py            # fit, check, estimates
python3 -I scripts/perf_model.py --markdown # the table

Documentation and a script only: no library code changes, so no benchmark impact.

Refs #159.