roxlap-core 0.24.0

Independent Rust voxel engine core — clean-room DDA renderer reading Voxlap .vxl/.kv6 formats.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

//! Per-frame render settings shared by the CPU renderer.
//!
//! Historically this module also held voxlap's `opticast` orchestrator
//! (the four-quadrant 2.5D scan loops). That renderer was replaced by
//! the per-pixel 3D-DDA renderer in [`crate::dda`] and removed; what
//! remains is [`OpticastSettings`], the framebuffer + projection +
//! scan-distance bundle both the DDA renderer and the sprite raycaster
//! still consume. (The name is kept for API stability; "opticast"
//! survives only as a label for the settings struct.)

/// Per-frame settings the renderer forwards through its passes. Most
/// fields map onto a classic raycaster control: `(hx, hy, hz)` are the
/// pinhole projection centre + focal length (the voxlap `setcamera`
/// `dahx`/`dahy`/`dahz`), `mip_*` drive the distance-mip ladder, and
/// `max_scan_dist` bounds the ray.
///
/// `y_start..y_end` is the strip-render iteration bound. Default is the
/// full framebuffer (`0..yres`). Tile / strip callers set a sub-range
/// to render only that horizontal strip; the projection centre stays in
/// absolute screen coords, only the viewport edges shrink.
#[derive(Debug, Clone, Copy)]
pub struct OpticastSettings {
    /// Framebuffer width in pixels. The projection centre and the
    /// strip / band bounds below are all in this full-frame space.
    pub xres: u32,
    /// Framebuffer height in pixels.
    pub yres: u32,
    /// First y-row this render call covers (inclusive). `0` for
    /// full-frame.
    pub y_start: u32,
    /// One past the last y-row (exclusive). `yres` for full-frame.
    pub y_end: u32,
    /// PF.13 (C7) — first x-column covered (inclusive). `0` for
    /// full-frame. The DDA renderer's pixels are fully independent, so
    /// an x sub-range is as safe as the y strip (the historical
    /// full-width-only constraint came from the deleted voxlap radar's
    /// column-indexed `angstart`).
    pub x_start: u32,
    /// One past the last x-column (exclusive). `xres` for full-frame.
    pub x_end: u32,
    /// Projection-centre x in pixels (the voxlap `setcamera` `dahx`).
    /// `xres / 2` for a centred view; stays in absolute screen coords
    /// even when a strip sub-range is set.
    pub hx: f32,
    /// Projection-centre y in pixels (the voxlap `dahy`). `yres / 2`
    /// for a centred view.
    pub hy: f32,
    /// Focal length in pixels (the voxlap `dahz`): pixel `(px, py)`
    /// casts along `(px−hx)·right + (py−hy)·down + hz·forward`, so the
    /// vertical field of view is `2·atan(yres/2 / hz)` and
    /// `hz = xres/2` gives 90° horizontal.
    pub hz: f32,
    /// Voxlap's `anginc` — the deleted opticast's per-column angle
    /// step (`1` = one ray per pixel column). The per-pixel DDA casts
    /// every pixel regardless; today the value survives only as the
    /// `anginc + 1` viewport padding in `roxlap-scene`'s screen-rect
    /// cull. Leave at the default `1`.
    pub anginc: f32,
    /// Depth of the distance-mip ladder: how many mip levels the
    /// renderer may sample, `1` = mip-0 only (level `n` is `2ⁿ`×
    /// coarser per axis). Also the clamp ceiling for the per-grid LOD
    /// overrides (`LodThresholds::mid_mip_levels`,
    /// `Grid::mip_levels_override` in `roxlap-scene`). The demos run 6.
    pub mip_levels: u32,
    /// Mip-transition distance in voxels: rays step through
    /// progressively coarser mips beyond it, so scan distance costs
    /// roughly logarithmically instead of linearly. Smaller ⇒ coarser
    /// sooner. The demos run 64; per-grid Mid-LOD overrides may only
    /// shrink it (`min`, never extend).
    pub mip_scan_dist: i32,
    /// Hard ray-length cap in voxels (voxlap's `vx5.maxscandist`): the
    /// march gives up (sky / fog) past it, and `roxlap-scene` skips
    /// whole grids entirely outside this radius. Floored at 1
    /// downstream; pair with the fog distance so the cutoff reads as
    /// atmosphere instead of a wall.
    pub max_scan_dist: i32,
}

impl OpticastSettings {
    /// Default settings for a `width × height` framebuffer with the
    /// convention `(hx, hy, hz) = (w/2, h/2, w/2)` and `anginc = 1`.
    /// Renders the full frame (`y_start = 0, y_end = height`).
    //
    // `width` / `height` cast to f32 is bounded by realistic screen
    // sizes (≤ 16M, well within f32's 24-bit mantissa).
    #[allow(clippy::cast_precision_loss)]
    #[must_use]
    pub fn for_oracle_framebuffer(width: u32, height: u32) -> Self {
        let half_w = (width as f32) * 0.5;
        let half_h = (height as f32) * 0.5;
        Self {
            xres: width,
            yres: height,
            y_start: 0,
            y_end: height,
            x_start: 0,
            x_end: width,
            hx: half_w,
            hy: half_h,
            hz: half_w,
            anginc: 1.0,
            mip_levels: 1,
            mip_scan_dist: 4,
            max_scan_dist: 1024,
        }
    }

    /// Pick an explicit vertical field of view (radians): sets the
    /// focal length `hz = (yres/2) / tan(fov_y/2)` so both renderer
    /// backends show exactly this FOV (QE.2a — the facade derives the
    /// GPU projection from these settings too). The projection centre
    /// (`hx`, `hy`) is untouched. The default
    /// [`Self::for_oracle_framebuffer`] focal (`hz = w/2`) equals
    /// `with_fov_y(2·atan(h/w))` — ≈ 73.7° for 4:3, ≈ 58.7° for 16:9.
    #[must_use]
    pub fn with_fov_y(mut self, fov_y_rad: f32) -> Self {
        // yres → f32 is exact for realistic screen sizes.
        #[allow(clippy::cast_precision_loss)]
        let half_h = (self.yres as f32) * 0.5;
        self.hz = half_h / (fov_y_rad * 0.5).tan();
        self
    }

    /// Restrict this settings struct to the `[y_start, y_end)`
    /// horizontal strip. Used by the per-strip parallel dispatch — each
    /// strip clones the base settings and clamps the y-range. Caller is
    /// responsible for ensuring `y_start < y_end <= yres`.
    #[must_use]
    pub fn with_y_range(mut self, y_start: u32, y_end: u32) -> Self {
        self.y_start = y_start;
        self.y_end = y_end;
        self
    }

    /// PF.13 (C7) — restrict to the `[x_start, x_end)` vertical band;
    /// the per-grid screen scissor pairs this with
    /// [`Self::with_y_range`] so a small grid renders only its true
    /// screen rect instead of full-width rows. Caller ensures
    /// `x_start < x_end <= xres`.
    #[must_use]
    pub fn with_x_range(mut self, x_start: u32, x_end: u32) -> Self {
        self.x_start = x_start;
        self.x_end = x_end;
        self
    }
}