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

SpriteCutawayClip

CA.4 — one clipped grid’s cutaway volume for the sprite cull: the footprint rule. An instance whose origin, mapped into the grid’s local voxel frame, lands inside the grid’s XY chunk footprint with z < z_clip is hidden this frame — dropped from the visible set, which also stops it casting sprite shadows (the shadow pass marches the culled visible set). Instances outside the footprint are never affected. Built per frame by SceneRenderer::render_scene from the per-grid world transforms + the resident chunk AABBs.

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