Struct GridView 

pub struct GridView<'a> {
    pub vsid: u32,
    pub chunk_size_xy: u32,
    pub chunk_size_z: u32,
    pub slab_buf: &'a [u8],
    pub column_offsets: &'a [u32],
    pub mip_base_offsets: &'a [usize],
    pub chunk_grid: Option<&'a ChunkGrid<'a>>,
}

Fields

vsid: u32

Square dimension of the currently-active chunk view (matches the source Vxl’s vsid for single-chunk callers). The per-chunk column_offsets table holds (vsid² + 1) entries.

chunk_size_xy: u32

S4B.2.a: square dimension of each chunk in XY voxel units. For today’s single-chunk callers, chunk_size_xy == vsid so (cx, cy) in [0, vsid) never crosses a chunk boundary. For multi-chunk callers (S4B.2.c+), chunk_size_xy is the per-chunk dimension (typically 128) and vsid is the same per-chunk value — they may diverge in S4B.4 when GridView stops carrying a “default” chunk’s flat fields.

chunk_size_z: u32

S4B.6.a: Z extent of each chunk in voxel units. Locked to MAXZDIM = 256 for every chunk (voxlap’s slab byte format uses a u8 z field). Tall worlds stack chunks vertically rather than extending this constant — see memory/project_s4b_6_z_stacking_plan.md. Pre-S4B.6.a callers set this to 256 (the only valid value) and the rasterizer ignores chunk-z boundaries; S4B.6.c will start consuming the field for cross-chunk-z column walks.

slab_buf: &'a [u8]

Flat slab byte buffer for every column at every built mip.

column_offsets: &'a [u32]

Per-column byte offsets into Self::slab_buf, concatenated across every mip’s sub-table. Mip-0 occupies indices mip_base_offsets[0]..mip_base_offsets[1].

mip_base_offsets: &'a [usize]

Mip-level boundaries inside Self::column_offsets. Length mip_count + 1; trailing sentinel equals column_offsets.len(). Single-mip callers pass &[0, vsid² + 1].

chunk_grid: Option<&'a ChunkGrid<'a>>

S4B.2.c.1: chunk-grid backend. None for single-chunk views (e.g. anything built via Self::from_single_vxl / Self::from_parts) — Self::chunk_at_xy falls back to the Some(Self) for [0, 0] behaviour. Some(&...) for multi-chunk views built via Self::from_chunk_grid — Self::chunk_at_xy consults the table.

Implementations

impl<'a> GridView<'a>

