Skip to main content

qualia_audio/
spatial.rs

1//! Zero-Heap 3D Spatial Audio & Doppler Engine (`spatial.rs`)
2//!
3//! Provides deterministic 3D spatial sound processing delegated to [`etalon_signal::spatial`]:
4//! - Distance attenuation models (Inverse, Linear, Exponential)
5//! - Directional emission cones (inner angle, outer angle, outer attenuation)
6//! - Doppler frequency pitch shifting based on relative emitter-listener velocities
7//! - Equal-power stereo binaural panning and interaural level/time differences
8//! - Caller-buffered zero-heap mixing
9//!
10//! Designed according to `AGENTS.md` ยง0 (Zero heap in hot paths).
11
12pub use etalon_signal::spatial::{
13    mix_spatial_voice_into, mix_spatial_voice_occluded_into, DistanceModel, SpatialEmitter,
14    SpatialListener, SpatialOcclusionBridge, SpatialOcclusionFilterState, SpatialVoiceParams,
15    MAX_SPATIAL_VOICES, SPEED_OF_SOUND_AIR,
16};
17
18#[cfg(test)]
19mod tests {
20    use super::*;
21
22    #[test]
23    fn test_distance_attenuation() {
24        let model = DistanceModel::Inverse {
25            ref_distance: 1.0,
26            max_distance: 50.0,
27            rolloff_factor: 1.0,
28        };
29
30        let g1 = model.calculate_gain(1.0);
31        let g2 = model.calculate_gain(2.0);
32        let g10 = model.calculate_gain(10.0);
33
34        assert!((g1 - 1.0).abs() < 1e-5);
35        assert!((g2 - 0.5).abs() < 1e-4);
36        assert!(g10 < g2);
37    }
38
39    #[test]
40    fn test_doppler_shift() {
41        let mut emitter = SpatialEmitter::default();
42        emitter.position = [0.0, 0.0, 100.0];
43        // Moving towards listener at 34.3 m/s (~10% speed of sound)
44        emitter.velocity = [0.0, 0.0, -34.32];
45
46        let listener = SpatialListener::default();
47        let params = emitter.evaluate_spatial(&listener);
48
49        // When approaching, pitch multiplier must be > 1.0 (approx 1.11)
50        assert!(params.pitch_multiplier > 1.05);
51    }
52
53    #[test]
54    fn test_stereo_panning() {
55        let mut emitter = SpatialEmitter::default();
56        // Place emitter directly to the right
57        emitter.position = [10.0, 0.0, 0.0];
58
59        let listener = SpatialListener::default();
60        let params = emitter.evaluate_spatial(&listener);
61
62        // Right channel must be significantly louder than left
63        assert!(params.gain_right > params.gain_left);
64    }
65
66    #[test]
67    fn test_pga_motor_listener_and_occluded_mixer_bridge() {
68        // Pure translation motor by [0.0, 2.0, -5.0] in PGA blade4 encoding
69        let r = [1.0, 0.0, 0.0, 0.0];
70        let d = [0.0, 2.5, -1.0, 0.0]; // blade4: [w, -z, -y, -x] for half-translation [0, 1, -2.5]
71        let listener = SpatialListener::from_pga_motor_blades(r, d, [0.0, 0.0, 0.0]);
72        assert!((listener.position[1] - 2.0).abs() < 1e-4);
73        assert!((listener.position[2] + 5.0).abs() < 1e-4);
74
75        let mut emitter = SpatialEmitter::default();
76        emitter.position = [4.0, 2.0, -5.0];
77        let occlusion = SpatialOcclusionBridge {
78            direct_gain: 0.4,
79            lowpass_cutoff_hz: 900.0,
80            diffraction_phase_rad: 0.25,
81            reverb_send: 0.35,
82        };
83        let params = emitter.evaluate_spatial_with_occlusion(&listener, &occlusion);
84        assert!(params.gain_right > params.gain_left);
85
86        let mono = [0.8_f32; 32];
87        let mut st = SpatialOcclusionFilterState::default();
88        let mut direct = [[0.0_f32; 2]; 32];
89        let mut reverb = [[0.0_f32; 2]; 32];
90        mix_spatial_voice_occluded_into(
91            &mono,
92            &params,
93            &occlusion,
94            48_000.0,
95            &mut st,
96            &mut direct,
97            &mut reverb,
98        );
99        assert!(direct[31][1] > direct[31][0]);
100        assert!(reverb[31][1] > 0.0);
101    }
102}