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.

Constants§

DEFAULT_SPEED_OF_SOUND
AU2.2 — default speed of sound for doppler_factor, world units/second. Deliberately game-tuned, not physical: at the real 343 m/s a 60 u/s bullet would bend pitch by ~1.5 semitones; at 90 the demo’s speeds read clearly. Hosts pass their own value to retune.
LISTENER_LOWPASS_OPEN_HZ
WT.3 — the neutral (fully open) listener-lowpass cutoff: passing this (or anything above) to AudioOut::set_listener_lowpass means “not submerged”. Defined AS crate::OPEN_CUTOFF_HZ — “open” means the same thing on the per-source and listener paths by construction, not by a pin test.
LISTENER_LOWPASS_SUBMERGED_HZ
WT.3 — the canonical SUBMERGED listener-lowpass cutoff: the value the demos (and any host without its own tuning) pass while the eye is under water. One named default so every call site muffles identically and a listening-pass retune is a one-line change. Tuned dark enough to read as “under the surface” while speech-band content stays intelligible.
OPEN_CUTOFF_HZ
The ONE definition of a fully-open (no muffle) lowpass cutoff, shared by every path that needs “not occluded / not submerged”: AcousticsConfig::default’s open_cutoff_hz, the listener lowpass (LISTENER_LOWPASS_OPEN_HZ is this constant), and the kira backend’s per-source filter rest position. One constant so the three can’t drift apart silently.

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§

doppler_factor
AU2.2 — the Doppler playback-rate factor for a moving source/listener pair: > 1 approaching (pitch up), < 1 receding, exactly 1.0 at rest. The classic two-sided formula (c − v_l·n̂) / (c − v_s·n̂) with n̂ the source→listener direction, made monotone and finite at the edges: the denominator floors at 0.05·c (a supersonic approach clamps instead of flipping sign) and the result clamps to [0.5, 2.0] — an octave down/up, past which game audio reads as a glitch.
hear_source
FW.4 — reveal a heard sound source in the fog of war (decision 6): hearing something behind the back or through a wall lights a temporary “heard” pocket around it. Runs source_acoustics to measure how much of the source reaches the listener through the geometry, scales base_loudness by that transmission, and stamps a heard blob at the source’s fog cell via FogOfWar::hear_world.
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).
path_thickness_weighted
AU2.0 — path_thickness with per-material weighting: each solid cell’s segment length is multiplied by its material’s absorption factor (material_map classifies the cell’s colour the way the renderer’s terrain map does; absorption maps material id → multiplier, unmapped = 1.0). One voxel of 0.35 glass muffles like 0.35 voxels of stone. The .vxl format stores surface colours only, so an interior cell reuses the last surface colour the ray crossed in that grid (weight 1.0 before the first — deep interiors read as rock, which is what they are).
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.