Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

6.2 KB
Raw Blame
//! Bounded direct lighting for RT2. World directions point from a hit towards each light.
//! Colours are linear sRGB; intensity is relative radiance, not watts or illuminance.
//! Visibility is supplied separately for every light by the ray-tracing consumer.

use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;

use crate::surface::{OpaqueSurface, unit_direction};

use super::{Result, TraceError};

pub const MAX_LIGHTS: usize = 8;
pub const MAX_LIGHT_INTENSITY: f64 = 64.0;
/// Refuse unrepresentable or excessive output rather than silently clip the transport.
pub const MAX_LINEAR_RADIANCE: f64 = 1.0e12;
pub const MAX_EXPOSURE_EV: f64 = 16.0;

#[derive(Clone, Copy, Debug, PartialEq)]
pub struct DirectionalLight {
    direction: Vec3,
    color: Vec3,
    intensity: f64,
}

impl DirectionalLight {
    pub fn new(direction: Vec3, linear_color: Vec3, intensity: f64) -> Result<Self> {
        let direction = unit_direction(direction).map_err(|_| TraceError::InvalidInput("finite nonzero light direction required"))?;
        if !linear_color.is_finite() || !channels(linear_color).into_iter().all(|c| (0.0..=1.0).contains(&c)) {
            return Err(TraceError::InvalidInput("light colour must be finite linear sRGB in [0, 1]"));
        }
        if !intensity.is_finite() || !(0.0..=MAX_LIGHT_INTENSITY).contains(&intensity) {
            return Err(TraceError::InvalidInput("light intensity must be finite relative radiance in [0, 64]"));
        }
        Ok(Self { direction, color: linear_color, intensity })
    }

    pub fn direction(self) -> Vec3 {
        self.direction
    }

    pub fn color(self) -> Vec3 {
        self.color
    }

    pub fn intensity(self) -> f64 {
        self.intensity
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StudioPreset {
    /// The existing three neutral lights, with unchanged directions and intensities.
    Neutral,
    /// Original warm key / cool fill colour composition, without a Kelvin claim.
    WarmCool,
    /// Original opposing key / rim composition. These are hard directional lights.
    KeyRim,
}

#[derive(Clone, Debug, PartialEq)]
pub struct Lighting {
    lights: Vec<DirectionalLight>,
}

impl Default for Lighting {
    fn default() -> Self {
        Self::studio_default()
    }
}

impl Lighting {
    pub fn new(lights: Vec<DirectionalLight>) -> Result<Self> {
        if lights.len() > MAX_LIGHTS || lights.capacity() > MAX_LIGHTS {
            return Err(TraceError::InvalidInput("RT2 admits at most eight directional lights and eight reserved light slots"));
        }
        // An empty list deliberately means no direct illumination.
        Ok(Self { lights })
    }

    pub fn studio_default() -> Self {
        Self {
            lights: crate::studio::LIGHTS
                .into_iter()
                .map(|(direction, intensity)| DirectionalLight { direction, color: Vec3::new(1.0, 1.0, 1.0), intensity })
                .collect(),
        }
    }

    pub fn preset(preset: StudioPreset) -> Result<Self> {
        let preset = match preset {
            StudioPreset::Neutral => return Ok(Self::studio_default()),
            StudioPreset::WarmCool => crate::job::LightingPreset::WarmCool,
            StudioPreset::KeyRim => crate::job::LightingPreset::KeyRim,
        };
        let lights = preset
            .directional_lights()
            .into_iter()
            .map(|light| {
                let [x, y, z] = light.direction;
                let [r, g, b] = light.color;
                DirectionalLight::new(Vec3::new(x, y, z), Vec3::new(r, g, b), light.intensity)
            })
            .collect::<Result<Vec<_>>>()?;
        Self::new(lights)
    }

    pub fn lights(&self) -> &[DirectionalLight] {
        &self.lights
    }

    /// Sum BRDF * cosine * incident colour/intensity for independently visible lights.
    /// `visible` returns true for an unobstructed shadow ray; its errors propagate.
    /// No ambient term, exposure, tone map, display encoding or indirect bounce occurs here.
    pub fn shade_linear(
        &self,
        surface: OpaqueSurface,
        normal: Vec3,
        view: Vec3,
        mut visible: impl FnMut(usize, Vec3) -> Result<bool>,
    ) -> Result<Vec3> {
        let n = unit_direction(normal).map_err(|_| TraceError::InvalidInput("finite nonzero shading normal required"))?;
        let v = unit_direction(view).map_err(|_| TraceError::InvalidInput("finite nonzero shading view required"))?;
        let mut sum = Vec3::ZERO;
        if n.dot(v) <= 0.0 {
            return Ok(sum);
        }
        for (index, light) in self.lights.iter().enumerate() {
            let cosine = n.dot(light.direction).max(0.0);
            if cosine == 0.0 || light.intensity == 0.0 || light.color == Vec3::ZERO || !visible(index, light.direction)? {
                continue;
            }
            let brdf = surface.brdf(n, v, light.direction).map_err(|_| TraceError::InvalidInput("invalid opaque surface lighting directions"))?;
            let weight = light.intensity * cosine;
            sum += Vec3::new(brdf.x * light.color.x, brdf.y * light.color.y, brdf.z * light.color.z) * weight;
            validate_radiance(sum)?;
        }
        Ok(sum)
    }
}

fn channels(v: Vec3) -> [f64; 3] {
    [v.x, v.y, v.z]
}

pub(super) fn validate_radiance(radiance: Vec3) -> Result<()> {
    if !radiance.is_finite() || !channels(radiance).into_iter().all(|c| (0.0..=MAX_LINEAR_RADIANCE).contains(&c)) {
        return Err(TraceError::InvalidInput("RT2 linear radiance must be finite and in [0, 1e12]"));
    }
    Ok(())
}

/// The output boundary applies exposure once, then Reinhard once. The returned value
/// is still linear sRGB: the image consumer must encode sRGB exactly once afterwards.
/// Call this once after summing all direct lighting, never once per light.
pub fn map_to_display(radiance: Vec3, exposure_ev: f64) -> Result<Vec3> {
    validate_radiance(radiance)?;
    if !exposure_ev.is_finite() || !(-MAX_EXPOSURE_EV..=MAX_EXPOSURE_EV).contains(&exposure_ev) {
        return Err(TraceError::InvalidInput("RT2 exposure must be finite and in [-16, 16] EV"));
    }
    crate::studio::tone_map(radiance * exposure_ev.exp2()).map_err(|_| TraceError::InvalidInput("invalid exposed radiance"))
}

#[cfg(test)]
#[path = "lighting_tests.rs"]
mod tests;