Skip to main content

Crate roxlap_audio

Crate roxlap_audio 

Source
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§

AcousticsConfig
Tuning knobs for source_acoustics. The defaults are the cave-demo tuning; every field is plain data so hosts can persist or lerp them.
CavityConfig
Tuning knobs for the cavity probe + the reverb mapping.
CavityEstimator
Stateful cavity estimator: probe_cavity plus the prior-art exponential smoothing, mapped to reverb parameters. One per listener; call update at ~2 Hz and reset on teleports.
CavityProbe
Raw (unsmoothed) result of one probe_cavity fan.
ListenerAcoustics
Smoothed reverb parameters for the listener’s surroundings, produced by CavityEstimator::update. Feed the reverb fields to the backend with long tweens (~1 s).
SoundKey
A registered sound asset (backend-owned decoded buffer).
SourceAcoustics
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.
SourceId
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.
SourcePool
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§

AudioOut
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 → b crosses, summed over every grid in the scene. This is the thickness building block under source_acoustics: exact per-cell segment lengths from a voxel DDA against roxlap_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 a CavityProbe. 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 of AcousticsConfig::rays thickness rays (the direct segment plus a fixed jitter ring around the source, perpendicular to the source→listener axis), each converted to transmitted energy exp(-absorption · thickness) and averaged.