#[derive(Clone, Copy, Debug)]
pub struct Point3 {
pub x: f32,
pub y: f32,
pub z: f32,
}
#[derive(Clone, Copy, Debug)]
pub struct Line3 {
pub start: Point3,
pub end: Point3,
}
#[derive(Clone, Debug)]
pub struct Polygon3 {
pub vertices: Vec<Point3>,
}
#[derive(Clone, Copy, Debug)]
pub struct ProjectLineParams {
pub center_x: f32,
pub center_y: f32,
pub screen_w: f32,
pub screen_h: f32,
pub subpixels_x: f32,
pub subpixels_y: f32,
pub min_scale: f32,
}
#[derive(Clone, Copy, Debug)]
pub struct Camera {
pub near: f32,
pub focal_length: f32,
}
pub const ASPECT_COMPENSATION: f32 = 2.0;
impl Camera {
pub fn project(&self, p: Point3, center_x: f32, center_y: f32) -> Option<(f32, f32, f32)> {
if p.z <= self.near {
return None;
}
let ndc_x = p.x / p.z;
let ndc_y = p.y / p.z;
let scale = self.focal_length / p.z;
let screen_x = center_x + ndc_x * self.focal_length * ASPECT_COMPENSATION;
let screen_y = center_y - ndc_y * self.focal_length;
Some((screen_x, screen_y, scale))
}
pub fn project_line(
&self,
line: Line3,
params: ProjectLineParams,
) -> Option<(u16, u16, u16, u16)> {
let (sx0, sy0, scale0) = self.project(line.start, params.center_x, params.center_y)?;
let (sx1, sy1, scale1) = self.project(line.end, params.center_x, params.center_y)?;
if scale0.max(scale1) < params.min_scale {
return None;
}
let (cx0, cy0, cx1, cy1) =
clip_to_screen(sx0, sy0, sx1, sy1, params.screen_w, params.screen_h)?;
Some((
(cx0 * params.subpixels_x)
.round()
.clamp(0.0, u16::MAX as f32) as u16,
(cy0 * params.subpixels_y)
.round()
.clamp(0.0, u16::MAX as f32) as u16,
(cx1 * params.subpixels_x)
.round()
.clamp(0.0, u16::MAX as f32) as u16,
(cy1 * params.subpixels_y)
.round()
.clamp(0.0, u16::MAX as f32) as u16,
))
}
pub fn project_polygon(
&self,
polygon: &Polygon3,
center_x: f32,
center_y: f32,
subpixels_x: f32,
subpixels_y: f32,
min_scale: f32,
) -> Option<Vec<(f32, f32)>> {
let mut points = Vec::with_capacity(polygon.vertices.len());
let mut max_scale = 0.0f32;
for &v in &polygon.vertices {
let (sx, sy, scale) = self.project(v, center_x, center_y)?;
max_scale = max_scale.max(scale);
points.push((sx * subpixels_x, sy * subpixels_y));
}
if max_scale < min_scale {
return None;
}
Some(points)
}
}
const OUTCODE_INSIDE: u8 = 0;
const OUTCODE_LEFT: u8 = 1;
const OUTCODE_RIGHT: u8 = 2;
const OUTCODE_TOP: u8 = 4;
const OUTCODE_BOTTOM: u8 = 8;
fn outcode(x: f32, y: f32, xmax: f32, ymax: f32) -> u8 {
let mut code = OUTCODE_INSIDE;
if x < 0.0 {
code |= OUTCODE_LEFT;
} else if x > xmax {
code |= OUTCODE_RIGHT;
}
if y < 0.0 {
code |= OUTCODE_TOP;
} else if y > ymax {
code |= OUTCODE_BOTTOM;
}
code
}
fn clip_to_screen(
mut x0: f32,
mut y0: f32,
mut x1: f32,
mut y1: f32,
xmax: f32,
ymax: f32,
) -> Option<(f32, f32, f32, f32)> {
let mut code0 = outcode(x0, y0, xmax, ymax);
let mut code1 = outcode(x1, y1, xmax, ymax);
loop {
if code0 | code1 == 0 {
return Some((x0, y0, x1, y1));
}
if code0 & code1 != 0 {
return None;
}
let out = if code0 != 0 { code0 } else { code1 };
let (x, y) = if out & OUTCODE_TOP != 0 {
(x0 + (x1 - x0) * (0.0 - y0) / (y1 - y0), 0.0)
} else if out & OUTCODE_BOTTOM != 0 {
(x0 + (x1 - x0) * (ymax - y0) / (y1 - y0), ymax)
} else if out & OUTCODE_RIGHT != 0 {
(xmax, y0 + (y1 - y0) * (xmax - x0) / (x1 - x0))
} else {
(0.0, y0 + (y1 - y0) * (0.0 - x0) / (x1 - x0))
};
if out == code0 {
x0 = x;
y0 = y;
code0 = outcode(x0, y0, xmax, ymax);
} else {
x1 = x;
y1 = y;
code1 = outcode(x1, y1, xmax, ymax);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn camera() -> Camera {
Camera {
near: 0.5,
focal_length: 8.0,
}
}
#[test]
fn point_behind_the_near_plane_returns_none() {
let cam = camera();
let p = Point3 {
x: 4.0,
y: 0.0,
z: 0.2,
};
assert_eq!(cam.project(p, 10.0, 5.0), None);
}
#[test]
fn point_exactly_at_the_near_plane_returns_none() {
let cam = camera();
let p = Point3 {
x: 4.0,
y: 0.0,
z: 0.5,
};
assert_eq!(cam.project(p, 10.0, 5.0), None);
}
#[test]
fn nearer_points_project_farther_from_center_and_with_larger_scale() {
let cam = camera();
let center_x = 10.0;
let center_y = 5.0;
let (x2, y2, s2) = cam
.project(
Point3 {
x: 4.0,
y: 0.0,
z: 2.0,
},
center_x,
center_y,
)
.unwrap();
let (x4, y4, s4) = cam
.project(
Point3 {
x: 4.0,
y: 0.0,
z: 4.0,
},
center_x,
center_y,
)
.unwrap();
let (x8, y8, s8) = cam
.project(
Point3 {
x: 4.0,
y: 0.0,
z: 8.0,
},
center_x,
center_y,
)
.unwrap();
assert_eq!((x2, s2), (42.0, 4.0));
assert_eq!((x4, s4), (26.0, 2.0));
assert_eq!((x8, s8), (18.0, 1.0));
assert_eq!(y2, 5.0);
assert_eq!(y4, 5.0);
assert_eq!(y8, 5.0);
assert!((x8 - center_x).abs() < (x4 - center_x).abs());
assert!((x4 - center_x).abs() < (x2 - center_x).abs());
assert!(s8 < s4 && s4 < s2);
}
#[test]
fn positive_world_y_maps_to_a_smaller_screen_y() {
let cam = camera();
let (x, y, _) = cam
.project(
Point3 {
x: 0.0,
y: 2.0,
z: 4.0,
},
10.0,
5.0,
)
.unwrap();
assert_eq!(x, 10.0); assert_eq!(y, 1.0);
}
fn assert_close(actual: f32, expected: f32, label: &str) {
assert!(
(actual - expected).abs() < 0.001,
"{label}: expected {expected}, got {actual}"
);
}
#[test]
fn clip_to_screen_leaves_a_fully_inside_line_unchanged() {
let result = clip_to_screen(2.0, 2.0, 8.0, 8.0, 10.0, 10.0);
assert_eq!(result, Some((2.0, 2.0, 8.0, 8.0)));
}
#[test]
fn clip_to_screen_rejects_a_line_fully_outside_on_each_side() {
assert_eq!(clip_to_screen(-5.0, 3.0, -1.0, 3.0, 10.0, 10.0), None); assert_eq!(clip_to_screen(15.0, 3.0, 20.0, 3.0, 10.0, 10.0), None); assert_eq!(clip_to_screen(3.0, -5.0, 3.0, -1.0, 10.0, 10.0), None); assert_eq!(clip_to_screen(3.0, 15.0, 3.0, 20.0, 10.0, 10.0), None); }
#[test]
fn clip_to_screen_clips_a_single_edge_crossing() {
let result = clip_to_screen(5.0, 5.0, 15.0, 5.0, 10.0, 10.0);
assert_eq!(result, Some((5.0, 5.0, 10.0, 5.0)));
}
#[test]
fn clip_to_screen_resolves_a_two_edge_corner_crossing() {
let result = clip_to_screen(20.0, 15.0, 5.0, 5.0, 10.0, 10.0);
let (cx0, cy0, cx1, cy1) = result.expect("line intersects the box");
assert_close(cx0, 10.0, "clipped start.x (right edge)");
assert!(
(0.0..=10.0).contains(&cy0),
"clipped start.y should be within the box, got {cy0}"
);
assert_eq!(cx1, 5.0);
assert_eq!(cy1, 5.0);
}
#[test]
fn project_line_returns_none_when_either_endpoint_is_behind_the_near_plane() {
let cam = camera();
let line = Line3 {
start: Point3 {
x: -1.0,
y: 0.0,
z: 4.0,
},
end: Point3 {
x: 1.0,
y: 0.0,
z: 0.2,
},
};
assert_eq!(
cam.project_line(
line,
ProjectLineParams {
center_x: 5.0,
center_y: 5.0,
screen_w: 10.0,
screen_h: 10.0,
subpixels_x: 2.0,
subpixels_y: 4.0,
min_scale: 0.0,
}
),
None
);
}
#[test]
fn project_line_returns_none_when_every_vertexs_scale_is_below_min_scale() {
let cam = camera();
let line = Line3 {
start: Point3 {
x: -1.0,
y: 0.0,
z: 100.0,
},
end: Point3 {
x: 1.0,
y: 0.0,
z: 100.0,
},
};
assert_eq!(
cam.project_line(
line,
ProjectLineParams {
center_x: 5.0,
center_y: 5.0,
screen_w: 10.0,
screen_h: 10.0,
subpixels_x: 2.0,
subpixels_y: 4.0,
min_scale: 0.1,
}
),
None
);
}
#[test]
fn project_line_projects_a_fully_visible_line_to_subpixel_coordinates() {
let cam = camera();
let line = Line3 {
start: Point3 {
x: -1.0,
y: 0.0,
z: 4.0,
},
end: Point3 {
x: 1.0,
y: 0.0,
z: 4.0,
},
};
let result = cam.project_line(
line,
ProjectLineParams {
center_x: 5.0,
center_y: 3.0,
screen_w: 10.0,
screen_h: 6.0,
subpixels_x: 2.0,
subpixels_y: 4.0,
min_scale: 0.0,
},
);
assert_eq!(result, Some((2, 12, 18, 12)));
}
#[test]
fn project_line_clips_instead_of_saturating_an_off_screen_endpoint() {
let cam = camera();
let line = Line3 {
start: Point3 {
x: 20.0,
y: 0.0,
z: 4.0,
},
end: Point3 {
x: 0.0,
y: 0.0,
z: 4.0,
},
};
let result = cam
.project_line(
line,
ProjectLineParams {
center_x: 5.0,
center_y: 5.0,
screen_w: 10.0,
screen_h: 10.0,
subpixels_x: 2.0,
subpixels_y: 4.0,
min_scale: 0.0,
},
)
.expect("line crosses into the visible screen");
assert_eq!(result, (20, 20, 10, 20));
}
#[test]
fn project_polygon_returns_none_when_any_vertex_is_behind_the_near_plane() {
let cam = camera();
let poly = Polygon3 {
vertices: vec![
Point3 {
x: -1.0,
y: -1.0,
z: 4.0,
},
Point3 {
x: -1.0,
y: 1.0,
z: 4.0,
},
Point3 {
x: 1.0,
y: 0.0,
z: 0.2,
},
],
};
assert_eq!(cam.project_polygon(&poly, 5.0, 5.0, 2.0, 4.0, 0.0), None);
}
#[test]
fn project_polygon_returns_none_when_every_vertexs_scale_is_below_min_scale() {
let cam = camera();
let poly = Polygon3 {
vertices: vec![
Point3 {
x: -1.0,
y: -1.0,
z: 100.0,
},
Point3 {
x: -1.0,
y: 1.0,
z: 100.0,
},
Point3 {
x: 1.0,
y: 0.0,
z: 100.0,
},
],
};
assert_eq!(cam.project_polygon(&poly, 5.0, 5.0, 2.0, 4.0, 0.1), None);
}
#[test]
fn project_polygon_projects_every_vertex_when_visible() {
let cam = camera();
let poly = Polygon3 {
vertices: vec![Point3 {
x: 0.0,
y: 0.0,
z: 4.0,
}],
};
let result = cam
.project_polygon(&poly, 5.0, 5.0, 2.0, 4.0, 0.0)
.expect("single visible vertex projects");
assert_eq!(result, vec![(10.0, 20.0)]);
}
}