Struct SpriteRegistryResident 

pub struct SpriteRegistryResident {
    pub occupancy: Buffer,
    pub colors: Buffer,
    pub dirs: Buffer,
    pub color_offsets: Buffer,
    pub model_meta: Buffer,
    pub instances: Buffer,
    pub instance_capacity: u32,
    pub colmul: Buffer,
    pub tile_ranges: Buffer,
    pub tile_instances: Buffer,
    /* private fields */
}

GPU-resident registry + instances: every model’s occupancy / colours / offsets concatenated into shared storage buffers, a per-model metadata table, and a capacity-sized instance buffer rewritten each frame with the frustum-visible subset (GPU.10.2). One bind group serves all models (same approach as the multi-grid scene).

Fields

occupancy: Buffer

colors: Buffer

dirs: Buffer

Per-voxel surface-normal index, concatenated across models in the same layout as colors. The shader indexes the per-instance kv6colmul table by it.

color_offsets: Buffer

model_meta: Buffer

instances: Buffer

Holds up to instance_capacity instances; the visible subset is packed into [0, count) each frame by Self::cull_bin_upload.

instance_capacity: u32

colmul: Buffer

Per-visible-instance kv6colmul[256] tables, packed in the same order as the instances buffer each frame (two u32 per u64 entry: lanes 0|1 then 2|3). Sized instance_capacity * 256 * 2 u32; rewritten by Self::cull_bin_upload.

tile_ranges: Buffer

GPU.10.3 — per-tile (offset, count) into tile_instances, flat 2 * tiles_x * tiles_y u32s. Grown to fit the screen.

tile_instances: Buffer

GPU.10.3 — flat list of visible-instance indices grouped by tile. Grown to fit the per-frame total.

Implementations

impl SpriteRegistryResident

pub fn upload( device: &Device, registry: &SpriteModelRegistry, instances: &[SpriteInstance], ) -> Self

Concatenate registry’s models into shared buffers and prepare instances for per-frame culling. Model-relative indices stay as built; the shader adds each model’s base offset from the metadata table.

pub fn set_instance_colmul(&mut self, tables: &[[u64; 256]])

Set the per-instance kv6colmul[256] lighting tables (voxlap’s update_reflects output), in the same order/length as the instances passed to Self::upload. The next Self::cull_bin_upload packs the visible subset to the GPU. Instances beyond tables.len() keep their previous tables.

pub fn update_transforms(&mut self, instances: &[SpriteInstance])

Refresh instance poses in place from instances — for animated sprites (e.g. KFA limbs re-posed each frame) — without any model-volume re-upload. instances must match the set passed to Self::upload in length + order; each keeps its model_id (LOD chain) so only the transform + cull centre change. No GPU write happens here: the next Self::cull_bin_upload re-uploads the packed visible subset, as it already does every frame.

pub fn update_model( &mut self, device: &Device, queue: &Queue, registry: &SpriteModelRegistry, chain_id: u32, )

GPU.12 incremental — re-upload only the entries of LOD chain chain_id after an in-place edit (carve / recolour) of its model, without rebuilding the whole registry. registry must be the same registry uploaded (same entry ids), with chain chain_id’s entries already edited (model_mut + rebuild_lod).

For each entry: occupancy + color_offsets are dims-fixed, so they are written in place; colors + dirs (variable, parallel) go through the suballocator — written in place when they fit the slack, relocated (with a model_meta rewrite) when they outgrow it, and only when the buffer tail overflows are colors/dirs grown + the whole registry repacked. Instances / cull / colmul are untouched (a carve never moves an instance or grows its bounds) — that is the win over Self::upload.

Panics (debug)

If an entry’s dims changed (occupancy / color_offsets length), which the in-place path can’t absorb — growing dims needs a full re-upload via Self::upload.

pub fn cull_bin_upload( &mut self, device: &Device, queue: &Queue, f: &ViewFrustum, screen_w: u32, screen_h: u32, tile_size: u32, lod_px: f32, ) -> (u32, u32, u32)

GPU.10.3 — frustum-cull, pack the visible subset into the instance buffer, then bin those instances into screen tiles: project each visible bounding sphere to a screen AABB and append its (visible) index to every overlapped tile. Uploads the instance buffer + tile_ranges (per-tile offset/count) + tile_instances (flat grouped indices), growing the tile buffers as needed. Returns (visible_count, tiles_x, tiles_y).