RustNotMC/docs/animated-sprite-mips-benchmark.md

Animated sprite mip cache

animate_sprites retains full mip chains for previously displayed source frames. The renderer owns an immutable snapshot of animations, size and mip settings; resource reload replaces that snapshot and drops its cache. Mipmap options only change the sampled view, so the full chains stay valid. Frame selection, skipped unchanged frames, upload order and mip bytes are preserved.

Admission is lazy, with an 8 MiB limit on retained Vec capacities and a separate 4,096-entry limit on map metadata. The existing fixed integer hasher avoids consuming random seeds for cache bookkeeping. An admitted frame stays until resource reload; a frame that does not fit uses the original generation path. There is no eviction churn. These limits apply to the additional cache, excluding the existing source frames and the original generator's temporary allocations. Map/allocator overhead is additional and bounded by the entry limit.

Reproduce

Use prepared 26.3 resources at .local/horizon-client/26.3. All block/item textures are loaded, including static layers that set the shared array size (the 64px straw-bed texture). The Python driver compiles the production gfx.rs functions and actual sprite/mipmap loaders into a private Cargo workspace under .local/sprite-mips-bench; it does not build the rest of the client or expose a benchmark API in the renderer. --ref selects the baseline's actual gfx code; the sprite/mipmap loaders are unchanged by this optimization. Both use release optimization, LTO off, 16 codegen units.

Build first, then release the lock before the paired measurement session. Keep all measurement pairs in one lock acquisition so other heavy work cannot overlap:

flock /tmp/horizon-optimizations-20261015-heavy.lock bash -c '
  set -e
  export CARGO_BUILD_JOBS=2
  python3 tools/bench_sprite_mips.py --ref 89b58991bbc02eb79b6965fc4ca56357fe2297d9 --label baseline --build-only
  python3 tools/bench_sprite_mips.py --label candidate --build-only
'
flock /tmp/horizon-optimizations-20261015-heavy.lock bash -c '
  set -e
  export CARGO_BUILD_JOBS=2
  for round in 1 2 3; do
    variants="baseline candidate"
    if [ "$round" = 2 ]; then variants="candidate baseline"; fi
    for variant in $variants; do
      python3 -c "import resource, subprocess, sys; subprocess.run(sys.argv[1:], check=True); print(\"max_rss_kib=\" + str(resource.getrusage(resource.RUSAGE_CHILDREN).ru_maxrss), file=sys.stderr)" \
        .local/sprite-mips-bench/target/release/sprite-mips-$variant \
        .local/horizon-client/26.3 .local/sprite-mips-bench/$variant/names.txt
    done
  done
'

Each process reports resource loading, its first frame (including one-time mip tables), nine warmed-code samples of fresh-state setup/first upload/teardown, and setup plus the first 4,096 ticks. It then samples 1,024 warmed animation ticks and 3,072 rendered frames at three renders per tick, nine times each. Another 1,024 ticks report CPU latency p50/p95/max. The warmed state is dropped before the unique workloads, keeping one live renderer cache at a time. A black-box upload callback consumes each slice without GPU calls. The unchanged initial atlas generation, GPU staging, draw calls and presentation are outside this CPU measurement; these numbers do not establish an FPS improvement.

The first-seen workloads request each distinct source frame found over 4,096 ticks once, and separately simulate 8,192 distinct array layers sharing real immutable inputs. The latter deliberately exceeds the cache budget and practical atlas sizes to exercise admission and fallback. Fresh-state samples include teardown. Source-frame samples report peak retained bytes for one animation; other samples report the state's retained pixel-buffer capacity.

Every process also compares complete upload streams with the original function at 517 tick positions, including duplicate ticks, jumps, rewinds and changing mip limits, using all real animations (including interpolation metadata). This preserves the existing frame-based path; it does not add or validate GPU blending of interpolated frames.

Validation

• pr_ready.py --base 89b58991bbc02eb79b6965fc4ca56357fe2297d9 --quick: public tree, formatting, workspace clippy, 196 Python tests and 635 client tests passed.
• Native animation parity: 907 fixtures (63 resource animations), including 258,996 tick states and 203 intentionally rejected inputs, match the pinned client.
• Native mipmap parity: 1,319 cases / 7,914 output lines match exactly.
• Native breaking-model parity: 2,740 cases / 155,928 vertices match within the harness tolerance; maximum error 1.40395e-07.

