docs: 更新 audio 和 resources 模块文档

- audio: 更新 audio-mixer, equalizer, fft-filter, hrtf, reverbation 方法文档 - resources: 更新资源管理文档 - debug: 新增 renderdoc-capture 文档
2026-03-26 01:52:36 +08:00
parent 14ffde371e
commit fae7362e9f
7 changed files with 151 additions and 76 deletions
--- a/docs/api/audio/audio-mixer/audio-mixer.md
+++ b/docs/api/audio/audio-mixer/audio-mixer.md
@@ -16,22 +16,20 @@ AudioMixer 是 XCEngine 音频模块中的混音器类，负责将多个音频

 | 方法 | 描述 |
 |------|------|
-| [`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) | 获取通道音量 |
+| `SetVolume` | 设置混音器音量 |
+| `GetVolume` | 获取混音器音量 |
+| `SetMute` | 设置静音状态 |
+| `IsMute` | 检查静音状态 |
+| `AddEffect` | 添加音频效果 |
+| `RemoveEffect` | 移除音频效果 |
+| `ClearEffects` | 清除所有效果 |
+| `ProcessAudio` | 处理音频数据 |
+| `SetOutputMixer` | 设置输出混音器 |
+| `GetOutputMixer` | 获取输出混音器 |
+| `Set3DParams` | 设置 3D 空间化参数 |
+| `Get3DParams` | 获取 3D 空间化参数 |
+| `SetChannelVolume` | 设置通道音量 |
+| `GetChannelVolume` | 获取通道音量 |

 ## 使用示例

--- a/docs/api/audio/equalizer/equalizer.md
+++ b/docs/api/audio/equalizer/equalizer.md
@@ -16,21 +16,19 @@ Equalizer 是基于双二阶滤波器（Biquad Filter）的多频段参数均衡

 | 方法 | 描述 |
 |------|------|
-| [`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) | 获取湿信号混合比例 |
+| `ProcessAudio` | 处理均衡后的音频 |
+| `SetBandCount` | 设置频段数量 |
+| `GetBandCount` | 获取频段数量 |
+| `SetBandFrequency` | 设置频段频率 |
+| `GetBandFrequency` | 获取频段频率 |
+| `SetBandGain` | 设置频段增益 |
+| `GetBandGain` | 获取频段增益 |
+| `SetBandQ` | 设置频段 Q 值 |
+| `GetBandQ` | 获取频段 Q 值 |
+| `SetEnabled` | 设置启用状态 |
+| `IsEnabled` | 检查启用状态 |
+| `SetWetMix` | 设置湿信号混合比例 |
+| `GetWetMix` | 获取湿信号混合比例 |

 ## 使用示例

--- a/docs/api/audio/fft-filter/fft-filter.md
+++ b/docs/api/audio/fft-filter/fft-filter.md
@@ -16,15 +16,13 @@ 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) | 获取频谱数据大小 |
+| `ProcessAudio` | 处理音频并计算频谱 |
+| `SetFFTSize` | 设置 FFT 大小 |
+| `GetFFTSize` | 获取 FFT 大小 |
+| `SetSmoothingFactor` | 设置平滑因子 |
+| `GetSmoothingFactor` | 获取平滑因子 |
+| `GetSpectrumData` | 获取频谱数据 |
+| `GetSpectrumSize` | 获取频谱数据大小 |

 ## 使用示例

--- a/docs/api/audio/hrtf/hrtf.md
+++ b/docs/api/audio/hrtf/hrtf.md
@@ -16,21 +16,19 @@ HRTF 实现了基于头部相关传输函数（Head-Related Transfer Function）

 | 方法 | 描述 |
 |------|------|
-| [`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) | 获取声速 |
+| `ProcessAudio` | 处理 3D 空间化音频 |
+| `SetEnabled` | 设置启用状态 |
+| `IsEnabled` | 检查启用状态 |
+| `SetHRTFEnabled` | 设置 HRTF 处理启用状态 |
+| `IsHRTFEnabled` | 检查 HRTF 处理启用状态 |
+| `SetQualityLevel` | 设置质量级别 |
+| `GetQualityLevel` | 获取质量级别 |
+| `SetCrossFeed` | 设置交叉馈送值 |
+| `GetCrossFeed` | 获取交叉馈送值 |
+| `SetDopplerShiftEnabled` | 设置多普勒效应启用状态 |
+| `IsDopplerShiftEnabled` | 检查多普勒效应启用状态 |
+| `SetSpeedOfSound` | 设置声速 |
+| `GetSpeedOfSound` | 获取声速 |

 ## 使用示例

--- a/docs/api/audio/reverbation/reverbation.md
+++ b/docs/api/audio/reverbation/reverbation.md
@@ -16,21 +16,19 @@ Reverbation 是 Schroeder 算法的并行 Comb 滤波器 + AllPass 滤波器混

 | 方法 | 描述 |
 |------|------|
-| [`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) | 检查冻结状态 |
+| `ProcessAudio` | 处理混响音频 |
+| `SetRoomSize` | 设置房间大小 |
+| `GetRoomSize` | 获取房间大小 |
+| `SetDamping` | 设置阻尼 |
+| `GetDamping` | 获取阻尼 |
+| `SetWetMix` | 设置湿信号混合比例 |
+| `GetWetMix` | 获取湿信号混合比例 |
+| `SetDryMix` | 设置干信号混合比例 |
+| `GetDryMix` | 获取干信号混合比例 |
+| `SetWidth` | 设置声场宽度 |
+| `GetWidth` | 获取声场宽度 |
+| `SetFreeze` | 设置冻结模式 |
+| `IsFreeze` | 检查冻结状态 |

 ## 使用示例

