2026-03-26 16:45:24 +08:00
|
|
|
|
# Audio
|
|
|
|
|
|
|
|
|
|
|
|
**命名空间**: `XCEngine::Audio`
|
|
|
|
|
|
|
|
|
|
|
|
**类型**: `module`
|
|
|
|
|
|
|
2026-03-27 19:18:53 +08:00
|
|
|
|
**描述**: 提供音频系统、输出后端、基础混音器、效果器和音频通用类型定义。
|
2026-03-26 16:45:24 +08:00
|
|
|
|
|
|
|
|
|
|
## 概览
|
|
|
|
|
|
|
2026-03-27 19:18:53 +08:00
|
|
|
|
`XCEngine::Audio` 是当前引擎音频运行时的基础模块。它的核心主链路比较明确：
|
|
|
|
|
|
|
|
|
|
|
|
- [AudioSourceComponent](../Components/AudioSourceComponent/AudioSourceComponent.md) 在组件层负责音频片段解码与源级播放状态。
|
|
|
|
|
|
- [AudioSystem](AudioSystem/AudioSystem.md) 负责维护全局监听器状态、活跃音频源列表和每帧混音入口。
|
|
|
|
|
|
- [IAudioBackend](IAudioBackend/IAudioBackend.md) / [WASAPIBackend](WindowsAudioBackend/WindowsAudioBackend.md) 负责把浮点混音结果交给平台输出。
|
|
|
|
|
|
|
|
|
|
|
|
同时，这个模块里还定义了 [AudioMixer](AudioMixer/AudioMixer.md)、[Equalizer](Equalizer/Equalizer.md)、[FFTFilter](FFTFilter/FFTFilter.md)、[HRTF](HRTF/HRTF.md)、[Reverbation](Reverbation/Reverbation.md) 等构件。但按当前源码取证，它们更多属于“基础能力和扩展点”，并没有全部接入当前的全局播放主链路。
|
|
|
|
|
|
|
|
|
|
|
|
## 设计理解
|
|
|
|
|
|
|
|
|
|
|
|
从设计方向看，这个模块明显是朝“Unity 风格的 `AudioSource + AudioListener + AudioMixer`”体系靠拢的：
|
|
|
|
|
|
|
|
|
|
|
|
- 场景对象负责挂载和空间关系。
|
|
|
|
|
|
- 全局音频系统负责设备与混音调度。
|
|
|
|
|
|
- 效果器和 mixer 负责后续音频处理扩展。
|
|
|
|
|
|
|
|
|
|
|
|
这种组织方式的好处是脚本层和编辑器层都容易理解，也便于以后逐步扩展到更完整的商用引擎音频架构。代价是当前版本里，很多接口形状已经有了，但接线成熟度并不一致，文档必须明确区分“已在主链路生效”和“当前只存值/基础实现”。
|
|
|
|
|
|
|
|
|
|
|
|
## 当前主链路
|
|
|
|
|
|
|
|
|
|
|
|
按当前实现，比较真实的运行路径是：
|
|
|
|
|
|
|
|
|
|
|
|
1. `AudioSourceComponent` 在 `Play()` 时向 `AudioSystem` 注册自己。
|
|
|
|
|
|
2. `AudioSystem::Update()` 遍历活跃音频源，把它们混到一个浮点 buffer。
|
|
|
|
|
|
3. `AudioSystem` 把结果交给当前 `IAudioBackend`。
|
|
|
|
|
|
4. 内建 Windows 后端把浮点样本转换为 `int16` 并交给系统音频输出。
|
|
|
|
|
|
|
|
|
|
|
|
需要特别注意的是：
|
|
|
|
|
|
|
|
|
|
|
|
- [AudioMixer](AudioMixer/AudioMixer.md) 当前没有被这条主链路自动调用。
|
|
|
|
|
|
- [Equalizer](Equalizer/Equalizer.md)、[FFTFilter](FFTFilter/FFTFilter.md)、[HRTF](HRTF/HRTF.md)、[Reverbation](Reverbation/Reverbation.md) 也没有自动接到全局 playback path。
|
|
|
|
|
|
- 所以这些类型不能直接按“已经等同 Unity Audio Mixer / 完整 DSP graph”理解。
|
|
|
|
|
|
|
|
|
|
|
|
## 当前实现边界
|
|
|
|
|
|
|
|
|
|
|
|
- 默认后端是 Windows 专用实现；`AudioSystem::Initialize()` 当前直接创建 `WASAPI::WASAPIBackend`。
|
|
|
|
|
|
- 尽管类名叫 `WASAPIBackend`，但当前实现实际使用的是 `waveOut*` WinMM API，而不是 Core Audio WASAPI COM 接口。
|
|
|
|
|
|
- `AudioSystem::Stats` 里只有 `activeSources` 和 `totalSources` 在当前实现中被更新，`memoryUsage` 和 `cpuUsage` 仍是占位字段。
|
|
|
|
|
|
- 公开的 mixer / effect / spatialization 类型已经存在，但并未完整串入全局混音图。
|
|
|
|
|
|
- 当前测试覆盖主要集中在 `Resources::AudioClip`，`Audio` 模块核心类型本身缺少直接单元测试。
|
2026-03-26 16:45:24 +08:00
|
|
|
|
|
|
|
|
|
|
## 头文件
|
|
|
|
|
|
|
2026-03-27 19:18:53 +08:00
|
|
|
|
- [AudioConfig](AudioConfig/AudioConfig.md) - `AudioConfig.h`，输出设备初始化配置。
|
|
|
|
|
|
- [AudioMixer](AudioMixer/AudioMixer.md) - `AudioMixer.h`，基础 mixer 容器与效果链扩展点。
|
|
|
|
|
|
- [AudioSystem](AudioSystem/AudioSystem.md) - `AudioSystem.h`，全局音频系统入口。
|
|
|
|
|
|
- [AudioTypes](AudioTypes/AudioTypes.md) - `AudioTypes.h`，音频通用枚举和参数结构。
|
|
|
|
|
|
- [Equalizer](Equalizer/Equalizer.md) - `Equalizer.h`，多段均衡器效果。
|
|
|
|
|
|
- [FFTFilter](FFTFilter/FFTFilter.md) - `FFTFilter.h`，FFT 频谱分析型处理器。
|
|
|
|
|
|
- [HRTF](HRTF/HRTF.md) - `HRTF.h`，简化双耳空间化处理器。
|
|
|
|
|
|
- [IAudioBackend](IAudioBackend/IAudioBackend.md) - `IAudioBackend.h`，平台输出后端接口。
|
|
|
|
|
|
- [IAudioEffect](IAudioEffect/IAudioEffect.md) - `IAudioEffect.h`，效果器通用接口。
|
|
|
|
|
|
- [Reverbation](Reverbation/Reverbation.md) - `Reverbation.h`，基础混响效果。
|
|
|
|
|
|
- [WASAPIBackend](WindowsAudioBackend/WindowsAudioBackend.md) - `WindowsAudioBackend.h`，当前内建 Windows 输出后端类型。
|
|
|
|
|
|
|
|
|
|
|
|
## 相关指南
|
|
|
|
|
|
|
|
|
|
|
|
- [Audio System And Effect Chain](../../_guides/Audio/Audio-System-And-Effect-Chain.md) - 解释当前音频主链路、与 Unity 风格系统的对应关系，以及 mixer/effect 为什么暂时还没完全接入。
|
2026-03-26 16:45:24 +08:00
|
|
|
|
|
|
|
|
|
|
## 相关文档
|
|
|
|
|
|
|
|
|
|
|
|
- [上级目录](../XCEngine.md)
|
2026-03-27 19:18:53 +08:00
|
|
|
|
- [AudioSourceComponent](../Components/AudioSourceComponent/AudioSourceComponent.md)
|
|
|
|
|
|
- [AudioListenerComponent](../Components/AudioListenerComponent/AudioListenerComponent.md)
|
2026-03-26 16:45:24 +08:00
|
|
|
|
- [API 总索引](../../main.md)
|
