Files
AniCraft/docs/performance.md
T
Tanish Manku 9adaf9dd5d perf(render): 1080p back under budget (19.8 -> 15.5 ms): parallel background fill, early edge rejection, deferred frees
Measured with anicraft-cli bench (release, 32 threads), 3 runs each: render_1080p 19.4-20.2 -> 15.3-15.8 ms, render_zoom400 11.6-11.9 -> 9.0-9.3 ms. Output byte-identical.
2026-11-06 22:19:38 -07:00

3.7 KiB
Raw Blame History

Performance

Rule: measure first, then optimize, then record the number here. Every optimization lands with a benchmark delta and a test that it did not change output (the CPU renderer is the oracle; its output must stay bit-identical).

How to measure

cargo run --release -p anicraft-cli -- bench                      # 50 layers × 200 shapes × 240 frames
cargo run --release -p anicraft-cli -- bench --layers 200 --shapes 500 --frames 600

bench builds a deterministic stress document (doc::sample::stress) and reports file size, save/load time, evaluate/render time per frame, zoomed render with culling, snapshot cost, per-edit and per-undo time, history bytes per step and hit-test time. In the app, the status bar shows render time, shapes drawn and culled, frame-cache size and hit rate, and history memory.

Budgets

The default bench scenario: 50 layers × 200 shapes × 240 frames, 200k element instances.

Scenario Budget Measured 2026-11-06 (release, 32 threads) Enforced by
Edit command on a 200k-instance document < 1 ms 0.013 ms ✅ bench --check
Undo / redo < 1 ms 0.009 ms ✅ bench --check
Undo memory per small edit < 16 KB 2.7 KB ✅ test, every PR
Document snapshot < 50 µs, shares everything 0.04 µs ✅ test (sharing) and bench --check
Evaluate one frame (200k instances) < 4 ms 1.7 ms ✅ bench --check
Render 1080p, ~10k visible shapes < 16.7 ms (60 fps) 15.3–15.8 ms ✅ bench --check
Render at 400% zoom < 16.7 ms 9.0–9.3 ms ✅ bench --check
Shapes drawn at 400% zoom ≤ 1/8 of the frame's shapes 5.5% ✅ test, every PR
Hit test < 200 µs 52 µs ✅ bench --check
File size < 400 bytes per element instance 342 ✅ test, every PR
Save / load 65 MB file < 500 ms 123 / 146 ms ✅ bench --check
UI frame while rendering never blocked worker thread ✅ design (ADR 0002)

1080p render, back under budget (2026-11-06). It had drifted to 19.4–20.2 ms (v0.1.0 measured 18.0–18.9 ms on the same machine; the 16.5 ms of 2026-10-28 didn't reproduce). Timing each step of a frame showed the time was outside the drawing itself:

Change 1080p 400%
Before 19.4–20.2 ms 11.6–11.9 ms
Background filled per band, in parallel, instead of one serial 33 MB fill 16.9–17.5 ms 9.1–9.6 ms
Edges wholly above or below a band skipped before splitting; fill polygons moved, not copied 17.0–17.2 ms 8.9–9.1 ms
Prepared polygons freed on the pool after the frame, off the critical path 15.3–15.8 ms 9.0–9.3 ms

Output is unchanged: the sample's frames and a bitmap document render byte-identical before and after.

How budgets are enforced

  • Budgets that don't depend on the machine (undo memory, snapshot sharing, file size, culling) are a test (machine_independent_budgets in crates/cli), so the CI gate fails any PR that breaks them.
  • Timing budgets are cargo run --release -p anicraft-cli -- bench --check yes. It prints every measurement next to its budget and fails when one is missed. Shared CI runners vary too much in speed and core count to gate on time, so this runs on a known machine before a release and after performance work. A dedicated benchmark runner would let CI run it too.
  • The limits live in TIME_BUDGETS in crates/cli/src/lib.rs; keep that list and this table in step.

Decisions

  • ADR 0001: persistent document and snapshot undo
  • ADR 0002: render worker, frame cache, band parallelism, culling
  • ADR 0003: compact file format with shared paths