use glam::DVec3;
use roxlap_formats::material::material_for_color;
use roxlap_scene::{Rgb, Scene};
#[derive(Debug, Clone, PartialEq)]
pub struct CavityConfig {
pub rays: u32,
pub max_ray_dist: f64,
pub min_feedback: f32,
pub max_feedback: f32,
pub max_wet: f32,
pub outdoor_openness: f32,
pub damping: f32,
pub material_map: Vec<(Rgb, u8)>,
pub damping_override: Vec<(u8, f32)>,
pub smoothing: f32,
}
impl Default for CavityConfig {
fn default() -> Self {
Self {
rays: 32,
max_ray_dist: 64.0,
min_feedback: 0.35,
max_feedback: 0.88,
max_wet: 0.5,
outdoor_openness: 0.5,
damping: 0.4,
material_map: Vec::new(),
damping_override: Vec::new(),
smoothing: 0.75,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CavityProbe {
pub mean_free_path: f32,
pub enclosed_free_path: f32,
pub openness: f32,
pub damping: f32,
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ListenerAcoustics {
pub mean_free_path: f32,
pub openness: f32,
pub reverb_feedback: f32,
pub reverb_damping: f32,
pub reverb_mix: f32,
}
#[must_use]
pub fn probe_cavity(scene: &Scene, listener: DVec3, cfg: &CavityConfig) -> CavityProbe {
let rays = cfg.rays.max(4);
let classify = !cfg.damping_override.is_empty();
let mut path_sum = 0.0f64;
let mut hit_sum = 0.0f64;
let mut damp_sum = 0.0f64;
let mut escaped = 0u32;
for k in 0..rays {
let dir = golden_spiral_dir(k, rays);
match scene.raycast(listener, dir, cfg.max_ray_dist) {
Some(hit) => {
path_sum += hit.t;
hit_sum += hit.t;
if classify {
let d = hit.color.map_or(cfg.damping, |c| resolve_damping(cfg, c.0));
damp_sum += f64::from(d);
}
}
None => {
path_sum += cfg.max_ray_dist;
escaped += 1;
}
}
}
let hits = rays - escaped;
#[allow(clippy::cast_possible_truncation)]
CavityProbe {
mean_free_path: (path_sum / f64::from(rays)) as f32,
enclosed_free_path: if hits == 0 {
cfg.max_ray_dist as f32
} else {
(hit_sum / f64::from(hits)) as f32
},
openness: escaped as f32 / rays as f32,
damping: if !classify || hits == 0 {
cfg.damping
} else {
(damp_sum / f64::from(hits)) as f32
},
}
}
fn resolve_damping(cfg: &CavityConfig, colour: u32) -> f32 {
let id = material_for_color(&cfg.material_map, colour);
cfg.damping_override
.iter()
.find(|&&(m, _)| m == id)
.map_or(cfg.damping, |&(_, d)| d)
}
fn golden_spiral_dir(k: u32, n: u32) -> DVec3 {
const GOLDEN_ANGLE: f64 = 2.399_963_229_728_653; let z = 1.0 - 2.0 * (f64::from(k) + 0.5) / f64::from(n);
let r = (1.0 - z * z).sqrt();
let phi = GOLDEN_ANGLE * f64::from(k);
DVec3::new(r * phi.cos(), r * phi.sin(), z)
}
#[derive(Debug, Clone)]
pub struct CavityEstimator {
cfg: CavityConfig,
smoothed: Option<CavityProbe>,
}
impl CavityEstimator {
#[must_use]
pub fn new(cfg: CavityConfig) -> Self {
Self {
cfg,
smoothed: None,
}
}
#[must_use]
pub fn config(&self) -> &CavityConfig {
&self.cfg
}
pub fn reset(&mut self) {
self.smoothed = None;
}
pub fn update(&mut self, scene: &Scene, listener: DVec3) -> ListenerAcoustics {
let raw = probe_cavity(scene, listener, &self.cfg);
let s = self.cfg.smoothing.clamp(0.0, 1.0);
let sm = match self.smoothed {
None => raw,
Some(prev) => CavityProbe {
mean_free_path: prev.mean_free_path * s + raw.mean_free_path * (1.0 - s),
enclosed_free_path: prev.enclosed_free_path * s
+ raw.enclosed_free_path * (1.0 - s),
openness: prev.openness * s + raw.openness * (1.0 - s),
damping: if self.cfg.damping_override.is_empty() {
raw.damping
} else {
prev.damping * s + raw.damping * (1.0 - s)
},
},
};
self.smoothed = Some(sm);
self.params(sm)
}
#[allow(clippy::cast_possible_truncation)]
fn params(&self, p: CavityProbe) -> ListenerAcoustics {
let size_norm =
(f64::from(p.enclosed_free_path) / self.cfg.max_ray_dist).clamp(0.0, 1.0) as f32;
let outdoor = self.cfg.outdoor_openness.max(1e-6);
let enclosure = ((outdoor - p.openness) / outdoor).clamp(0.0, 1.0);
ListenerAcoustics {
mean_free_path: p.mean_free_path,
openness: p.openness,
reverb_feedback: self.cfg.min_feedback
+ (self.cfg.max_feedback - self.cfg.min_feedback) * size_norm,
reverb_damping: p.damping,
reverb_mix: self.cfg.max_wet * enclosure,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use glam::IVec3;
use roxlap_scene::{GridTransform, VoxColor};
const STONE: VoxColor = VoxColor(0x80_66_77_88);
fn room(side: i32, c: IVec3) -> (Scene, DVec3) {
let mut scene = Scene::new();
let id = scene.add_grid(GridTransform::identity());
let g = scene.grid_mut(id).expect("grid just added");
let h = side / 2;
let shell = 2;
g.set_rect(
c - IVec3::splat(h + shell),
c + IVec3::splat(h + shell),
Some(STONE),
);
g.set_rect(c - IVec3::splat(h), c + IVec3::splat(h), None);
let centre = DVec3::new(
f64::from(c.x) + 0.5,
f64::from(c.y) + 0.5,
f64::from(c.z) + 0.5,
);
(scene, centre)
}
#[test]
fn empty_scene_is_fully_open() {
let scene = Scene::new();
let cfg = CavityConfig::default();
let p = probe_cavity(&scene, DVec3::new(64.0, 64.0, 128.0), &cfg);
assert_eq!(p.openness, 1.0);
#[allow(clippy::cast_possible_truncation)]
let cap = cfg.max_ray_dist as f32;
assert!((p.mean_free_path - cap).abs() < 1e-4);
assert!((p.enclosed_free_path - cap).abs() < 1e-4, "no-hit sentinel");
let a = CavityEstimator::new(cfg).params(p);
assert_eq!(a.reverb_mix, 0.0);
}
#[test]
fn bigger_room_reads_bigger_and_both_are_sealed() {
let cfg = CavityConfig::default();
let (small, sc) = room(8, IVec3::new(64, 64, 128));
let (big, bc) = room(40, IVec3::new(64, 64, 128));
let ps = probe_cavity(&small, sc, &cfg);
let pb = probe_cavity(&big, bc, &cfg);
assert_eq!(ps.openness, 0.0, "small room is sealed");
assert_eq!(pb.openness, 0.0, "big room is sealed");
assert!(
pb.mean_free_path > ps.mean_free_path * 2.0,
"room size ordering: big {} vs small {}",
pb.mean_free_path,
ps.mean_free_path
);
let est = CavityEstimator::new(cfg.clone());
let a_small = est.params(ps);
let a_big = est.params(pb);
assert!(a_big.reverb_feedback > a_small.reverb_feedback);
assert!((a_small.reverb_mix - cfg.max_wet).abs() < 1e-6);
assert!(a_small.reverb_feedback >= cfg.min_feedback);
assert!(a_big.reverb_feedback <= cfg.max_feedback);
}
#[test]
fn open_ground_is_much_drier_than_a_cavern() {
let cfg = CavityConfig::default();
let mut scene = Scene::new();
let id = scene.add_grid(GridTransform::identity());
let g = scene.grid_mut(id).expect("grid");
g.set_rect(
IVec3::new(0, 0, 200),
IVec3::new(255, 255, 220),
Some(STONE),
);
let outdoors = probe_cavity(&scene, DVec3::new(128.0, 128.0, 198.0), &cfg);
assert!(
outdoors.openness > 0.4,
"standing on open ground, roughly the upper hemisphere escapes: {}",
outdoors.openness
);
assert!(
outdoors.enclosed_free_path < outdoors.mean_free_path * 0.6,
"enclosed path ({}) must ignore escaped rays (mean {})",
outdoors.enclosed_free_path,
outdoors.mean_free_path
);
let (cavern, cc) = room(40, IVec3::new(64, 64, 128));
let inside = probe_cavity(&cavern, cc, &cfg);
let est = CavityEstimator::new(cfg.clone());
let dry = est.params(outdoors);
let wet = est.params(inside);
assert!(
dry.reverb_mix < 0.05,
"open ground must be bone dry, got mix {}",
dry.reverb_mix
);
assert!(
dry.reverb_feedback < cfg.min_feedback + 0.15,
"open ground must not read as a big hall: feedback {}",
dry.reverb_feedback
);
assert!(
wet.reverb_mix > cfg.max_wet * 0.8,
"sealed cavern stays wet: {}",
wet.reverb_mix
);
}
#[test]
fn smoothing_seeds_raw_then_converges_monotonically() {
let cfg = CavityConfig::default();
let (small, sc) = room(8, IVec3::new(64, 64, 128));
let (big, bc) = room(40, IVec3::new(64, 64, 128));
let mut est = CavityEstimator::new(cfg.clone());
let first = est.update(&big, bc);
let raw_big = probe_cavity(&big, bc, &cfg);
assert!((first.mean_free_path - raw_big.mean_free_path).abs() < 1e-6);
let raw_small = probe_cavity(&small, sc, &cfg);
let mut prev = first.mean_free_path;
for step in 0..12 {
let a = est.update(&small, sc);
assert!(
a.mean_free_path < prev,
"step {step}: estimate must decrease ({} vs {prev})",
a.mean_free_path
);
prev = a.mean_free_path;
}
assert!(
(prev - raw_small.mean_free_path).abs() < 2.0,
"after 12 updates the estimate ({prev}) nears the raw small-room value ({})",
raw_small.mean_free_path
);
est.reset();
let after = est.update(&big, bc);
assert!((after.mean_free_path - raw_big.mean_free_path).abs() < 1e-6);
}
#[test]
fn deterministic() {
let cfg = CavityConfig::default();
let (scene, c) = room(16, IVec3::new(64, 64, 128));
assert_eq!(probe_cavity(&scene, c, &cfg), probe_cavity(&scene, c, &cfg));
}
const GLASS: VoxColor = VoxColor(0x80_40_C0_E0);
const GLASS_ID: u8 = 7;
fn boxed_room(side: i32, c: IVec3, col: VoxColor) -> (Scene, DVec3) {
let mut scene = Scene::new();
let id = scene.add_grid(GridTransform::identity());
let g = scene.grid_mut(id).expect("grid just added");
let h = side / 2;
let (lo, hi) = (c - IVec3::splat(h), c + IVec3::splat(h));
for ax in 0..3 {
for side in 0..2 {
let mut slo = lo - IVec3::splat(2);
let mut shi = hi + IVec3::splat(2);
if side == 0 {
shi[ax] = lo[ax] - 1;
} else {
slo[ax] = hi[ax] + 1;
}
g.set_rect(slo, shi, Some(col));
}
}
let centre = DVec3::new(
f64::from(c.x) + 0.5,
f64::from(c.y) + 0.5,
f64::from(c.z) + 0.5,
);
(scene, centre)
}
fn glassy_cfg() -> CavityConfig {
CavityConfig {
material_map: vec![(GLASS.rgb_part(), GLASS_ID)],
damping_override: vec![(GLASS_ID, 0.1)],
..CavityConfig::default()
}
}
#[test]
fn empty_override_damping_is_legacy_exact() {
let (scene, c) = boxed_room(16, IVec3::new(64, 64, 128), GLASS);
let cfg = CavityConfig {
material_map: vec![(GLASS.rgb_part(), GLASS_ID)],
..CavityConfig::default()
};
let p = probe_cavity(&scene, c, &cfg);
assert_eq!(p.damping.to_bits(), cfg.damping.to_bits());
let mut est = CavityEstimator::new(cfg.clone());
let a = est.update(&scene, c);
let b = est.update(&scene, c); assert_eq!(a.reverb_damping.to_bits(), cfg.damping.to_bits());
assert_eq!(b.reverb_damping.to_bits(), cfg.damping.to_bits());
}
#[test]
fn glass_cavern_rings_brighter_than_stone() {
let cfg = glassy_cfg();
let (glass, gc) = boxed_room(16, IVec3::new(64, 64, 128), GLASS);
let (stone, sc) = boxed_room(16, IVec3::new(64, 64, 128), STONE);
let pg = probe_cavity(&glass, gc, &cfg);
let ps = probe_cavity(&stone, sc, &cfg);
assert_eq!(pg.openness, 0.0, "sealed glass box");
assert!(
(pg.damping - 0.1).abs() < 1e-4,
"all-glass walls take the override: {}",
pg.damping
);
assert_eq!(
ps.damping.to_bits(),
cfg.damping.to_bits(),
"unmapped stone keeps the default"
);
let mut est = CavityEstimator::new(cfg);
let a = est.update(&glass, gc);
assert!(
a.reverb_damping < 0.15,
"the mapped damping reaches the listener params: {}",
a.reverb_damping
);
}
#[test]
fn mixed_walls_average_damping() {
let cfg = glassy_cfg();
let c = IVec3::new(64, 64, 128);
let (mut scene, centre) = boxed_room(16, c, GLASS);
{
let id = scene.grids().next().expect("one grid").0;
let g = scene.grid_mut(id).expect("grid");
g.set_rect(
IVec3::new(c.x + 7, c.y - 10, c.z - 10),
IVec3::new(c.x + 7, c.y + 10, c.z + 10),
Some(STONE),
);
}
let p = probe_cavity(&scene, centre, &cfg);
assert!(
p.damping > 0.11 && p.damping < 0.39,
"mixed walls land between glass (0.1) and stone (0.4): {}",
p.damping
);
}
}