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

Consumed by crate::opticast_prelude::recompute_in_bounds_xy (camera-inside-grid check) and the rasterizer’s gline world-edge gxmax clip.

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>