3.2 KiB
3.2 KiB
IAudioBackend
命名空间: XCEngine::Audio
类型: class (interface)
头文件: XCEngine/Audio/IAudioBackend.h
描述: 定义平台音频输出后端的抽象接口，让 AudioSystem 能以统一方式控制设备、音量、静音和样本提交。
角色概述
IAudioBackend 把平台相关的设备枚举、设备切换、播放线程和最终样本输出从 AudioSystem 中分离出来。这样做的主要收益是：
- 音频系统可以保持统一的上层入口
- 平台后端可以独立替换
- Windows、未来的其他平台或测试后端都可以复用同一套调用形状
接口契约
当前接口主要分成四组：
- 生命周期:
Initialize()、Shutdown()、Start()、Stop()、Suspend()、Resume() - 设备管理:
GetDeviceName()、GetAvailableDevices()、SetDevice() - 全局控制:
GetMasterVolume()、SetMasterVolume()、IsMuted()、SetMuted() - 音频提交:
ProcessAudio()、IsRunning()、GetConfig()
从设计上说，这是一层典型的 runtime backend 抽象，而不是资源加载接口或效果器接口。
当前实现语境
在当前代码库里，已取证到的内建实现只有 WASAPIBackend。
因此，这个接口虽然是跨平台抽象形状，但当前落地能力仍然以 Windows 输出为中心。
ProcessAudio() 的现实语义
这是当前接口里最需要谨慎理解的一个方法。
签名是：
void ProcessAudio(float* buffer, uint32 bufferSize, uint32 channels, uint32 sampleRate);
从命名上看，bufferSize 像是“缓冲大小”；但在当前调用路径里：
AudioSystem::Update()把“浮点样本数量”传给它WASAPIBackend::ProcessAudio()却按“字节大小”去做bufferSize / sizeof(float)计算
这说明当前接口的 buffer size 语义还没有完全收敛成稳定契约。文档不应把它描述成已经完全明确且无歧义的规范。
线程语义
接口本身没有声明线程模型，也没有提供同步保证。具体线程行为完全取决于实现类。
例如当前 Windows 实现会自己维护后台线程和回调；但这不代表所有 IAudioBackend 实现都必须采用同样模型。
当前实现限制
- 当前只有 Windows 内建实现。
ProcessAudio()的bufferSize语义在当前调用方和实现方之间存在不一致。- 文档范围内没有发现专门针对该接口契约的测试后端或 mock backend。
相关方法
- Initialize
- Shutdown
- GetDeviceName
- GetAvailableDevices
- SetDevice
- GetMasterVolume
- SetMasterVolume
- IsMuted
- SetMuted
- Start
- Stop
- Suspend
- Resume
- ProcessAudio
- IsRunning
- GetConfig