common/

vec3.rs

use std::ops::{
    Add, AddAssign, Div, DivAssign, Index, IndexMut, Mul, MulAssign, Neg, Sub,
};

/// A 3D vector with `f64` components.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Vec3 {
    /// Components stored as `[x, y, z]`.
    pub e: [f64; 3],
}

/// Type alias for a 3D point.
pub type Point3 = Vec3;
/// Type alias for an RGB color (components in \[0, 1\]).
pub type Color = Vec3;

// --- Constructors and Accessors ---

impl Vec3 {
    /// Creates a new `Vec3` from three `f64` components.
    pub fn new(e0: f64, e1: f64, e2: f64) -> Self {
        Vec3 { e: [e0, e1, e2] }
    }

    /// Returns the x component.
    pub fn x(self) -> f64 { self.e[0] }
    /// Returns the y component.
    pub fn y(self) -> f64 { self.e[1] }
    /// Returns the z component.
    pub fn z(self) -> f64 { self.e[2] }

    /// Returns the squared length (dot product with itself).
    pub fn length_squared(self) -> f64 {
        self.e[0] * self.e[0] + self.e[1] * self.e[1] + self.e[2] * self.e[2]
    }

    /// Returns the Euclidean length.
    pub fn length(self) -> f64 {
        self.length_squared().sqrt()
    }

    /// Returns `true` if all components are very close to zero (zero-vector check).
    pub fn near_zero(self) -> bool {
        const S: f64 = 1e-8;
        self.e[0].abs() < S && self.e[1].abs() < S && self.e[2].abs() < S
    }
}

impl Default for Vec3 {
    fn default() -> Self {
        Vec3 { e: [0.0, 0.0, 0.0] }
    }
}

// --- Output ---

impl std::fmt::Display for Vec3 {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "{} {} {}", self.e[0], self.e[1], self.e[2])
    }
}

// --- Operator Overloads ---

impl Neg for Vec3 {
    type Output = Vec3;
    fn neg(self) -> Vec3 {
        Vec3::new(-self.e[0], -self.e[1], -self.e[2])
    }
}

impl Index<usize> for Vec3 {
    type Output = f64;
    fn index(&self, i: usize) -> &f64 { &self.e[i] }
}

impl IndexMut<usize> for Vec3 {
    fn index_mut(&mut self, i: usize) -> &mut f64 { &mut self.e[i] }
}

impl AddAssign for Vec3 {
    fn add_assign(&mut self, v: Vec3) {
        self.e[0] += v.e[0];
        self.e[1] += v.e[1];
        self.e[2] += v.e[2];
    }
}

impl MulAssign<f64> for Vec3 {
    fn mul_assign(&mut self, t: f64) {
        self.e[0] *= t;
        self.e[1] *= t;
        self.e[2] *= t;
    }
}

impl DivAssign<f64> for Vec3 {
    fn div_assign(&mut self, t: f64) {
        *self *= 1.0 / t;
    }
}

impl Add for Vec3 {
    type Output = Vec3;
    fn add(self, v: Vec3) -> Vec3 {
        Vec3::new(self.e[0] + v.e[0], self.e[1] + v.e[1], self.e[2] + v.e[2])
    }
}

impl Sub for Vec3 {
    type Output = Vec3;
    fn sub(self, v: Vec3) -> Vec3 {
        Vec3::new(self.e[0] - v.e[0], self.e[1] - v.e[1], self.e[2] - v.e[2])
    }
}

impl Mul for Vec3 {
    type Output = Vec3;
    fn mul(self, v: Vec3) -> Vec3 {
        Vec3::new(self.e[0] * v.e[0], self.e[1] * v.e[1], self.e[2] * v.e[2])
    }
}

impl Mul<f64> for Vec3 {
    type Output = Vec3;
    fn mul(self, t: f64) -> Vec3 {
        Vec3::new(self.e[0] * t, self.e[1] * t, self.e[2] * t)
    }
}

impl Mul<Vec3> for f64 {
    type Output = Vec3;
    fn mul(self, v: Vec3) -> Vec3 { v * self }
}

impl Div<f64> for Vec3 {
    type Output = Vec3;
    fn div(self, t: f64) -> Vec3 { self * (1.0 / t) }
}

// --- Utility Functions ---

