Module scene 

GPU.5 — multi-grid scene upload + shared storage layout.

Concatenates every chunk of every grid into one set of storage buffers + a per-grid offsets table. Each grid keeps its own vsid, chunks_dims, origin_chunk, and runtime transform; the shader iterates grids 0..grid_count, transforms the world camera into each grid’s local frame, runs that grid’s outer-DDA over chunks, and tracks the closest hit across all grids.

Why concatenate rather than one bind group per grid? wgpu’s MAX_BIND_GROUPS default is 4; demos with 10+ grids (roxlap-scene-demo has ground + ship + 10 marker pillars = 12) need a single bind-group layout that scales.

Structs

GpuSceneResident

GPU-resident storage for an entire scene’s grids.

GridRuntimeTransform

Per-grid runtime transform — voxlap-style (world → grid-local). rotation is column-major and encodes the inverse rotation applied to the world camera basis before passing it to that grid’s marcher. Identity for the ground; non-trivial for the rotating ship.

GridStaticMeta

Per-grid static metadata: offsets into the concatenated storage buffers + the grid’s slot-pool dimensions. Uploaded once.

MipLayout

GPU.11 — per-slot occupancy/color-offset strides + per-mip within-slot relative offsets for a grid of side vsid. All chunks of a grid share these (uniform mip count by gpu_mip_count). colors keep their fixed COLORS_PER_CHUNK_WORDS stride; each mip’s colours are concatenated within that block and indexed by the chunk’s own (absolute) color_offsets.

SceneUpload

CPU-side aggregation of every grid in a scene. Built once at startup; per-grid transforms are recomputed each frame and passed to render_scene separately.

Enums

RefreshOutcome

Outcome of GpuSceneResident::refresh_chunk. Most callers can ignore the result; ColorsTruncated indicates the chunk’s colour data overflowed the per-slot stride and was clipped.

Constants

COLORS_PER_CHUNK_WORDS

Per-chunk colour-slot stride, in u32 words (256 KiB). Each chunk’s colour data lives at meta_idx * COLORS_PER_CHUNK_WORDS within its grid’s colours range. Fixed-stride layout means every slot — present or absent at upload time — has the same capacity, so GpuSceneResident::refresh_chunk can always write new colour data into the slot when a chunk arrives via streaming or is re-baked.

MAX_GPU_MIPS

GPU.11 — max mip levels the per-slot layout reserves room for in GridStaticMeta’s relative-offset tables. Matches crate::decompress::GPU_MAX_MIPS; the shader’s array<u32, N> must use the same N.

MAX_OCC_PAGES

Number of separate storage bindings the concatenated occupancy buffer is split (“paged”) across. A single storage binding may not exceed the device’s max_storage_buffer_binding_size — on strict drivers that’s a hard 128 MiB (lavapipe), which the streaming demo’s occupancy already reaches. Splitting into pages keeps every binding under the limit while preserving a single global word index in the shader (each page is a whole number of chunk slots, so no slot ever straddles a page boundary).

MAX_SCENE_GRIDS

Maximum number of grids the shader’s per-grid camera uniform array can hold. The scene-demo has 12 (1 ground + 1 ship + 10 markers); 16 leaves headroom for a future +4 without re-cooking the shader. The runtime check rejects scenes that overflow.

SLOT_EMPTY_SENTINEL

Sentinel chunk_idx written into empty slot_chunk_idx entries. Real chunk indices never use i32::MIN, so the shader can distinguish empty slots from collisions via a single equality check.

Functions

modular_slot_idx

Modular slot index for chunk_idx given the grid’s power-of-2 pool_dims. Negative chunk_idx components map via two’s-complement bitwise AND, matching the shader’s chunk_idx & (pool_dims - 1).