Performance Baselines

This page records measured memory and timing baselines. The allocation test is the regression gate; the CLI numbers are diagnostics for changes that cannot be measured inside the test process.

Allocation peak test

crates/litematic/tests/memory.rs measures peak heap allocation for LitematicFile::parse_bytes and parse_bytes + into_scene. It uses a process-global GlobalAlloc meter, so all scenarios live in one binary and run sequentially.

cargo test -p blockscope-core --test memory -- --nocapture

The fixtures are synthetic and compressed before the measured window. The 512^3 sparse fixture uses custom volume limits because the default 100M per-region limit rejects it. This is intentional: it measures the representation cost, not the admission policy. Baseline on 2026-10-28, Windows x86_64, 48 GB host, cargo test debug profile:

Fixture	Blocks	Parse peak	Parse + scene peak
tiny `2^3` dense	8	76,406 B	76,406 B
sparse `256^3`, 1 stone	16.8M volume	12,588,227 B	12,588,227 B
sparse `512^3`, 1 stone	134.2M volume	100,668,611 B	100,668,611 B
dense `256^3` stone	16.8M	12,588,226 B	12,588,226 B

Re-verified after the review fixes on 2026-10-28: all four rows are byte-identical. The new crates/nbt/tests/memory.rs also pins the decoder’s pre-allocation guard: a truncated NBT document that declares a 64M-element int array or a 1M-element list must stay below 1 MiB of allocation instead of reserving the declared size. The sparse peak scales with bounding-box volume: 512^3 is 8x 256^3, which is exactly the volume ratio. parse+scene adds no measurable peak because the packed array is moved into the scene rather than copied.

CLI diagnostics

Measured with the release binary on the same host. 000001 is the 9.39M-block, 211^3 fixture. render used a color-only catalog, 1024x1024, supersample 2, 12 threads, and --force-limits because the default 5M-quad cap rejects the exact mesh. The rows below were re-measured on 2026-10-28 after the review fixes; peak working set is sampled every 20 ms, so expect roughly 10-15% run-to-run variation on the short validate cases.

Command	Peak working set	Notes
`validate 000001`	103 MB	parse + scene
`validate 000002 --force-limits`	176 MB	50.65M blocks; 176-178 MB observed
`validate 000003 --force-limits`	145 MB	67.1M blocks; 140-145 MB observed
`validate 000004 --force-limits`	140 MB	67.1M blocks; 122-149 MB observed
`render 000001 --stream-mesh --force-limits`	433-435 MB	color-only, 11.1-11.4 s wall, 91.5M triangles
`render 000001 --stream-mesh=off --force-limits`	7.68 GB	color-only, 11.9 s wall, same PNG as streamed
`render 000001 --force-limits --client-jar`	591 MB	exact translucent spill, 17.0 s wall, same PNG hash
`render 000002 --force-limits --client-jar`	216 MB	default auto streaming, 4.1 s wall
`bench 000001 --force-limits`	6.8 GB	historical full-mesh run; not re-measured
`bench 000002 --force-limits --client-jar`	3.8 GB	historical full-mesh run; not re-measured
synthetic sparse `1024^3`, 1 block, `--force-limits`	495 MB	historical `validate` run; not re-measured

The older table rows for validate 000002/000003/000004 (132/130/115 MB) and the 407 MB / 8.8 s color stream were from an earlier build and host state. Both the current build and the pre-review HEAD binary measure 176-178 MB for 000002 and 11.6-11.8 s for the color stream on this host, so the differences are not review regressions. The textured 000001 stream is 591 MB after the spill path was enabled; the earlier in-memory path peaked at 1.52 GB before spilling. The material set itself is about 227 MB; most of the remaining difference is the mesh chunk, resident tiles, and translucent triangles. The client-jar PNG SHA-256 is identical between HEAD and the review build. The 18.9 GB figure in docs/rendering.md is the client-jar full-mesh path with more quads, not the streamed render path. The re-measured streamed color path is 433-435 MB and the current full color-only path is 7.68 GB. This is why the sparse parser is a conditional spike rather than a committed rewrite.

CPU client-jar baseline (2026-11-06)

The color-only rows above are diagnostics, not a model of real use. On 000002 the jar path has 17.3x more triangles (2.30M to 39.82M); on 000001 it has 2.5x more translucent triangles (9.52M to 24.09M). It also spends about 1.7 s decoding the 227 MB material set before rendering starts. Measured on the R1 host with the release binary, CPU backend, --stream-mesh=on, 1024x1024, supersample 2, 12 threads, --force-limits, and fixtures/private/texture/26.2-Fabric.jar. Peak working set is sampled every 20 ms.

Case	Triangles	Parse	Mesh	Render	PNG	Total	Peak
`000002` color	2.30M	224.5 ms	423.5 ms	666.7 ms	46.7 ms	1,399.8 ms	191.1 MB
`000002` jar	39.82M	230.3 ms	1,453.4 ms	2,458.5 ms	46.9 ms	4,586.9 ms	205.3 MB
`000001` color	91.57M	203.5 ms	5,472.5 ms	6,933.9 ms	64.6 ms	12,714.7 ms	433.7 MB
`000001` jar	128.63M	198.3 ms	5,349.3 ms	12,421.6 ms	64.5 ms	19,736.8 ms	580.6 MB

Total is the CLI-reported total. For the jar rows it includes about 0.4 s (000002) and 1.7 s (000001) of material and texture loading that is not part of parse, mesh, render, or PNG. The peaks are 205 MB and 581 MB, not the multi-gigabyte full-mesh path. The jar triangle mix explains the render split:

Case	Opaque	Cutout	Translucent
`000002` jar	39.60M	181k	38k
`000001` jar	84.68M	19.87M	24.09M

Stage timing from a temporary instrumentation build. The timed run is about 9% slower than the non-timed render on 000001; use the ratios, not the absolute sum.

Case	Project + bin	Tile	Spill write	Translucent resolve	Assembly	Downsample
`000002` jar	923 ms	1,690 ms	157 ms	4 ms	57 ms	5 ms
`000001` jar	2,586 ms	3,866 ms	2,853 ms	4,171 ms	50 ms	5 ms

