4.6 KiB
4.6 KiB
Audio
命名空间: XCEngine::Audio
类型: module
描述: 提供音频系统、输出后端、基础混音器、效果器和音频通用类型定义。
概览
XCEngine::Audio 是当前引擎音频运行时的基础模块。它的核心主链路比较明确：
- AudioSourceComponent 在组件层负责音频片段解码与源级播放状态。
- AudioSystem 负责维护全局监听器状态、活跃音频源列表和每帧混音入口。
- IAudioBackend / WASAPIBackend 负责把浮点混音结果交给平台输出。
同时，这个模块里还定义了 AudioMixer、Equalizer、FFTFilter、HRTF、Reverbation 等构件。但按当前源码取证，它们更多属于“基础能力和扩展点”，并没有全部接入当前的全局播放主链路。
设计理解
从设计方向看，这个模块明显是朝“Unity 风格的 AudioSource + AudioListener + AudioMixer”体系靠拢的：
- 场景对象负责挂载和空间关系。
- 全局音频系统负责设备与混音调度。
- 效果器和 mixer 负责后续音频处理扩展。
这种组织方式的好处是脚本层和编辑器层都容易理解，也便于以后逐步扩展到更完整的商用引擎音频架构。代价是当前版本里，很多接口形状已经有了，但接线成熟度并不一致，文档必须明确区分“已在主链路生效”和“当前只存值/基础实现”。
当前主链路
按当前实现，比较真实的运行路径是：
AudioSourceComponent在Play()时向AudioSystem注册自己。AudioSystem::Update()遍历活跃音频源，把它们混到一个浮点 buffer。AudioSystem把结果交给当前IAudioBackend。- 内建 Windows 后端把浮点样本转换为
int16并交给系统音频输出。
需要特别注意的是：
- AudioMixer 当前没有被这条主链路自动调用。
- Equalizer、FFTFilter、HRTF、Reverbation 也没有自动接到全局 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模块核心类型本身缺少直接单元测试。
头文件
- AudioConfig -
AudioConfig.h，输出设备初始化配置。 - AudioMixer -
AudioMixer.h，基础 mixer 容器与效果链扩展点。 - AudioSystem -
AudioSystem.h，全局音频系统入口。 - AudioTypes -
AudioTypes.h，音频通用枚举和参数结构。 - Equalizer -
Equalizer.h，多段均衡器效果。 - FFTFilter -
FFTFilter.h，FFT 频谱分析型处理器。 - HRTF -
HRTF.h，简化双耳空间化处理器。 - IAudioBackend -
IAudioBackend.h，平台输出后端接口。 - IAudioEffect -
IAudioEffect.h，效果器通用接口。 - Reverbation -
Reverbation.h，基础混响效果。 - WASAPIBackend -
WindowsAudioBackend.h，当前内建 Windows 输出后端类型。
相关指南
- Audio System And Effect Chain - 解释当前音频主链路、与 Unity 风格系统的对应关系，以及 mixer/effect 为什么暂时还没完全接入。