pub fn from_parts( vsid: u32, slab_buf: &'a [u8], column_offsets: &'a [u32], mip_base_offsets: &'a [usize], ) -> Self

Build from explicit fields. Test fixtures use this directly; production callers usually go through from_single_vxl.

Sets chunk_size_xy = vsid (single-chunk semantics). Use with_chunk_size_xy to mark the view as part of a chunk grid.

pub fn from_single_vxl(vxl: &'a Vxl) -> Self

Borrow a parsed .vxl map as a single-chunk grid view. The scene-graph stage’s eventual multi-chunk constructor will live alongside this one (from_grid over roxlap_scene::Grid).

pub fn from_chunk_grid( chunk_grid: &'a ChunkGrid<'a>, chunk_size_xy: u32, ) -> Self

S4B.2.c.1: build a multi-chunk view from a ChunkGrid.

The returned GridView’s flat (vsid, slab_buf, column_offsets, mip_base_offsets) fields are seeded from the first populated chunk in the grid (so opticast’s prelude has a sensible default before its camera-chunk lookup refreshes them). chunk_size_xy carries the caller-supplied per-chunk dimension; Self::chunk_grid points at chunk_grid so Self::chunk_at_xy resolves every in-range index to its actual chunk borrow.

Empty-grid case: if every chunk is None, the flat fields fall back to empty slices and vsid = chunk_size_xy. The grouscan column-step swap will see chunk_at_xy → None for every index and render the whole grid as sky.

pub fn with_chunk_size_xy(self, chunk_size_xy: u32) -> Self

S4B.2.a builder: override Self::chunk_size_xy. Multi-chunk callers (S4B.2.c+) use this to mark the view as one chunk of a larger grid. Today no caller needs it; the existence makes the seam testable in isolation.

pub fn mip_count(&self) -> u32

Number of built mip levels (mip-0 always counts). 0 only for a degenerate empty view.

pub fn voxel_run_top(&self, x: u32, y: u32, z: u32) -> Option<i32>

Top z of the solid run containing voxel (x, y, z) at mip 0, or None if the voxel is air. See Self::voxel_run_top_mip.

pub fn voxel_run_top_mip(&self, x: u32, y: u32, z: u32, mip: u32) -> Option<i32>

Top z of the solid run containing voxel (x, y, z) at mip mip, or None if air. Coordinates are in mip-mip units (x, y ∈ [0, vsid >> mip), z ∈ [0, CHUNK_SIZE_Z >> mip)).

Mirrors roxlap_formats::edit::expandrle’s run decomposition (the same [top, bot) solid runs the scene’s voxel_solid uses), walking the slab chain in place. The returned top is always a colour-list voxel, so callers can shade an interior / side-face hit with voxel_color_mip(x, y, top, mip).

pub fn for_each_run(&self, x: u32, y: u32, f: impl FnMut(i32, i32))

Call f(top, bot) for each solid run [top, bot) of column (x, y) at mip 0. See Self::for_each_run_mip.

pub fn for_each_run_mip( &self, x: u32, y: u32, mip: u32, f: impl FnMut(i32, i32), )

Call f(top, bot) for each solid run [top, bot) of column (x, y) at mip mip, top-to-bottom (the roxlap_formats::edit::expandrle decomposition). No-op for an out-of-range / unbacked column. The brickmap builder (crate::dda) uses this to mark occupied bricks.

pub fn surface_color(&self, x: u32, y: u32, z: u32) -> Option<u32>

DDA hit colour for voxel (x, y, z) at mip 0. See Self::surface_color_mip.

pub fn surface_color_mip(&self, x: u32, y: u32, z: u32, mip: u32) -> Option<u32>

DDA hit colour for voxel (x, y, z) at mip mip: the display colour if the cell is solid and renderable, or None for air or an uncoloured bedrock run (stepped through transparently).

Exact colour-list cells return their own colour; interior / side-face cells fall back to the colour of their run’s top voxel (the surface colour “bleeds” down a cliff face).

pub fn voxel_color(&self, x: u32, y: u32, z: u32) -> Option<u32>

Surface colour of voxel (x, y, z) at mip 0. See Self::voxel_color_mip.

pub fn voxel_color_mip(&self, x: u32, y: u32, z: u32, mip: u32) -> Option<u32>

Surface colour of voxel (x, y, z) at mip mip (mip-mip coordinates), or None for an empty / out-of-range cell.

Decodes the column’s slab chain directly from the GridView borrow (the same vbuf floor + ceiling list walk roxlap_formats::vxl::Vxl::voxel_color performs). The returned u32 is packed 0xAARRGGBB; a zero-RGB cell (empty-chunk placeholder) reads as None. Surface voxels only — use Self::surface_color_mip for the full solid-cell hit test.

pub fn aabb_xy(&self) -> ([i32; 2], [i32; 2])

S4B.2.d: voxel-space XY axis-aligned bounding box of the grid. Returns ([xmin, ymin], [xmax, ymax]) in voxel units; the grid contains voxels with coordinates in [xmin, xmax) × [ymin, ymax).

• Single-chunk (chunk_grid: None): returns ([0, 0], [vsid, vsid]). Byte-identical to the historical single-chunk world-edge math.
• Multi-chunk (chunk_grid: Some(&cg)): derived from cg.origin_chunk_xy + cg.chunks_x/y * chunk_size_xy.

Used as the renderer’s outer DDA bounds (the world-edge box the per-pixel ray is clipped to).

pub fn voxel_bounds(&self) -> ([i32; 3], [i32; 3])

Full voxel-space bounding box of the grid: ([x0, y0, z0], [x1, y1, z1]) half-open in grid-local voxel coordinates. XY comes from Self::aabb_xy; Z spans the chunk grid’s chunks_z layers (origin_chunk_z * CHUNK_SIZE_Z upward), or a single [0, CHUNK_SIZE_Z) chunk when un-stacked. The DDA renderer (crate::dda) uses this as the outer traversal box.

pub fn chunk_at_xy(&self, chunk_idx: [i32; 2]) -> Option<GridView<'a>>

S4B.2.a: chunk lookup for the cross-chunk-XY DDA.

Returns the GridView for the chunk at XY index chunk_idx if one exists, None otherwise. Routes by Self::chunk_grid:

• chunk_grid: Some(&cg) — multi-chunk view. Resolves chunk_idx against cg.origin_chunk_xy / cg.chunks_x / cg.chunks_y and returns cg.chunks[..] at the matching slot (which may itself be None for empty chunks).
• chunk_grid: None — single-chunk view. Returns Some(Self) for [0, 0], None for any other index. Matches today’s single-chunk callers (every from_single_vxl / from_parts consumer).

The grouscan column-step treats None as an empty chunk (renders as sky / empty until the ray re-enters a populated chunk).

pub fn chunk_at_xyz(&self, chunk_idx: [i32; 3]) -> Option<GridView<'a>>

S4B.6.a: 3D chunk lookup for the future cross-chunk-Z DDA.

Same dispatch contract as Self::chunk_at_xy but extended to a z axis:

• chunk_grid: Some(&cg) — multi-chunk view. Resolves chunk_idx against cg.origin_chunk_xy / cg.origin_chunk_z / cg.chunks_x / cg.chunks_y / cg.chunks_z and returns cg.chunks[..] at the matching slot (which may itself be None for empty chunks).
• chunk_grid: None — single-chunk view. Returns Some(Self) for [0, 0, *], None otherwise. The z index is ignored because single-chunk callers carry an un-stacked world — the camera’s chz, even when non-zero (e.g. camera at world z >= 256 below the chunk’s bedrock with treat_z_max_as_air), still refers to the same one chunk. S4B.6.c will start treating chz as a separator only for multi-chunk grids.

Trait Implementations

impl<'a> Clone for GridView<'a>

fn clone(&self) -> GridView<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for GridView<'a>