Files
texturecraft/crates/render/src/ibl.rs
bflatastic 963008635c display.set: refuse unknown environment names
The built-in environment list moves to core (render re-exports it), so
the engine can name the valid ones in the error.

Fixes #65.
2026-11-02 05:34:40 +07:00

354 lines
15 KiB
Rust
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Image-based lighting, computed on the CPU: procedural HDR environments (no image assets),
//! a GGX-prefiltered mip chain for specular, and 9 spherical-harmonics coefficients for
//! diffuse.
//!
//! Equirect convention: `u = φ / 2π`, `v = θ / π`, direction
//! `(sin θ cos φ, cos θ, sin θ sin φ)`; row 0 is straight up.
use std::f32::consts::{PI, TAU};
use rayon::prelude::*;
use texturecraft_geom::glam::{Vec2, Vec3};
/// An equirect HDR image (linear RGB).
#[derive(Clone, Debug)]
pub struct EnvImage {
pub width: u32,
pub height: u32,
pub data: Vec<[f32; 3]>,
}
pub use texturecraft_core::project::ENVIRONMENTS;
pub fn dir_of(u: f32, v: f32) -> Vec3 {
let (theta, phi) = (v * PI, u * TAU);
Vec3::new(theta.sin() * phi.cos(), theta.cos(), theta.sin() * phi.sin())
}
pub fn uv_of(d: Vec3) -> Vec2 {
let phi = d.z.atan2(d.x);
Vec2::new((phi / TAU).rem_euclid(1.0), d.y.clamp(-1.0, 1.0).acos() / PI)
}
/// A soft rectangular light: azimuth/elevation center (degrees), half sizes (degrees).
struct SoftBox {
az: f32,
el: f32,
hw: f32,
hh: f32,
color: Vec3,
}
impl SoftBox {
fn eval(&self, d: Vec3) -> Vec3 {
let el = d.y.clamp(-1.0, 1.0).asin().to_degrees();
let az = d.z.atan2(d.x).to_degrees();
let daz = ((az - self.az + 540.0).rem_euclid(360.0)) - 180.0;
let (x, y) = (daz.abs() / self.hw, (el - self.el).abs() / self.hh);
let e = |t: f32| 1.0 - smooth((t - 0.8) / 0.4);
self.color * e(x) * e(y)
}
}
fn smooth(t: f32) -> f32 {
let t = t.clamp(0.0, 1.0);
t * t * (3.0 - 2.0 * t)
}
fn sky(d: Vec3, zenith: Vec3, horizon: Vec3, ground: Vec3) -> Vec3 {
if d.y >= 0.0 { horizon.lerp(zenith, d.y.powf(0.6)) } else { horizon.lerp(ground, (-d.y).powf(0.25)) }
}
fn radiance(name: &str, d: Vec3) -> Vec3 {
match name {
"Studio Contrast" => {
let base = sky(d, Vec3::splat(0.04), Vec3::splat(0.03), Vec3::splat(0.01));
base + SoftBox { az: 35.0, el: 30.0, hw: 22.0, hh: 18.0, color: Vec3::new(14.0, 13.2, 12.0) }.eval(d)
+ SoftBox { az: -150.0, el: 40.0, hw: 6.0, hh: 30.0, color: Vec3::new(4.0, 4.4, 5.0) }.eval(d)
}
"Overcast" => {
let base = sky(d, Vec3::new(1.2, 1.25, 1.35), Vec3::new(0.95, 0.95, 0.95), Vec3::new(0.18, 0.2, 0.15));
base + SoftBox { az: 60.0, el: 55.0, hw: 40.0, hh: 25.0, color: Vec3::splat(0.6) }.eval(d)
}
"Sunset" => {
let base = sky(d, Vec3::new(0.15, 0.25, 0.55), Vec3::new(1.4, 0.65, 0.3), Vec3::new(0.08, 0.06, 0.05));
let sun_dir = dir_of(0.12, 0.47);
let sun = smooth((d.dot(sun_dir) - 0.9985) / 0.0012) * 120.0;
base + Vec3::new(1.0, 0.6, 0.3) * sun
}
"Warehouse" => {
let mut c = sky(d, Vec3::splat(0.25), Vec3::splat(0.18), Vec3::splat(0.06));
for k in 0..6 {
c += SoftBox { az: -150.0 + k as f32 * 60.0, el: 50.0, hw: 6.0, hh: 3.0, color: Vec3::new(9.0, 8.5, 7.5) }.eval(d);
}
c + SoftBox { az: 90.0, el: 5.0, hw: 30.0, hh: 12.0, color: Vec3::new(1.6, 1.8, 2.2) }.eval(d)
}
"Night" => {
let base = sky(d, Vec3::new(0.01, 0.015, 0.04), Vec3::new(0.03, 0.03, 0.06), Vec3::splat(0.005));
base + SoftBox { az: 20.0, el: 15.0, hw: 10.0, hh: 10.0, color: Vec3::new(0.4, 1.6, 4.0) }.eval(d)
+ SoftBox { az: -110.0, el: 10.0, hw: 12.0, hh: 8.0, color: Vec3::new(4.0, 0.8, 1.6) }.eval(d)
}
// "Studio Soft" (default)
_ => {
let base = sky(d, Vec3::new(0.5, 0.52, 0.56), Vec3::new(0.32, 0.32, 0.33), Vec3::new(0.08, 0.075, 0.07));
base + SoftBox { az: 40.0, el: 35.0, hw: 28.0, hh: 20.0, color: Vec3::new(5.5, 5.2, 4.8) }.eval(d)
+ SoftBox { az: -125.0, el: 20.0, hw: 35.0, hh: 22.0, color: Vec3::new(1.1, 1.25, 1.5) }.eval(d)
+ SoftBox { az: 175.0, el: 55.0, hw: 8.0, hh: 25.0, color: Vec3::new(3.0, 3.0, 3.0) }.eval(d)
}
}
}
/// Render a built-in environment (unknown names give the default studio).
pub fn environment(name: &str, width: u32) -> EnvImage {
let w = width.clamp(16, 4096);
let h = w / 2;
let mut data = vec![[0.0f32; 3]; (w * h) as usize];
data.par_chunks_mut(w as usize).enumerate().for_each(|(y, row)| {
for (x, px) in row.iter_mut().enumerate() {
let d = dir_of((x as f32 + 0.5) / w as f32, (y as f32 + 0.5) / h as f32);
*px = radiance(name, d).to_array();
}
});
EnvImage { width: w, height: h, data }
}
impl EnvImage {
fn get(&self, x: i64, y: i64) -> Vec3 {
let xx = x.rem_euclid(self.width as i64) as u32;
let yy = y.clamp(0, self.height as i64 - 1) as u32;
self.data.get((yy * self.width + xx) as usize).map(|v| Vec3::from(*v)).unwrap_or(Vec3::ZERO)
}
/// Bilinear lookup by direction.
pub fn sample(&self, d: Vec3) -> Vec3 {
let uv = uv_of(d);
let (fx, fy) = (uv.x * self.width as f32 - 0.5, uv.y * self.height as f32 - 0.5);
let (x0, y0) = (fx.floor() as i64, fy.floor() as i64);
let (tx, ty) = (fx - x0 as f32, fy - y0 as f32);
let a = self.get(x0, y0).lerp(self.get(x0 + 1, y0), tx);
let b = self.get(x0, y0 + 1).lerp(self.get(x0 + 1, y0 + 1), tx);
a.lerp(b, ty)
}
/// Box-downsample by 2.
pub fn half(&self) -> EnvImage {
let (w, h) = ((self.width / 2).max(1), (self.height / 2).max(1));
let mut data = vec![[0.0f32; 3]; (w * h) as usize];
data.par_chunks_mut(w as usize).enumerate().for_each(|(y, row)| {
for (x, px) in row.iter_mut().enumerate() {
let (sx, sy) = (x as i64 * 2, y as i64 * 2);
let s = (self.get(sx, sy) + self.get(sx + 1, sy) + self.get(sx, sy + 1) + self.get(sx + 1, sy + 1)) * 0.25;
*px = s.to_array();
}
});
EnvImage { width: w, height: h, data }
}
/// An imported equirect image (`rgba` row-major, top row first, sRGB-encoded when `srgb`) as
/// linear radiance: non-finite and negative values become 0, values are capped to the f16
/// range, and images larger than [`MAX_IMPORT_WIDTH`] are box-downsampled. None when the
/// pixel count does not match the size.
pub fn from_rgba(width: u32, height: u32, rgba: &[[f32; 4]], srgb: bool) -> Option<EnvImage> {
if width == 0 || height == 0 || rgba.len() as u64 != width as u64 * height as u64 {
return None;
}
let lin = |v: f32| {
let v = if v.is_finite() { v.clamp(0.0, 65_000.0) } else { 0.0 };
if srgb { texturecraft_texel::srgb_to_linear(v.min(1.0)) } else { v }
};
let data = rgba.par_iter().map(|p| [lin(p[0]), lin(p[1]), lin(p[2])]).collect();
let mut img = EnvImage { width, height, data };
while img.width > MAX_IMPORT_WIDTH || img.height > MAX_IMPORT_WIDTH {
img = img.half();
}
// The mip chain needs at least 4×2 texels at its last level.
if img.width < 128 || img.height < 64 {
let (w, h) = (img.width.max(128), img.height.max(64));
let data = (0..w * h).map(|i| img.sample(dir_of(((i % w) as f32 + 0.5) / w as f32, ((i / w) as f32 + 0.5) / h as f32)).to_array()).collect();
img = EnvImage { width: w, height: h, data };
}
Some(img)
}
}
/// Widest imported environment kept (2K equirect: about 5.6 texels per degree).
pub const MAX_IMPORT_WIDTH: u32 = 2048;
fn hammersley(i: u32, n: u32) -> Vec2 {
Vec2::new(i as f32 / n as f32, i.reverse_bits() as f32 * 2.328_306_4e-10)
}
/// GGX-prefiltered mip chain: level `l` of `levels` is filtered for roughness `l / (levels-1)`.
pub fn prefilter(env: &EnvImage, levels: u32) -> Vec<EnvImage> {
let levels = levels.clamp(1, 8);
// Clamp fireflies, then build a box pyramid to sample from (filtered importance sampling).
let clamped = EnvImage { data: env.data.iter().map(|c| c.map(|v| v.min(64.0))).collect(), ..env.clone() };
let mut pyramid = vec![clamped];
while pyramid.len() < 10 && pyramid.last().is_some_and(|p| p.width > 8) {
if let Some(next) = pyramid.last().map(EnvImage::half) {
pyramid.push(next);
}
}
let mut out = vec![env.clone()];
let mut size = (env.width, env.height);
for l in 1..levels {
size = ((size.0 / 2).max(4), (size.1 / 2).max(2));
let rough = l as f32 / (levels - 1) as f32;
let a = (rough * rough).max(1e-3);
let samples = 128u32;
let (w, h) = size;
let sa_texel = 4.0 * PI / (env.width as f32 * env.height as f32);
// With n = v, every sample's half vector, n·l and source level depend only on its index:
// tabulate them once per level as (tangent-space half vector, n·l, pyramid level).
let table: Vec<(Vec3, f32, &EnvImage)> = (0..samples)
.filter_map(|i| {
let xi = hammersley(i, samples);
let phi = TAU * xi.x;
let cos_t = ((1.0 - xi.y) / (1.0 + (a * a - 1.0) * xi.y)).max(0.0).sqrt();
let sin_t = (1.0 - cos_t * cos_t).max(0.0).sqrt();
let ndl = 2.0 * cos_t * cos_t - 1.0;
if ndl <= 0.0 {
return None;
}
let dd = a * a / (PI * ((cos_t * cos_t) * (a * a - 1.0) + 1.0).powi(2)).max(1e-8);
let sa_sample = 1.0 / (samples as f32 * dd / 4.0 + 1e-6);
let lod = (0.5 * (sa_sample / sa_texel).log2() + 1.0).clamp(0.0, (pyramid.len() - 1) as f32);
let src = pyramid.get(lod.round() as usize).unwrap_or(&pyramid[0]);
Some((Vec3::new(sin_t * phi.cos(), sin_t * phi.sin(), cos_t), ndl, src))
})
.collect();
let wsum: f32 = table.iter().map(|t| t.1).sum();
let mut data = vec![[0.0f32; 3]; (w * h) as usize];
data.par_chunks_mut(w as usize).enumerate().for_each(|(y, row)| {
for (x, px) in row.iter_mut().enumerate() {
let n = dir_of((x as f32 + 0.5) / w as f32, (y as f32 + 0.5) / h as f32);
let up = if n.y.abs() < 0.999 { Vec3::Y } else { Vec3::X };
let tx = up.cross(n).normalize();
let ty = n.cross(tx);
let mut acc = Vec3::ZERO;
for (hv, ndl, src) in &table {
let hw = tx * hv.x + ty * hv.y + n * hv.z;
acc += src.sample(hw * (2.0 * hv.z) - n) * *ndl;
}
*px = (acc / wsum.max(1e-6)).to_array();
}
});
out.push(EnvImage { width: w, height: h, data });
}
out
}
/// Diffuse irradiance as 9 SH coefficients (already convolved with the cosine lobe and divided
/// by π, so `Σ c·Y(n)` times albedo is the diffuse radiance).
pub fn sh9(env: &EnvImage) -> [[f32; 3]; 9] {
let mut src = env.clone();
while src.width > 128 {
src = src.half();
}
let (w, h) = (src.width, src.height);
let mut c = [Vec3::ZERO; 9];
for y in 0..h {
let theta = PI * (y as f32 + 0.5) / h as f32;
let dw = (TAU / w as f32) * (PI / h as f32) * theta.sin();
for x in 0..w {
let d = dir_of((x as f32 + 0.5) / w as f32, (y as f32 + 0.5) / h as f32);
// No firefly clamp: the projection integrates, so a bright sun lights diffuse fully.
let l = src.get(x as i64, y as i64) * dw;
for (k, ylm) in sh_basis(d).iter().enumerate() {
c[k] += l * *ylm;
}
}
}
let a = [PI, 2.0 * PI / 3.0, 2.0 * PI / 3.0, 2.0 * PI / 3.0, PI / 4.0, PI / 4.0, PI / 4.0, PI / 4.0, PI / 4.0];
let mut out = [[0.0; 3]; 9];
for k in 0..9 {
out[k] = (c[k] * a[k] / PI).to_array();
}
out
}
pub fn sh_basis(d: Vec3) -> [f32; 9] {
let (x, y, z) = (d.x, d.y, d.z);
[
0.282_095,
0.488_603 * y,
0.488_603 * z,
0.488_603 * x,
1.092_548 * x * y,
1.092_548 * y * z,
0.315_392 * (3.0 * z * z - 1.0),
1.092_548 * x * z,
0.546_274 * (x * x - y * y),
]
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn uv_and_direction_round_trip() {
for i in 1..20 {
for j in 1..10 {
let (u, v) = (i as f32 / 20.0, j as f32 / 10.0);
let back = uv_of(dir_of(u, v));
assert!((back.x - u).abs() < 1e-4 && (back.y - v).abs() < 1e-4);
}
}
}
#[test]
fn sh_of_a_uniform_environment_is_constant_irradiance() {
let env = EnvImage { width: 64, height: 32, data: vec![[1.0, 1.0, 1.0]; 64 * 32] };
let c = sh9(&env);
for d in [Vec3::Y, Vec3::X, Vec3::NEG_Z, Vec3::new(0.3, -0.8, 0.5).normalize()] {
let b = sh_basis(d);
let e: f32 = (0..9).map(|k| c[k][0] * b[k]).sum();
assert!((e - 1.0).abs() < 0.03, "{e}");
}
}
#[test]
fn prefilter_levels_shrink_and_stay_finite() {
let env = environment("Studio Soft", 128);
let mips = prefilter(&env, 5);
assert_eq!(mips.len(), 5);
assert!(mips[4].width < mips[1].width);
for m in &mips {
assert!(m.data.iter().all(|c| c.iter().all(|v| v.is_finite() && *v >= 0.0)));
}
for name in ENVIRONMENTS {
let e = environment(name, 64);
assert!(e.data.iter().any(|c| c[0] > 0.5), "{name} has no light");
}
}
#[test]
fn imported_images_become_safe_linear_environments() {
assert!(EnvImage::from_rgba(4, 2, &[[0.0; 4]; 7], false).is_none(), "pixel count must match");
// HDR values stay above 1; NaN, infinity and negatives become 0; tiny images grow to 128×64.
let px = [[50.0, f32::NAN, -1.0, 1.0], [f32::INFINITY, 0.5, 0.25, 1.0]];
let e = EnvImage::from_rgba(2, 1, &px, false).unwrap();
assert_eq!((e.width, e.height), (128, 64));
assert!(e.data.iter().all(|c| c.iter().all(|v| v.is_finite() && *v >= 0.0)));
assert!(e.data.iter().any(|c| c[0] > 40.0), "HDR range is kept");
// 8-bit images are sRGB-decoded; big ones are halved down to the import limit.
let e = EnvImage::from_rgba(4096, 2048, &vec![[0.5, 0.5, 0.5, 1.0]; 4096 * 2048], true).unwrap();
assert_eq!((e.width, e.height), (MAX_IMPORT_WIDTH, MAX_IMPORT_WIDTH / 2));
assert!((e.data[0][0] - 0.214).abs() < 0.01, "{}", e.data[0][0]);
let mips = prefilter(&e, 6);
assert!(mips.iter().all(|m| m.data.iter().all(|c| c.iter().all(|v| v.is_finite()))));
}
/// CPU cost of a 2K import: `cargo test -p texturecraft-render --release -- --ignored --nocapture`.
#[test]
#[ignore]
fn bench_prefilter_2k() {
let src = environment("Sunset", 2048);
let t = std::time::Instant::now();
let mips = prefilter(&src, 6);
let sh = sh9(&src);
println!("2K environment: prefilter + SH {:.0} ms ({} levels, sh0 {:?})", t.elapsed().as_secs_f64() * 1000.0, mips.len(), sh[0]);
}
}