SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Original bounded specular sampling. All values are linear-light quantities.
use super::{Result, TraceError};
use crate::anisotropic_surface::{AnisotropicSurface, VisualFrame};
use crate::surface::{OpaqueSurface, unit_direction};
use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;
#[cfg(test)]
use std::f64::consts::{PI, TAU};
#[derive(Clone, Copy, Debug)]
pub struct ReflectionSample {
pub direction: Vec3,
pub weight: Vec3,
pub pdf: f64,
}
fn fresnel(surface: OpaqueSurface, cosine: f64) -> Vec3 {
surface.specular_fresnel(cosine)
}
pub fn mirror(surface: OpaqueSurface, normal: Vec3, view: Vec3) -> Result<Option<ReflectionSample>> {
let n = unit_direction(normal).map_err(|_| TraceError::InvalidInput("mirror normal"))?;
let v = unit_direction(view).map_err(|_| TraceError::InvalidInput("mirror view"))?;
let nv = n.dot(v);
if nv <= 0.0 {
return Ok(None);
}
Ok(Some(ReflectionSample { direction: n * (2.0 * nv) - v, weight: fresnel(surface, nv), pdf: 1.0 }))
}
/// Matched visible-GGX proposal. The BSDF remains separable Smith/Schlick;
/// p(l)=D(h)*G1(v)/(4*n.v), weight=F(v.h)*G1(l). Nulls still count in R.
pub fn rough_specular(surface: OpaqueSurface, normal: Vec3, view: Vec3, u: [f64; 2]) -> Result<Option<ReflectionSample>> {
let n = unit_direction(normal).map_err(|_| TraceError::InvalidInput("GGX normal"))?;
let axis = if n.z.abs() < 0.9 { Vec3::Z } else { Vec3::X };
let frame = VisualFrame::new(n, axis.cross(n)).map_err(|_| TraceError::InvalidInput("GGX visible frame"))?;
let matched = AnisotropicSurface::from_isotropic_optical(surface);
matched
.sample_visible_reflection(frame, n, view, u)
.map(|s| s.map(|s| ReflectionSample { direction: s.direction, weight: s.weight, pdf: s.pdf }))
.map_err(|_| TraceError::InvalidInput("GGX visible sample"))
}
/// Previous NDF estimator retained only as an explicit test control.
#[cfg(test)]
fn rough_specular_ndf(surface: OpaqueSurface, normal: Vec3, view: Vec3, u: [f64; 2]) -> Result<Option<ReflectionSample>> {
if !u.into_iter().all(|v| v.is_finite() && (0.0..1.0).contains(&v)) {
return Err(TraceError::InvalidInput("GGX variates outside [0,1)"));
}
let n = unit_direction(normal).map_err(|_| TraceError::InvalidInput("GGX normal"))?;
let v = unit_direction(view).map_err(|_| TraceError::InvalidInput("GGX view"))?;
let nv = n.dot(v);
if nv <= 0.0 {
return Ok(None);
}
let alpha = surface.roughness().powi(2);
let a2 = alpha * alpha;
let cos = ((1.0 - u[0]) / (1.0 + (a2 - 1.0) * u[0])).sqrt();
let sin = (1.0 - cos * cos).max(0.0).sqrt();
let phi = TAU * u[1];
let axis = if n.z.abs() < 0.9 { Vec3::Z } else { Vec3::X };
let tangent = unit_direction(axis.cross(n)).map_err(|_| TraceError::InvalidInput("GGX tangent"))?;
let bitangent = n.cross(tangent);
let h = unit_direction(tangent * (sin * phi.cos()) + bitangent * (sin * phi.sin()) + n * cos)
.map_err(|_| TraceError::InvalidInput("GGX half vector"))?;
let vh = v.dot(h);
if vh <= 0.0 {
return Ok(None);
}
let direction = h * (2.0 * vh) - v;
let nl = n.dot(direction);
if nl <= 0.0 {
return Ok(None);
}
let nh = n.dot(h).clamp(0.0, 1.0);
let denominator = (1.0 - nh * nh) + nh * nh * a2;
let distribution = a2 / (PI * denominator * denominator);
let pdf = distribution * nh / (4.0 * vh);
let visibility = |c: f64| 2.0 / (c + (a2 + (1.0 - a2) * c * c).sqrt());
let specular = distribution * 0.25 * visibility(nv) * visibility(nl);
let weight = fresnel(surface, vh) * (specular * nl / pdf);
if !pdf.is_finite() || pdf <= 0.0 || !weight.is_finite() {
return Err(TraceError::InvalidInput("nonfinite GGX sample"));
}
Ok(Some(ReflectionSample { direction, weight, pdf }))
}
/// Bounded stratified reflection sequence, keyed by captured pixel/bounce identity.
/// The first coordinate visits each of R radial strata exactly once. The second
/// uses a digitally shifted base-two radical inverse: exact dyadic coverage only
/// for power-of-two R. This is not a progressive prefix or a variance guarantee.
/// Callers supply their matched BSDF/PDF; this function only supplies variates.
/// Null-event accounting, R-attempt and bounce bounds are unchanged.
/// Actual outgoing paths, null samples and work can differ with the directions.
pub fn variates(pixel: u64, sample: u64, bounce: u64, samples: u64) -> Result<[f64; 2]> {
if !(1..=64).contains(&samples) || sample >= samples {
return Err(TraceError::InvalidInput("reflection sample ordinal/count outside 1..64 strata"));
}
fn mix(mut x: u64) -> u64 {
x ^= x >> 30;
x = x.wrapping_mul(0xbf58476d1ce4e5b9);
x ^= x >> 27;
x = x.wrapping_mul(0x94d049bb133111eb);
x ^ (x >> 31)
}
let key = pixel.wrapping_mul(0x9e3779b97f4a7c15) ^ bounce.wrapping_mul(0x632be59bd9b4e019);
// A 32-bit midpoint jitter stays at least 2^-33 from either radial-cell
// edge. Even adding ordinal63 and dividing by64 cannot round to an edge.
let radial_jitter = ((mix(key) >> 32) as f64 + 0.5) / (1u64 << 32) as f64;
let radial = (sample as f64 + radial_jitter) / samples as f64;
let azimuth_bits = (sample.reverse_bits() >> 12) ^ (mix(key ^ 0xa0761d6478bd642f) >> 12);
let azimuth = (azimuth_bits as f64 + 0.5) / (1u64 << 52) as f64;
Ok([radial, azimuth])
}
// Preserve the original hashed sequence as a test-only comparison control.
#[cfg(test)]
fn hash_variates(pixel: u64, sample: u64, bounce: u64) -> [f64; 2] {
fn mix(mut x: u64) -> u64 {
x ^= x >> 30;
x = x.wrapping_mul(0xbf58476d1ce4e5b9);
x ^= x >> 27;
x = x.wrapping_mul(0x94d049bb133111eb);
x ^ (x >> 31)
}
let key = pixel.wrapping_mul(0x9e3779b97f4a7c15) ^ sample.wrapping_mul(0xd1b54a32d192ed03) ^ bounce.wrapping_mul(0x632be59bd9b4e019);
let value = |x: u64| ((mix(x) >> 12) as f64 + 0.5) / (1u64 << 52) as f64;
[value(key), value(key ^ 0xa0761d6478bd642f)]
}
#[cfg(test)]
#[path = "reflection_stratified_tests.rs"]
mod stratified_tests;
#[cfg(test)]
#[path = "reflection_vndf_tests.rs"]
mod vndf_tests;
#[cfg(test)]
mod tests {
use super::{OpaqueSurface, PI, Vec3, hash_variates as variates, mirror, rough_specular};
use solidcraft_geom::prelude::*;
fn white() -> OpaqueSurface {
OpaqueSurface::new(Vec3::new(1.0, 1.0, 1.0), 1.0, 1.0, 1.5).unwrap()
}
#[test]
fn mirror_is_explicit_delta_with_normal_fresnel_and_reflection_law() {
let surface = OpaqueSurface::new(Vec3::new(0.8, 0.5, 0.2), 0.0, 0.045, 1.5).unwrap();
let sample = mirror(surface, Vec3::Z, Vec3::Z).unwrap().unwrap();
assert_eq!(sample.direction, Vec3::Z);
assert!((sample.weight.x - 0.04).abs() < 1e-14);
let view = Vec3::new(0.6, 0.0, 0.8);
let sample = mirror(surface, Vec3::Z, view).unwrap().unwrap();
assert!((sample.direction - Vec3::new(-0.6, 0.0, 0.8)).len() < 1e-14);
assert!(rough_specular(surface, Vec3::Z, view, [0.4, 0.1]).unwrap().is_some());
}
#[test]
fn fully_rough_conductor_has_analytic_pdf_weight_and_null_probability() {
let sample = rough_specular(white(), Vec3::Z, Vec3::Z, [0.25, 0.2]).unwrap().unwrap();
assert!((sample.direction.z - 0.5).abs() < 1e-14);
assert!((sample.pdf - 1.0 / (4.0 * PI)).abs() < 1e-14);
assert!((sample.weight.x - 2.0 / 3.0).abs() < 1e-14);
assert!(rough_specular(white(), Vec3::Z, Vec3::Z, [0.75, 0.2]).unwrap().is_none());
let mut reflectance = 0.0;
for i in 0..4096 {
reflectance += rough_specular(white(), Vec3::Z, Vec3::Z, [(i as f64 + 0.5) / 4096.0, 0.3]).unwrap().map_or(0.0, |s| s.weight.x);
}
// Independent exact hemispherical integral for alpha=1, F=1, normal view.
assert!((reflectance / 4096.0 - (1.0 - 2.0_f64.ln())).abs() < 1e-6);
}
#[test]
fn invalid_variates_directions_and_deterministic_open_samples() {
for bad in [f64::NAN, f64::INFINITY, -0.1, 1.0] {
assert!(rough_specular(white(), Vec3::Z, Vec3::Z, [bad, 0.2]).is_err());
}
assert!(mirror(white(), Vec3::ZERO, Vec3::Z).is_err());
for pixel in 0..100 {
let u = variates(pixel, 17, 4);
assert_eq!(u, variates(pixel, 17, 4));
assert!(u.into_iter().all(|v| v > 0.0 && v < 1.0));
}
}
}