000002 is tile-bound. 000001 spends about 7.0 s in the translucent path, more than half of its render time, and the spill write is serial on the main thread. The library path behind the older full-mesh benchmark rows is not a substitute for these streamed CLI numbers. The streamed CLI color-only 000002 render is 667 ms here, not the roughly 214 ms measured through the four-chunk library path, because the streamed mesh builder emits 432 32-page chunks for this fixture. That fixed per-chunk cost is another reason not to use color-only bench results as a jar proxy. --greedy-mesh with the jar was also measured: 000001 triangles changed by -0.06% while mesh time grew 35% and render time grew 1%; 000002 triangles fell 1.2% while mesh time grew 73% and render time fell 3.5%. It stays opt-in. Commands:

$exe = (Resolve-Path .\target\release\blockscope.exe).Path
$jar = (Resolve-Path .\fixtures\private\texture\26.2-Fabric.jar).Path
& $exe render fixtures\private\000001.litematic --client-jar $jar `
  --backend cpu --stream-mesh=on --width 1024 --height 1024 `
  --supersample 2 --threads 12 --force-limits --output .\out.png

P0 CPU streaming changes (2026-11-06)

The first CPU P0 slice targets the client-jar hot path:

Translucent spill writes run on a FIFO writer thread with a 16-part queue, so spill I/O overlaps opaque rasterization.
The spill bucket reader decodes the next bucket while the current bucket is sorted and rasterized, using one reader plus the normal tile workers.
Quads and triangles whose bounds lie entirely outside the image are dropped before binning, and tile rasterization no longer repeats the bounding-box intersection test for every binned candidate.

A temporary BLOCKSCOPE_SYNC_SPILL build switch disabled the writer overlap and bucket read-ahead so both paths could be timed on the same binary. It has been removed. 000001 jar, 1024x1024 ss2, 12 threads, two alternating runs per mode:

Mode	Render	Wall	Peak
serial spill + serial bucket read	11,698 / 11,690 ms	21.73 / 21.75 s	580.6 / 580.1 MB
writer overlap + bucket read-ahead	11,114 / 11,133 ms	20.70 / 20.60 s	579.8 / 579.7 MB

The controlled difference is about 4.9% render and 5.2% wall time, with no measurable peak change. 000002 jar measured 2,701 / 3,011 ms serial versus 2,788 / 2,775 ms overlapped; its translucent layer is too small for a stable signal. The PNG SHA-256 values for both fixtures are unchanged. A post-change spot check on the same host measured 000001 jar render 9.42-9.79 s, total 16.86-17.79 s, peak 578-580 MB, and 000002 jar render 2.35 s, total 4.52 s, peak 205 MB. Both PNG hashes still match the pre-change files. Treat these as point-in-time diagnostics; the alternating A/B above is the attribution. Three experiments were measured and reverted:

Quad-level triangle setup: no render win and a slower 000002.
Adaptive mesh chunks sized by a quad budget: neutral speed, but peak rose by 26-90 MB depending on the target.
Batch texture preload with parallel PNG decode: no wall-time win even after preserving first-use texture ids; on 000001 the prefetch runs were 0.7-1.1 s slower than the clean run, because the model pre-scan offset the decode gain.

Absolute run times drift with host state; use the alternating A/B table for the P0 claim rather than comparing runs from different times.

Fast CPU projection (2026-11-07)

--precision fast stores the CPU screen-space quad table as f32 instead of f64. QuadRender drops from 128 to 80 bytes, so projection writes and tile reads shrink; the default exact path and its golden PNGs are unchanged. Same-process A/B with the client jar, alternating exact and fast iterations on one parsed scene and mesh:

Case	Exact median	Fast median	Gain
`000002` jar	2,403.8 ms	2,007.4 ms	16.5%
`000001` jar	10,781.2 ms	10,203.4 ms	5.4%

Peak working set on the CLI path: 000001 exact 575-579 MB, fast 546-549 MB; 000002 is about 206 MB in both modes. Fast mode is explicitly approximate. On the same 1024x1024 jar renders it changed 297 pixels (0.028%, max channel delta 21, no alpha changes) on 000002, and 66,978 pixels (6.388%, max delta 180, 75 alpha pixels) on 000001. It is opt-in; use exact for byte-for-byte comparisons. A hybrid fast point (f32 x/y with f64 depth) was also measured. It reduced the 000001 difference only from 6.39% to 5.94% while cutting the 000002 gain from 16.5% to 10.7%, so the simpler f32 point is the shipped fast path.

Compact mesh quads (2026-11-07)

Quad no longer stores four float vertices. Grid positions are packed as i16 with a per-quad scale, axis normals as i8 components, and UVs as four Q12 pairs. Fluid, rotated, or otherwise non-grid vertices use per-page float_positions and float_normals side tables. The packing only accepts a value when i16 / scale reproduces the original f32 value (signed zero is canonicalized), so rendered output is unchanged. Measured with the client jar, release build:

Case	Old mesh	New mesh	Change	Old mesh build	New mesh build
`000002` jar	3,897.5 MB	2,909.0 MB	-25.4%	1,136 ms	1,403 ms
`000001` jar	12,608.0 MB	11,321.3 MB	-10.2%	4,236 ms	5,213 ms

The gain depends on how many quads are on the grid. 000001 is dominated by fractional plant and fluid geometry, which must stay in the float tables and is therefore larger than the old uniform quad. Ranked medians of three alternating runs measured mesh build CPU 20-25% higher. Streamed exact-render peaks were about 204 MB (000002) and 565 MB (000001), slightly below the main build; both PNG hashes match it exactly. Public API note: Quad.vertices and Quad.normal are gone. Read positions through MeshPage::quad_positions, normals through MeshPage::quad_normal, and UVs through Quad::uvs; Quad::new is the builder entry point.

Quantized mesh positions (2026-11-07)

