d84914ef1e5a
ibl.rs
//! 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]);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (鈱極 on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.