The full game parity suite was not run. This checkout has no recorded harness index; pr_ready --quick lists that deferred selection, and the relevant native harnesses above were run explicitly. GPU interpolation pixels and end-to-end FPS remain outside this evaluation.

Measured outcome

Kept. Ryzen 5 5600X (12 logical CPUs), rustc 1.99.0 (b940084d7, 2026-09-28), Linux; 2,131 prepared block/item textures, 54 animations and 594 distinct source frames. Three paired process runs, reversing baseline/candidate order in round two, each with one warmup and nine samples per workload (27 samples per variant). Both binaries used the same private Cargo dependency resolution and optimized profile. Baseline gfx is 89b58991bbc02eb79b6965fc4ca56357fe2297d9.

CPU times below are median [minimum, maximum], in milliseconds. Each repeated sample averages 1,024 ticks or 3,072 render calls; unique/cold samples include state setup and teardown.

Workload	Baseline	Cache	Median change
Fresh state + first tick + drop	7.532 [7.193, 7.567]	7.545 [7.128, 7.791]	+0.18%
Repeated tick	3.627 [3.491, 3.720]	1.692 [1.646, 1.739]	-53.34%
Repeated render, three renders/tick	1.203 [1.181, 1.244]	0.562 [0.546, 0.585]	-53.33%
Each actual source frame once	98.168 [96.647, 102.813]	97.093 [96.674, 104.441]	-1.09%
8,192 distinct layers, first frame	1123.475 [1088.996, 1156.957]	1121.300 [1087.745, 1154.184]	-0.19%

Repeated-tick medians for the three processes were respectively 3.647 / 3.646 / 3.540 ms baseline and 1.702 / 1.674 / 1.692 ms cached. The corresponding render-call medians were 1.233 / 1.195 / 1.192 ms and 0.562 / 0.556 / 0.562 ms. The improvement repeats in every pair; cold and unique-frame differences are within the observed variation.

Additional per-process samples, baseline → cache:

• Resource decoding: 69.829 / 69.350 / 67.308 → 68.632 / 66.235 / 67.252 ms.
• Process-first setup/upload/drop, including mip table initialization: 7.255 / 7.979 / 7.610 → 8.796 / 7.706 / 7.688 ms. The first cached process had a cold outlier; no cold-start speedup is claimed.
• Setup plus first 4,096 ticks, including cache fill: 14.835 / 15.001 / 14.746 → 7.053 / 6.997 / 6.955 seconds.
• Individual warmed-tick p50: 4.311 / 4.313 / 4.318 → 1.639 / 1.543 / 1.550 ms; p95: 6.613 / 6.617 / 6.885 → 4.139 / 3.960 / 3.972 ms; maximum: 7.621 / 7.702 / 7.569 → 5.285 / 6.448 / 5.213 ms.
• Whole-process peak RSS: 84412 / 83388 / 85416 → 84480 / 83820 / 84524 KiB, using a fresh Python parent's resource.getrusage(RUSAGE_CHILDREN).ru_maxrss per invocation. RSS includes resource loading and the synthetic workload, and allocator reuse/other peaks hide the retained cache cost; it does not establish zero added memory.

At 64px, each generated chain has 32,768 bytes of Vec capacity. The cache retains 256 entries / exactly 8,388,608 bytes, with map capacity 448, and bypasses the remaining frames. Retaining all 594 frames would require 18.56 MiB of buffer capacity. The first tick retains 1,769,472 bytes; the one-animation-at-a-time unique-source workload peaks at 1 MiB. The separate 4,096-entry cap bounds map metadata for tiny textures. No GPU memory or upload bytes are saved.

All six measured processes passed the 517-position upload-stream comparison. The 196 Python tests were rerun after adding the build-only driver mode and passed. The first RSS wrapper attempt failed before collecting samples because /usr/bin/time was unavailable; the complete paired session above uses Python resource counters. Private raw output remains under .local/sprite-mips-*.