--quantize-mesh keeps the compact 64-byte Quad layout but rounds every position to a 1/1440 block grid, so MeshPage::float_positions normally stays empty. 1440 is the least common multiple of common model denominators (2, 3, 4, 5, 8, 9, 16), so vanilla fluid and plant vertices remain exact; arbitrary rotations move by at most 1/2880 block. It is opt-in because those rotations can change edge pixels. Measured against the compact exact build with the client jar:

Case	Exact mesh	Quantized mesh	Change	Exact build	Quantized build
`000002` jar	2,909 MB	2,868 MB	-1.4%	1,373 ms	1,408 ms
`000001` jar	11,321.8 MB	9,594.9 MB	-15.3%	4,759 ms	4,865 ms

000002 renders the same PNG hash and gains little because most of its quads were already grid-packed. 000001 is fluid/plant-heavy: total mesh memory is 23.9% below the pre-compact build, and the streamed exact-render peak fell from 566.6 MB to 543.8 MB. The cost is 22,443 changed pixels (2.14%, max channel delta 180, 31 alpha pixels). Mesh build CPU stays within about 3% of the exact compact path. Use exact mode for golden or hash comparisons.

CPU streaming pipeline (2026-11-07)

The CPU streaming path now batches small mesh chunks before rendering, reuses per-tile bin allocations across chunks, and persists the page capacity hint across streamed chunks. render and the CPU serve path buffer small chunks until 150,000 quads and pass larger chunks through; the mesh builder still emits 32-page chunks, so the mesh peak does not grow just because the render batch is larger. Moving the hint out of build_page_chunk was the largest mesh change: the 000001 jar mesh median fell from 5.5 s to 3.1 s without increasing the resident page count. Bin lists reuse their allocations, but bins above 256 entries are shrunk to 128 on reuse so one dense chunk cannot pin the peak for the rest of the render. The mesh crate also exposes owned-chunk streaming variants, so the CLI moves pages instead of cloning every Quad. The translucent spill encodes each triangle once and only patches the tile index per record. Per-tile translucent sorting uses sort_unstable_by with the original bin position as the tie-break, so equal depth keys keep their previous order while the sort avoids the stable merge-sort allocation. Same-host A/B, baseline commit 219350b versus the current build, release, CPU, --stream-mesh=on, 1024x1024, supersample 2, 12 threads, --force-limits, and --no-file. Runs alternate baseline and current binaries; PNG hashes were checked in separate runs.

Case	Baseline render	Current render	Render change	Baseline total	Current total
`000002` color	758.9 / 669.0 ms	179.2 / 192.3 ms	median -74.0%	1583.6 / 1416.3 ms	964.2 / 990.5 ms
`000002` jar	2250.2 / 2173.8 ms	1929.0 / 1852.7 ms	median -14.5%	4173.2 / 3989.3 ms	3752.7 / 3634.8 ms
`000001` jar	9438.9 / 9201.7 ms	9377.7 / 8618.5 ms	median -3.5%	16827.3 / 16603.0 ms	14229.5 / 13639.4 ms

000002 color is the clearest case: the old streamed CLI path paid the projection and tile barriers once per 32-page chunk; batching cuts 432 render passes to roughly 16 at 150,000 quads. 000002 jar also benefits from the smaller retained bin pool. 000001 jar is dominated by the translucent spill and sort, but its mesh stage still drops from a 5.49 s median to 3.04 s, cutting total wall time by about 16.6 percent. Peak working set is 8-13 percent above the baseline because the render batch and bin pool are slightly larger; it remains far below the old spilled in-memory path:

Case	Baseline peak	Current peak
`000002` color	175.2 MB	about 199 MB
`000002` jar	205.6 MB	231.5 MB
`000001` jar	585.9 MB	636.6 MB

The unstable sort was isolated with two binaries built from the same tree, one with the stable sort and one with the tie-break sort. On 000001 jar: stable 9,490.1 / 10,305.4 ms, tie-break unstable 9,132.2 / 9,615.2 ms, a 5.3% median render reduction. PNG SHA-256 values are unchanged:

Case	SHA-256
`000002` color	`92F1244E88CF2F390B24A239419B5C8D4B732206303AEA22C525085D9D1C0BB3`
`000002` jar	`38250F5E3A96F6488CB48368AC373E24620B7339658FB4857C73D981AF56B328`
`000001` jar	`D143DA27D670E887AE25C4313CE331E1F22066F98D119659879764A0F5C28CCC`

CPU texture sampling fast path (2026-11-07)

Nearest sampling now bypasses repeat and rem_euclid when both UV components are inside 0..1, which is the common case for model faces. The fast path keeps the same texel index and wrap behavior, including the rare f32 multiplication that rounds up to the texture width. Controlled A/B with the same tree before and after the change, 000001 jar, 12 threads, 1024x1024, supersample 2, default streaming:

Metric	Before	After
Render	9058.9 / 9416.1 ms	9150.1 / 8834.5 ms
Tile stage (one timed run)	3.50 s	3.35 s
`000002` jar render	1882.8 / 1957.2 ms	1933.2 / 1839.0 ms

The 000001 render median fell by about 2.7 percent and the tile stage by about 4 percent. 000002 is within run noise. PNG SHA-256 values are unchanged. BLOCKSCOPE_STREAM_TIMING=1 prints the project, spill, tile, resolve, assembly, and downsample stage timings; BLOCKSCOPE_TRANSLUCENT_BUDGET overrides the in-memory translucent triangle budget for diagnostics. A stage trace on 000001 jar measured project 2.0 s, tile 3.4 s, and resolve 2.8 s, with only 0.04 s waiting for the spill writer. The spill writer is therefore not the critical path, and parallel spill writers were not pursued.

Rejected CPU experiments (2026-11-07)

