2026-03-26 16:45:24 +08:00
|
|
|
|
# AudioMixer
|
|
|
|
|
|
|
|
|
|
|
|
**命名空间**: `XCEngine::Audio`
|
|
|
|
|
|
|
|
|
|
|
|
**类型**: `class`
|
|
|
|
|
|
|
|
|
|
|
|
**头文件**: `XCEngine/Audio/AudioMixer.h`
|
|
|
|
|
|
|
2026-03-27 19:18:53 +08:00
|
|
|
|
**描述**: 表示一个基础 mixer 容器，公开了总音量、静音、效果链、输出 mixer 和 3D 参数等混音控制接口。
|
|
|
|
|
|
|
|
|
|
|
|
## 角色概述
|
|
|
|
|
|
|
|
|
|
|
|
从 API 形状看，`AudioMixer` 明显是为更完整的音频路由系统预留的核心类型。它的设计方向和 Unity `AudioMixer` 概念相似：
|
|
|
|
|
|
|
|
|
|
|
|
- 可以挂效果器
|
|
|
|
|
|
- 可以连接到另一个 output mixer
|
|
|
|
|
|
- 可以保存 3D 参数和每声道音量
|
|
|
|
|
|
|
|
|
|
|
|
但按当前实现，它还处在比较早期的基础阶段。
|
|
|
|
|
|
|
|
|
|
|
|
## 当前实现行为
|
|
|
|
|
|
|
|
|
|
|
|
### 1. 真实生效的部分很少
|
|
|
|
|
|
|
|
|
|
|
|
`ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels)` 当前实际做的事情只有：
|
|
|
|
|
|
|
|
|
|
|
|
- 如果静音，则等效音量为 `0`
|
|
|
|
|
|
- 如果总音量接近 0，则直接返回
|
|
|
|
|
|
- 否则对整个 buffer 乘以一个全局音量系数
|
|
|
|
|
|
|
|
|
|
|
|
也就是说，当前 mixer 的实际生效能力基本只有：
|
|
|
|
|
|
|
|
|
|
|
|
- 总音量
|
|
|
|
|
|
- 总静音
|
|
|
|
|
|
|
|
|
|
|
|
### 2. 效果链目前只存，不处理
|
|
|
|
|
|
|
|
|
|
|
|
`AddEffect()` / `RemoveEffect()` / `ClearEffects()` 会维护 `m_effects` 容器，但 `ProcessAudio()` 当前并不会遍历效果器并调用它们的 `ProcessAudio()`。
|
|
|
|
|
|
|
|
|
|
|
|
这意味着效果链 API 已经有了，但主处理逻辑还没接上。
|
|
|
|
|
|
|
|
|
|
|
|
### 3. 其他配置当前主要是存值
|
|
|
|
|
|
|
|
|
|
|
|
以下状态当前也只是被保存下来：
|
|
|
|
|
|
|
|
|
|
|
|
- `m_outputMixer`
|
|
|
|
|
|
- `m_3DParams`
|
|
|
|
|
|
- `m_channelVolumes`
|
|
|
|
|
|
|
|
|
|
|
|
按当前源码，没有看到它们在 `ProcessAudio()` 里被真正使用。
|
|
|
|
|
|
|
|
|
|
|
|
## 所有权语义
|
|
|
|
|
|
|
|
|
|
|
|
- `AudioMixer` 不拥有 `IAudioEffect*`
|
|
|
|
|
|
- `AddEffect()` 只保存裸指针
|
|
|
|
|
|
- `ClearEffects()` 只清空容器，不负责销毁 effect 实例
|
|
|
|
|
|
|
|
|
|
|
|
因此，效果器实例的生命周期需要由外部系统管理。
|
|
|
|
|
|
|
|
|
|
|
|
## 设计理解
|
|
|
|
|
|
|
|
|
|
|
|
这类设计在商用引擎里通常是合理的：先把 mixer、route、effect slot 的抽象搭起来，再逐步接线具体 DSP 逻辑。当前版本的问题不在于接口方向，而在于“多数字段已经存在，但还没被处理路径消费”。
|
|
|
|
|
|
|
|
|
|
|
|
## 线程语义
|
|
|
|
|
|
|
|
|
|
|
|
- 当前实现没有内部加锁。
|
|
|
|
|
|
- 效果链和参数更新默认应按主线程配置路径使用。
|
|
|
|
|
|
|
|
|
|
|
|
## 当前实现限制
|
|
|
|
|
|
|
|
|
|
|
|
- 效果器链当前不会被执行。
|
|
|
|
|
|
- `outputMixer` 当前不会形成真正的级联混音图。
|
|
|
|
|
|
- `Audio3DParams` 当前不会直接影响 mixer 输出。
|
|
|
|
|
|
- 每声道音量只被存储，没有应用到样本处理。
|
|
|
|
|
|
- `ChannelVolume` 结构里的 `mute` 字段当前既无 public setter，也无处理路径消费。
|
|
|
|
|
|
- 没有发现该类型的直接单元测试。
|
|
|
|
|
|
|
|
|
|
|
|
## 相关方法
|
|
|
|
|
|
|
|
|
|
|
|
- [Constructor](Constructor.md)
|
|
|
|
|
|
- [Destructor](Destructor.md)
|
|
|
|
|
|
- [SetVolume](SetVolume.md)
|
|
|
|
|
|
- [GetVolume](GetVolume.md)
|
|
|
|
|
|
- [SetMute](SetMute.md)
|
|
|
|
|
|
- [IsMute](IsMute.md)
|
|
|
|
|
|
- [AddEffect](AddEffect.md)
|
|
|
|
|
|
- [RemoveEffect](RemoveEffect.md)
|
|
|
|
|
|
- [ClearEffects](ClearEffects.md)
|
|
|
|
|
|
- [ProcessAudio](ProcessAudio.md)
|
|
|
|
|
|
- [SetOutputMixer](SetOutputMixer.md)
|
|
|
|
|
|
- [GetOutputMixer](GetOutputMixer.md)
|
|
|
|
|
|
- [Set3DParams](Set3DParams.md)
|
|
|
|
|
|
- [Get3DParams](Get3DParams.md)
|
|
|
|
|
|
- [SetChannelVolume](SetChannelVolume.md)
|
|
|
|
|
|
- [GetChannelVolume](GetChannelVolume.md)
|
|
|
|
|
|
|
|
|
|
|
|
## 相关指南
|
|
|
|
|
|
|
|
|
|
|
|
- [Audio System And Effect Chain](../../../_guides/Audio/Audio-System-And-Effect-Chain.md)
|
2026-03-26 16:45:24 +08:00
|
|
|
|
|
|
|
|
|
|
## 相关文档
|
|
|
|
|
|
|
2026-03-27 19:18:53 +08:00
|
|
|
|
- [当前模块](../Audio.md)
|
|
|
|
|
|
- [IAudioEffect](../IAudioEffect/IAudioEffect.md)
|
|
|
|
|
|
- [AudioSystem](../AudioSystem/AudioSystem.md)
|
|
|
|
|
|
- [API 总索引](../../../main.md)
|
