roxlap-core 0.16.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

//! 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 {
    pub xres: u32,
    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,
    pub hx: f32,
    pub hy: f32,
    pub hz: f32,
    pub anginc: f32,
    pub mip_levels: u32,
    pub mip_scan_dist: i32,
    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,
            hx: half_w,
            hy: half_h,
            hz: half_w,
            anginc: 1.0,
            mip_levels: 1,
            mip_scan_dist: 4,
            max_scan_dist: 1024,
        }
    }

    /// 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
    }
}