0011: A surface dragged is previewed by a draft, patched in place; the edit compiles on release¶
2026-11-03. Accepted.
Context¶
An edit of the input recompiles against the model shown (decision 0010): 2.5–5 s on the reference model, most of it the front end, whole universes rebuilt and a 1.5 GB GPU upload. That is fine for an edit typed and applied, but too slow to follow a surface as it is dragged.
Moving one surface changes little:
- its shapes (one or a few, shared by every cell that uses it);
- the boxes of the cells using it;
- through the rois, the boxes of the universes those cells fill;
- the BVH boxes above all of these.
Every query stays exact without octrees and without node boxes: both are accelerators.
A census of the reference model (592 587 surfaces used) found 6 surfaces used by lattice
cells, none with TRCL copies, and each in one universe. Cells per surface: p50 6,
p99 164, max 6 350.
Decision¶
llevant::draft::Draft(draft.rs) holds a copy of the model shown (sharing its octrees) and moves one surface in it.Draft::beginrefuses what it cannot follow exactly, with the reason:- a cut model;
- a surface not in the input, or not compiled;
TRCLcopies;- surfaces used by lattice cells;
- an
IMP:N=0cell of universe 0 when a problem box exists.
Draft::set(coeffs)does the following:- rebuilds the shapes on the compiler's own path (
build_surface); - bounds the moved cells against their unit's roi, leaving their node boxes unrestricted;
- grows the rois of the universes they fill, lattices too, and bounds those cells again (rois only grow, so boxes stay conservative);
- refits the BVHs;
- turns the CPU octree of every moved unit off (
pending, so the draft cannot be saved).
- rebuilds the shapes on the compiler's own path (
- It returns a
DraftPatch: what changed, in export layout. Patches are cumulative: each one covers every record any step changed, so only the latest is ever needed.revert_patchgives the model back. GpuModel::patchwrites a patch into the model uploaded, in place:- one staging buffer and one copy per run of contiguous words;
- no new upload and no new shader.
- A unit with at most 64 moved cells keeps its octree on the GPU: their leaf
programs become
PROG_FULL, and they join the unit's always list in a slack area of 2¹⁶ words reserved at the end of the pool. A unit with more moved cells has its octree switched off (grid_root = NONE), and the GPU falls back to the BVH there. Draft::widen_skipmakes the skip of the visibility shown safe for the draft: nothing is skipped in, or under, a unit that moved.- The viewer offers a surface's coefficients as scrub fields in the inspector.
- A worker thread owns the draft and runs the latest step asked for.
- The GPU backend's trace thread writes the latest patch between jobs, so no job mixes two models.
- When no newer step waits, a snapshot of the draft goes to the slice view (and to the CPU backend).
- On release, the card is written (
Source::surface_with_coeffs) and compiled through the existing edit path. The preview stays until the new model lands. - Esc, a drag back to where it began, or a failed edit write the revert patch.
- The edit itself is unchanged. The model kept is always the one recompiled from the text, with the byte identity of decision 0010. A draft is never saved, cached or reused.
Numbers (reference model, release, laptop)¶
Draft::begin (model copy, analysis, cells using the surface) |
92–140 ms |
| A step, p95: envelope and filler surfaces, median and most cells | 0.5–13 ms |
| A step whose roi cascade bounds 6 330 filler cells again | 36 ms |
| Snapshot for the CPU views | 46–68 ms |
| CPU slice, 1000 rows: model / draft with the level-0 octree off | 97 / 213 ms |
| GPU patch (written and waited for) | 7–28 ms |
| GPU 1080p frames, draft vs model: level-0 octree kept | 1.01× |
| The same, the 6 350-cell filler surface (its moved cells' node boxes unrestricted) | 1.23–1.41× |
Before this design, with node boxes bounded and the octree switched off, a level-0 step took up to 325 ms, and frames ran up to 10× the model's. Those numbers are why node boxes are left unrestricted and level-0 octrees are kept on the GPU.
Consequences¶
- A draft is exact. Its classify labels are those of brute force on a fresh compile of
the edited input, its traces agree with that compile, and its cell boxes contain
that compile's (
crates/llevant/tests/draft.rs). A patched upload renders as a fresh compile does (crates/llevant-gpu/tests/draft.rs). - The GPU patch (7–28 ms) misses the 5 ms gate the plan set. It runs on the trace thread between jobs, not on the UI thread, and patches are cumulative, so a slow one only delays the next frame of the preview.
- The upload reserves 256 KB of slack, whether or not a drag ever happens.
- What is not draggable falls back to typing the card and Apply. While a drag runs, the 3D backend cannot be switched.
- Drafts move one surface at a time. A draft for a
TRcard was built and dropped (2026-11-08, decision 0012 step 6): oneTRcan move thousands of surfaces in universe 0, and keeping the octree, its programs per leaf and the hidden-space skip valid in place cost 0.25–2.6 s a step. Without them, the reference model's overview was 50× slower while dragging.