docs: 添加 Audio 模块和 Components 模块 API 文档
- 新增 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:
@@ -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
103
docs/api/components/audio-source/audio-source-component.md
Normal 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
51
docs/api/components/components.md
Normal 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 核心类型
|
||||
Reference in New Issue
Block a user