--- a/docs/api/debug/renderdoc-capture/renderdoc-capture.md
+++ b/docs/api/debug/renderdoc-capture/renderdoc-capture.md
@@ -0,0 +1,86 @@
+# RenderDocCapture
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class (singleton)`
+
+**头文件**: `XCEngine/Debug/RenderDocCapture.h`
+
+**描述**: RenderDoc 帧捕获工具集成，用于图形调试和帧分析。
+
+## 概述
+
+RenderDocCapture 是 RenderDoc 图形调试器的集成类，提供程序化帧捕获功能。通过 LoadRenderDoc API，可以触发帧捕获、获取捕获信息、设置捕获选项等。
+
+该类为单例模式，通过 `Get()` 获取实例。支持设置捕获文件路径、捕获注释、捕获选项等。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `Get` | 获取单例实例 |
+| `Initialize` | 初始化 RenderDoc 集成，可选指定设备和窗口句柄 |
+| `Shutdown` | 关闭 RenderDoc 集成 |
+| `SetDevice` | 设置图形设备指针（GPU 相关） |
+| `SetWindow` | 设置窗口句柄 |
+| `IsLoaded` | 检查 RenderDoc API 是否已加载 |
+| `IsCapturing` | 检查是否正在捕获 |
+| `GetNumCaptures` | 获取已捕获的帧数量 |
+| `GetCapture` | 获取指定捕获的信息 |
+| `BeginCapture` | 开始帧捕获 |
+| `EndCapture` | 结束帧捕获 |
+| `TriggerCapture` | 触发单帧捕获（等同于按 F12） |
+| `SetCaptureFilePath` | 设置捕获文件保存路径 |
+| `SetCaptureComments` | 设置捕获文件注释 |
+| `SetCaptureOptionU32` | 设置32位捕获选项 |
+| `LaunchReplayUI` | 启动 RenderDoc 回放界面 |
+
+## 结构体
+
+### RenderDocCaptureInfo
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `filename` | `char[256]` | 捕获文件名 |
+| `length` | `uint32_t` | 文件大小（字节） |
+| `timestamp` | `uint64_t` | 捕获时间戳 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Debug/RenderDocCapture.h>
+
+using namespace XCEngine::Debug;
+
+// 获取单例实例
+RenderDocCapture& renderDoc = RenderDocCapture::Get();
+
+// 初始化（传入设备和窗口）
+renderDoc.Initialize(devicePtr, windowHandle);
+
+// 设置捕获文件路径
+renderDoc.SetCaptureFilePath("captures/frame_%04i.cap");
+renderDoc.SetCaptureComments("Test capture - stress scene");
+
+// 开始捕获
+renderDoc.BeginCapture("Main Window");
+
+// ... 渲染代码 ...
+
+// 结束捕获
+renderDoc.EndCapture();
+
+// 或触发单帧捕获
+renderDoc.TriggerCapture();
+
+// 检查捕获数量
+uint32_t numCaptures = renderDoc.GetNumCaptures();
+
+// 启动回放界面
+renderDoc.LaunchReplayUI();
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - Debug 模块总览
+- [Profiler](../profiler/profiler.md) - 性能分析器
--- a/docs/api/resources/resources.md
+++ b/docs/api/resources/resources.md
@@ -19,16 +19,15 @@ Resources 模块提供了一套完整的资源管理解决方案，支持同步
 | 组件 | 文件 | 描述 |
 |------|------|------|
 | [IResource](iresource/iresource.md) | `IResource.h` | 资源基类 |
-| [ResourceHandle](resourcehandle/resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 |
+| [ResourceHandle](resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 |
 | [IResourceLoader](iloader/iloader.md) | `IResourceLoader.h` | 资源加载器接口 |
-| [ShaderLoader](../rhi/d3d12/fence/index.md) | `ShaderLoader.h` | 着色器加载器 |
-| [ResourceManager](resourcemanager/resourcemanager.md) | `ResourceManager.h` | 资源管理器 |
-| [ResourceCache](resourcecache/resourcecache.md) | `ResourceCache.h` | 资源缓存 |
+| [ResourceManager](resource-manager/resource-manager.md) | `ResourceManager.h` | 资源管理器 |
+| [ResourceCache](resourcecache.md) | `ResourceCache.h` | 资源缓存 |
 | [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 |
-| [ResourceDependencyGraph](dependencygraph/dependencygraph.md) | `ResourceDependencyGraph.h` | 依赖图 |
+| [ResourceDependencyGraph](resource-dependency-graph/index.md) | `ResourceDependencyGraph.h` | 依赖图 |
 | [ResourceTypes](resourcetypes/resourcetypes.md) | `ResourceTypes.h` | 资源类型定义 |
 | [ResourcePath](resourcepath/resourcepath.md) | `ResourcePath.h` | 资源路径封装 |
-| [ResourceFileSystem](filesystem/filesystem.md) | `ResourceFileSystem.h` | 虚拟文件系统 |
+| [ResourceFileSystem](resource-file-system/index.md) | `ResourceFileSystem.h` | 虚拟文件系统 |
 | [ImportSettings](importsettings/importsettings.md) | `ImportSettings.h` | 导入设置基类 |

 ### 文件与打包