Module sprite_model 

GPU.10 — KV6 sprite as a DDA-marchable voxel model.

Unlike the GPU.9 splatter (one thread per voxel, screen-space squares, overdraw + atomic contention), a sprite model is a small voxel volume the precise ray-DDA marches one ray per pixel — crisp, correct occlusion, no overdraw. This is the GPU.10.0 single sprite; instancing + tiling + LOD come in later sub-substages.

The volume reuses the chunk occupancy/colour scheme but sized to the KV6 bbox: per-column occupancy bitmask (occ_words_per_col u32s, CHUNK_Z-style 32-bits-per-word), a flat colour array in ascending-z order per column, and a color_offsets prefix table. The shader finds a voxel’s colour by offset[col] + popcount(bits below z), so colours MUST be ascending-z (we sort per column).

Structs

SpriteInstance

One sprite instance: a model reference + world pose.

SpriteInstanceTransform

Per-instance transform consumed by the model-DDA shader: the inverse model→world rotation (so a world ray can be brought into model-local space) plus the instance’s world position. Stored as three padded columns for std140/std430 (mat3x3 16-byte columns).

SpriteModel

CPU-built voxel volume for one KV6 model.

SpriteModelRegistry

A registry of sprite models. Instances reference a model by model_id, which is a LOD chain id: each chain holds one or more concrete mip levels (finest first; GPU.10.4), and the renderer picks the level per instance by distance. Identical KV6s are added once and shared by many instances. Copy-on-modify: Self::fork deep-copies a chain so edits to the fork leave the parent (and its instances) intact.

SpriteRegistryResident

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).

ViewFrustum

View frustum for CPU instance culling, in world space. Built each frame from the world camera. half_w/half_h are the tangents of the half-FOV (so the side planes are |x| <= half_w * z etc. in camera space).

Functions

build_sprite_model

Build the DDA volume from a KV6. Columns are packed in x + y*mx order; each column’s voxels are sorted ascending by z so the shader’s popcount-rank colour lookup is correct.

build_sprite_model_with_materials

Build the DDA volume from a KV6, classifying each voxel into a per-voxel material id by colour (TV.3 mixed models) via material_map ((rgb, material_id) pairs; see material_for_color). An empty map produces a model with no per-voxel materials (identical to build_sprite_model).

sprite_model_from_clip_frame

Build the SpriteModel for frame frame of a decoded clip — the per-frame model uploaded into a flipbook chain (VCL.2).

sprite_model_from_clip_frame_with_materials

Like sprite_model_from_clip_frame but classifies the frame’s voxels into per-voxel material ids by colour (TV.3 mixed models) via material_map. An empty map is identical to sprite_model_from_clip_frame.

sprite_model_from_voxel_frame

Build a SpriteModel directly from a decoded voxel-clip frame (VCL.2). The VoxelFrame dense-column layout is byte-for-byte the SpriteModel layout that build_sprite_model produces, so this is a field move — no per-column bucket-sort. dirs is the frame’s surface-normal LUT indices (from DecodedClip::dirs), parallel to frame.colors.

sprite_model_from_voxel_frame_with_materials

Like sprite_model_from_voxel_frame but classifies each voxel into a per-voxel material id by colour (TV.3 mixed models) via material_map ((rgb, material_id) pairs). An empty map produces a model with no per-voxel materials (identical to sprite_model_from_voxel_frame).