Expand description
Voxel-aware acoustics for the roxlap engine (stage AU —
docs/porting/PORTING-AUDIO.md).
This crate computes acoustic parameters from the voxel world; it
deliberately owns no audio device and spawns no audio thread. The
host feeds the numbers into whatever playback stack it uses (the
optional kira backend lands in AU.2): per sound source an
occlusion-driven gain + lowpass cutoff + reverb send, and (AU.1) per
listener a cavity-driven reverb feedback/mix.
The occlusion model follows the convergent games recipe (Sound
Physics, Teardown, Overwatch — see the entry doc): a small fan of
rays from the source to the listener, each accumulating the solid
path length it crosses (voxel units, exact segment lengths from a
DDA march — not a boolean hit test), averaged into a 0..=1
transmission. Thickness matters: one voxel of wall muffles less
than five, and a doorway passes some rays untouched, so sound leaks
around corners instead of gating on/off.
Everything here is pure and deterministic — the jitter fan is a fixed ring, not RNG — so tests pin exact values and hosts can call it from any thread.
Re-exports§
pub use synth::SoundBuffer;
Modules§
- synth
- AU.2 — procedurally synthesized demo sounds (house pattern: no binary assets; the Doom demo synthesizes its GIFs, we synthesize our bleeps). Deterministic — the noise source is a fixed LCG — so buffers are testable byte-for-byte and identical across runs.
Structs§
- Acoustics
Config - Tuning knobs for
source_acoustics. The defaults are the cave-demo tuning; every field is plain data so hosts can persist or lerp them. - Cavity
Config - Tuning knobs for the cavity probe + the reverb mapping.
- Cavity
Estimator - Stateful cavity estimator:
probe_cavityplus the prior-art exponential smoothing, mapped to reverb parameters. One per listener; callupdateat ~2 Hz andreseton teleports. - Cavity
Probe - Raw (unsmoothed) result of one
probe_cavityfan. - Listener
Acoustics - Smoothed reverb parameters for the listener’s surroundings,
produced by
CavityEstimator::update. Feed the reverb fields to the backend with long tweens (~1 s). - Sound
Key - A registered sound asset (backend-owned decoded buffer).
- Source
Acoustics - Occlusion-driven playback parameters for one source→listener pair,
produced by
source_acoustics. Feed them to the playback layer with short tweens (~120 ms) — never as raw jumps. - Source
Id - One live spatial source (a pooled backend track). Stale after the source is stopped or stolen — backend calls on a stale id are no-ops by contract.
- Source
Pool - Backend-agnostic voice-slot policy for a fixed pool of spatial
tracks — pure and unit-tested here so every backend (the built-in
kira one, or a host’s own
AudioOut) inherits the same behaviour (hazard 2: tracks are created up front and reused; a per-shot allocation storm is the classic mistake). One-shots are stealable (oldest first) when the pool is full; loops hold their slot until explicitly stopped.
Traits§
- Audio
Out - The playback backend the acoustics core drives. Implementations apply parameter changes with tweens (~120 ms for per-source occlusion, ~1 s for the listener’s reverb) — never as raw jumps (hazard 3: parameter zippering).
Functions§
- path_
thickness - Total solid path length (world/voxel units) the straight segment
a → bcrosses, summed over every grid in the scene. This is the thickness building block undersource_acoustics: exact per-cell segment lengths from a voxel DDA againstroxlap_scene::Grid::voxel_solid(a diagonal crossing of a 1-voxel wall correctly reports ~√2). - probe_
cavity - Probe the space around
listener: cast the golden-spiral fan and reduce it to aCavityProbe. Pure and deterministic — the fan is a fixed direction set, so tests pin exact values and the estimator can round-robin freely. - source_
acoustics - Occlusion parameters for one source heard from
listener: a fan ofAcousticsConfig::raysthickness rays (the direct segment plus a fixed jitter ring around the source, perpendicular to the source→listener axis), each converted to transmitted energyexp(-absorption · thickness)and averaged.