roxlap_core/camera.rs
1//! Camera state — position + orthonormal basis.
2//!
3//! Mirrors voxlaptest's `setcamera(ipo, ist, ihe, ifo, ...)` ABI: a
4//! starting point and three orthonormal axes (right, down, forward).
5//! The convention matches the voxlap C engine so a `.vxl` file's
6//! camera vectors load directly.
7
8/// Camera state. All vectors are in voxel-world units (1 unit = 1
9/// voxel); the basis is right-handed with `down` aligned to +z (i.e.
10/// z grows downward into the map, matching voxlap's coordinate
11/// system).
12///
13/// # Examples
14///
15/// ```
16/// use roxlap_core::Camera;
17///
18/// let cam = Camera::default();
19/// assert_eq!(cam.pos, [1024.0, 1024.0, 128.0]);
20/// assert_eq!(cam.forward, [0.0, 1.0, 0.0]); // looking +y (north)
21/// ```
22#[derive(Debug, Clone, Copy, PartialEq)]
23pub struct Camera {
24 /// Camera position (`ipo` / `dpoint3d` in voxlaptest).
25 pub pos: [f64; 3],
26 /// Right vector (`ist`).
27 pub right: [f64; 3],
28 /// Down vector (`ihe`).
29 pub down: [f64; 3],
30 /// Forward vector (`ifo`).
31 pub forward: [f64; 3],
32}
33
34impl Default for Camera {
35 /// Centred at the middle of a 2048-VSID map, looking +y, level.
36 /// Matches the placeholder vectors voxlaptest's oracle writes
37 /// into the `.vxl` header (see `tests/oracle/oracle.c`).
38 ///
39 /// **Caution:** this placeholder basis is *left-handed*
40 /// (`right × down = -forward`). It is fine for the world raycaster,
41 /// but the sprite frustum cull requires the canonical right-handed
42 /// chirality (`right × down = +forward`) and will reject every
43 /// sprite under this basis. For an interactive camera build the
44 /// basis with [`Camera::from_yaw_pitch`] / [`Camera::orbit`] /
45 /// [`Camera::look_at`] instead of starting from `default()` and
46 /// rotating it. See the [crate-level handedness
47 /// notes](crate#world-handedness-and-the-horizontal-mirror).
48 fn default() -> Self {
49 Self {
50 pos: [1024.0, 1024.0, 128.0],
51 right: [1.0, 0.0, 0.0],
52 down: [0.0, 0.0, 1.0],
53 forward: [0.0, 1.0, 0.0],
54 }
55 }
56}
57
58impl Camera {
59 /// Build a camera from a position plus `yaw` / `pitch` (radians),
60 /// with no roll.
61 ///
62 /// This is the **canonical** voxlap-convention constructor: it
63 /// reproduces `oracle.c::set_camera_yaw_pitch` bit-for-bit, so the
64 /// frustum cull (which requires `right × down = +forward`) accepts
65 /// sprites and the render matches the bit-exact oracle goldens.
66 /// Any project that hand-rolls `right = [-sin yaw, cos yaw, 0]`
67 /// should call this instead — that hand-rolled form is exactly
68 /// this basis, and copying it by hand is the usual source of
69 /// chirality mistakes.
70 ///
71 /// `yaw` sweeps the world's horizontal (x/y) plane: `yaw = 0` looks
72 /// down `+x`, increasing `yaw` turns toward `+y`. `pitch` tilts
73 /// toward `+z` (down): `pitch = 0` is level, positive pitch aims
74 /// downward.
75 ///
76 /// See the [crate-level handedness
77 /// notes](crate#world-handedness-and-the-horizontal-mirror) for why
78 /// the rendered image is horizontally mirrored versus a real camera
79 /// and what to do if you need an un-mirrored world.
80 ///
81 /// # Examples
82 /// ```
83 /// use roxlap_core::Camera;
84 ///
85 /// let cam = Camera::from_yaw_pitch([1024.0, 1024.0, 128.0], 0.0, 0.0);
86 /// // yaw = 0, pitch = 0 → looking down +x.
87 /// assert_eq!(cam.forward, [1.0, 0.0, 0.0]);
88 /// assert_eq!(cam.right, [0.0, 1.0, 0.0]);
89 /// assert_eq!(cam.down, [0.0, 0.0, 1.0]);
90 ///
91 /// // Canonical chirality: right × down == +forward. The sprite
92 /// // frustum cull depends on this; `Camera::default`'s placeholder
93 /// // basis does *not* satisfy it.
94 /// let cross = [
95 /// cam.right[1] * cam.down[2] - cam.right[2] * cam.down[1],
96 /// cam.right[2] * cam.down[0] - cam.right[0] * cam.down[2],
97 /// cam.right[0] * cam.down[1] - cam.right[1] * cam.down[0],
98 /// ];
99 /// assert_eq!(cross, cam.forward);
100 /// ```
101 #[must_use]
102 pub fn from_yaw_pitch(pos: [f64; 3], yaw: f64, pitch: f64) -> Self {
103 let (sy, cy) = yaw.sin_cos();
104 let (sp, cp) = pitch.sin_cos();
105 Self {
106 pos,
107 right: [-sy, cy, 0.0],
108 down: [-cy * sp, -sy * sp, cp],
109 forward: [cy * cp, sy * cp, sp],
110 }
111 }
112
113 /// Orbit camera: look *at* `center` from `dist` voxels away, at the
114 /// given `yaw` / `pitch`. Heading conventions match
115 /// [`Camera::from_yaw_pitch`]; the position is placed `dist` behind
116 /// the forward axis so `center` sits on the view ray.
117 ///
118 /// # Examples
119 /// ```
120 /// use roxlap_core::Camera;
121 ///
122 /// // yaw = 0 → forward = +x, so the eye sits at center − dist·(+x).
123 /// let cam = Camera::orbit(0.0, 0.0, 100.0, [1024.0, 1024.0, 128.0]);
124 /// assert_eq!(cam.forward, [1.0, 0.0, 0.0]);
125 /// assert_eq!(cam.pos, [924.0, 1024.0, 128.0]);
126 /// ```
127 #[must_use]
128 pub fn orbit(yaw: f64, pitch: f64, dist: f64, center: [f64; 3]) -> Self {
129 let mut cam = Self::from_yaw_pitch([0.0; 3], yaw, pitch);
130 cam.pos = [
131 center[0] - cam.forward[0] * dist,
132 center[1] - cam.forward[1] * dist,
133 center[2] - cam.forward[2] * dist,
134 ];
135 cam
136 }
137
138 /// Look from `eye` toward `target`, with no roll (the `right` axis
139 /// stays in the world's horizontal plane). Produces the same
140 /// canonical chirality as [`Camera::from_yaw_pitch`] by recovering
141 /// yaw / pitch from the look direction.
142 ///
143 /// If `eye == target` (or the look direction is purely vertical),
144 /// yaw collapses to `0`; the resulting basis is still orthonormal
145 /// and correctly handed.
146 ///
147 /// # Examples
148 /// ```
149 /// use roxlap_core::Camera;
150 ///
151 /// // Looking from x=924 toward x=1024 (i.e. down +x).
152 /// let cam = Camera::look_at([924.0, 1024.0, 128.0], [1024.0, 1024.0, 128.0]);
153 /// assert_eq!(cam.forward, [1.0, 0.0, 0.0]);
154 /// assert_eq!(cam.right, [0.0, 1.0, 0.0]);
155 /// ```
156 #[must_use]
157 pub fn look_at(eye: [f64; 3], target: [f64; 3]) -> Self {
158 let fx = target[0] - eye[0];
159 let fy = target[1] - eye[1];
160 let fz = target[2] - eye[2];
161 let yaw = fy.atan2(fx);
162 let horiz = (fx * fx + fy * fy).sqrt();
163 let pitch = fz.atan2(horiz);
164 Self::from_yaw_pitch(eye, yaw, pitch)
165 }
166}