Attempt	Result	Verdict	Why
Camera-depth buckets for opaque early-Z (`BLOCKSCOPE_CPU_DEPTH_BUCKETS=16/32/64`)	`000002` jar render 2,333-2,654 ms off versus 2,757-3,944 ms on	reverted	Extra bins and scatter cost outweighed any early-Z saving; depth testing was not the limiting fragment cost.
f32 edge/barycentric rasterizer for `--precision fast`	`000002` jar median 1,797.7 ms exact versus 1,757.1 ms fast (2.3%, within run noise); 0.779% pixels differ, max delta 21	reverted	The tile path is memory and setup bound; the extra approximation did not buy a stable win. The existing fast point-storage mode remains.
Flat CSR bins with a counting pass plus fill	`000001` jar render 10.5-10.8 s versus 9.4-9.6 s with reused `Vec<Vec<u32>>` bins; peak 589 MB versus 676 MB	not used	The memory win was real, but the extra pass and scatter cost about 1 s. The bounded bin-capacity reuse keeps the peak near 637 MB without that regression.
64-page mesh chunks	`000001` jar mesh 4.6 s versus 5.9 s at 32 pages; total 16.1 s; peak 929 MB	not kept	The larger page chunk raises the peak by about 250 MB. Persisting the page capacity hint gives the mesh speedup at 32 pages.
Render splitting inside a mesh chunk at 100k/150k quads	`000001` jar render 12.0-15.9 s versus 9.4-9.6 s with whole-chunk renders	reverted	Smaller render batches revisit the resident tile buffers more often; extra tile passes cost more than the smaller working set saves.
Part-outer opaque/cutout tile scheduling	`000001` jar tile 7.2-7.5 s versus 3.4-3.8 s; render 12.5-14.3 s versus 9.1-9.4 s	reverted	One thread scope and one tile-buffer setup per projection slice cost more than the improved quad-table locality saves.
Pairing two translucent buckets per render batch	`000001` jar render 9.2-10.0 s versus 9.1-9.4 s; bucket render improved but bucket read wait rose from 0.77-0.78 s to 1.02-1.64 s	reverted	Two buckets per batch improved tile load balance but the larger read-ahead could not finish before the render, so the gains cancelled.
`BUCKET_TILES=8` translucent spill buckets	resolve 2.64-2.84 s versus 2.82-2.99 s; peak 829 MB versus 641 MB	reverted	Larger buckets improved bucket-render balance but raised the peak by about 190 MB for no stable wall-time win.
128px tiles at 2048 internal	tile 4.25 s versus 3.58 s; resolve 2.98 s versus 2.81 s; render 9.49 s versus 8.88 s	reverted	The larger tile buffers lose more cache locality than the lower per-tile overhead saves.
1 MB bucket buffer plus block record decode	resolve unchanged at about 2.8 s	reverted	The reader is already overlapped and is not the critical path; the extra buffer and decoding code did not pay for itself.

A small-bbox triangle fast path was also proposed, but a prior measurement showed no gain and a slowdown, so it was not retried.

Review-fix performance check (2026-10-28)

The review fixes do not change the single-view render hot path. The pre-review HEAD binary (6b5a680) and the current build were compared on the same host with the same commands:

Case	`HEAD`	Current
`000001` color stream, 1024x1024 ss2, 12 threads	11.65-11.75 s, 434-438 MB	11.1-11.4 s, 432-435 MB
`000001` client jar stream, same settings	16.98 s, 591.0 MB	17.00 s, 590.8 MB
PNG SHA-256, client jar	`7D7E583F...C5D687`	`7D7E583F...C5D687`
NBT allocation test rows	76,406 / 12,588,227 / 100,668,611 / 12,588,226 B	identical

The color-stream difference is within host noise; no path regressed. The 000001 client-jar image is byte-identical. The current full-mesh color path measured 7.68 GB / 11.9 s and produced the same PNG SHA-256 as the streamed path; it was not re-run on HEAD because the full-mesh path is unchanged and costs about 8 GB per run. Multi-view rendering now batches by a 256 MiB output-byte budget and writes each view before starting the next batch. At 1024x1024 (4 MiB RGBA) and 2048x2048 (16 MiB RGBA), the thread budget remains the limiting factor, so normal multi-view parallelism is unchanged. At 4096x4096 (64 MiB RGBA), a batch is capped at four views instead of retaining every output; this is the intended memory tradeoff and is covered by view_batch_budget unit tests. The supervisor hashes inputs on a dedicated thread instead of its event loop, and reuses a caller-supplied input.hash for routing. This is a latency improvement; no end-to-end render throughput table is claimed for it because the renderer remains the bottleneck.

Textured render memory

Texture memory is not the dominant cost. For 000001 with the client jar:

the material set is about 227 MB;
12.59M translucent triangles were retained for the per-tile depth sort;
each Triangle was 112 bytes, so the retained triangles were about 1.41 GB;
streamed rendering peaked at 2.28 GB before the compact layout.

Triangle now stores projected screen points as f32 and no longer stores the always-translucent layer tag. The depth key stays f64, so the sort order is unchanged; the struct is 72 bytes and the regression test in crates/render/src/rasterizer/project.rs pins that ceiling. The in-memory translucent path measured 1.52 GB before spilling was implemented. Above 262,144 retained triangles, the streamed renderer spills exact records to temporary bucket files and processes one bucket at a time. Re-measured after the review fixes, 000001 with the client jar peaks at 591 MB in 17.0 s with the same PNG SHA-256 as HEAD (the previous 618 MB / 16.2 s row was from an earlier host/build state). The temporary directory is removed when the render finishes. render defaults to --stream-mesh=auto, which streams like on; --stream-mesh=off restores the full-mesh path. This is what avoids the 18.9 GB full-mesh peak without requiring a flag.

Reproducing the CLI peak

Windows PowerShell, sampling the child working set every 20 ms:

$exe = (Resolve-Path .\target\release\blockscope.exe).Path
$p = Start-Process -FilePath $exe -ArgumentList @(
  'render', 'fixtures\private\000001.litematic',
  '--output', "$env:TEMP\peak.png",
  '--width', '1024', '--height', '1024', '--supersample', '2',
  '--threads', '12', '--stream-mesh', '--force-limits'
) -PassThru -NoNewWindow
$peak = 0
while (-not $p.HasExited) {
  try {
    $p.Refresh()
    if ($p.WorkingSet64 -gt $peak) { $peak = $p.WorkingSet64 }
  } catch {}
  Start-Sleep -Milliseconds 20
}
$p.WaitForExit()
"exit=$($p.ExitCode) peakMB=$([math]::Round($peak / 1MB, 1))"

