use glam::DVec3;
use roxlap_scene::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 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,
smoothing: 0.75,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CavityProbe {
pub mean_free_path: f32,
pub enclosed_free_path: f32,
pub openness: 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 mut path_sum = 0.0f64;
let mut hit_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;
}
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,
}
}
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),
},
};
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: self.cfg.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));
}
}