164 lines
4.2 KiB
Markdown
164 lines
4.2 KiB
Markdown
# Phase 6-2: 3D Audio — Design Spec
|
|
|
|
## Overview
|
|
|
|
`voltex_audio`에 3D 공간 오디오를 추가한다. 거리 기반 감쇠와 스테레오 패닝으로 소리의 공간감을 표현한다.
|
|
|
|
## Scope
|
|
|
|
- Listener (위치, 방향)
|
|
- SpatialParams (이미터 위치, min/max 거리)
|
|
- 거리 감쇠 (inverse distance)
|
|
- 스테레오 패닝 (equal-power)
|
|
- play_3d, set_listener API
|
|
|
|
## Out of Scope
|
|
|
|
- 도플러 효과
|
|
- HRTF
|
|
- Reverb/Echo
|
|
- 다중 리스너
|
|
|
|
## Module Structure
|
|
|
|
### voltex_audio (수정/추가)
|
|
- `crates/voltex_audio/src/spatial.rs` — Listener, SpatialParams, 감쇠/패닝 순수 함수 (Create)
|
|
- `crates/voltex_audio/src/mixing.rs` — PlayingSound에 spatial 추가, mix에 spatial 적용 (Modify)
|
|
- `crates/voltex_audio/src/audio_system.rs` — Play3d, SetListener 명령 추가 (Modify)
|
|
- `crates/voltex_audio/src/lib.rs` — spatial 모듈 등록 (Modify)
|
|
|
|
## Dependencies
|
|
|
|
- `voltex_math` — Vec3 (위치, 방향 계산)
|
|
- `crates/voltex_audio/Cargo.toml`에 voltex_math 의존 추가
|
|
|
|
## Types
|
|
|
|
### Listener
|
|
|
|
```rust
|
|
#[derive(Debug, Clone, Copy)]
|
|
pub struct Listener {
|
|
pub position: Vec3,
|
|
pub forward: Vec3,
|
|
pub right: Vec3,
|
|
}
|
|
```
|
|
|
|
- `default()` → position=ZERO, forward=-Z, right=X
|
|
|
|
### SpatialParams
|
|
|
|
```rust
|
|
#[derive(Debug, Clone, Copy)]
|
|
pub struct SpatialParams {
|
|
pub position: Vec3,
|
|
pub min_distance: f32,
|
|
pub max_distance: f32,
|
|
}
|
|
```
|
|
|
|
- `new(position, min_distance, max_distance)` — 생성
|
|
- `at(position)` — min=1.0, max=50.0 기본값으로 간편 생성
|
|
|
|
## Functions (spatial.rs)
|
|
|
|
### distance_attenuation
|
|
|
|
```rust
|
|
pub fn distance_attenuation(distance: f32, min_dist: f32, max_dist: f32) -> f32
|
|
```
|
|
|
|
- distance <= min_dist → 1.0
|
|
- distance >= max_dist → 0.0
|
|
- 사이: `min_dist / distance` (inverse distance, clamped)
|
|
|
|
### stereo_pan
|
|
|
|
```rust
|
|
pub fn stereo_pan(listener: &Listener, emitter_pos: Vec3) -> (f32, f32)
|
|
```
|
|
|
|
1. direction = (emitter_pos - listener.position).normalize()
|
|
2. pan = direction.dot(listener.right) — -1.0(왼쪽) ~ 1.0(오른쪽)
|
|
3. Equal-power panning:
|
|
- left_gain = cos(pan * PI/4 + PI/4) — pan=-1일 때 1.0, pan=1일 때 0.0
|
|
- right_gain = sin(pan * PI/4 + PI/4) — pan=-1일 때 0.0, pan=1일 때 1.0
|
|
4. 이미터가 리스너 위치와 동일하면 (1.0, 1.0) 반환
|
|
|
|
### compute_spatial_gains
|
|
|
|
```rust
|
|
pub fn compute_spatial_gains(listener: &Listener, spatial: &SpatialParams) -> (f32, f32, f32)
|
|
```
|
|
|
|
Returns (attenuation, left_gain, right_gain).
|
|
편의 함수: distance_attenuation + stereo_pan 결합.
|
|
|
|
## Mixing Integration
|
|
|
|
### PlayingSound 변경
|
|
|
|
```rust
|
|
pub struct PlayingSound {
|
|
pub clip_index: usize,
|
|
pub position: usize,
|
|
pub volume: f32,
|
|
pub looping: bool,
|
|
pub spatial: Option<SpatialParams>, // NEW
|
|
}
|
|
```
|
|
|
|
### mix_sounds 변경
|
|
|
|
시그니처에 `listener: &Listener` 파라미터 추가:
|
|
|
|
```rust
|
|
pub fn mix_sounds(
|
|
output: &mut [f32],
|
|
playing: &mut Vec<PlayingSound>,
|
|
clips: &[AudioClip],
|
|
device_sample_rate: u32,
|
|
device_channels: u16,
|
|
frames: usize,
|
|
listener: &Listener, // NEW
|
|
)
|
|
```
|
|
|
|
spatial이 Some인 사운드:
|
|
1. compute_spatial_gains로 (attenuation, left, right) 계산
|
|
2. 볼륨에 attenuation 곱하기
|
|
3. 스테레오 출력에 left/right gain 적용
|
|
|
|
spatial이 None인 사운드 (2D):
|
|
- 기존 동작 유지 (전체 볼륨 균등)
|
|
|
|
## AudioSystem API 변경
|
|
|
|
### 새 명령
|
|
|
|
```rust
|
|
AudioCommand::Play3d { clip_index, volume, looping, spatial: SpatialParams },
|
|
AudioCommand::SetListener { position: Vec3, forward: Vec3, right: Vec3 },
|
|
```
|
|
|
|
### 새 메서드
|
|
|
|
```rust
|
|
pub fn play_3d(&self, clip_index: usize, volume: f32, looping: bool, spatial: SpatialParams)
|
|
pub fn set_listener(&self, position: Vec3, forward: Vec3, right: Vec3)
|
|
```
|
|
|
|
## Test Plan
|
|
|
|
### spatial.rs
|
|
- distance_attenuation: at min_dist (1.0), at max_dist (0.0), between, zero distance
|
|
- stereo_pan: right side → right gain > left, left side → left gain > right, front → roughly equal, same position → (1.0, 1.0)
|
|
- compute_spatial_gains: combines both correctly
|
|
|
|
### mixing.rs (spatial integration)
|
|
- 2D sound unchanged (spatial=None, listener 무관)
|
|
- 3D sound at max_distance → near-silent output
|
|
- 3D sound at min_distance → full volume
|
|
- 3D sound on right → right channel louder
|