Struct FrameParams 

#[non_exhaustive]
pub struct FrameParams<'a> {
    pub settings: &'a OpticastSettings,
    pub sky_color: Rgb,
    pub sky: Option<&'a Sky>,
    pub fog_color: Rgb,
    pub fog_max_scan_dist: i32,
    pub treat_z_max_as_air: bool,
    pub draw_sprites: bool,
    pub side_shades: [i8; 6],
    pub lights: Option<LightRig<'a>>,
    pub tint: Option<Tint>,
}

Per-frame inputs both backends consume. The host builds the OpticastSettings (it owns scan distance, projection etc.); the facade does everything else (pool config, sky fill, render, present).

Both backends derive their projection from settings (QE.2a): the vertical field of view is 2·atan(yres/2 / hz) and the GPU outer-DDA step budget follows OpticastSettings::max_scan_dist, so the two backends can no longer disagree about what they show. Pick an explicit FOV with OpticastSettings::with_fov_y.

#[non_exhaustive]: construct with FrameParams::new and override fields — a future field addition is then not a breaking change (pre-QE.2, every added field broke every host’s struct literal).

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

settings: &'a OpticastSettings

Render settings both backends share: framebuffer geometry + projection (hx/hy/hz), scan distances, and the mip ladder. (Named for the CPU renderer it configured first; the GPU backend derives its FOV + step budget from it too.)

sky_color: Rgb

Packed engine sky colour: the CPU sky-miss fill + skycast, and the clear colour if no scene renders.

sky: Option<&'a Sky>

Optional sky panorama for the CPU rasterizer’s sky sampling.

fog_color: Rgb

CPU fog: the packed colour distant voxels fade toward.

fog_max_scan_dist: i32

CPU fog: full-fog distance (voxels). 0 disables CPU fog.

treat_z_max_as_air: bool

CPU: treat z=255 as air (avoids the S1.X bedrock path for out-of-bounds cameras).

draw_sprites: bool

Whether to draw the renderer’s sprites this frame. Both backends draw KV6 sprites flat-lit (the clean-room DDA sprite raycaster on CPU; uploaded model colours on GPU), so no host-supplied lighting is needed — this is just the on/off opt-in. false skips sprite drawing.

side_shades: [i8; 6]

Per-face directional shading for the voxel grids — voxlap’s setsideshades(top, bot, left, right, up, down), the grid-scan analogue of draw_sprites. Each entry darkens the faces pointing that way; the host typically passes its engine’s side_shades(). The default [0; 6] keeps sideshademode off (no per-side shading), so existing hosts and the oracle goldens are unaffected. Applied each frame by both backends: the CPU rasteriser via gcsub, and the GPU scene-DDA pass by darkening a hit voxel’s brightness by the hit face’s shade (the face taken from the DDA’s last-stepped axis).

lights: Option<LightRig<'a>>

Dynamic lighting (stages DL + SL) — runtime sun + point + spot lights + stylized shadows, applied by both backends (GPU shaders since DL; the CPU renderer since CPU.1/CPU.2). None (the default for hosts that don’t set it) ⇒ exactly the pre-DL render, both backends. The baked brightness byte is reinterpreted as the ambient/AO channel; direct light composites on top (albedo*ambient + Σ direct).

tint: Option<Tint>

WT.2 — full-screen colour tint (Tint), applied by both backends in the resolve step at the logical resolution: after the SSAA downfilter, BEFORE posterize (grade first, quantize after — the reduced palette stays palette-shaped under the tint). The canonical use is the underwater look — lerp toward a deep blue-green while CharacterBody::eye_in_water — but it is a general grade hook (damage flash, night vision). None (the default) is byte-identical to the pre-WT.2 output.

Implementations

impl<'a> FrameParams<'a>

pub fn new(settings: &'a OpticastSettings) -> Self

Frame params with sensible defaults for everything except settings (which the host owns): the default sky colour (RenderOptions::clear_sky’s default), no panorama, CPU fog off, sprites on, no per-side shading, no dynamic lights. Both backends’ projection comes from settings (see the struct docs).

treat_z_max_as_air defaults to true (what every demo passes; out-of-bounds cameras skip the bedrock path). Hosts that want the pre-QE literal-struct behaviour set it back to false.

Every field stays public — construct with new and override what differs:

let mut fp = FrameParams::new(&settings);
fp.sky = Some(&sky);
fp.lights = Some(rig);

pub fn fov_y_rad(&self) -> f32

The vertical field of view both backends render settings with: 2·atan(yres/2 / hz) — resolution-independent, so it holds at any window / logical size.

pub fn gpu_outer_steps(&self) -> u32

The GPU outer-DDA step budget (chunks) derived from OpticastSettings::max_scan_dist: enough chunk steps to cover the scan distance, plus slack for the entry/exit chunks.