0010: Models are usable before their octrees, and an edit recompiles against the last version¶
2026-11-01. Accepted.
Context¶
A cold compile of the reference model takes ~40 s (dist): parse and assemble 1.3 s, cell boxes 8.3 s, BVHs 0.04 s, octrees 30–40 s. Every change to the input paid all of it again, and the viewer's reload rebuilt everything (document, undo, selection, GPU upload).
The octrees are an accelerator: every query is exact through the BVHs alone. Measured on the reference model (dist, 16 threads, laptop):
| Without octrees | With octrees | |
|---|---|---|
| Compile | 8.7 s | 39.5 s |
| GPU frame, 1920×1080 | 452 ms | 279 ms |
| CPU slice, 1000 rows | 263 ms | 88 ms |
| Points | 7.8·10⁵/s | 6.6·10⁶/s |
| CPU render | 27.9 s | 2.0 s |
check |
393 s | 89 s |
The GPU stays usable without octrees (frames are sliced and previewed, so the view stays responsive), so a model can be shown before they are built.
Decision¶
- Staged models.
Model::compile_stagedstops after the BVHs and leaves each unit's octree pending;Model::complete(orcompleted) builds them;compileis the two in turn. A staged model answers every query exactly, only more slowly, and cannot be saved. Completed, it saves the same bytes ascompile. - Node-box ids local to each cell (
Cell::node_start), and octrees seeded by universe number: what a unit's boxes and octree are depends on that unit alone. Model::recompile(old, input)runs the front in full (parse, surfaces, cells, assembly) and lets each unit take its cell boxes, node boxes and octree from the unit of the same universe inoldwhen its content is the same: same region, same cells by number in the same order, programs equal up to shape indices, shapes equal bit for bit, same flags and options. Indices that moved (cells or surfaces added or removed before it) are remapped: the octree's candidates and its residual programs' leaves are rewritten. Other units are computed again and left pending. Reuse is decided on compiled content, soLIKE BUT,#n,TRchains and comments need nothing of their own, and migjorn needs no change.- The contract is byte identity: a recompiled model, completed, saves the same
bytes as a fresh compile of the new input (
tests/recompile.rs: every kind of edit on the zoo models and a proptest, from complete and staged bases, back and forth). A reuse bug cannot hide behind a test that only samples queries. - The cache recompiles against the last version.
Storekeeps the last entry of each input path (<cache>/last/); on a miss it reads it (~1 s) and recompiles against it.Store::loadstays complete (CLI, Python);Store::load_stagedreturns a staged model andStore::completefinishes and stores it (the viewer). - The viewer shows a staged model at once and swaps in the completed one when its octrees land; a reload recompiles against the model shown and replaces it in place (history, selection, tools' state kept), completing first when the rebuilt universes hold at most a quarter of the cells.
Numbers (reference model, dist, laptop)¶
| Before | Now | |
|---|---|---|
| Viewer, cold: first view | ~45 s | 14.9 s (complete at ~52 s) |
| Envelope surface moved: staged / complete | 39.5 s | 3.3 s / 5.1 s |
| Filler surface moved: staged / complete | 39.5 s | 2.5 s / 3.5 s |
| CLI after an edit (cache recompiles) | 42.8 s | 7.4 s |
| Level-0 cell removed (every index after it moves): staged / complete | 10.9 s / 44.4 s (nothing reused) | 4.3 s / 5.8 s (release) |
Consequences¶
EXPORT_VERSION2 (node boxes per cell,CELL_WORDS13) and saved format 3.- The first GPU upload of a new layout compiled a shader variant in the driver (~9 s staged, ~30 s complete, once per driver cache). Since 2026-11-02 the shader depends only on the depth of programs and BVHs: staged, complete and most edits share it.
- While octrees build, the viewer's previews were slower (the CPU is shared): 95th percentile frames of 33 ms. The viewer builds them on a pool of lower-priority threads since 2026-11-02: 19 ms.
- After a reload the viewer checks where the edit can have opened a gap or an
overlap: the instances of the changed cells, old and new (
Model::instance_boxes,Model::volumes_within): 6 s for an envelope surface of the reference model. - The viewer edits cards in the inspector: migjorn replaces the card's text
(
llevant_scene::source::edit_card), thenrecompileagainst the model shown, the cards read again alongside. On the reference model (377 MB of input) migjorn added ~2 s to an edit (parse and write) beside the recompile; undo keeps only the bytes each edit replaced. Since 2026-11-02 the viewer keeps migjorn's tree, edits it in place and compiles it (Model::recompile_parsed): no parse per edit. - Open: on the reference model, the upload of the completed model can wait while the views keep the GPU busy (orbiting without a pause, it did not land within 40 s); it lands once the view rests.
Left out¶
- Local octree patches: they save at most 1–4 s per edit, make the model differ from a fresh compile, and need their own proof.
- A cache per universe: recompiling against the last entry of the same path gets the same reuse with no new format or eviction policy.
- Reusing BVHs: 0.04 s to build.
- Stack depths rounded up so that edits deepening a program keep the shader: 6–7 % slower frames.