Use bench with the same file and without --stream-mesh to record the full-mesh path. That path is intentionally not part of the default CI gate; it is a diagnostic for deciding whether streaming should become the default.

Sparse spike

The prototype is crates/litematic/examples/sparse_probe.rs. It scans the gzip stream twice: the first pass records region headers and BlockStates offsets, and the second pass decodes the packed words without retaining the decompressed document or the long array. It counts non-zero palette values; it does not build a scene or validate palette indices yet.

cargo run --release -p blockscope-core --example sparse_probe -- path\to\file.litematic --dense

Measured on 2026-10-28 with the release example:

File	Dense parse peak	Stream probe peak	Dense parse	Stream decode
synthetic sparse `512^3`, 1 block	100,668,608 B	141,739 B	48.4 ms	97.7 ms
synthetic sparse `1024^3`, 1 block	805,311,680 B	141,739 B	354.6 ms	689.5 ms
`000001` (9.39M blocks)	83,846,504 B	141,711 B	120.4 ms	20.3 ms

The probe peak is constant at about 142 KB. The sparse case is about 2x slower because it decodes every value from a second gzip pass; the dense fixture is faster because it avoids building the NBT tree. Decision: go for the integration spike follow-up. The peak reduction is far above the 50 percent bar and the sparse parse time is under 2x. This is not yet a production parser: the next step is a scoped implementation plan for RegionStates, canonical scene hashing, and parity tests. The probe’s occupied_nonzero counter is not the same as non_air when the palette has a non-zero default entry; the production path must use the palette default and preserve diagnostics.

GPU backend baseline (2026-11-05)

This is the pre-G2 baseline for tasks/gpu-performance-spec.md. It records why the current GPU path is not yet a net win on a strong CPU. The host is the 12-core / 48 GB Windows machine with an NVIDIA GTX 1650 SUPER (4 GB), release build, D3D12, color-only materials, 1024x1024 output, supersample 2, 12 threads, --force-limits. The CLI default backend was still cpu when measured; the spec changes it to auto in G6. Build and run:

cargo build --release -p blockscope-cli --features gpu

$exe = (Resolve-Path .\target\release\blockscope.exe).Path
& $exe bench fixtures\private\000002.litematic --backend cpu --iterations 3
& $exe bench fixtures\private\000002.litematic --backend gpu --iterations 3
& $exe bench fixtures\private\000001.litematic --backend cpu --iterations 1
& $exe bench fixtures\private\000001.litematic --backend gpu --iterations 2

End-to-end:

Case	CPU 12t	CPU 2t	GPU	Notes
`000002` render	190 ms	341 ms	201 ms	GPU 6% slower than CPU 12t
`000002` render + PNG	235 ms	385 ms	245 ms	GPU 4% slower than CPU 12t
`000001` render, full mesh	7,046 ms	-	14,881 ms	GPU 2.1x slower
`000001` end to end	about 11.3 s	-	about 18.7 s	includes parse, mesh, render, PNG

000001 used 87.9M quads in this build. The GPU path requires the full mesh, so it also chooses the 7.68 GB color-only memory peak instead of the 433 MB streamed peak. GPU stage timings from the last iteration of a three-iteration 000002 run:

Stage	Time
setup	0.7 ms
atlas build/upload	0.1 ms
CPU projection/cull	81.0 ms
CPU vertex encode	59.7 ms
buffer upload	28.4 ms
opaque draw	0.8 ms
translucent sort/draw	0.6 ms
readback	6.9 ms
resolve	2.2 ms
total	199.2 ms

The GPU draw itself is under 1% of render time. CPU projection, vertex expansion, and upload account for about 85%. This is the bottleneck G2 removes. Current GPU parity on the 96x96 reference scenes:

Scene	Differing pixels	Max channel delta	Alpha mismatch
opaque/cutout/translucent	1,021 / 9,216 (11.1%)	1	none
solid background	815 / 9,216 (8.8%)	1	none
textured nearest	0	0	none
textured linear (M4 host)	44 / 9,216	1	none

The 0.1% gate is a target for the second-generation path, not a property of the current path. G2 and G5 own closing it or recording the measured exception.

Shared texture storage (2026-11-05)

TextureSet now stores Arc<Texture> entries, so cloning it for a material snapshot only bumps refcounts. The 000001 client-jar stream still peaks at 581.4 MB, within the 591 MB baseline’s run-to-run variance; the live material set is dropped before rendering, so the steady peak does not include a second copy. The change removes the transient texture copy during snapshot creation and is required for the process-wide GPU atlas cache. The measured command is the same streamed client-jar render used for the 591 MB row in the summary table. The GPU atlas cache is keyed by a weak texture-set identity. Its byte cap is one quarter of the 60% VRAM working set, clamped to 64-512 MiB; the session also includes the atlas in its admission check. On 000002 --client-jar, the first GPU render spent 1,037 ms building/uploading the atlas; the next render reported atlasCacheHit=true and 4 microseconds. The second view of the same material snapshot therefore reuses the atlas instead of repacking 227 MB of textures.

Instanced opaque/cutout path (2026-11-05)

The GPU path now uploads one 92-byte GpuQuad instance per opaque/cutout quad instead of six projected 36-byte vertices. The camera transform, UV decode, AO, and quad expansion run in the vertex shader; translucent geometry still uses the CPU-projected path until G5. 000002, color-only, 1024x1024, ss2, 12 threads, median of 3:

Path	Render	Render + PNG	Mesh
CPU 12t	197.0 ms	242.7 ms	235.2 ms
GPU instanced	116.3 ms	161.2 ms	228.9 ms

GPU stage timings for the same run: encode 70.4 ms, translucent projection 11.5 ms, upload 11.3 ms, draw 1.0 ms, readback 5.3 ms, resolve 2.1 ms, total 113.1 ms. The GPU is now faster than 12-thread CPU on this fixture. 000001, full mesh, color-only, one iteration:

Path	Render	End to end
GPU instanced	8,650 ms	about 12.5 s
Previous GPU path	14,881 ms	about 18.7 s
CPU 12t	7,046 ms	about 11.3 s

