Module render 

Scene-level rendering — drives roxlap_core::opticast::opticast across the grids of a Scene.

Two entry points:

• render_scene_composed (recommended for multi-grid scenes): per grid, allocates a temporary framebuffer + zbuffer, runs opticast into the temp, then merges into the shared output via per-pixel min-z. Correctly composites overlapping grid output.
• render_scene (single-grid trusting caller): writes every grid directly into the shared rasterizer. For single-grid scenes this matches a direct opticast call byte-for-byte; for multi-grid it’s last-grid-wins (sky writes from grid B overwrite grid A’s hits). Useful for tests / single-grid sanity checks.

S4B.2.e: Approach B multi-chunk dispatch

Both APIs route per-grid rendering through crate::Grid::chunk_xy_backing → roxlap_core::ChunkGrid → roxlap_core::GridView::from_chunk_grid → opticast. opticast’s prelude looks up the camera’s chunk via roxlap_core::GridView::chunk_at_xy; the grouscan column-step swaps the active per-chunk (slab_buf, column_offsets) when rays cross a chunk-XY boundary. The combined-world stitch (Approach C, S4.0..S4.2) is no longer in the render path — the lighting bake still uses it until S4B.4 lands a per-chunk bake.

Per-grid rotation (S5) and per-grid LOD (S6) plug in at the same dispatch point: rotate the world camera into grid-local before the chunk-grid lookup, then dispatch coarse / fine / billboard based on grid-camera distance.

Structs

ComposedFrameParams

The composed render’s bundled per-frame inputs: the positional wrapper ladder (render_scene_composed → _with_materials → _with_materials_scratch) had reached 17 arguments with adjacent same-typed Options a compiler can’t tell apart — a swapped slot would compile fine. #[non_exhaustive]: construct with ComposedFrameParams::new and override fields, so future frame inputs (OC.4 ghost mode, …) are field additions, not new wrappers.

CpuFog

CPU fog + per-face shading config for the DDA backend, passed by value into the scene render entry points (replaces the old &mut ScratchPool parameter the voxlap path threaded fog through).

SceneRenderScratch

PF.7 (C6) — reusable scratch for the composed scene render: the per-grid temp framebuffer/z-buffer pair (was two full-frame vec! allocations + initialising writes per call — ≈7.4 MB at 720p, ×16 under 4×SSAA), the per-grid light scratch, and the phase-A mip map. Own one per renderer and pass it to render_scene_composed_with_materials_scratch; the buffers grow to the frame size on first use and are reused verbatim afterwards (every pixel the render reads is filled per grid first, so no per-frame clear is needed).

SceneViewCutout

OC.0 — the frame’s view cutout (“keyhole”, stage OC) as the facade hands it to the composed render: the view-cone half-angles (already derived from the keyhole’s pixel radius under the frame’s own projection — hazard 1: never window/host pixels; angles are resolution- and rotation-invariant) plus the world-space camera + focus the per-grid loop converts into each grid’s frame (exactly like the lights / CA clip conversions). Per-frame VIEW state — primary rays only: shadows, occluders, collision and gameplay raycasts never see it.

Enums

RenderOutcome

Outcome of a render_scene / render_scene_composed call.

Functions

compose_into

Per-pixel “min-z wins” merge of (temp_fb, temp_zb) into (shared_fb, shared_zb).

cutout_grid_local

OC — the view cutout’s focus in a grid’s frame: world focus → grid-local VOXEL coordinates plus the biased focus-plane z (floor() into the kernels’ >> mip integer domain). The ONE conversion both backends’ facades feed their kernels from — a one-voxel drift between hand-copies would cut the floor out from under the character on one backend only.

render_scene

matches-direct-opticast property — the test suite uses it as a sanity check that the combined-world stitch + render harness doesn’t drift vs. a raw opticast call.

render_scene_composed

Render every grid in scene with per-grid temporary buffers + z-buffer composition. The canonical multi-grid scene render path.

render_scene_composed_frame

The composed multi-grid render with its per-frame inputs bundled (ComposedFrameParams) — the production entry point (the positional wrappers below predate it and forward here). Caller pre-fills fb with sky and zb with INFINITY; grids z-merge in.

render_scene_composed_with_materials

render_scene_composed with TV terrain materials: materials is the global palette and terrain_materials the colour→material map; together they make matching-colour terrain voxels translucent (front-to-back composited). An empty map / None palette renders identically to render_scene_composed.

render_scene_composed_with_materials_scratch

render_scene_composed_with_materials with a caller-owned SceneRenderScratch (PF.7) — the temp buffer pair and per-grid scratch are reused across frames instead of re-allocated per call. (New inputs land as ComposedFrameParams fields consumed by render_scene_composed_frame — this positional family is frozen.)