90 lines
3.2 KiB
Markdown
90 lines
3.2 KiB
Markdown
# IAudioBackend
|
|
|
|
**命名空间**: `XCEngine::Audio`
|
|
|
|
**类型**: `class (interface)`
|
|
|
|
**头文件**: `XCEngine/Audio/IAudioBackend.h`
|
|
|
|
**描述**: 定义平台音频输出后端的抽象接口，让 `AudioSystem` 能以统一方式控制设备、音量、静音和样本提交。
|
|
|
|
## 角色概述
|
|
|
|
`IAudioBackend` 把平台相关的设备枚举、设备切换、播放线程和最终样本输出从 [AudioSystem](../AudioSystem/AudioSystem.md) 中分离出来。这样做的主要收益是：
|
|
|
|
- 音频系统可以保持统一的上层入口
|
|
- 平台后端可以独立替换
|
|
- Windows、未来的其他平台或测试后端都可以复用同一套调用形状
|
|
|
|
## 接口契约
|
|
|
|
当前接口主要分成四组：
|
|
|
|
- 生命周期: `Initialize()`、`Shutdown()`、`Start()`、`Stop()`、`Suspend()`、`Resume()`
|
|
- 设备管理: `GetDeviceName()`、`GetAvailableDevices()`、`SetDevice()`
|
|
- 全局控制: `GetMasterVolume()`、`SetMasterVolume()`、`IsMuted()`、`SetMuted()`
|
|
- 音频提交: `ProcessAudio()`、`IsRunning()`、`GetConfig()`
|
|
|
|
从设计上说，这是一层典型的 runtime backend 抽象，而不是资源加载接口或效果器接口。
|
|
|
|
## 当前实现语境
|
|
|
|
在当前代码库里，已取证到的内建实现只有 [WASAPIBackend](../WindowsAudioBackend/WindowsAudioBackend.md)。
|
|
|
|
因此，这个接口虽然是跨平台抽象形状，但当前落地能力仍然以 Windows 输出为中心。
|
|
|
|
## `ProcessAudio()` 的现实语义
|
|
|
|
这是当前接口里最需要谨慎理解的一个方法。
|
|
|
|
签名是：
|
|
|
|
```cpp
|
|
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](Initialize.md)
|
|
- [Shutdown](Shutdown.md)
|
|
- [GetDeviceName](GetDeviceName.md)
|
|
- [GetAvailableDevices](GetAvailableDevices.md)
|
|
- [SetDevice](SetDevice.md)
|
|
- [GetMasterVolume](GetMasterVolume.md)
|
|
- [SetMasterVolume](SetMasterVolume.md)
|
|
- [IsMuted](IsMuted.md)
|
|
- [SetMuted](SetMuted.md)
|
|
- [Start](Start.md)
|
|
- [Stop](Stop.md)
|
|
- [Suspend](Suspend.md)
|
|
- [Resume](Resume.md)
|
|
- [ProcessAudio](ProcessAudio.md)
|
|
- [IsRunning](IsRunning.md)
|
|
- [GetConfig](GetConfig.md)
|
|
|
|
## 相关文档
|
|
|
|
- [当前模块](../Audio.md)
|
|
- [AudioSystem](../AudioSystem/AudioSystem.md)
|
|
- [WASAPIBackend](../WindowsAudioBackend/WindowsAudioBackend.md)
|
|
- [API 总索引](../../../main.md)
|