Skip to main content

pointblitz_core/
camera.rs

1//! Camera in ENU metres (decision 0013): x east, y north, z up.
2//!
3//! Rendering is camera-relative: the view matrix places the eye at the origin and every chunk is
4//! shifted by `chunk.origin − eye`, computed in f64, so f32 precision is spent near the viewer.
5//! Projection is reversed-Z with an infinite far plane (depth 1 at the near plane, 0 at infinity).
6
7use glam::{DMat4, DVec3, DVec4, Mat4};
8
9/// Right-handed view matrix for an eye at the origin looking along `dir`
10/// (view space: x right, y up, −z forward).
11fn look_dir_rh(dir: DVec3, up: DVec3) -> DMat4 {
12    let f = dir.normalize();
13    let s = f.cross(up).normalize();
14    let u = s.cross(f);
15    DMat4::from_cols(
16        DVec4::new(s.x, u.x, -f.x, 0.0),
17        DVec4::new(s.y, u.y, -f.y, 0.0),
18        DVec4::new(s.z, u.z, -f.z, 0.0),
19        DVec4::new(0.0, 0.0, 0.0, 1.0),
20    )
21}
22
23/// Reversed-Z, infinite far plane: depth = near / distance (1 at the near plane, → 0 far away).
24fn perspective_infinite_reverse_rh(fov_y: f64, aspect: f64, near: f64) -> DMat4 {
25    let f = 1.0 / (fov_y / 2.0).tan();
26    DMat4::from_cols(
27        DVec4::new(f / aspect, 0.0, 0.0, 0.0),
28        DVec4::new(0.0, f, 0.0, 0.0),
29        DVec4::new(0.0, 0.0, 0.0, -1.0),
30        DVec4::new(0.0, 0.0, near, 0.0),
31    )
32}
33
34#[derive(Debug, Clone, PartialEq)]
35pub struct Camera {
36    pub eye: DVec3,
37    pub target: DVec3,
38    pub up: DVec3,
39    pub fov_y_deg: f64,
40    pub near: f64,
41}
42
43impl Camera {
44    pub fn new(eye: [f64; 3], target: [f64; 3], up: [f64; 3], fov_y_deg: f64) -> Self {
45        Self {
46            eye: eye.into(),
47            target: target.into(),
48            up: up.into(),
49            fov_y_deg,
50            near: 0.05,
51        }
52    }
53
54    /// View (eye at origin) × projection, as f32 for the GPU.
55    pub fn view_proj(&self, aspect: f64) -> Mat4 {
56        let view = look_dir_rh(self.target - self.eye, self.up);
57        let proj = perspective_infinite_reverse_rh(self.fov_y_deg.to_radians(), aspect, self.near);
58        (proj * view).as_mat4()
59    }
60
61    /// Where an ENU point lands in pixels (x right, y down, pixel centres at i + 0.5), or None if
62    /// it is behind the camera. CPU reference used by tests and culling checks.
63    pub fn project_px(&self, p: [f64; 3], width: u32, height: u32) -> Option<[f64; 2]> {
64        let aspect = f64::from(width) / f64::from(height);
65        let view = look_dir_rh(self.target - self.eye, self.up);
66        let proj = perspective_infinite_reverse_rh(self.fov_y_deg.to_radians(), aspect, self.near);
67        let clip = proj * view * (DVec3::from(p) - self.eye).extend(1.0);
68        if clip.w <= 0.0 {
69            return None;
70        }
71        let ndc = clip.truncate() / clip.w;
72        Some([
73            (ndc.x + 1.0) / 2.0 * f64::from(width),
74            (1.0 - ndc.y) / 2.0 * f64::from(height),
75        ])
76    }
77}
78
79#[cfg(test)]
80mod tests {
81    use super::*;
82
83    #[test]
84    fn target_projects_to_centre() {
85        let c = Camera::new([0.0, -10.0, 5.0], [0.0, 0.0, 0.0], [0.0, 0.0, 1.0], 50.0);
86        let p = c.project_px([0.0, 0.0, 0.0], 1920, 1080).unwrap();
87        assert!((p[0] - 960.0).abs() < 1e-9 && (p[1] - 540.0).abs() < 1e-9);
88    }
89
90    #[test]
91    fn east_is_right_and_up_is_up_when_looking_north() {
92        let c = Camera::new([0.0, -10.0, 0.0], [0.0, 0.0, 0.0], [0.0, 0.0, 1.0], 50.0);
93        let east = c.project_px([1.0, 0.0, 0.0], 100, 100).unwrap();
94        let up = c.project_px([0.0, 0.0, 1.0], 100, 100).unwrap();
95        assert!(east[0] > 50.0);
96        assert!(up[1] < 50.0);
97    }
98
99    #[test]
100    fn behind_camera_is_none() {
101        let c = Camera::new([0.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0], 50.0);
102        assert_eq!(c.project_px([0.0, -1.0, 0.0], 100, 100), None);
103    }
104
105    #[test]
106    fn far_coordinates_keep_precision() {
107        // 5 km from the ENU origin, 1 cm apart: still distinct pixels when viewed from 1 m.
108        let base = [5000.0, 5000.0, 100.0];
109        let c = Camera::new(
110            [base[0], base[1] - 1.0, base[2]],
111            base,
112            [0.0, 0.0, 1.0],
113            50.0,
114        );
115        let a = c.project_px(base, 1920, 1080).unwrap();
116        let b = c
117            .project_px([base[0] + 0.01, base[1], base[2]], 1920, 1080)
118            .unwrap();
119        assert!(b[0] - a[0] > 10.0);
120    }
121}