use crate::math::ToneMapping;
use crate::math::Vector3;
use super::settings::{Aov, RaytraceSettings};
const LUM_R: f64 = 0.2126;
const LUM_G: f64 = 0.7152;
const LUM_B: f64 = 0.0722;
#[inline]
pub(crate) fn luminance_sample(radiance: Vector3) -> f32 {
0.2126 * radiance.x + 0.7152 * radiance.y + 0.0722 * radiance.z
}
#[inline]
pub(crate) fn pixel_mean_luminance(p: &Pixel) -> f64 {
if p.samples == 0 {
return 0.0;
}
let inv = 1.0 / p.samples as f64;
LUM_R * p.color[0] as f64 * inv
+ LUM_G * p.color[1] as f64 * inv
+ LUM_B * p.color[2] as f64 * inv
}
#[inline]
pub(crate) fn pixel_mean_variance(p: &Pixel) -> f32 {
if p.samples < 2 {
return f32::INFINITY;
}
let n = p.samples as f64;
let m2 = p.lum_sq as f64;
if !m2.is_finite() {
return f32::INFINITY;
}
let var = (m2.max(0.0) / (n * n)) as f32;
if !var.is_finite() {
return f32::INFINITY;
}
var
}
#[inline]
pub(crate) fn sum_sq_from_m2(p: &Pixel) -> f32 {
if p.samples == 0 {
return 0.0;
}
let n = p.samples as f64;
let mean = pixel_mean_luminance(p);
let sum_sq = p.lum_sq as f64 + n * mean * mean;
if !sum_sq.is_finite() {
return f32::INFINITY;
}
sum_sq.max(0.0) as f32
}
#[inline]
pub(crate) fn m2_from_sum_sq(color: [f32; 3], samples: u32, sum_sq: f32) -> f32 {
if samples == 0 {
return 0.0;
}
if !sum_sq.is_finite() {
return f32::INFINITY;
}
let n = samples as f64;
let mean =
LUM_R * color[0] as f64 / n + LUM_G * color[1] as f64 / n + LUM_B * color[2] as f64 / n;
let m2 = sum_sq as f64 - n * mean * mean;
if !m2.is_finite() {
return f32::INFINITY;
}
m2.max(0.0) as f32
}
#[derive(Debug, Clone, Copy, Default, PartialEq)]
pub struct Pixel {
pub color: [f32; 3],
pub alpha: f32,
pub albedo: [f32; 3],
pub normal: [f32; 3],
pub depth: f32,
pub depth_samples: u32,
pub samples: u32,
pub lum_sq: f32,
}
impl Pixel {
#[inline]
pub fn add(&mut self, radiance: Vector3, alpha: f32) {
let lum = luminance_sample(radiance);
let n_old = self.samples as f32;
let n_new = n_old + 1.0;
let mean_old = if self.samples == 0 {
0.0
} else {
pixel_mean_luminance(self) as f32
};
let mut delta = lum - mean_old;
if self.samples >= 2 {
let m2 = self.lum_sq.max(0.0);
let std_sample = if m2 > 0.0 {
(m2 / (n_old - 1.0).max(1.0)).sqrt()
} else {
0.0
};
let cap = if std_sample > 1e-6 {
(std_sample * 4.0).max(mean_old.abs() * 0.25 + 1e-4)
} else {
mean_old.abs().max(1e-3) * 8.0 + 1e-3
};
if cap.is_finite() && delta.abs() > cap {
delta = delta.clamp(-cap, cap);
}
}
let lum_eff = mean_old + delta;
let mean_new = mean_old + delta / n_new;
self.lum_sq += delta * (lum_eff - mean_new);
self.color[0] += radiance.x;
self.color[1] += radiance.y;
self.color[2] += radiance.z;
self.alpha += alpha;
self.samples += 1;
}
#[inline]
pub fn merge_pixel(&mut self, other: &Pixel) {
if other.samples == 0 {
return;
}
if self.samples == 0 {
*self = *other;
return;
}
let n_a = self.samples as f64;
let n_b = other.samples as f64;
let n = n_a + n_b;
let mean_a = pixel_mean_luminance(self);
let mean_b = pixel_mean_luminance(other);
let delta = mean_b - mean_a;
let m2 = self.lum_sq as f64 + other.lum_sq as f64 + delta * delta * n_a * n_b / n;
for c in 0..3 {
self.color[c] += other.color[c];
self.albedo[c] += other.albedo[c];
self.normal[c] += other.normal[c];
}
self.alpha += other.alpha;
self.depth += other.depth;
self.depth_samples += other.depth_samples;
self.samples += other.samples;
self.lum_sq = if m2.is_finite() {
m2.max(0.0) as f32
} else {
f32::INFINITY
};
}
#[inline]
pub fn relative_error(&self) -> f32 {
let var = pixel_mean_variance(self);
if var.is_infinite() {
return f32::INFINITY;
}
if var <= 0.0 {
return 0.0;
}
let mean = pixel_mean_luminance(self).abs().max(1e-3) as f32;
var.sqrt() / mean
}
#[inline]
pub fn is_converged(&self, threshold: f32, min_samples: u32) -> bool {
threshold > 0.0 && self.samples >= min_samples.max(2) && self.relative_error() < threshold
}
#[inline]
pub fn add_aux(&mut self, albedo: Vector3, normal: Vector3, depth: f32) {
self.albedo[0] += albedo.x;
self.albedo[1] += albedo.y;
self.albedo[2] += albedo.z;
self.normal[0] += normal.x;
self.normal[1] += normal.y;
self.normal[2] += normal.z;
if depth.is_finite() {
self.depth += depth;
self.depth_samples += 1;
}
}
}
#[derive(Debug, Clone)]
pub struct Film {
width: u32,
height: u32,
pixels: Vec<Pixel>,
samples: u32,
}
impl Film {
pub fn new(width: u32, height: u32) -> Self {
let (width, height) = (width.max(1), height.max(1));
Self {
width,
height,
pixels: vec![Pixel::default(); (width as usize) * (height as usize)],
samples: 0,
}
}
pub fn width(&self) -> u32 {
self.width
}
pub fn height(&self) -> u32 {
self.height
}
pub fn samples(&self) -> u32 {
self.samples
}
pub fn clear(&mut self) {
self.pixels.fill(Pixel::default());
self.samples = 0;
}
pub fn advance(&mut self, n: u32) {
self.samples += n;
}
pub fn set_samples(&mut self, samples: u32) {
self.samples = samples;
}
pub fn converged_fraction(&self, threshold: f32, min_samples: u32) -> f32 {
if threshold <= 0.0 || self.pixels.is_empty() {
return 0.0;
}
let converged = self
.pixels
.iter()
.filter(|p| p.is_converged(threshold, min_samples))
.count();
converged as f32 / self.pixels.len() as f32
}
pub fn rows_mut(&mut self) -> impl Iterator<Item = (usize, &mut [Pixel])> {
let w = self.width as usize;
self.pixels.chunks_mut(w).enumerate()
}
pub fn pixels(&self) -> &[Pixel] {
&self.pixels
}
pub fn pixels_mut(&mut self) -> &mut [Pixel] {
&mut self.pixels
}
pub fn merge(&mut self, other: &Film) {
if other.width != self.width || other.height != self.height {
return;
}
for (a, b) in self.pixels.iter_mut().zip(other.pixels.iter()) {
a.merge_pixel(b);
}
self.samples += other.samples;
}
pub fn resolve_hdr(&self) -> Vec<f32> {
let mut out = Vec::with_capacity(self.pixels.len() * 4);
for p in &self.pixels {
let inv = inv_samples(p);
out.push(p.color[0] * inv);
out.push(p.color[1] * inv);
out.push(p.color[2] * inv);
out.push((p.alpha * inv).clamp(0.0, 1.0));
}
out
}
pub fn resolve_variance(&self) -> Vec<f32> {
self.pixels.iter().map(pixel_mean_variance).collect()
}
pub fn resolve_error(&self) -> Vec<f32> {
self.pixels.iter().map(|p| p.relative_error()).collect()
}
pub fn resolve_sample_counts(&self) -> Vec<u32> {
self.pixels.iter().map(|p| p.samples).collect()
}
pub fn sample_range(&self) -> (u32, u32) {
self.pixels.iter().fold((u32::MAX, 0), |(lo, hi), p| {
(lo.min(p.samples), hi.max(p.samples))
})
}
pub fn resolve_albedo(&self) -> Vec<[f32; 3]> {
self.pixels
.iter()
.map(|p| {
let inv = inv_samples(p);
[p.albedo[0] * inv, p.albedo[1] * inv, p.albedo[2] * inv]
})
.collect()
}
pub fn resolve_normal(&self) -> Vec<[f32; 3]> {
let mut out = Vec::with_capacity(self.pixels.len());
for p in &self.pixels {
let inv = if p.samples > 0 {
1.0 / p.samples as f32
} else {
1.0
};
let v = Vector3::new(p.normal[0] * inv, p.normal[1] * inv, p.normal[2] * inv);
let v = if v.length_sq() > 1e-12 {
v.normalize()
} else {
Vector3::ZERO
};
out.push([v.x, v.y, v.z]);
}
out
}
pub fn resolve_depth(&self) -> Vec<f32> {
self.pixels
.iter()
.map(|p| {
if p.depth_samples == 0 {
f32::INFINITY
} else {
p.depth / p.depth_samples as f32
}
})
.collect()
}
pub fn resolve_rgba8(&self, settings: &RaytraceSettings) -> Vec<u8> {
match settings.aov {
Aov::Beauty => self.beauty_rgba8(&self.resolve_hdr(), settings),
Aov::Albedo => {
let a = self.resolve_albedo();
let mut out = Vec::with_capacity(a.len() * 4);
for c in a {
out.extend_from_slice(&[
encode_srgb(c[0]),
encode_srgb(c[1]),
encode_srgb(c[2]),
255,
]);
}
out
}
Aov::Normal => {
let n = self.resolve_normal();
let mut out = Vec::with_capacity(n.len() * 4);
for v in n {
let enc = |x: f32| ((x * 0.5 + 0.5).clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
out.extend_from_slice(&[enc(v[0]), enc(v[1]), enc(v[2]), 255]);
}
out
}
Aov::Depth => {
let d = self.resolve_depth();
let (near, far) = d
.iter()
.filter(|v| v.is_finite())
.fold((f32::INFINITY, 0.0f32), |(lo, hi), &v| {
(lo.min(v), hi.max(v))
});
let span = (far - near).max(1e-6);
let mut out = Vec::with_capacity(d.len() * 4);
for v in d {
let t = if v.is_finite() {
1.0 - ((v - near) / span).clamp(0.0, 1.0)
} else {
0.0
};
let b = (t * 255.0 + 0.5) as u8;
out.extend_from_slice(&[b, b, b, 255]);
}
out
}
}
}
pub fn beauty_rgba8(&self, hdr: &[f32], settings: &RaytraceSettings) -> Vec<u8> {
let mut out = Vec::with_capacity(self.pixels.len() * 4);
for px in hdr.as_chunks::<4>().0 {
let c = tone_map(
Vector3::new(px[0], px[1], px[2]) * settings.exposure,
settings.tone_mapping,
);
out.extend_from_slice(&[
encode_srgb(c.x),
encode_srgb(c.y),
encode_srgb(c.z),
(px[3].clamp(0.0, 1.0) * 255.0 + 0.5) as u8,
]);
}
out
}
}
#[inline]
fn inv_samples(p: &Pixel) -> f32 {
if p.samples == 0 {
0.0
} else {
1.0 / p.samples as f32
}
}
pub fn tone_map(c: Vector3, mode: ToneMapping) -> Vector3 {
match mode {
ToneMapping::None | ToneMapping::Linear => Vector3::new(
c.x.clamp(0.0, 1.0),
c.y.clamp(0.0, 1.0),
c.z.clamp(0.0, 1.0),
),
_ => {
let v = mode.apply([c.x, c.y, c.z]);
Vector3::new(v[0], v[1], v[2])
}
}
}
pub fn encode_srgb(v: f32) -> u8 {
let v = v.clamp(0.0, 1.0);
let s = if v <= 0.0031308 {
v * 12.92
} else {
1.055 * v.powf(1.0 / 2.4) - 0.055
};
(s * 255.0 + 0.5) as u8
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn variance_is_infinite_when_unknown_and_never_nan() {
let mut film = Film::new(2, 2);
for v in film.resolve_variance() {
assert!(v.is_infinite() && v > 0.0, "empty film gave {v}");
}
film.pixels_mut()[0].add(Vector3::new(1e30, 1e30, 1e30), 1.0);
film.pixels_mut()[0].add(Vector3::ZERO, 1.0);
for v in film.resolve_variance() {
assert!(!v.is_nan(), "variance was NaN");
}
}
#[test]
fn variance_stays_stable_at_high_dynamic_range() {
let mut film = Film::new(1, 1);
let p = film.pixels_mut();
for _ in 0..99 {
p[0].add(Vector3::new(1000.0, 1000.0, 1000.0), 1.0);
}
p[0].add(Vector3::new(1010.0, 1010.0, 1010.0), 1.0);
let v = film.resolve_variance()[0];
assert!(v.is_finite() && v > 0.0, "variance collapsed to {v}");
assert!(film.pixels()[0].relative_error().is_finite());
}
#[test]
fn fireflies_do_not_inflate_variance() {
let mut film = Film::new(1, 1);
for _ in 0..32 {
film.pixels_mut()[0].add(Vector3::new(1.0, 1.0, 1.0), 1.0);
}
film.pixels_mut()[0].add(Vector3::new(1e4, 1e4, 1e4), 1.0);
let v = film.resolve_variance()[0];
assert!(v.is_finite() && v < 0.5, "firefly inflated variance to {v}");
}
#[test]
fn firefly_does_not_block_adaptive_convergence() {
let mut p = Pixel::default();
for _ in 0..64 {
p.add(Vector3::new(1.0, 1.0, 1.0), 1.0);
}
assert!(
p.is_converged(0.02, 16),
"quiet pixel not converged: err={}",
p.relative_error()
);
p.add(Vector3::new(1e5, 1e5, 1e5), 1.0);
assert!(
p.is_converged(0.05, 16),
"firefly kept pixel open: err={}",
p.relative_error()
);
}
#[test]
fn high_variance_still_blocks_convergence() {
let mut p = Pixel::default();
for i in 0..32u32 {
let v = if i % 2 == 0 { 0.2 } else { 2.0 };
p.add(Vector3::new(v, v, v), 1.0);
}
assert!(
!p.is_converged(0.02, 8),
"bimodal pixel converged early: err={}",
p.relative_error()
);
}
#[test]
fn welford_matches_second_moment_on_mild_data() {
let mut film = Film::new(1, 1);
for i in 0..16u32 {
let v = 0.5 + (i as f32) * 0.01;
film.pixels_mut()[0].add(Vector3::new(v, v, v), 1.0);
}
let p = &film.pixels()[0];
let sum_sq = sum_sq_from_m2(p);
let n = p.samples as f64;
let mean = pixel_mean_luminance(p);
let classic = ((sum_sq as f64 / n - mean * mean).max(0.0) / n) as f32;
let welford = pixel_mean_variance(p);
assert!(
(classic - welford).abs() < 1e-5,
"classic {classic} vs welford {welford}"
);
let round = m2_from_sum_sq(p.color, p.samples, sum_sq);
assert!((round - p.lum_sq).abs() < 1e-4);
}
#[test]
fn merge_combines_welford_m2() {
let mut a = Film::new(1, 1);
let mut b = Film::new(1, 1);
for _ in 0..8 {
a.pixels_mut()[0].add(Vector3::new(1.0, 1.0, 1.0), 1.0);
b.pixels_mut()[0].add(Vector3::new(2.0, 2.0, 2.0), 1.0);
}
a.advance(8);
b.advance(8);
let mut both = Film::new(1, 1);
for _ in 0..8 {
both.pixels_mut()[0].add(Vector3::new(1.0, 1.0, 1.0), 1.0);
}
for _ in 0..8 {
both.pixels_mut()[0].add(Vector3::new(2.0, 2.0, 2.0), 1.0);
}
a.merge(&b);
let va = a.resolve_variance()[0];
let vb = both.resolve_variance()[0];
assert!((va - vb).abs() < 1e-5, "merged {va} vs sequential {vb}");
}
#[test]
fn accumulation_averages() {
let mut film = Film::new(2, 2);
for i in 0..4u32 {
for p in film.pixels_mut() {
p.add(Vector3::new(i as f32, 0.0, 0.0), 1.0);
}
film.advance(1);
}
let hdr = film.resolve_hdr();
assert!((hdr[0] - 1.5).abs() < 1e-6, "{}", hdr[0]);
assert!((hdr[3] - 1.0).abs() < 1e-6);
assert_eq!(film.samples(), 4);
}
#[test]
fn an_empty_film_resolves_to_black_rather_than_nan() {
let film = Film::new(3, 3);
let hdr = film.resolve_hdr();
assert!(hdr.iter().all(|v| v.is_finite() && *v == 0.0));
let rgba = film.resolve_rgba8(&RaytraceSettings::default());
assert_eq!(rgba.len(), 9 * 4);
}
#[test]
fn clear_resets_everything() {
let mut film = Film::new(2, 1);
film.pixels_mut()[0].add(Vector3::new(5.0, 5.0, 5.0), 1.0);
film.advance(1);
film.clear();
assert_eq!(film.samples(), 0);
assert_eq!(film.resolve_hdr()[0], 0.0);
}
#[test]
fn merge_sums_two_partial_renders() {
let mut a = Film::new(2, 1);
let mut b = Film::new(2, 1);
for p in a.pixels_mut() {
p.add(Vector3::new(1.0, 0.0, 0.0), 1.0);
}
a.advance(1);
for p in b.pixels_mut() {
p.add(Vector3::new(3.0, 0.0, 0.0), 1.0);
}
b.advance(1);
a.merge(&b);
assert_eq!(a.samples(), 2);
assert!((a.resolve_hdr()[0] - 2.0).abs() < 1e-6);
}
#[test]
fn merge_rejects_a_mismatched_film() {
let mut a = Film::new(2, 2);
let b = Film::new(4, 4);
a.merge(&b);
assert_eq!(a.samples(), 0);
}
#[test]
fn rows_are_disjoint_and_cover_the_film() {
let mut film = Film::new(5, 3);
let mut count = 0;
for (y, row) in film.rows_mut() {
assert_eq!(row.len(), 5);
assert!(y < 3);
count += row.len();
}
assert_eq!(count, 15);
}
#[test]
fn srgb_encoding_hits_the_known_anchors() {
assert_eq!(encode_srgb(0.0), 0);
assert_eq!(encode_srgb(1.0), 255);
assert_eq!(encode_srgb(0.5), 188);
assert_eq!(encode_srgb(-1.0), 0);
assert_eq!(encode_srgb(50.0), 255);
}
#[test]
fn aces_rolls_off_instead_of_clipping() {
let a = tone_map(Vector3::new(1.0, 1.0, 1.0), ToneMapping::AcesFilmic);
let b = tone_map(Vector3::new(3.0, 3.0, 3.0), ToneMapping::AcesFilmic);
assert!(a.x < 0.9, "{a:?}");
assert!(b.x < 1.0 && b.x > a.x, "{a:?} -> {b:?}");
let c = tone_map(Vector3::new(8.0, 8.0, 8.0), ToneMapping::None);
assert_eq!(c.x, 1.0);
}
#[test]
fn normals_are_renormalised_on_resolve() {
let mut film = Film::new(1, 1);
for _ in 0..4 {
film.pixels_mut()[0].add_aux(
Vector3::new(0.5, 0.5, 0.5),
Vector3::new(0.0, 0.0, 1.0),
2.0,
);
film.advance(1);
}
let n = film.resolve_normal();
assert!((n[0][2] - 1.0).abs() < 1e-6, "{:?}", n[0]);
let d = film.resolve_depth();
assert!((d[0] - 2.0).abs() < 1e-6);
}
#[test]
fn pixels_that_never_hit_report_infinite_depth() {
let mut film = Film::new(1, 1);
film.pixels_mut()[0].add_aux(Vector3::ZERO, Vector3::ZERO, f32::INFINITY);
film.advance(1);
assert!(film.resolve_depth()[0].is_infinite());
let s = RaytraceSettings {
aov: Aov::Depth,
..Default::default()
};
let rgba = film.resolve_rgba8(&s);
assert_eq!(&rgba[..3], &[0, 0, 0]);
}
}