ssdfasd
161a0896d5
- 新增 Audio 模块文档 (54 个文件) - AudioSystem 单例类及 20 个方法页 - AudioMixer 混音器类及 11 个方法页 - IAudioBackend、IAudioEffect 接口 - FFTFilter、Reverbation、Equalizer、HRTF 效果类 - WASAPIBackend Windows 后端 - AudioConfig、Audio3DParams 等结构体 - 9 个枚举类型文档 - 新增 Components 模块文档 (3 个文件) - AudioSourceComponent 音频源组件 - AudioListenerComponent 音频监听器组件 - 更新 docs/api/main.md 添加模块导航
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) - 音频监听器组件
|