112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
|
# Audio 模块概览
|
|||
|
|
|
|||
|
|
**命名空间**: `XCEngine::Audio`
|
|||
|
|
|
|||
|
|
**类型**: `module`
|
|||
|
|
|
|||
|
|
**描述**: XCEngine 的音频系统模块，提供完整的音频播放、3D 空间化、效果处理和混音功能。
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
Audio 模块是 XCEngine 的音频子系统，支持多通道音频播放、3D 空间化定位（HRTF）、音频效果处理（混响、均衡器、FFT）、以及基于 WASAPI 的 Windows 音频后端。该模块设计为与 ECS 组件系统集成，通过 AudioSourceComponent 和 AudioListenerComponent 实现音频源的播放和空间化处理。
|
|||
|
|
|
|||
|
|
## 模块内容
|
|||
|
|
|
|||
|
|
### 核心系统
|
|||
|
|
|
|||
|
|
| 组件 | 文件 | 描述 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| [AudioSystem](audio-system/audio-system.md) | `AudioSystem.h` | 音频系统单例，管理所有音频源和后端 |
|
|||
|
|
| [AudioMixer](audio-mixer/audio-mixer.md) | `AudioMixer.h` | 音频混音器，支持效果链和 3D 参数 |
|
|||
|
|
| [IAudioBackend](i-audio-backend/i-audio-backend.md) | `IAudioBackend.h` | 音频后端抽象接口 |
|
|||
|
|
| [IAudioEffect](i-audio-effect/i-audio-effect.md) | `IAudioEffect.h` | 音频效果接口基类 |
|
|||
|
|
|
|||
|
|
### 音频效果
|
|||
|
|
|
|||
|
|
| 组件 | 文件 | 描述 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| [FFTFilter](fft-filter/fft-filter.md) | `FFTFilter.h` | FFT 频谱分析滤波器 |
|
|||
|
|
| [Reverbation](reverbation/reverbation.md) | `Reverbation.h` | 混响效果器（ Schroeder 算法的并行 Comb 滤波器 + AllPass 滤波器） |
|
|||
|
|
| [Equalizer](equalizer/equalizer.md) | `Equalizer.h` | 多频段参数均衡器 |
|
|||
|
|
| [HRTF](hrtf/hrtf.md) | `HRTF.h` | 基于头部相关传输函数的 3D 空间化 |
|
|||
|
|
|
|||
|
|
### Windows 后端
|
|||
|
|
|
|||
|
|
| 组件 | 文件 | 描述 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| [WASAPIBackend](wasapi-backend/wasapi-backend.md) | `WASAPI/WASAPIBackend.h` | Windows WASAPI 音频后端实现 |
|
|||
|
|
|
|||
|
|
### 配置与类型
|
|||
|
|
|
|||
|
|
| 组件 | 文件 | 描述 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| [AudioConfig](audio-config/audio-config.md) | `AudioConfig.h` | 音频系统配置 |
|
|||
|
|
| [Audio3DParams](audio-3d-params/audio-3d-params.md) | `AudioTypes.h` | 3D 空间化参数 |
|
|||
|
|
| [AudioBufferDesc](audio-buffer-desc/audio-buffer-desc.md) | `AudioTypes.h` | 音频缓冲区描述符 |
|
|||
|
|
| [SpatializerParams](spatializer-params/spatializer-params.md) | `AudioTypes.h` | 空间化计算参数 |
|
|||
|
|
|
|||
|
|
### 枚举类型
|
|||
|
|
|
|||
|
|
| 枚举 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| [AudioResourceType](enums/audio-resource-type.md) | 音频资源类型 |
|
|||
|
|
| [AudioLoadState](enums/audio-load-state.md) | 音频加载状态 |
|
|||
|
|
| [AudioFormat](enums/audio-format.md) | 音频格式（WAV, OGG, MP3, FLAC, AAC） |
|
|||
|
|
| [SpeakerMode](enums/speaker-mode.md) | 扬声器模式（Mono, Stereo, Surround51, Surround71 等） |
|
|||
|
|
| [AudioChannel](enums/audio-channel.md) | 音频通道（FrontLeft, FrontRight, FrontCenter, LFE 等） |
|
|||
|
|
| [PlayState](enums/play-state.md) | 播放状态（Stopped, Playing, Paused） |
|
|||
|
|
| [StopMode](enums/stop-mode.md) | 停止模式（Immediate, AllowFadeOut） |
|
|||
|
|
| [PanMode](enums/pan-mode.md) | 声像模式（Pan3D, Pan2D） |
|
|||
|
|
| [VolumeSource](enums/volume-source.md) | 音量来源（Direct, PathOcclusion, Transmission, Obstruction） |
|
|||
|
|
|
|||
|
|
## 使用示例
|
|||
|
|
|
|||
|
|
```cpp
|
|||
|
|
#include <XCEngine/Audio/AudioSystem.h>
|
|||
|
|
#include <XCEngine/Audio/AudioMixer.h>
|
|||
|
|
#include <XCEngine/Audio/Equalizer.h>
|
|||
|
|
#include <XCEngine/Audio/Reverbation.h>
|
|||
|
|
|
|||
|
|
using namespace XCEngine::Audio;
|
|||
|
|
|
|||
|
|
void InitializeAudioSystem() {
|
|||
|
|
AudioConfig config;
|
|||
|
|
config.sampleRate = 48000;
|
|||
|
|
config.channels = 2;
|
|||
|
|
config.bitsPerSample = 16;
|
|||
|
|
config.speakerMode = SpeakerMode::Stereo;
|
|||
|
|
config.bufferSize = 8192;
|
|||
|
|
config.bufferCount = 2;
|
|||
|
|
|
|||
|
|
AudioSystem::Get().Initialize(config);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
void SetupAudioWithEffects() {
|
|||
|
|
AudioMixer* mixer = new AudioMixer();
|
|||
|
|
|
|||
|
|
Reverbation* reverb = new Reverbation();
|
|||
|
|
reverb->SetRoomSize(0.5f);
|
|||
|
|
reverb->SetWetMix(0.3f);
|
|||
|
|
reverb->SetDryMix(0.7f);
|
|||
|
|
|
|||
|
|
Equalizer* eq = new Equalizer();
|
|||
|
|
eq->SetBandCount(4);
|
|||
|
|
eq->SetBandFrequency(0, 100.0f);
|
|||
|
|
eq->SetBandGain(0, 3.0f);
|
|||
|
|
|
|||
|
|
mixer->AddEffect(eq);
|
|||
|
|
mixer->AddEffect(reverb);
|
|||
|
|
mixer->SetVolume(0.8f);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
void UpdateListener(const Math::Vector3& pos, const Math::Quaternion& rot) {
|
|||
|
|
AudioSystem::Get().SetListenerTransform(pos, rot);
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
|
|||
|
|
- [Resources 模块 - AudioClip](../resources/audioclip/audio-clip.md) - 音频资源管理
|
|||
|
|
- [Components 模块 - AudioSourceComponent](../components/audio-source/audio-source-component.md) - 音频源组件
|
|||
|
|
- [Components 模块 - AudioListenerComponent](../components/audio-listener/audio-listener-component.md) - 音频监听器组件
|