On the large fixture the remaining GPU cost is dominated by CPU instance encoding (2.94 s), translucent projection (1.13 s), and the old translucent sort/draw (2.81 s). The full-mesh 7.68 GB peak is still the reason G3 streaming is next.

GPU streaming (2026-11-05)

render --backend gpu --stream-mesh=on now builds page chunks and feeds GpuRenderSession; the full mesh is not retained. 000001, color-only, 1024x1024, ss2, 12 threads, --force-limits:

Metric	Value
Peak working set	1,678 MB
Wall time	11.27 s
Render	5.10 s
Mesh	5.04 s
PNG	65.6 ms
Triangles	91.6M

The 2 GB memory gate passes. The 10 s wall gate is not met yet: the remaining cost is the 32-page mesh chunk policy (P0) and the 9.5M retained translucent triangles in the old GPU path (G5/WBOIT). --stream-mesh=auto and on produce byte-identical PNGs to the full-mesh GPU path on the CLI fixture. Multi-view GPU jobs use one GpuRenderSession and one mesh build:

Case	Wall	Peak working set
`000002`, 1 view	1.38 s	-
`000002`, 2 views	1.40 s	-
`000002`, 12 views	3.15 s	943 MB

Views are batched by the 60 percent VRAM target budget minus atlas and staging headroom. On this host that permits the 12 views at 1024x1024 ss2 in two sessions, with one mesh build and one upload per session.

GPU translucent depth buckets (2026-11-05)

Translucent triangles above 262,144 entries spill into 128 camera-depth bucket files instead of being retained in one vector. 000001 GPU streaming, color-only, 1024x1024, ss2, 12 threads:

Metric	Before buckets	After buckets
Peak working set	1,678 MB	499 MB
Wall	11.27 s	11.35 s
Render	5.10 s	5.16 s
PNG SHA-256	`42309C9F...`	unchanged

The 9.5M translucent triangles are written to depth buckets and read far-to-near in bounded sub-batches. The 10 s wall gate is still mesh-bound (5.08 s); the bucket reader and per-bucket sort are not the bottleneck.

WBOIT capture (2026-11-05)

Translucent buckets now draw into Rgba16Float accumulation and revealage targets with depth test on and depth write off; a full-screen composite pass resolves them over the opaque color target. Revealage is RGBA rather than R16Float because WebGPU needs a per-fragment source alpha for OneMinusSrcAlpha. 000001 GPU streaming, color-only, 1024x1024, ss2, 12 threads:

Metric	Old translucent path	WBOIT
Peak working set	499 MB	538 MB
Wall	11.35 s	12.20 s
Render	5.16 s	5.34 s
PNG	identical to pre-bucket	visually similar, not byte-identical

The 9,216-pixel parity scene keeps a maximum channel delta of 1 but still has 1,039 differing blended pixels, so the 0.1% tolerance remains a calibration item for Task 17. The extra ~39 MB and ~0.2 s are the two half-float targets plus the composite pass. 000001 with the client jar, GPU streaming, 1024x1024, ss2, 12 threads:

Metric	Value
Peak working set	656 MB
Wall	22.64 s
Render	12.21 s
Mesh	6.32 s
Parse	0.37 s
Triangles	127.2M (24.1M translucent)

The 3 GB memory gate passes; the 15 s wall gate does not. The gap is the 24.1M translucent triangles (projection + WBOIT fill) and the 6.3 s streamed mesh. This is recorded as a target-not-met rather than hidden. Calibration defaults are 128 depth buckets, a 262,144-triangle in-memory/read cap, and the WBOIT weight 0.03 / (1e-5 + depth^4) clamped to 1e-5..3000.

GPU performance path final results (2026-11-06)

auto is now the default backend for the CLI, bench, and serve. The policy is deterministic for a machine description and chooses the GPU only when the calibrated estimate predicts a win:

CPU cost per quad and per internal pixel is scaled by (12 / per_view_threads)^0.35 from the reference host; multi-view jobs split the thread budget across views.
GPU cost includes device/target setup, readback, per-quad encode/upload/draw, and a 10 percent streaming overhead.
The GPU is rejected without a hardware adapter, with a software adapter, above the f32-safe scene span, above the 60 percent VRAM working set, or for meshes below 10,000 quads.
When the process-wide GPU context is not initialized, a single-view job on a CPU with eight or more threads is kept on the CPU. Shader compilation and device setup cost a few hundred milliseconds, which a one-shot CLI render cannot amortize; multi-view jobs amortize it across views, and a warm process that already paid setup can still choose the GPU.
A predicted win requires a 5 percent margin, so setup noise cannot flip the decision.

