xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加 Audio 模块和 Components 模块 API 文档

Browse Source 
- 新增 Audio 模块文档 (54 个文件)
  - AudioSystem 单例类及 20 个方法页
  - AudioMixer 混音器类及 11 个方法页
  - IAudioBackend、IAudioEffect 接口
  - FFTFilter、Reverbation、Equalizer、HRTF 效果类
  - WASAPIBackend Windows 后端
  - AudioConfig、Audio3DParams 等结构体
  - 9 个枚举类型文档
- 新增 Components 模块文档 (3 个文件)
  - AudioSourceComponent 音频源组件
  - AudioListenerComponent 音频监听器组件
- 更新 docs/api/main.md 添加模块导航
This commit is contained in:
ssdfasd
2026-03-22 01:56:16 +08:00
parent 6e5ed41fbf
commit 161a0896d5
58 changed files with 1990 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/api/audio/audio-3d-params/audio-3d-params.md Normal file
View File

@@ -0,0 +1,46 @@
# Audio3DParams
**命名空间**: `XCEngine::Audio`
**类型**: `struct`
**头文件**: `XCEngine/Audio/AudioTypes.h`
**描述**: 3D 空间化音频参数。
## 结构体成员
| 成员 | 类型 | 描述 | 默认值 |
|------|------|------|--------|
| `dopplerLevel` | `float` | 多普勒效应等级，0.0=禁用，1.0=正常 | `1.0f` |
| `speedOfSound` | `float` | 声速（米/秒） | `343.0f` |
| `minDistance` | `float` | 最小衰减距离（米） | `1.0f` |
| `maxDistance` | `float` | 最大衰减距离（米） | `500.0f` |
| `panLevel` | `float` | 声像等级，0.0=无 3D，1.0=完全 3D | `1.0f` |
| `spread` | `float` | 声源展开角度（度） | `0.0f` |
| `reverbZoneMix` | `float` | 混响区域混合比例 | `1.0f` |
## 使用示例
```cpp
#include <XCEngine/Audio/AudioTypes.h>
using namespace XCEngine::Audio;
Audio3DParams CreateOutdoorParams() {
Audio3DParams params;
params.dopplerLevel = 1.0f;
params.speedOfSound = 343.0f;
params.minDistance = 1.0f;
params.maxDistance = 1000.0f;
params.panLevel = 1.0f;
params.spread = 0.0f;
params.reverbZoneMix = 0.5f;
return params;
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [AudioMixer](../audio-mixer/audio-mixer.md) - 音频混音器

25
docs/api/audio/audio-buffer-desc/audio-buffer-desc.md Normal file
View File

@@ -0,0 +1,25 @@
# AudioBufferDesc
**命名空间**: `XCEngine::Audio`
**类型**: `struct`
**头文件**: `XCEngine/Audio/AudioTypes.h`
**描述**: 音频缓冲区描述符。
## 结构体成员
| 成员 | 类型 | 描述 | 默认值 |
|------|------|------|--------|
| `size` | `uint32_t` | 缓冲区大小（字节） | `0` |
| `channels` | `uint32_t` | 通道数 | `2` |
| `sampleRate` | `uint32_t` | 采样率（Hz） | `48000` |
| `bitsPerSample` | `uint16_t` | 位深度 | `16` |
| `isFloat` | `bool` | 是否为浮点格式 | `false` |
| `isCompressed` | `bool` | 是否为压缩格式 | `false` |
| `format` | `AudioFormat` | 音频格式 | `AudioFormat::Unknown` |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

44
docs/api/audio/audio-config/audio-config.md Normal file
View File

@@ -0,0 +1,44 @@
# AudioConfig
**命名空间**: `XCEngine::Audio`
**类型**: `struct`
**头文件**: `XCEngine/Audio/AudioConfig.h`
**描述**: 音频系统配置参数。
## 结构体成员
| 成员 | 类型 | 描述 | 默认值 |
|------|------|------|--------|
| `sampleRate` | `uint32_t` | 采样率（Hz），常用值：44100, 48000 | `48000` |
| `channels` | `uint16_t` | 通道数，1=单声道，2=立体声 | `2` |
| `bitsPerSample` | `uint16_t` | 位深度，常用值：16, 24, 32 | `16` |
| `speakerMode` | `SpeakerMode` | 扬声器模式 | `SpeakerMode::Stereo` |
| `bufferSize` | `uint32_t` | 音频缓冲区大小（样本数） | `8192` |
| `bufferCount` | `uint32_t` | 缓冲区数量 | `2` |
## 使用示例
```cpp
#include <XCEngine/Audio/AudioConfig.h>
using namespace XCEngine::Audio;
AudioConfig CreateHighQualityConfig() {
AudioConfig config;
config.sampleRate = 48000;
config.channels = 2;
config.bitsPerSample = 24;
config.speakerMode = SpeakerMode::Stereo;
config.bufferSize = 4096;
config.bufferCount = 4;
return config;
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [AudioSystem](../audio-system/audio-system.md) - 音频系统

17
docs/api/audio/audio-mixer/add-effect.md Normal file
View File

@@ -0,0 +1,17 @@
# AudioMixer::AddEffect
添加音频效果到效果链。
```cpp
void AddEffect(IAudioEffect* effect);
```
效果按添加顺序依次处理音频数据。
**参数：**
- `effect` - IAudioEffect 指针，混音器不拥有效果对象的所有权
## 相关文档
- [AudioMixer 总览](audio-mixer.md)
- [RemoveEffect](remove-effect.md)

69
docs/api/audio/audio-mixer/audio-mixer.md Normal file
View File

@@ -0,0 +1,69 @@
# AudioMixer
**命名空间**: `XCEngine::Audio`
**类型**: `class`
**头文件**: `XCEngine/Audio/AudioMixer.h`
**描述**: 音频混音器，管理效果链、通道音量和 3D 空间化参数。
## 概述
AudioMixer 是 XCEngine 音频模块中的混音器类，负责将多个音频效果串联处理、管理通道音量和 3D 空间化参数。混音器支持添加或移除 IAudioEffect 效果（如 Reverbation、Equalizer、FFTFilter），支持输出到父混音器形成混音树结构。
## 公共方法
| 方法 | 描述 |
|------|------|
| [`AudioMixer`](constructor.md) | 构造函数 |
| [`~AudioMixer`](destructor.md) | 析构函数 |
| [`SetVolume`](set-volume.md) | 设置混音器音量 |
| [`GetVolume`](get-volume.md) | 获取混音器音量 |
| [`SetMute`](set-mute.md) | 设置静音状态 |
| [`IsMute`](is-mute.md) | 检查静音状态 |
| [`AddEffect`](add-effect.md) | 添加音频效果 |
| [`RemoveEffect`](remove-effect.md) | 移除音频效果 |
| [`ClearEffects`](clear-effects.md) | 清除所有效果 |
| [`ProcessAudio`](process-audio.md) | 处理音频数据 |
| [`SetOutputMixer`](set-output-mixer.md) | 设置输出混音器 |
| [`GetOutputMixer`](get-output-mixer.md) | 获取输出混音器 |
| [`Set3DParams`](set-3d-params.md) | 设置 3D 空间化参数 |
| [`Get3DParams`](get-3d-params.md) | 获取 3D 空间化参数 |
| [`SetChannelVolume`](set-channel-volume.md) | 设置通道音量 |
| [`GetChannelVolume`](get-channel-volume.md) | 获取通道音量 |
## 使用示例
```cpp
#include <XCEngine/Audio/AudioMixer.h>
#include <XCEngine/Audio/Reverbation.h>
#include <XCEngine/Audio/Equalizer.h>
using namespace XCEngine::Audio;
void SetupMixerWithEffects() {
AudioMixer* mixer = new AudioMixer();
mixer->SetVolume(0.8f);
Reverbation* reverb = new Reverbation();
reverb->SetRoomSize(0.5f);
reverb->SetWetMix(0.3f);
Equalizer* eq = new Equalizer();
eq->SetBandCount(4);
mixer->AddEffect(eq);
mixer->AddEffect(reverb);
}
void RouteToParentMixer(AudioMixer* child, AudioMixer* parent) {
child->SetOutputMixer(parent);
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [IAudioEffect](../i-audio-effect/i-audio-effect.md) - 音频效果接口
- [Audio3DParams](../audio-3d-params/audio-3d-params.md) - 3D 空间化参数

12
docs/api/audio/audio-mixer/clear-effects.md Normal file
View File

@@ -0,0 +1,12 @@
# AudioMixer::ClearEffects
清除效果链中的所有音频效果。
```cpp
void ClearEffects();
```
## 相关文档
- [AudioMixer 总览](audio-mixer.md)
- [AddEffect](add-effect.md)

16
docs/api/audio/audio-mixer/get-channel-volume.md Normal file
View File

@@ -0,0 +1,16 @@
# AudioMixer::GetChannelVolume
获取指定音频通道的音量。
```cpp
float GetChannelVolume(AudioChannel channel) const;
```
**参数：**
- `channel` - 音频通道枚举值
**返回：** `float` - 通道音量值
## 相关文档
- [AudioMixer 总览](audio-mixer.md)

16
docs/api/audio/audio-mixer/process-audio.md Normal file
View File

@@ -0,0 +1,16 @@
# AudioMixer::ProcessAudio
处理音频数据，应用所有效果和音量。
```cpp
void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels);
```
**参数：**
- `buffer` - 音频缓冲区指针
- `sampleCount` - 样本数量
- `channels` - 通道数
## 相关文档
- [AudioMixer 总览](audio-mixer.md)

15
docs/api/audio/audio-mixer/remove-effect.md Normal file
View File

@@ -0,0 +1,15 @@
# AudioMixer::RemoveEffect
从效果链移除音频效果。
```cpp
void RemoveEffect(IAudioEffect* effect);
```
**参数：**
- `effect` - 要移除的 IAudioEffect 指针
## 相关文档
- [AudioMixer 总览](audio-mixer.md)
- [AddEffect](add-effect.md)

15
docs/api/audio/audio-mixer/set-3d-params.md Normal file
View File

@@ -0,0 +1,15 @@
# AudioMixer::Set3DParams
设置 3D 空间化参数。
```cpp
void Set3DParams(const Audio3DParams& params);
```
**参数：**
- `params` - 3D 空间化参数结构体引用
## 相关文档
- [AudioMixer 总览](audio-mixer.md)
- [Audio3DParams](../audio-3d-params/audio-3d-params.md)

15
docs/api/audio/audio-mixer/set-channel-volume.md Normal file
View File

@@ -0,0 +1,15 @@
# AudioMixer::SetChannelVolume
设置指定音频通道的音量。
```cpp
void SetChannelVolume(AudioChannel channel, float volume);
```
**参数：**
- `channel` - 音频通道枚举值
- `volume` - 音量值，有效范围 [0.0, 1.0]
## 相关文档
- [AudioMixer 总览](audio-mixer.md)

15
docs/api/audio/audio-mixer/set-mute.md Normal file
View File

@@ -0,0 +1,15 @@
# AudioMixer::SetMute
设置混音器静音状态。
```cpp
void SetMute(bool mute);
```
**参数：**
- `mute` - true 为启用静音，false 为禁用静音
## 相关文档
- [AudioMixer 总览](audio-mixer.md)
- [IsMute](is-mute.md)

16
docs/api/audio/audio-mixer/set-output-mixer.md Normal file
View File

@@ -0,0 +1,16 @@
# AudioMixer::SetOutputMixer
设置输出混音器。
```cpp
void SetOutputMixer(AudioMixer* mixer);
```
设置父混音器，处理后的音频将输出到父混音器进行进一步混音。
**参数：**
- `mixer` - 父混音器指针，nullptr 表示直接输出到后端
## 相关文档
- [AudioMixer 总览](audio-mixer.md)

15
docs/api/audio/audio-mixer/set-volume.md Normal file
View File

@@ -0,0 +1,15 @@
# AudioMixer::SetVolume
设置混音器音量。
```cpp
void SetVolume(float volume);
```
**参数：**
- `volume` - 音量值，有效范围 [0.0, 1.0]
## 相关文档
- [AudioMixer 总览](audio-mixer.md)
- [GetVolume](get-volume.md)

88
docs/api/audio/audio-system/audio-system.md Normal file
View File

@@ -0,0 +1,88 @@
# AudioSystem
**命名空间**: `XCEngine::Audio`
**类型**: `class (singleton)`
**头文件**: `XCEngine/Audio/AudioSystem.h`
**描述**: 音频系统单例，管理所有音频源、音频后端和监听器状态。
## 概述
AudioSystem 是 XCEngine 音频模块的核心单例类，负责管理整个音频子系统的生命周期。它维护音频监听器（listener）的 3D 变换和速度信息，注册和管理所有活动的音频源（AudioSourceComponent），并通过配置的 IAudioBackend 实现进行实际的音频输出。AudioSystem 每帧调用 Update 方法处理音频源的 3D 空间化计算和混音。
## 单例访问
| 方法 | 描述 |
|------|------|
| `static AudioSystem& Get()` | 获取音频系统单例实例 |
## 公共方法
| 方法 | 描述 |
|------|------|
| [`Initialize`](initialize.md) | 初始化音频系统 |
| [`Shutdown`](shutdown.md) | 关闭音频系统 |
| [`Update`](update.md) | 每帧更新音频系统状态 |
| [`SetBackend`](set-backend.md) | 设置音频后端实现 |
| [`GetBackend`](get-backend.md) | 获取当前音频后端 |
| [`GetCurrentDevice`](get-current-device.md) | 获取当前音频设备名称 |
| [`SetDevice`](set-device.md) | 设置音频设备 |
| [`GetAvailableDevices`](get-available-devices.md) | 获取可用音频设备列表 |
| [`GetMasterVolume`](get-master-volume.md) | 获取主音量 |
| [`SetMasterVolume`](set-master-volume.md) | 设置主音量 |
| [`IsMuted`](is-muted.md) | 检查是否静音 |
| [`SetMuted`](set-muted.md) | 设置静音状态 |
| [`ProcessAudio`](process-audio.md) | 处理音频数据 |
| [`SetListenerTransform`](set-listener-transform.md) | 设置监听器变换 |
| [`SetListenerVelocity`](set-listener-velocity.md) | 设置监听器速度 |
| [`GetListenerPosition`](get-listener-position.md) | 获取监听器位置 |
| [`GetListenerRotation`](get-listener-rotation.md) | 获取监听器旋转 |
| [`GetListenerVelocity`](get-listener-velocity.md) | 获取监听器速度 |
| [`RegisterSource`](register-source.md) | 注册音频源 |
| [`UnregisterSource`](unregister-source.md) | 注销音频源 |
| [`GetStats`](get-stats.md) | 获取音频系统统计信息 |
## 内部方法
| 方法 | 描述 |
|------|------|
| `ProcessSource()` | 处理单个音频源的音频数据（私有） |
## 使用示例
```cpp
#include <XCEngine/Audio/AudioSystem.h>
#include <XCEngine/Audio/WASAPI/WASAPIBackend.h>
using namespace XCEngine::Audio;
void SetupAudio() {
AudioConfig config;
config.sampleRate = 48000;
config.channels = 2;
config.bitsPerSample = 16;
config.speakerMode = SpeakerMode::Stereo;
AudioSystem::Get().SetBackend(std::make_unique<WASAPIBackend>());
AudioSystem::Get().Initialize(config);
}
void GameLoop(float deltaTime) {
Math::Vector3 listenerPos = mainCamera->GetPosition();
Math::Quaternion listenerRot = mainCamera->GetRotation();
AudioSystem::Get().SetListenerTransform(listenerPos, listenerRot);
AudioSystem::Get().Update(deltaTime);
}
void CleanupAudio() {
AudioSystem::Get().Shutdown();
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [IAudioBackend](../i-audio-backend/i-audio-backend.md) - 音频后端接口
- [AudioConfig](../audio-config/audio-config.md) - 音频配置

34
docs/api/audio/audio-system/get-available-devices.md Normal file
View File

@@ -0,0 +1,34 @@
# AudioSystem::GetAvailableDevices
获取可用音频设备列表。
```cpp
void GetAvailableDevices(std::vector<std::string>& devices);
```
填充传入的 vector，获取系统中所有可用的音频输出设备列表。
**参数：**
- `devices` - 用于存储设备名称列表的 vector引用
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void ListAudioDevices() {
std::vector<std::string> devices;
AudioSystem::Get().GetAvailableDevices(devices);
for (size_t i = 0; i < devices.size(); ++i) {
printf("Device %zu: %s\n", i, devices[i].c_str());
}
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [SetDevice](set-device.md) - 设置音频设备

26
docs/api/audio/audio-system/get-current-device.md Normal file
View File

@@ -0,0 +1,26 @@
# AudioSystem::GetCurrentDevice
获取当前音频设备名称。
```cpp
std::string GetCurrentDevice() const;
```
**返回：** `std::string` - 当前使用的音频设备名称
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void PrintCurrentDevice() {
std::string device = AudioSystem::Get().GetCurrentDevice();
printf("Current audio device: %s\n", device.c_str());
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)

14
docs/api/audio/audio-system/get-listener-position.md Normal file
View File

@@ -0,0 +1,14 @@
# AudioSystem::GetListenerPosition
获取监听器位置。
```cpp
const Math::Vector3& GetListenerPosition() const;
```
**返回：** `const Math::Vector3&` - 监听器当前位置引用
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [SetListenerTransform](set-listener-transform.md) - 设置监听器变换

14
docs/api/audio/audio-system/get-listener-rotation.md Normal file
View File

@@ -0,0 +1,14 @@
# AudioSystem::GetListenerRotation
获取监听器旋转。
```cpp
const Math::Quaternion& GetListenerRotation() const;
```
**返回：** `const Math::Quaternion&` - 监听器当前旋转引用
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [SetListenerTransform](set-listener-transform.md) - 设置监听器变换

14
docs/api/audio/audio-system/get-listener-velocity.md Normal file
View File

@@ -0,0 +1,14 @@
# AudioSystem::GetListenerVelocity
获取监听器速度。
```cpp
const Math::Vector3& GetListenerVelocity() const;
```
**返回：** `const Math::Vector3&` - 监听器当前速度引用
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [SetListenerVelocity](set-listener-velocity.md) - 设置监听器速度

27
docs/api/audio/audio-system/get-master-volume.md Normal file
View File

@@ -0,0 +1,27 @@
# AudioSystem::GetMasterVolume
获取主音量。
```cpp
float GetMasterVolume() const;
```
**返回：** `float` - 主音量值，范围 [0.0, 1.0]
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void PrintMasterVolume() {
float volume = AudioSystem::Get().GetMasterVolume();
printf("Master volume: %.1f%%\n", volume * 100.0f);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [SetMasterVolume](set-master-volume.md) - 设置主音量

39
docs/api/audio/audio-system/get-stats.md Normal file
View File

@@ -0,0 +1,39 @@
# AudioSystem::GetStats
获取音频系统统计信息。
```cpp
const Stats& GetStats() const;
```
返回包含音频系统运行时统计信息的结构体，包括活跃源数量、总源数量、内存使用量和 CPU 使用率。
**返回：** `const Stats&` - 统计信息结构体引用
**Stats 结构体：**
| 成员 | 类型 | 描述 |
|------|------|------|
| `activeSources` | `uint32_t` | 当前正在播放的音频源数量 |
| `totalSources` | `uint32_t` | 注册的音频源总数 |
| `memoryUsage` | `uint64_t` | 音频系统内存使用量（字节） |
| `cpuUsage` | `float` | CPU 使用率估算值 |
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void PrintAudioStats() {
const auto& stats = AudioSystem::Get().GetStats();
printf("Active sources: %u / %u\n", stats.activeSources, stats.totalSources);
printf("Memory usage: %.2f MB\n", stats.memoryUsage / (1024.0 * 1024.0));
printf("CPU usage: %.1f%%\n", stats.cpuUsage * 100.0f);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)

40
docs/api/audio/audio-system/initialize.md Normal file
View File

@@ -0,0 +1,40 @@
# AudioSystem::Initialize
初始化音频系统。
```cpp
void Initialize(const AudioConfig& config);
```
使用指定的配置参数初始化音频系统。在此之前必须先通过 SetBackend 设置音频后端实现。初始化过程会配置音频缓冲区大小、采样率、通道数等参数。
**参数：**
- `config` - 音频系统配置，包含采样率、通道数、位深度、扬声器模式、缓冲区大小等
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
#include <XCEngine/Audio/WASAPI/WASAPIBackend.h>
using namespace XCEngine::Audio;
void SetupAudio() {
AudioSystem::Get().SetBackend(std::make_unique<WASAPIBackend>());
AudioConfig config;
config.sampleRate = 48000;
config.channels = 2;
config.bitsPerSample = 16;
config.speakerMode = SpeakerMode::Stereo;
config.bufferSize = 8192;
config.bufferCount = 2;
AudioSystem::Get().Initialize(config);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [AudioConfig](../audio-config/audio-config.md) - 音频配置

28
docs/api/audio/audio-system/is-muted.md Normal file
View File

@@ -0,0 +1,28 @@
# AudioSystem::IsMuted
检查是否静音。
```cpp
bool IsMuted() const;
```
**返回：** `bool` - 如果当前处于静音状态则返回 true
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void CheckMuteState() {
if (AudioSystem::Get().IsMuted()) {
printf("Audio is muted\n");
}
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [SetMuted](set-muted.md) - 设置静音状态

18
docs/api/audio/audio-system/process-audio.md Normal file
View File

@@ -0,0 +1,18 @@
# AudioSystem::ProcessAudio
处理音频数据。
```cpp
void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels);
```
将所有注册的音频源混音到输出缓冲区。内部处理 3D 空间化、音量控制和效果链。
**参数：**
- `buffer` - 输出音频缓冲区指针
- `sampleCount` - 样本数量
- `channels` - 通道数
## 相关文档
- [AudioSystem 总览](audio-system.md)

29
docs/api/audio/audio-system/register-source.md Normal file
View File

@@ -0,0 +1,29 @@
# AudioSystem::RegisterSource
注册音频源。
```cpp
void RegisterSource(Components::AudioSourceComponent* source);
```
将音频源组件注册到音频系统。已注册的音频源将在每帧 Update 时被处理和混音。
**参数：**
- `source` - 要注册的 AudioSourceComponent 指针
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void RegisterAudioSource(Components::AudioSourceComponent* audioSource) {
AudioSystem::Get().RegisterSource(audioSource);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [UnregisterSource](unregister-source.md) - 注销音频源

30
docs/api/audio/audio-system/set-backend.md Normal file
View File

@@ -0,0 +1,30 @@
# AudioSystem::SetBackend
设置音频后端实现。
```cpp
void SetBackend(std::unique_ptr<IAudioBackend> backend);
```
设置音频系统的后端实现。必须在调用 Initialize 之前设置后端。音频系统不拥有后端的所有权，后端通过 unique_ptr 传递。
**参数：**
- `backend` - 音频后端实现的 unique_ptr，支持 IAudioBackend 接口
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
#include <XCEngine/Audio/WASAPI/WASAPIBackend.h>
using namespace XCEngine::Audio;
void SetupAudio() {
AudioSystem::Get().SetBackend(std::make_unique<WASAPIBackend>());
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [IAudioBackend](../i-audio-backend/i-audio-backend.md) - 音频后端接口

34
docs/api/audio/audio-system/set-device.md Normal file
View File

@@ -0,0 +1,34 @@
# AudioSystem::SetDevice
设置音频设备。
```cpp
void SetDevice(const std::string& deviceName);
```
切换到指定的音频设备。如果设备名称无效或设备不可用，操作失败。
**参数：**
- `deviceName` - 目标音频设备名称
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void SwitchAudioDevice() {
std::vector<std::string> devices;
AudioSystem::Get().GetAvailableDevices(devices);
if (devices.size() > 1) {
AudioSystem::Get().SetDevice(devices[1]);
}
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [GetAvailableDevices](get-available-devices.md) - 获取可用设备列表

31
docs/api/audio/audio-system/set-listener-transform.md Normal file
View File

@@ -0,0 +1,31 @@
# AudioSystem::SetListenerTransform
设置监听器变换。
```cpp
void SetListenerTransform(const Math::Vector3& position, const Math::Quaternion& rotation);
```
设置音频监听器的位置和旋转。用于 3D 空间音频计算，包括声音的方向、距离衰减和多普勒效应。
**参数：**
- `position` - 监听器位置（世界坐标）
- `rotation` - 监听器旋转（四元数）
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void UpdateListenerFromCamera(Camera* camera) {
Math::Vector3 pos = camera->GetPosition();
Math::Quaternion rot = camera->GetRotation();
AudioSystem::Get().SetListenerTransform(pos, rot);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)

29
docs/api/audio/audio-system/set-listener-velocity.md Normal file
View File

@@ -0,0 +1,29 @@
# AudioSystem::SetListenerVelocity
设置监听器速度。
```cpp
void SetListenerVelocity(const Math::Vector3& velocity);
```
设置音频监听器的速度向量。用于多普勒效应计算，当声源与监听器之间存在相对运动时会产生音调偏移。
**参数：**
- `velocity` - 监听器速度向量（世界坐标，单位：米/秒）
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void UpdateListenerVelocity(RigidBody* listenerBody) {
Math::Vector3 velocity = listenerBody->GetVelocity();
AudioSystem::Get().SetListenerVelocity(velocity);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)

29
docs/api/audio/audio-system/set-master-volume.md Normal file
View File

@@ -0,0 +1,29 @@
# AudioSystem::SetMasterVolume
设置主音量。
```cpp
void SetMasterVolume(float volume);
```
设置全局主音量系数。该值影响所有音频源的输出电平。
**参数：**
- `volume` - 主音量值，有效范围 [0.0, 1.0]
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void SetGlobalVolume() {
AudioSystem::Get().SetMasterVolume(0.75f);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [GetMasterVolume](get-master-volume.md) - 获取主音量

30
docs/api/audio/audio-system/set-muted.md Normal file
View File

@@ -0,0 +1,30 @@
# AudioSystem::SetMuted
设置静音状态。
```cpp
void SetMuted(bool muted);
```
启用或禁用全局静音。静音状态下所有音频输出将被消音。
**参数：**
- `muted` - true 为启用静音，false 为禁用静音
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void ToggleMute() {
bool currentlyMuted = AudioSystem::Get().IsMuted();
AudioSystem::Get().SetMuted(!currentlyMuted);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [IsMuted](is-muted.md) - 检查静音状态

25
docs/api/audio/audio-system/shutdown.md Normal file
View File

@@ -0,0 +1,25 @@
# AudioSystem::Shutdown
关闭音频系统，释放所有资源。
```cpp
void Shutdown();
```
关闭音频系统并释放相关资源。调用后音频系统将停止所有音频处理，已注册的音频源将被注销。在程序退出或音频系统不再需要时调用。
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void CleanupAudio() {
AudioSystem::Get().Shutdown();
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)

29
docs/api/audio/audio-system/unregister-source.md Normal file
View File

@@ -0,0 +1,29 @@
# AudioSystem::UnregisterSource
注销音频源。
```cpp
void UnregisterSource(Components::AudioSourceComponent* source);
```
将音频源组件从音频系统注销。已注销的音频源将不再被处理和混音。
**参数：**
- `source` - 要注销的 AudioSourceComponent 指针
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void UnregisterAudioSource(Components::AudioSourceComponent* audioSource) {
AudioSystem::Get().UnregisterSource(audioSource);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)
- [RegisterSource](register-source.md) - 注册音频源

28
docs/api/audio/audio-system/update.md Normal file
View File

@@ -0,0 +1,28 @@
# AudioSystem::Update
每帧更新音频系统状态。
```cpp
void Update(float deltaTime);
```
每帧调用以更新音频系统状态。该方法处理所有已注册音频源的 3D 空间化计算，包括多普勒效应、距离衰减、声像定位等。同时更新内部统计信息。
**参数：**
- `deltaTime` - 距离上一帧的时间增量（秒）
**示例：**
```cpp
#include <XCEngine/Audio/AudioSystem.h>
using namespace XCEngine::Audio;
void GameLoop(float deltaTime) {
AudioSystem::Get().Update(deltaTime);
}
```
## 相关文档
- [AudioSystem 总览](audio-system.md)

111
docs/api/audio/audio.md Normal file
View File

@@ -0,0 +1,111 @@
# Audio 模块概览
**命名空间**: `XCEngine::Audio`
**类型**: `module`
**描述**: XCEngine 的音频系统模块，提供完整的音频播放、3D 空间化、效果处理和混音功能。
## 概述
Audio 模块是 XCEngine 的音频子系统，支持多通道音频播放、3D 空间化定位（HRTF）、音频效果处理（混响、均衡器、FFT）、以及基于 WASAPI 的 Windows 音频后端。该模块设计为与 ECS 组件系统集成，通过 AudioSourceComponent 和 AudioListenerComponent 实现音频源的播放和空间化处理。
## 模块内容
### 核心系统
| 组件 | 文件 | 描述 |
|------|------|------|
| [AudioSystem](audio-system/audio-system.md) | `AudioSystem.h` | 音频系统单例，管理所有音频源和后端 |
| [AudioMixer](audio-mixer/audio-mixer.md) | `AudioMixer.h` | 音频混音器，支持效果链和 3D 参数 |
| [IAudioBackend](i-audio-backend/i-audio-backend.md) | `IAudioBackend.h` | 音频后端抽象接口 |
| [IAudioEffect](i-audio-effect/i-audio-effect.md) | `IAudioEffect.h` | 音频效果接口基类 |
### 音频效果
| 组件 | 文件 | 描述 |
|------|------|------|
| [FFTFilter](fft-filter/fft-filter.md) | `FFTFilter.h` | FFT 频谱分析滤波器 |
| [Reverbation](reverbation/reverbation.md) | `Reverbation.h` | 混响效果器（ Schroeder 算法的并行 Comb 滤波器 + AllPass 滤波器） |
| [Equalizer](equalizer/equalizer.md) | `Equalizer.h` | 多频段参数均衡器 |
| [HRTF](hrtf/hrtf.md) | `HRTF.h` | 基于头部相关传输函数的 3D 空间化 |
### Windows 后端
| 组件 | 文件 | 描述 |
|------|------|------|
| [WASAPIBackend](wasapi-backend/wasapi-backend.md) | `WASAPI/WASAPIBackend.h` | Windows WASAPI 音频后端实现 |
### 配置与类型
| 组件 | 文件 | 描述 |
|------|------|------|
| [AudioConfig](audio-config/audio-config.md) | `AudioConfig.h` | 音频系统配置 |
| [Audio3DParams](audio-3d-params/audio-3d-params.md) | `AudioTypes.h` | 3D 空间化参数 |
| [AudioBufferDesc](audio-buffer-desc/audio-buffer-desc.md) | `AudioTypes.h` | 音频缓冲区描述符 |
| [SpatializerParams](spatializer-params/spatializer-params.md) | `AudioTypes.h` | 空间化计算参数 |
### 枚举类型
| 枚举 | 描述 |
|------|------|
| [AudioResourceType](enums/audio-resource-type.md) | 音频资源类型 |
| [AudioLoadState](enums/audio-load-state.md) | 音频加载状态 |
| [AudioFormat](enums/audio-format.md) | 音频格式（WAV, OGG, MP3, FLAC, AAC） |
| [SpeakerMode](enums/speaker-mode.md) | 扬声器模式（Mono, Stereo, Surround51, Surround71 等） |
| [AudioChannel](enums/audio-channel.md) | 音频通道（FrontLeft, FrontRight, FrontCenter, LFE 等） |
| [PlayState](enums/play-state.md) | 播放状态（Stopped, Playing, Paused） |
| [StopMode](enums/stop-mode.md) | 停止模式（Immediate, AllowFadeOut） |
| [PanMode](enums/pan-mode.md) | 声像模式（Pan3D, Pan2D） |
| [VolumeSource](enums/volume-source.md) | 音量来源（Direct, PathOcclusion, Transmission, Obstruction） |
## 使用示例
```cpp
#include <XCEngine/Audio/AudioSystem.h>
#include <XCEngine/Audio/AudioMixer.h>
#include <XCEngine/Audio/Equalizer.h>
#include <XCEngine/Audio/Reverbation.h>
using namespace XCEngine::Audio;
void InitializeAudioSystem() {
AudioConfig config;
config.sampleRate = 48000;
config.channels = 2;
config.bitsPerSample = 16;
config.speakerMode = SpeakerMode::Stereo;
config.bufferSize = 8192;
config.bufferCount = 2;
AudioSystem::Get().Initialize(config);
}
void SetupAudioWithEffects() {
AudioMixer* mixer = new AudioMixer();
Reverbation* reverb = new Reverbation();
reverb->SetRoomSize(0.5f);
reverb->SetWetMix(0.3f);
reverb->SetDryMix(0.7f);
Equalizer* eq = new Equalizer();
eq->SetBandCount(4);
eq->SetBandFrequency(0, 100.0f);
eq->SetBandGain(0, 3.0f);
mixer->AddEffect(eq);
mixer->AddEffect(reverb);
mixer->SetVolume(0.8f);
}
void UpdateListener(const Math::Vector3& pos, const Math::Quaternion& rot) {
AudioSystem::Get().SetListenerTransform(pos, rot);
}
```
## 相关文档
- [Resources 模块 - AudioClip](../resources/audioclip/audio-clip.md) - 音频资源管理
- [Components 模块 - AudioSourceComponent](../components/audio-source/audio-source-component.md) - 音频源组件
- [Components 模块 - AudioListenerComponent](../components/audio-listener/audio-listener-component.md) - 音频监听器组件

28
docs/api/audio/enums/audio-channel.md Normal file
View File

@@ -0,0 +1,28 @@
# AudioChannel
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
音频通道枚举，定义多声道音频系统中的各个声道。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `FrontLeft` | 0 | 前左声道 |
| `FrontRight` | 1 | 前右声道 |
| `FrontCenter` | 2 | 前中声道 |
| `LFE` | 3 | 低频效果声道（低音炮） |
| `BackLeft` | 4 | 后左声道 |
| `BackRight` | 5 | 后右声道 |
| `SideLeft` | 6 | 侧左声道 |
| `SideRight` | 7 | 侧右声道 |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

26
docs/api/audio/enums/audio-format.md Normal file
View File

@@ -0,0 +1,26 @@
# AudioFormat
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
支持的音频格式枚举。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `Unknown` | 0 | 未知格式 |
| `WAV` | 1 | WAV 格式（Microsoft） |
| `OGG` | 2 | OGG Vorbis 格式 |
| `MP3` | 3 | MP3 格式（MPEG-1 Audio Layer 3） |
| `FLAC` | 4 | FLAC 格式（Free Lossless Audio Codec） |
| `AAC` | 5 | AAC 格式（Advanced Audio Coding） |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

24
docs/api/audio/enums/audio-load-state.md Normal file
View File

@@ -0,0 +1,24 @@
# AudioLoadState
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
音频资源加载状态枚举。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `Unloaded` | 0 | 未加载 |
| `Loading` | 1 | 正在加载 |
| `Loaded` | 2 | 已加载 |
| `Failed` | 3 | 加载失败 |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

23
docs/api/audio/enums/audio-resource-type.md Normal file
View File

@@ -0,0 +1,23 @@
# AudioResourceType
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
音频资源类型枚举，区分不同种类的音频资源。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `AudioClip` | 0 | 音频片段资源 |
| `AudioMixer` | 1 | 音频混音器资源 |
| `AudioBank` | 2 | 音频银行/打包资源 |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

22
docs/api/audio/enums/pan-mode.md Normal file
View File

@@ -0,0 +1,22 @@
# PanMode
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
声像模式枚举，控制 2D/3D 声像定位方式。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `Pan3D` | 0 | 3D 空间化声像 |
| `Pan2D` | 1 | 2D 平坦声像 |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

23
docs/api/audio/enums/play-state.md Normal file
View File

@@ -0,0 +1,23 @@
# PlayState
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
音频播放状态枚举。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `Stopped` | 0 | 已停止 |
| `Playing` | 1 | 正在播放 |
| `Paused` | 2 | 已暂停 |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

26
docs/api/audio/enums/speaker-mode.md Normal file
View File

@@ -0,0 +1,26 @@
# SpeakerMode
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
扬声器输出模式枚举，定义音频输出的声道配置。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `Mono` | 0 | 单声道 |
| `Stereo` | 1 | 立体声（2.0） |
| `Surround51` | 2 | 5.1 环绕声 |
| `Surround71` | 3 | 7.1 环绕声 |
| `Surround51_2` | 4 | 5.1 环绕声（第二版） |
| `Surround71_2` | 5 | 7.1 环绕声（第二版） |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

22
docs/api/audio/enums/stop-mode.md Normal file
View File

@@ -0,0 +1,22 @@
# StopMode
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
音频停止模式枚举，控制停止播放时的行为。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `Immediate` | 0 | 立即停止 |
| `AllowFadeOut` | 1 | 允许淡出后停止 |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

24
docs/api/audio/enums/volume-source.md Normal file
View File

@@ -0,0 +1,24 @@
# VolumeSource
**命名空间**: `XCEngine::Audio`
**类型**: `enum class`
**头文件**: `XCEngine/Audio/AudioTypes.h`
## 概述
音量来源枚举，定义不同物理因素对音量的影响。
## 枚举值
| 枚举值 | 数值 | 描述 |
|--------|------|------|
| `Direct` | 0 | 直接音量（无遮挡） |
| `PathOcclusion` | 1 | 路径遮挡（声波绕过障碍物） |
| `Transmission` | 2 | 透射（声波穿透障碍物） |
| `Obstruction` | 3 | 阻塞（直达声被完全遮挡） |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

67
docs/api/audio/equalizer/equalizer.md Normal file
View File

@@ -0,0 +1,67 @@
# Equalizer
**命名空间**: `XCEngine::Audio`
**类型**: `class`
**头文件**: `XCEngine/Audio/Equalizer.h`
**描述**: 多频段参数均衡器。
## 概述
Equalizer 是基于双二阶滤波器（Biquad Filter）的多频段参数均衡器实现。它支持设置任意数量的频段，每个频段可独立调节频率、增益（Gain/dB）和 Q 值。可用于调整音频频谱响应，实现低音增强、高音切平等效果。
## 公共方法
| 方法 | 描述 |
|------|------|
| [`Equalizer`](constructor.md) | 构造函数 |
| [`~Equalizer`](destructor.md) | 析构函数 |
| [`ProcessAudio`](process-audio.md) | 处理均衡后的音频 |
| [`SetBandCount`](set-band-count.md) | 设置频段数量 |
| [`GetBandCount`](get-band-count.md) | 获取频段数量 |
| [`SetBandFrequency`](set-band-frequency.md) | 设置频段频率 |
| [`GetBandFrequency`](get-band-frequency.md) | 获取频段频率 |
| [`SetBandGain`](set-band-gain.md) | 设置频段增益 |
| [`GetBandGain`](get-band-gain.md) | 获取频段增益 |
| [`SetBandQ`](set-band-q.md) | 设置频段 Q 值 |
| [`GetBandQ`](get-band-q.md) | 获取频段 Q 值 |
| [`SetEnabled`](set-enabled.md) | 设置启用状态 |
| [`IsEnabled`](is-enabled.md) | 检查启用状态 |
| [`SetWetMix`](set-wet-mix.md) | 设置湿信号混合比例 |
| [`GetWetMix`](get-wet-mix.md) | 获取湿信号混合比例 |
## 使用示例
```cpp
#include <XCEngine/Audio/Equalizer.h>
using namespace XCEngine::Audio;
void SetupEqualizer() {
Equalizer* eq = new Equalizer();
eq->SetBandCount(4);
eq->SetBandFrequency(0, 100.0f);
eq->SetBandGain(0, 3.0f);
eq->SetBandQ(0, 1.0f);
eq->SetBandFrequency(1, 1000.0f);
eq->SetBandGain(1, 0.0f);
eq->SetBandQ(1, 1.0f);
eq->SetBandFrequency(2, 5000.0f);
eq->SetBandGain(2, -2.0f);
eq->SetBandQ(2, 1.0f);
eq->SetBandFrequency(3, 10000.0f);
eq->SetBandGain(3, 0.0f);
eq->SetBandQ(3, 1.0f);
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [IAudioEffect](../i-audio-effect/i-audio-effect.md) - 音频效果接口

55
docs/api/audio/fft-filter/fft-filter.md Normal file
View File

@@ -0,0 +1,55 @@
# FFTFilter
**命名空间**: `XCEngine::Audio`
**类型**: `class`
**头文件**: `XCEngine/Audio/FFTFilter.h`
**描述**: FFT 频谱分析滤波器，用于音频频谱可视化和分析。
## 概述
FFTFilter 是基于 kissfft 库的 FFT（快速傅里叶变换）频谱分析滤波器。它将时域音频信号转换为频域频谱数据，支持频谱平滑处理，可用于音频可视化（如频谱图、音频分析器）和基于频谱的效果处理。
## 公共方法
| 方法 | 描述 |
|------|------|
| [`FFTFilter`](constructor.md) | 构造函数 |
| [`~FFTFilter`](destructor.md) | 析构函数 |
| [`ProcessAudio`](process-audio.md) | 处理音频并计算频谱 |
| [`SetFFTSize`](set-fft-size.md) | 设置 FFT 大小 |
| [`GetFFTSize`](get-fft-size.md) | 获取 FFT 大小 |
| [`SetSmoothingFactor`](set-smoothing-factor.md) | 设置平滑因子 |
| [`GetSmoothingFactor`](get-smoothing-factor.md) | 获取平滑因子 |
| [`GetSpectrumData`](get-spectrum-data.md) | 获取频谱数据 |
| [`GetSpectrumSize`](get-spectrum-size.md) | 获取频谱数据大小 |
## 使用示例
```cpp
#include <XCEngine/Audio/FFTFilter.h>
using namespace XCEngine::Audio;
void AnalyzeAudio() {
FFTFilter fft(1024);
fft.SetSmoothingFactor(0.8f);
float buffer[1024];
fft.ProcessAudio(buffer, 1024, 2);
const float* spectrum = fft.GetSpectrumData();
size_t size = fft.GetSpectrumSize();
for (size_t i = 0; i < size; ++i) {
printf("Bin %zu: %.2f\n", i, spectrum[i]);
}
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [IAudioEffect](../i-audio-effect/i-audio-effect.md) - 音频效果接口

42
docs/api/audio/hrtf-params/hrtf-params.md Normal file
View File

@@ -0,0 +1,42 @@
# HRTFParams
**命名空间**: `XCEngine::Audio`
**类型**: `struct`
**头文件**: `XCEngine/Audio/HRTF.h`
**描述**: HRTF 空间化参数。
## 结构体成员
| 成员 | 类型 | 描述 | 默认值 |
|------|------|------|--------|
| `azimuth` | `float` | 方位角（度） | `0.0f` |
| `elevation` | `float` | 仰角（度） | `0.0f` |
| `interauralTimeDelay` | `float` | 耳间时间差（秒） | `0.0f` |
| `interauralLevelDifference` | `float` | 耳间电平差 | `0.0f` |
| `headShadowing` | `float` | 头部阴影系数 | `0.0f` |
| `pinnaCues` | `float` | 耳廓线索系数 | `0.0f` |
| `torsoShoulderRotation` | `float` | 躯干/肩部旋转角度 | `0.0f` |
## 使用示例
```cpp
#include <XCEngine/Audio/HRTF.h>
using namespace XCEngine::Audio;
void ProcessWithHRTFParams(HRTF* hrtf) {
HRTFParams params;
params.azimuth = 45.0f;
params.elevation = 0.0f;
params.interauralTimeDelay = 0.0006f;
params.interauralLevelDifference = 3.0f;
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [HRTF](../hrtf/hrtf.md) - HRTF 类

55
docs/api/audio/hrtf/hrtf.md Normal file
View File

@@ -0,0 +1,55 @@
# HRTF
**命名空间**: `XCEngine::Audio`
**类型**: `class`
**头文件**: `XCEngine/Audio/HRTF.h`
**描述**: 基于头部相关传输函数（Head-Related Transfer Function）的 3D 空间音频处理器。
## 概述
HRTF 实现了基于头部相关传输函数（Head-Related Transfer Function）的 3D 空间音频算法。它通过计算声音的耳间时间差（ITD）、耳间电平差（ILD）和耳廓线索（Pinna Cues），在双耳耳机或扬声器上重现逼真的 3D 空间音效。支持多普勒效应、交叉馈送（Cross-feed）调节和质量级别设置。
## 公共方法
| 方法 | 描述 |
|------|------|
| [`HRTF`](constructor.md) | 构造函数 |
| [`~HRTF`](destructor.md) | 析构函数 |
| [`ProcessAudio`](process-audio.md) | 处理 3D 空间化音频 |
| [`SetEnabled`](set-enabled.md) | 设置启用状态 |
| [`IsEnabled`](is-enabled.md) | 检查启用状态 |
| [`SetHRTFEnabled`](set-hrtf-enabled.md) | 设置 HRTF 处理启用状态 |
| [`IsHRTFEnabled`](is-hrtf-enabled.md) | 检查 HRTF 处理启用状态 |
| [`SetQualityLevel`](set-quality-level.md) | 设置质量级别 |
| [`GetQualityLevel`](get-quality-level.md) | 获取质量级别 |
| [`SetCrossFeed`](set-cross-feed.md) | 设置交叉馈送值 |
| [`GetCrossFeed`](get-cross-feed.md) | 获取交叉馈送值 |
| [`SetDopplerShiftEnabled`](set-doppler-shift-enabled.md) | 设置多普勒效应启用状态 |
| [`IsDopplerShiftEnabled`](is-doppler-shift-enabled.md) | 检查多普勒效应启用状态 |
| [`SetSpeedOfSound`](set-speed-of-sound.md) | 设置声速 |
| [`GetSpeedOfSound`](get-speed-of-sound.md) | 获取声速 |
## 使用示例
```cpp
#include <XCEngine/Audio/HRTF.h>
using namespace XCEngine::Audio;
void SetupHRTF() {
HRTF* hrtf = new HRTF();
hrtf->SetHRTFEnabled(true);
hrtf->SetQualityLevel(2);
hrtf->SetCrossFeed(0.2f);
hrtf->SetDopplerShiftEnabled(true);
hrtf->SetSpeedOfSound(343.0f);
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [HRTFParams](../hrtf-params/hrtf-params.md) - HRTF 参数结构体

60
docs/api/audio/i-audio-backend/i-audio-backend.md Normal file
View File

@@ -0,0 +1,60 @@
# IAudioBackend
**命名空间**: `XCEngine::Audio`
**类型**: `class (abstract)`
**头文件**: `XCEngine/Audio/IAudioBackend.h`
**描述**: 音频后端抽象接口，定义音频输出的统一接口。
## 概述
IAudioBackend 是音频后端的抽象接口，定义了音频系统与具体音频 API（如 WASAPI、OpenAL）交互的统一接口。不同的音频后端实现（如 WASAPIBackend）继承此接口，提供实际的音频输出能力。
## 抽象方法
| 方法 | 描述 |
|------|------|
| [`Initialize`](initialize.md) | 初始化音频后端 |
| [`Shutdown`](shutdown.md) | 关闭音频后端 |
| [`GetDeviceName`](get-device-name.md) | 获取设备名称 |
| [`GetAvailableDevices`](get-available-devices.md) | 获取可用设备列表 |
| [`SetDevice`](set-device.md) | 设置音频设备 |
| [`GetMasterVolume`](get-master-volume.md) | 获取主音量 |
| [`SetMasterVolume`](set-master-volume.md) | 设置主音量 |
| [`IsMuted`](is-muted.md) | 检查静音状态 |
| [`SetMuted`](set-muted.md) | 设置静音状态 |
| [`Start`](start.md) | 启动音频处理 |
| [`Stop`](stop.md) | 停止音频处理 |
| [`Suspend`](suspend.md) | 暂停音频处理 |
| [`Resume`](resume.md) | 恢复音频处理 |
| [`ProcessAudio`](process-audio.md) | 处理音频数据 |
| [`IsRunning`](is-running.md) | 检查是否正在运行 |
| [`GetConfig`](get-config.md) | 获取配置信息 |
## 使用示例
```cpp
#include <XCEngine/Audio/IAudioBackend.h>
#include <XCEngine/Audio/WASAPI/WASAPIBackend.h>
using namespace XCEngine::Audio;
void CreateBackend() {
IAudioBackend* backend = new WASAPIBackend();
AudioConfig config;
config.sampleRate = 48000;
config.channels = 2;
backend->Initialize(config);
backend->Start();
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [WASAPIBackend](../wasapi-backend/wasapi-backend.md) - WASAPI 后端实现
- [AudioSystem](../audio-system/audio-system.md) - 音频系统

49
docs/api/audio/i-audio-effect/i-audio-effect.md Normal file
View File

@@ -0,0 +1,49 @@
# IAudioEffect
**命名空间**: `XCEngine::Audio`
**类型**: `class (abstract)`
**头文件**: `XCEngine/Audio/IAudioEffect.h`
**描述**: 音频效果接口基类，定义音频效果处理的统一接口。
## 概述
IAudioEffect 是所有音频效果处理器的抽象基类。它定义了音频效果的基本接口，包括音频处理方法、启用/禁用状态和干湿混合比例。具体的音频效果（如 Reverbation、Equalizer、FFTFilter）继承此接口并实现 ProcessAudio 方法来处理音频数据。
## 抽象方法
| 方法 | 描述 |
|------|------|
| [`ProcessAudio`](process-audio.md) | 处理音频数据（纯虚函数） |
## 虚方法
| 方法 | 描述 |
|------|------|
| [`SetEnabled`](set-enabled.md) | 设置启用状态 |
| [`IsEnabled`](is-enabled.md) | 检查启用状态 |
| [`SetWetMix`](set-wet-mix.md) | 设置湿信号混合比例 |
| [`GetWetMix`](get-wet-mix.md) | 获取湿信号混合比例 |
## 使用示例
```cpp
#include <XCEngine/Audio/IAudioEffect.h>
#include <XCEngine/Audio/Reverbation.h>
using namespace XCEngine::Audio;
void ConfigureEffect(IAudioEffect* effect) {
effect->SetEnabled(true);
effect->SetWetMix(0.5f);
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [AudioMixer](../audio-mixer/audio-mixer.md) - 音频混音器
- [Reverbation](../reverbation/reverbation.md) - 混响效果
- [Equalizer](../equalizer/equalizer.md) - 均衡器效果

55
docs/api/audio/reverbation/reverbation.md Normal file
View File

@@ -0,0 +1,55 @@
# Reverbation
**命名空间**: `XCEngine::Audio`
**类型**: `class`
**头文件**: `XCEngine/Audio/Reverbation.h`
**描述**: 混响效果器，基于 Schroeder 算法实现。
## 概述
Reverbation 是 Schroeder 算法的并行 Comb 滤波器 + AllPass 滤波器混响实现。它模拟真实环境中声音的早期反射和后期混响，支持调节房间大小（RoomSize）、阻尼（Damping）、干湿信号混合比等参数，适用于游戏场景中的环境混响效果。
## 公共方法
| 方法 | 描述 |
|------|------|
| [`Reverbation`](constructor.md) | 构造函数 |
| [`~Reverbation`](destructor.md) | 析构函数 |
| [`ProcessAudio`](process-audio.md) | 处理混响音频 |
| [`SetRoomSize`](set-room-size.md) | 设置房间大小 |
| [`GetRoomSize`](get-room-size.md) | 获取房间大小 |
| [`SetDamping`](set-damping.md) | 设置阻尼 |
| [`GetDamping`](get-damping.md) | 获取阻尼 |
| [`SetWetMix`](set-wet-mix.md) | 设置湿信号混合比例 |
| [`GetWetMix`](get-wet-mix.md) | 获取湿信号混合比例 |
| [`SetDryMix`](set-dry-mix.md) | 设置干信号混合比例 |
| [`GetDryMix`](get-dry-mix.md) | 获取干信号混合比例 |
| [`SetWidth`](set-width.md) | 设置声场宽度 |
| [`GetWidth`](get-width.md) | 获取声场宽度 |
| [`SetFreeze`](set-freeze.md) | 设置冻结模式 |
| [`IsFreeze`](is-freeze.md) | 检查冻结状态 |
## 使用示例
```cpp
#include <XCEngine/Audio/Reverbation.h>
using namespace XCEngine::Audio;
void SetupReverb() {
Reverbation* reverb = new Reverbation();
reverb->SetRoomSize(0.5f);
reverb->SetDamping(0.5f);
reverb->SetWetMix(0.3f);
reverb->SetDryMix(0.7f);
reverb->SetWidth(1.0f);
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [IAudioEffect](../i-audio-effect/i-audio-effect.md) - 音频效果接口

26
docs/api/audio/spatializer-params/spatializer-params.md Normal file
View File

@@ -0,0 +1,26 @@
# SpatializerParams
**命名空间**: `XCEngine::Audio`
**类型**: `struct`
**头文件**: `XCEngine/Audio/AudioTypes.h`
**描述**: 空间化计算参数。
## 结构体成员
| 成员 | 类型 | 描述 | 默认值 |
|------|------|------|--------|
| `azimuth` | `float` | 方位角（弧度） | `0.0f` |
| `elevation` | `float` | 仰角（弧度） | `0.0f` |
| `distance` | `float` | 到声源的距离（米） | `0.0f` |
| `volumeDb` | `float` | 体积（分贝） | `0.0f` |
| `panCartesianX` | `float` | 声像 X 坐标 | `0.0f` |
| `panCartesianY` | `float` | 声像 Y 坐标 | `0.0f` |
| `isOccluded` | `bool` | 是否被遮挡 | `false` |
| `isObstructed` | `bool` | 是否被阻塞 | `false` |
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览

60
docs/api/audio/wasapi-backend/wasapi-backend.md Normal file
View File

@@ -0,0 +1,60 @@
# WASAPIBackend
**命名空间**: `XCEngine::Audio::WASAPI`
**类型**: `class`
**头文件**: `XCEngine/Audio/WASAPI/WASAPIBackend.h`
**描述**: Windows Audio Session API (WASAPI) 音频后端实现。
## 概述
WASAPIBackend 是基于 Windows WASAPI 的音频后端实现，通过 Windows MultiMedia API (waveXxx 函数) 提供音频输出能力。它运行在单独的音频线程上，使用双缓冲区交换机制实现流畅的音频播放，支持设备枚举、音量控制和静音管理。
## 公共方法
| 方法 | 描述 |
|------|------|
| [`WASAPIBackend`](constructor.md) | 构造函数 |
| [`~WASAPIBackend`](destructor.md) | 析构函数 |
| [`Initialize`](initialize.md) | 初始化 WASAPI 后端 |
| [`Shutdown`](shutdown.md) | 关闭 WASAPI 后端 |
| [`GetDeviceName`](get-device-name.md) | 获取当前设备名称 |
| [`GetAvailableDevices`](get-available-devices.md) | 获取可用设备列表 |
| [`SetDevice`](set-device.md) | 设置音频设备 |
| [`GetMasterVolume`](get-master-volume.md) | 获取主音量 |
| [`SetMasterVolume`](set-master-volume.md) | 设置主音量 |
| [`IsMuted`](is-muted.md) | 检查静音状态 |
| [`SetMuted`](set-muted.md) | 设置静音状态 |
| [`Start`](start.md) | 启动音频处理 |
| [`Stop`](stop.md) | 停止音频处理 |
| [`Suspend`](suspend.md) | 暂停音频处理 |
| [`Resume`](resume.md) | 恢复音频处理 |
| [`ProcessAudio`](process-audio.md) | 处理音频数据 |
| [`IsRunning`](is-running.md) | 检查是否正在运行 |
| [`GetConfig`](get-config.md) | 获取配置信息 |
## 使用示例
```cpp
#include <XCEngine/Audio/AudioSystem.h>
#include <XCEngine/Audio/WASAPI/WASAPIBackend.h>
using namespace XCEngine::Audio;
void SetupAudioWithWASAPI() {
AudioSystem::Get().SetBackend(std::make_unique<WASAPI::WASAPIBackend>());
AudioConfig config;
config.sampleRate = 48000;
config.channels = 2;
AudioSystem::Get().Initialize(config);
}
```
## 相关文档
- [Audio 模块总览](../audio.md) - Audio 模块总览
- [IAudioBackend](../i-audio-backend/i-audio-backend.md) - 音频后端接口

64
docs/api/components/audio-listener/audio-listener-component.md Normal file
View File

@@ -0,0 +1,64 @@
# AudioListenerComponent
**命名空间**: `XCEngine::Components`
**类型**: `class`
**头文件**: `XCEngine/Components/AudioListenerComponent.h`
**描述**: 音频监听器组件，代表场景中"听声音的人"（通常是主摄像机）。
## 概述
AudioListenerComponent 是 XCEngine ECS 系统中的音频监听器组件，通常附加在主摄像机或玩家控制的角色上。它接收场景中所有 AudioSourceComponent 发出的声音，并根据监听器与声源的相对位置、速度和方向计算 3D 空间化音效。场景中应当只有一个活跃的 AudioListenerComponent。
## 公共方法
| 方法 | 描述 |
|------|------|
| [`AudioListenerComponent`](constructor.md) | 构造函数 |
| [`~AudioListenerComponent`](destructor.md) | 析构函数 |
| [`GetEnergy`](get-energy.md) | 获取音频能量 |
| [`GetFrequencyData`](get-frequency-data.md) | 获取频谱数据 |
| [`GetFrequencyDataSize`](get-frequency-data-size.md) | 获取频谱数据大小 |
| [`SetMasterVolume`](set-master-volume.md) | 设置主音量 |
| [`GetMasterVolume`](get-master-volume.md) | 获取主音量 |
| [`SetMute`](set-mute.md) | 设置静音状态 |
| [`IsMute`](is-mute.md) | 检查静音状态 |
| [`SetDopplerLevel`](set-doppler-level.md) | 设置多普勒等级 |
| [`GetDopplerLevel`](get-doppler-level.md) | 获取多普勒等级 |
| [`SetSpeedOfSound`](set-speed-of-sound.md) | 设置声速 |
| [`GetSpeedOfSound`](get-speed-of-sound.md) | 获取声速 |
| [`SetReverbLevel`](set-reverb-level.md) | 设置混响等级 |
| [`GetReverbLevel`](get-reverb-level.md) | 获取混响等级 |
| [`SetReverb`](set-reverb.md) | 设置混响混音器 |
| [`GetReverb`](get-reverb.md) | 获取混响混音器 |
## 组件方法
| 方法 | 描述 |
|------|------|
| [`Update`](update.md) | 每帧更新 |
| [`GetName`](get-name.md) | 获取组件名称 |
## 使用示例
```cpp
#include <XCEngine/Components/AudioListenerComponent.h>
using namespace XCEngine::Components;
void SetupAudioListener(Entity cameraEntity) {
AudioListenerComponent* listener = cameraEntity.AddComponent<AudioListenerComponent>();
listener->SetMasterVolume(1.0f);
listener->SetDopplerLevel(1.0f);
listener->SetSpeedOfSound(343.0f);
listener->SetReverbLevel(0.5f);
}
```
## 相关文档
- [Components 模块总览](../components.md) - Components 模块总览
- [AudioSourceComponent](../audio-source/audio-source-component.md) - 音频源组件
- [AudioSystem 模块](../../audio/audio.md) - 音频系统模块

103
docs/api/components/audio-source/audio-source-component.md Normal file
View File

@@ -0,0 +1,103 @@
# AudioSourceComponent
**命名空间**: `XCEngine::Components`
**类型**: `class`
**头文件**: `XCEngine/Components/AudioSourceComponent.h`
**描述**: 音频源组件，负责在 ECS 实体上播放音频。
## 概述
AudioSourceComponent 是 XCEngine ECS 系统中的音频源组件，附加到游戏实体上后可以播放音频片段（AudioClip）。它支持 3D 空间化定位、音量、音调、循环、展开角度、多普勒效应等丰富的音频播放参数。该组件需要与 AudioListenerComponent 配合使用以实现 3D 空间音效。
## 公共方法
| 方法 | 描述 |
|------|------|
| [`AudioSourceComponent`](constructor.md) | 构造函数 |
| [`~AudioSourceComponent`](destructor.md) | 析构函数 |
| [`Play`](play.md) | 开始播放 |
| [`Pause`](pause.md) | 暂停播放 |
| [`Stop`](stop.md) | 停止播放 |
| [`IsPlaying`](is-playing.md) | 检查是否正在播放 |
| [`IsPaused`](is-paused.md) | 检查是否已暂停 |
| [`SetClip`](set-clip.md) | 设置音频片段 |
| [`GetClip`](get-clip.md) | 获取音频片段 |
| [`SetVolume`](set-volume.md) | 设置音量 |
| [`GetVolume`](get-volume.md) | 获取音量 |
| [`SetPitch`](set-pitch.md) | 设置音调 |
| [`GetPitch`](get-pitch.md) | 获取音调 |
| [`SetPan`](set-pan.md) | 设置声像 |
| [`GetPan`](get-pan.md) | 获取声像 |
| [`SetLooping`](set-looping.md) | 设置循环播放 |
| [`IsLooping`](is-looping.md) | 检查循环状态 |
| [`SetSpatialize`](set-spatialize.md) | 设置是否启用空间化 |
| [`IsSpatialize`](is-spatialize.md) | 检查空间化状态 |
| [`Set3DParams`](set-3d-params.md) | 设置 3D 参数 |
| [`Get3DParams`](get-3d-params.md) | 获取 3D 参数 |
| [`SetDopplerLevel`](set-doppler-level.md) | 设置多普勒等级 |
| [`GetDopplerLevel`](get-doppler-level.md) | 获取多普勒等级 |
| [`SetSpread`](set-spread.md) | 设置展开角度 |
| [`GetSpread`](get-spread.md) | 获取展开角度 |
| [`SetReverbZoneMix`](set-reverb-zone-mix.md) | 设置混响区域混合 |
| [`GetReverbZoneMix`](get-reverb-zone-mix.md) | 获取混响区域混合 |
| [`SetOutputMixer`](set-output-mixer.md) | 设置输出混音器 |
| [`GetOutputMixer`](get-output-mixer.md) | 获取输出混音器 |
| [`SetTime`](set-time.md) | 设置播放时间 |
| [`GetTime`](get-time.md) | 获取播放时间 |
| [`GetDuration`](get-duration.md) | 获取音频时长 |
| [`GetEnergy`](get-energy.md) | 获取音频能量 |
| [`StartEnergyDetect`](start-energy-detect.md) | 开始能量检测 |
| [`StopEnergyDetect`](stop-energy-detect.md) | 停止能量检测 |
| [`IsEnergyDetecting`](is-energy-detecting.md) | 检查能量检测状态 |
## 组件方法
| 方法 | 描述 |
|------|------|
| [`Update`](update.md) | 每帧更新 |
| [`OnEnable`](on-enable.md) | 启用时回调 |
| [`OnDisable`](on-disable.md) | 禁用时回调 |
| [`OnDestroy`](on-destroy.md) | 销毁时回调 |
| [`GetName`](get-name.md) | 获取组件名称 |
## 使用示例
```cpp
#include <XCEngine/Components/AudioSourceComponent.h>
#include <XCEngine/Resources/ResourceManager.h>
using namespace XCEngine::Components;
void PlaySoundEffect(Entity entity, const char* soundPath) {
AudioSourceComponent* audioSource = entity.AddComponent<AudioSourceComponent>();
auto clip = Resources::ResourceManager::Get().Load<Resources::AudioClip>(soundPath);
audioSource->SetClip(clip.Get());
audioSource->SetVolume(0.8f);
audioSource->SetLooping(false);
audioSource->SetSpatialize(true);
audioSource->Play();
}
void PlayLoopingMusic(Entity entity, const char* musicPath) {
AudioSourceComponent* audioSource = entity.AddComponent<AudioSourceComponent>();
auto clip = Resources::ResourceManager::Get().Load<Resources::AudioClip>(musicPath);
audioSource->SetClip(clip.Get());
audioSource->SetVolume(0.5f);
audioSource->SetLooping(true);
audioSource->SetSpatialize(false);
audioSource->Play();
}
```
## 相关文档
- [Components 模块总览](../components.md) - Components 模块总览
- [AudioListenerComponent](../audio-listener/audio-listener-component.md) - 音频监听器组件
- [AudioSystem 模块](../../audio/audio.md) - 音频系统模块

51
docs/api/components/components.md Normal file
View File

@@ -0,0 +1,51 @@
# Components 模块概览
**命名空间**: `XCEngine::Components`
**类型**: `module`
**描述**: XCEngine 的 ECS（实体组件系统）组件模块。
## 概述
Components 模块是 XCEngine ECS 架构中的组件层，提供各种游戏对象组件。这些组件附加到实体（Entity）上，定义了游戏对象的行为和数据。组件系统支持 Transform、Audio、Render 等功能。
## 模块内容
### 音频组件
| 组件 | 文件 | 描述 |
|------|------|------|
| [AudioSourceComponent](audio-source/audio-source-component.md) | `AudioSourceComponent.h` | 音频源组件，负责播放音频 |
| [AudioListenerComponent](audio-listener/audio-listener-component.md) | `AudioListenerComponent.h` | 音频监听器组件，接收声音 |
### 变换组件
| 组件 | 文件 | 描述 |
|------|------|------|
| TransformComponent | `TransformComponent.h` | 变换组件，包含位置、旋转、缩放 |
## 使用示例
```cpp
#include <XCEngine/Components/GameObject.h>
#include <XCEngine/Components/TransformComponent.h>
#include <XCEngine/Components/AudioSourceComponent.h>
using namespace XCEngine::Components;
void CreateAudioEntity() {
GameObject* entity = new GameObject("AudioEntity");
auto transform = entity->AddComponent<TransformComponent>();
transform->SetPosition(Vector3(0, 0, 0));
auto audioSource = entity->AddComponent<AudioSourceComponent>();
audioSource->SetVolume(0.8f);
}
```
## 相关文档
- [Audio 模块](../audio/audio.md) - 音频系统模块
- [Core 模块](../core/core.md) - ECS 核心类型

2
docs/api/main.md
View File

@@ -18,6 +18,8 @@
| **Debug** | [debug/](debug/debug.md) | 调试和日志 |
| **Math** | [math/](math/math.md) | 数学库 |
| **Resources** | [resources/](resources/resources.md) | 资源管理系统 |
| **Audio** | [audio/](audio/audio.md) | 音频系统 |
| **Components** | [components/](components/components.md) | ECS 组件系统 |
---