/// Computes the dot product of two vectors.
pub fn dot(u: Vec3, v: Vec3) -> f64 {
    u.e[0] * v.e[0] + u.e[1] * v.e[1] + u.e[2] * v.e[2]
}

/// Computes the cross product of two vectors.
pub fn cross(u: Vec3, v: Vec3) -> Vec3 {
    Vec3::new(
        u.e[1] * v.e[2] - u.e[2] * v.e[1],
        u.e[2] * v.e[0] - u.e[0] * v.e[2],
        u.e[0] * v.e[1] - u.e[1] * v.e[0],
    )
}

/// Returns the unit vector in the same direction as `v`.
pub fn unit_vector(v: Vec3) -> Vec3 {
    v / v.length()
}

/// Computes the reflection vector (v: incident direction, n: unit surface normal).
///
/// **r** = **v** - 2(**v**·**n**)**n**
pub fn reflect(v: Vec3, n: Vec3) -> Vec3 {
    v - 2.0 * dot(v, n) * n
}

/// Computes the refraction vector (Snell's law).
///
/// `uv`: unit incident direction, `n`: unit normal pointing outward from the incident medium, `etai_over_etat`: η/η'.
pub fn refract(uv: Vec3, n: Vec3, etai_over_etat: f64) -> Vec3 {
    let cos_theta = dot(-uv, n).min(1.0);
    let r_out_parallel = etai_over_etat * (uv + cos_theta * n);
    let r_out_perp = -(1.0 - r_out_parallel.length_squared()).sqrt() * n;
    r_out_parallel + r_out_perp
}

/// Returns a random point **inside** the unit sphere (rejection method).
pub fn random_in_unit_sphere() -> Vec3 {
    use crate::utils::random_double_range;
    loop {
        let p = Vec3::new(
            random_double_range(-1.0, 1.0),
            random_double_range(-1.0, 1.0),
            random_double_range(-1.0, 1.0),
        );
        if p.length_squared() < 1.0 {
            return p;
        }
    }
}

/// Returns a random point **on** the unit sphere surface (true Lambertian reflection).
pub fn random_unit_vector() -> Vec3 {
    unit_vector(random_in_unit_sphere())
}

/// Returns a random point inside the unit **disk** (z=0 plane, rejection method).
pub fn random_in_unit_disk() -> Vec3 {
    use crate::utils::random_double_range;
    loop {
        let p = Vec3::new(
            random_double_range(-1.0, 1.0),
            random_double_range(-1.0, 1.0),
            0.0,
        );
        if p.length_squared() < 1.0 {
            return p;
        }
    }
}

/// Returns a random point in the hemisphere around the normal (uniform hemisphere sampling).
pub fn random_in_hemisphere(normal: Vec3) -> Vec3 {
    let in_unit_sphere = random_in_unit_sphere();
    if dot(in_unit_sphere, normal) > 0.0 {
        in_unit_sphere
    } else {
        -in_unit_sphere
    }
}

// --- Color Utilities ---

/// Averages `pixel_color` over `samples_per_pixel` samples and converts to an "R G B" string.
pub fn write_color(pixel_color: Color, samples_per_pixel: i32) -> String {
    let scale = 1.0 / samples_per_pixel as f64;
    let r = (pixel_color.x() * scale).clamp(0.0, 0.999);
    let g = (pixel_color.y() * scale).clamp(0.0, 0.999);
    let b = (pixel_color.z() * scale).clamp(0.0, 0.999);
    let ir = (256.0 * r) as i32;
    let ig = (256.0 * g) as i32;
    let ib = (256.0 * b) as i32;
    format!("{} {} {}", ir, ig, ib)
}

/// Averages `pixel_color` over `samples_per_pixel` samples, applies gamma=2 correction (square root), and converts to an "R G B" string.
pub fn write_color_gamma(pixel_color: Color, samples_per_pixel: i32) -> String {
    let scale = 1.0 / samples_per_pixel as f64;
    let r = (pixel_color.x() * scale).sqrt().clamp(0.0, 0.999);
    let g = (pixel_color.y() * scale).sqrt().clamp(0.0, 0.999);
    let b = (pixel_color.z() * scale).sqrt().clamp(0.0, 0.999);
    let ir = (256.0 * r) as i32;
    let ig = (256.0 * g) as i32;
    let ib = (256.0 * b) as i32;
    format!("{} {} {}", ir, ig, ib)
}