The 60 percent VRAM budget uses the platform probe where available and a conservative floor otherwise: 2 GiB for discrete adapters and 1 GiB for integrated or virtual adapters. BLOCKSCOPE_GPU_VRAM_BYTES overrides the probe. Linux reads /sys/class/drm/*/device/mem_info_vram_total; Windows and macOS currently use the floor. The session admits targets, readback, one 32 MiB staging batch times three slots, and the atlas inside that budget. Larger page chunks are split into bounded instance uploads. R1 is the 12-thread Ryzen 5 5500 / GTX 1650 SUPER host, Windows D3D12, release build, color-only, 1024x1024, supersample 2, --force-limits. Render and total medians are from three iterations; total includes PNG.

Case	CPU render	auto render	CPU total	auto total	backend used
`000002`, 12 threads	259.0 ms	224.6 ms	312.7 ms	279.4 ms	cpu
`000002`, 2 threads	437.1 ms	148.3 ms	491.7 ms	199.7 ms	gpu

On 12 threads auto keeps the one-shot render exact on the CPU: the warm GPU render is 190.2 ms, but the first GPU render in a fresh process is 535.5 ms because it pays shader compilation and device setup. On 2 threads the GPU wins even with setup. auto reports backendUsed, so the caller can always tell. Commands:

cargo build --release -p blockscope-cli --features gpu
$exe = (Resolve-Path .\target\release\blockscope.exe).Path
& $exe bench fixtures\private\000002.litematic --backend auto --threads 12 --iterations 3 --force-limits --json
& $exe bench fixtures\private\000002.litematic --backend cpu  --threads 12 --iterations 3 --force-limits --json
& $exe bench fixtures\private\000002.litematic --backend auto --threads 2  --iterations 3 --force-limits --json
& $exe bench fixtures\private\000002.litematic --backend cpu  --threads 2  --iterations 3 --force-limits --json

Explicit GPU full-mesh render finished a single view in 1.84 s and two views in 1.71 s wall, inside the 1.3x two-view gate. Twelve auto views were batched by the VRAM budget and finished in 3.42 s with a 1006.7 MB peak. Multi-view jobs amortize setup across views, so the policy uses the GPU even on a strong CPU; single-view auto keeps the exact CPU on 12 threads. 000001 auto streaming (--backend auto, default --stream-mesh=auto) on the 12-thread host selects the CPU for exact one-shot output:

Case	Wall	Peak working set	Render	Mesh
color-only	15.03 s	473 MB	6.80 s	5.45 s
client jar	20.42 s	619 MB	12.08 s	5.33 s

Explicit --backend gpu measured 14.64 s / 502 MB for color-only and 19.83 s / 655 MB for the client jar. The difference is within run-to-run noise, so auto keeps the byte-exact CPU on this strong host. The 2 GB and 3 GB memory gates pass. The 10 s and 15 s wall gates do not; the remaining cost is page-chunk meshing and CPU/WBOIT translucent work. These are recorded as not met. Parity on the 96x96 GPU scenes, D3D12, max channel delta 1:

Scene	Differing pixels	0.1% target
translucent hybrid	1,039 / 9,216 (11.3%)	not met
opaque/cutout	842 / 9,216 (9.1%)	not met
textured opaque	245 / 9,216 (2.7%)	not met

Alpha coverage matches exactly in all three. The spec’s 0.1 percent differing-pixel target is therefore not met on this driver; the maximum channel delta target (2) is met. The parity tests keep a 15 percent regression cap and record the measured values instead of hiding them. The CPU backend remains the byte-exact reference and the explicit exactness override.

GPU frame session (2026-11-06)

GpuFrameSession is the first resident-geometry slice for video export. It uploads every opaque/cutout quad once and keeps the vertex buffers for the life of the session; each frame rewrites only the camera uniform and re-projects the translucent layer. This is the session shape that avoids re-uploading the full mesh for every video frame. Measured with the release build, 12-thread host, GTX 1650 SUPER, D3D12, color-only materials, 256x256, supersample 1, 12 yaw frames, sphere fit on:

Input	12-frame full renders	12-frame resident session	Speedup	Resident bytes
`000002`	2,567.9 ms	413.5 ms	6.21x	201.9 MB

Both time columns are totals for the 12-frame loop; divide by 12 for the per-frame average. The resident geometry is a hard VRAM constraint: 000001 color-only needs about 7.27 GB for the instance table plus targets, above the 1.29 GB working-set budget on this host, so the session returns BACKEND_UNAVAILABLE instead of attempting an allocation. Large or textured scenes keep using the streaming GpuRenderSession (or a future bounded frame batch) rather than a resident session. Run the diagnostic with:

cargo run --release -p blockscope-cli --features gpu --example frame_session_bench -- `
  fixtures/private/000002.litematic

This is a diagnostic, not a CI gate. The existing GPU parity and frame-loop tests protect correctness.

Animate CLI (2026-11-06)

blockscope animate drives the resident frame session end to end. Measured on the same host and release build, 000002 color-only, 128x128, supersample 1, 12 threads, 60 frames at 4 fps, sphere fit on, ffmpeg 9.0.2:

Backend	Mesh	Render	Encode	Total
CPU	328.3 ms	5,553.0 ms	37.6 ms	6,248.9 ms
GPU resident session	460.2 ms	2,989.1 ms	68.0 ms	4,856.4 ms

The GPU session renders the frame loop 1.86x faster and the complete command is 1.29x faster. Short clips can still be faster on the CPU because the resident session pays its upload/setup cost up front: 12 frames at the same size measured 1,861 ms on CPU versus 2,089 ms on GPU. 000001 color-only cannot hold the resident instance table and --backend auto falls back to the CPU; explicit --backend gpu reports BACKEND_UNAVAILABLE. The command uses an external ffmpeg. MP4 is H.264/yuv420p with an opaque background and even dimensions; GIF is a two-pass palette encode with optional 1-bit transparency.

Video frame-loop memory and speed (2026-11-07)

Measured on the same host, release build, ffmpeg 2026-03-12-git, with a 41,127-block private fixture and the 26.2 client jar: 1024x1024, supersample 2, 60 fps, 600 frames, GPU backend and NVENC via --encoder auto. Readback reuse (GpuFrameSession owns one readback buffer and resolves directly from the mapped range):

Metric	Before	After
Peak process RSS	260.2 MiB	179.8 MiB
Peak private bytes	379.9 MiB	364.9 MiB
Total time	11.15 s	9.69 s

Resident translucent geometry (pre-extract translucent quads instead of scanning every page per frame), interleaved 3x A/B under the same load:

Metric	Baseline median	Resident median
`projectUs`	4.21 s	3.12 s
Total command time	11.51 s	10.61 s

After both changes, three runs measured a median 183.9 MiB peak RSS and 370.0 MiB peak private bytes. GPU VRAM delta stayed in the 260-330 MiB range, within measurement noise; the readback and resident changes target host memory and CPU-side per-frame work, not VRAM. External ffmpeg peaked around 190 MiB working set. Rejected video-path experiments:

Idea	Result	Verdict
Parallel translucent projection per frame	`projectUs` 3.33 -> 4.18 s	reverted; thread setup cost exceeded the gain
Reused translucent vertex buffer	`translucentUs` 1.10 -> 0.72 s, total within noise	reverted; no user-visible win
Specialized 1x/2x resolve loops	`resolveUs` unchanged within noise	reverted

Large fixture limit: 000001 (211x211x211, 9.39M blocks) builds about 128.6M triangles and exceeds the default mesh limit. A 10-frame probe at 1024x1024, supersample 2, with the 26.2 client jar and --sphere-fit measured 12.0 s per frame on the CPU, 5.6 s mesh time, 10.55 GiB peak RSS, and 11.98 GiB peak private bytes. Extrapolated 600 frames would take about two hours; the resident GPU session cannot hold the instance table. The full run was not executed. NVENC CQ is not equivalent to x264 CRF. Calibrating low/medium/high to CQ 32/28/23 gives:

Quality	NVENC size (600 frames)	NVENC SSIM	libx264 reference
low	7.9 MB	0.941	SSIM 0.918
medium	13.3 MB	0.959	11.3 MB, SSIM 0.957
high	21.2 MB	0.976	SSIM 0.973

Medium output dropped from 21.2 MB to 13.3 MB (-37%) while matching libx264 medium visual quality. SSIM values are from a static frame against the GPU render; the libx264 medium size is the full 600-frame output, while the low and high libx264 sizes were not recorded. Video quality varies with motion and content.

Model UV cache (2026-11-07)

PaletteTables now caches the Q12-encoded UVs of every model quad once per resolved palette entry. Mesh building still computes block-local positions, but it no longer calls encode_uv for every emitted block quad. Full-mesh 000002 with the client jar, CPU, 12 threads, 16 alternating bench runs:

Path	Mesh median	Range
Re-encode UVs per quad	1,249.8 ms	1,110.3-1,433.0 ms
Cached Q12 UVs	1,133.1 ms	1,019.5-1,318.6 ms

The cached path is 9.3% lower at the median. The two fixtures checked (000002 and 000001, client jar, 1024x1024, supersample 2) produce byte-identical PNG SHA-256 values before and after the change. Caching the scaled corner offsets as well was also measured. It added 48 bytes per model quad to the working set and reduced the combined gain to 1.3%, so only the UV cache is kept.

SIMD investigation (2026-11-07)

The perf/simd-rasterizer branch measured whether explicit AVX2 kernels help the CPU render path. The answer for the current workload is no: the hot loops are dominated by per-triangle and per-quad setup, not by wide arithmetic over long contiguous runs. The experimental kernels were reverted rather than kept as neutral complexity.

Where the time goes

000002 with the client jar, CPU backend, --stream-mesh=on, 1024x1024, supersample 2, 12 threads, and --force-limits. Stage timings came from a temporary instrumentation build; the render column is the CLI total.

Stage	Wall
Project + bin	804-844 ms
Tile rasterization	1,336-1,343 ms
Assembly (encode + copy)	43-47 ms
Translucent resolve	3 ms
Render total	2,331-2,384 ms

Mesh building in the same run is about 1.4 s wall. The sampled page breakdown shows the inner block loop is dominated by model iteration and culling (41%), quad push and allocation (19%), ambient occlusion (17%), and vertex creation (12.5%). Each of those is branch-heavy, and the largest SIMD-able share is well under half of the mesh stage.

Why per-pixel SIMD does not fill

The rasterizer was instrumented to count triangle invocations, rows, and non-empty rows on 000001 with the client jar:

Counter	Value
Triangle rasterize calls	142,936,956
Rows visited	735,406,071
Non-empty rows	334,038,619
Pixels tested	597,506,052

That is 1.79 tested pixels per non-empty row. A four-lane row kernel almost always falls through to its scalar tail, so it cannot repay its setup cost. The same distribution holds on 000002 (133.0M tested pixels over 33.7M triangles). SIMD across triangles would need a batched setup that preserves draw order; that is a rasterizer redesign, not a local kernel change.

Rejected attempts

Attempt	Result	Verdict	Why
AVX2 four-pixel row rasterizer	`000002` render 2,110-2,201 ms vs baseline 2,057-2,273 ms	reverted	No stable win; rows average under two pixels.
AVX2 four-vertex quad projection	Kernel 2.897 ms -> 2.773 ms per 200k quads (4.5%); project CPU 3,612 ms -> 3,672 ms end to end	reverted	The kernel is a small part of projection, and the target-feature call boundary erased the gain.
Batched two-quad / four-triangle setup	`000002` tile 1,800-2,033 ms vs baseline 1,356-1,622 ms; render 2,807-3,148 ms vs 2,374-2,745 ms	reverted	Copying triangle inputs and prepared setups between passes cost more than the shared bounds/edge work; the single-triangle path was already inlined and kept inputs in registers.
AVX2 four-triangle setup kernel	400k batches: scalar 27.6 ms, AVX2 40.2 ms	reverted	Lane assembly, stores, and scalar clipping outweighed the four-wide arithmetic on the reference Zen 2 host.
Six-face cull mask in `PageGrid::fill`	Full-mesh median 1,152.6 ms vs 1,144.1 ms over 8 alternating `bench` runs	reverted	Six face rules per cell is more neighbour work than the ~3.75 model quads per cell consume; the existing `occludes` byte check already covers most culls.
Cached Q12 UVs plus scaled corner offsets	Full-mesh median 1,253.4 ms vs 1,269.4 ms over 16 alternating runs	offset half reverted	The extra 48 bytes per quad offset most of the UV-only win; keep the UV cache alone.
SIMD ambient occlusion / vertex creation	Not implemented	rejected by measurement	Sampled shares are 17% and 12.5% of the block loop; gather-based AO is not faster than L1 scalar loads on the reference Zen 2 host.

Follow-up options

The measurements point at algorithmic work rather than wider vectors:

Keep explicit SIMD for bulk image paths only if they grow beyond the current assembly and downsample costs, which are under 50 ms per render.
Do not retry four-triangle batching without a copy-free design that keeps the scalar setup inlined; the measured version regressed tile time by 33-47%.
Do not retry a full six-face cull mask without a vectorized mask build; the scalar version does more neighbour work than the block loop saves.

Server preview latency spike

The server-preview latency spike, the textured resident-session result, and the color-only blockout follow-up are recorded in performance-preview.md. Short version: textured preview is not viable at 384x384 on the 4 GB reference host; color-only 000002 meets the 300 ms gate; 000001 stays batch-only.

Pipeline Architecture

System & Protocol

Performance