docs: 重构 API 文档 - components 和 scene 模块

- components: 修复英文标题为中文，添加缺失组件文档 - 新增 camera-component, light-component, audio-source-component, audio-listener-component 类总览 - 修复 get-position.md 格式 - 更新 components.md 模块总览 - scene: 修复方法文档格式，新增缺失方法 - 修复 find.md, create-game-object.md 英文标题 - 新增 FindByID, SerializeToString, DeserializeFromString 方法文档 - 更新 scene.md 类总览方法列表
2026-03-26 01:50:27 +08:00
parent 7c3f304688
commit f5a34f8adc
46 changed files with 781 additions and 157 deletions
--- a/docs/api/components/audio-listener-component/audio-listener-component.md
+++ b/docs/api/components/audio-listener-component/audio-listener-component.md
@@ -0,0 +1,86 @@
+# AudioListenerComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/AudioListenerComponent.h`
+
+**描述**: 音频监听组件，接收声音并处理多普勒效应、混响和音量控制。
+
+## 概述
+
+AudioListenerComponent 是 XCEngine ECS 系统中的音频监听组件，通常附加到相机或玩家对象上。它负责接收场景中所有 AudioSourceComponent 发出的声音，并进行多普勒效应、混响和音量控制处理。每个场景通常只有一个 AudioListenerComponent。
+
+## 公共方法
+
+### 音量控制
+
+| 方法 | 描述 |
+|------|------|
+| [`SetMasterVolume`](../../audio/audio-system/set-master-volume.md) | 设置主音量 |
+| [`GetMasterVolume`](../../audio/audio-system/get-master-volume.md) | 获取主音量 |
+
+### 静音控制
+
+| 方法 | 描述 |
+|------|------|
+| [`SetMute`](../../audio/audio-mixer/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) | 获取混响效果器 |
+
+### 频谱分析
+
+| 方法 | 描述 |
+|------|------|
+| [`GetEnergy`](get-energy.md) | 获取当前能量值 |
+| [`GetFrequencyData`](get-frequency-data.md) | 获取频谱数据 |
+| [`GetFrequencyDataSize`](get-frequency-data-size.md) | 获取频谱数据大小 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Components/AudioListenerComponent.h>
+#include <XCEngine/Components/GameObject.h>
+
+using namespace XCEngine::Components;
+
+void SetupAudioListener(GameObject* listenerObject) {
+    auto listener = listenerObject->AddComponent<AudioListenerComponent>();
+    
+    listener->SetMasterVolume(1.0f);
+    listener->SetDopplerLevel(1.0f);
+    listener->SetSpeedOfSound(343.0f);
+    listener->SetReverbLevel(0.5f);
+}
+
+void AdjustVolume(GameObject* listenerObject, float volume) {
+    auto listener = listenerObject->GetComponent<AudioListenerComponent>();
+    if (listener) {
+        listener->SetMasterVolume(volume);
+    }
+}
+```
+
+## 相关文档
+
+- [Components 模块总览](../components.md) - Components 模块总览
+- [Component](../component/component.md) - 组件基类
+- [AudioSourceComponent](../audio-source-component/audio-source-component.md) - 音频源组件
--- a/docs/api/components/audio-source-component/audio-source-component.md
+++ b/docs/api/components/audio-source-component/audio-source-component.md
@@ -0,0 +1,121 @@
+# AudioSourceComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/AudioSourceComponent.h`
+
+**描述**: 音频源组件，负责声音播放、3D 空间化、衰减和多普勒效应。
+
+## 概述
+
+AudioSourceComponent 是 XCEngine ECS 系统中的音频源组件，用于在场景中播放声音。它支持 3D 空间化、声音衰减、多普勒效应、混响区域混合等功能。该组件需要配合 AudioListenerComponent 使用来接收声音并进行音频处理。
+
+## 公共方法
+
+### 播放控制
+
+| 方法 | 描述 |
+|------|------|
+| [`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`](../../audio/audio-mixer/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) | 检查是否循环播放 |
+
+### 3D 空间化
+
+| 方法 | 描述 |
+|------|------|
+| [`SetSpatialize`](set-spatialize.md) | 设置是否启用 3D 空间化 |
+| [`IsSpatialize`](is-spatialize.md) | 检查是否启用 3D 空间化 |
+| [`Set3DParams`](../../audio/audio-mixer/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`](../../audio/audio-mixer/set-output-mixer.md) | 设置输出混音器 |
+| [`GetOutputMixer`](get-output-mixer.md) | 获取输出混音器 |
+
+### 播放时间
+
+| 方法 | 描述 |
+|------|------|
+| [`SetTime`](set-time.md) | 设置播放位置 |
+| [`GetTime`](get-time.md) | 获取当前播放位置 |
+| [`GetDuration`](../../resources/audioclip/get-duration.md) | 获取音频总时长 |
+
+### 能量检测
+
+| 方法 | 描述 |
+|------|------|
+| [`GetEnergy`](get-energy.md) | 获取当前能量值 |
+| [`StartEnergyDetect`](start-energy-detect.md) | 开始能量检测 |
+| [`StopEnergyDetect`](stop-energy-detect.md) | 停止能量检测 |
+| [`IsEnergyDetecting`](is-energy-detecting.md) | 检查是否正在能量检测 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Components/AudioSourceComponent.h>
+#include <XCEngine/Components/GameObject.h>
+#include <XCEngine/Resources/AudioClip/AudioClip.h>
+
+using namespace XCEngine::Components;
+
+void PlaySound(GameObject* audioObject) {
+    auto audioSource = audioObject->AddComponent<AudioSourceComponent>();
+    
+    audioSource->SetVolume(0.8f);
+    audioSource->SetPitch(1.0f);
+    audioSource->SetLooping(false);
+    audioSource->SetSpatialize(true);
+    
+    audioSource->Play();
+}
+
+void Setup3DAudio(GameObject* audioObject) {
+    auto audioSource = audioObject->AddComponent<AudioSourceComponent>();
+    
+    Audio::Audio3DParams params;
+    params.dopplerLevel = 1.0f;
+    params.spread = 0.0f;
+    params.reverbZoneMix = 1.0f;
+    audioSource->Set3DParams(params);
+}
+```
+
+## 相关文档
+
+- [Components 模块总览](../components.md) - Components 模块总览
+- [Component](../component/component.md) - 组件基类
+- [AudioListenerComponent](../audio-listener-component/audio-listener-component.md) - 音频监听组件
--- a/docs/api/components/camera-component/camera-component.md
+++ b/docs/api/components/camera-component/camera-component.md
@@ -0,0 +1,80 @@
+# CameraComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/CameraComponent.h`
+
+**描述**: 相机组件，定义视图和投影参数，支持透视和正交两种投影模式。
+
+## 概述
+
+CameraComponent 是 XCEngine ECS 系统中的相机组件，用于定义场景的观察视角。它支持透视投影（Perspective）和正交投影（Orthographic）两种模式，可以设置视场角、近裁剪面、远裁剪面、深度值和清除颜色等参数。
+
+## 枚举
+
+### CameraProjectionType
+
+| 枚举值 | 描述 |
+|--------|------|
+| `Perspective` | 透视投影，符合人眼观察习惯 |
+| `Orthographic` | 正交投影，保持物体真实大小 |
+
+## 公共方法
+
+### 投影设置
+
+| 方法 | 描述 |
+|------|------|
+| [`GetProjectionType`](get-projection-type.md) | 获取投影类型 |
+| [`SetProjectionType`](set-projection-type.md) | 设置投影类型 |
+| [`GetFieldOfView`](get-field-of-view.md) | 获取视场角（透视投影） |
+| [`SetFieldOfView`](set-field-of-view.md) | 设置视场角 |
+| [`GetOrthographicSize`](get-orthographic-size.md) | 获取正交投影大小 |
+| [`SetOrthographicSize`](set-orthographic-size.md) | 设置正交投影大小 |
+
+### 裁剪平面
+
+| 方法 | 描述 |
+|------|------|
+| [`GetNearClipPlane`](get-near-clip-plane.md) | 获取近裁剪面距离 |
+| [`SetNearClipPlane`](set-near-clip-plane.md) | 设置近裁剪面距离 |
+| [`GetFarClipPlane`](get-far-clip-plane.md) | 获取远裁剪面距离 |
+| [`SetFarClipPlane`](set-far-clip-plane.md) | 设置远裁剪面距离 |
+
+### 相机属性
+
+| 方法 | 描述 |
+|------|------|
+| [`GetDepth`](../../rhi/texture/get-depth.md) | 获取深度值 |
+| [`SetDepth`](set-depth.md) | 设置深度值 |
+| [`IsPrimary`](is-primary.md) | 检查是否为主相机 |
+| [`SetPrimary`](set-primary.md) | 设置为主相机 |
+| [`GetClearColor`](get-clear-color.md) | 获取清除颜色 |
+| [`SetClearColor`](../../rhi/opengl/pipeline-state/set-clear-color.md) | 设置清除颜色 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Components/CameraComponent.h>
+#include <XCEngine/Components/GameObject.h>
+
+using namespace XCEngine::Components;
+
+void SetupCamera(GameObject* cameraObject) {
+    auto camera = cameraObject->AddComponent<CameraComponent>();
+    
+    camera->SetProjectionType(CameraProjectionType::Perspective);
+    camera->SetFieldOfView(60.0f);
+    camera->SetNearClipPlane(0.1f);
+    camera->SetFarClipPlane(1000.0f);
+    camera->SetPrimary(true);
+}
+```
+
+## 相关文档
+
+- [Components 模块总览](../components.md) - Components 模块总览
+- [Component](../component/component.md) - 组件基类
+- [TransformComponent](../transform-component/transform-component.md) - 变换组件
--- a/docs/api/components/component/component.md
+++ b/docs/api/components/component/component.md
@@ -63,5 +63,5 @@ public:
 ## 相关文档

 - [Components 模块总览](../components.md) - Components 模块总览
- [GameObject](game-object/game-object.md) - 游戏对象
- [TransformComponent](transform-component/transform-component.md) - 变换组件
+- [GameObject](../game-object/game-object.md) - 游戏对象
+- [TransformComponent](../transform-component/transform-component.md) - 变换组件
--- a/docs/api/components/component/get-scene.md
+++ b/docs/api/components/component/get-scene.md
@@ -11,4 +11,4 @@ Scene* GetScene() const;
 ## 相关文档

 - [Component 总览](component.md)
- [Scene](../scene/scene/scene.md)
+- [Scene](../../scene/scene.md)
--- a/docs/api/components/component/transform.md
+++ b/docs/api/components/component/transform.md
@@ -13,4 +13,4 @@ TransformComponent& transform() const;
 ## 相关文档

 - [Component 总览](component.md)
- [TransformComponent](transform-component/transform-component.md)
+- [TransformComponent](../transform-component/transform-component.md)
--- a/docs/api/components/components.md
+++ b/docs/api/components/components.md
@@ -25,6 +25,20 @@ Components 模块是 XCEngine ECS 架构中的组件层，提供各种游戏对
 |------|------|------|
 | [TransformComponent](transform-component/transform-component.md) | `TransformComponent.h` | 变换组件，包含位置、旋转、缩放 |

+### 渲染组件
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [CameraComponent](camera-component/camera-component.md) | `CameraComponent.h` | 相机组件，定义视图和投影参数 |
+| [LightComponent](light-component/light-component.md) | `LightComponent.h` | 光源组件，支持方向光、点光、聚光灯 |
+
+### 音频组件
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [AudioSourceComponent](audio-source-component/audio-source-component.md) | `AudioSourceComponent.h` | 音频源组件，负责声音播放和3D音效 |
+| [AudioListenerComponent](audio-listener-component/audio-listener-component.md) | `AudioListenerComponent.h` | 音频监听组件，接收声音并处理多普勒效应和混响 |
+
 ## 使用示例

 ```cpp
--- a/docs/api/components/game-object/add-component.md
+++ b/docs/api/components/game-object/add-component.md
@@ -20,4 +20,4 @@ T* AddComponent(Args&&... args);
 ## 相关文档

 - [GameObject 总览](game-object.md)
- [Component](component/component.md)
+- [Component](../component/component.md)
--- a/docs/api/components/game-object/game-object.md
+++ b/docs/api/components/game-object/game-object.md
@@ -113,6 +113,6 @@ void FindAndOperate() {
 ## 相关文档

 - [Components 模块总览](../components.md) - Components 模块总览
- [Component](component/component.md) - 组件基类
- [TransformComponent](transform-component/transform-component.md) - 变换组件
- [Scene](../scene/scene/scene.md) - 场景
+- [Component](../component/component.md) - 组件基类
+- [TransformComponent](../transform-component/transform-component.md) - 变换组件
+- [Scene](../../scene/scene.md) - 场景
--- a/docs/api/components/game-object/get-scene.md
+++ b/docs/api/components/game-object/get-scene.md
@@ -11,4 +11,4 @@ Scene* GetScene() const;
 ## 相关文档

 - [GameObject 总览](game-object.md)
- [Scene](../scene/scene/scene.md)
+- [Scene](../../scene/scene.md)
--- a/docs/api/components/game-object/get-transform.md
+++ b/docs/api/components/game-object/get-transform.md
@@ -12,4 +12,4 @@ const TransformComponent* GetTransform() const;
 ## 相关文档

 - [GameObject 总览](game-object.md)
- [TransformComponent](transform-component/transform-component.md)
+- [TransformComponent](../transform-component/transform-component.md)
--- a/docs/api/components/light-component/light-component.md
+++ b/docs/api/components/light-component/light-component.md
@@ -0,0 +1,90 @@
+# LightComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/LightComponent.h`
+
+**描述**: 光源组件，支持方向光、点光、聚光灯三种类型，可设置颜色、强度和阴影。
+
+## 概述
+
+LightComponent 是 XCEngine ECS 系统中的光源组件，支持三种光源类型：方向光（Directional）、点光（Point）和聚光灯（Spot）。方向光从无穷远处照射，模拟太阳光；点光从一个点向所有方向照射；聚光灯沿一个锥形方向照射。光源组件可以设置颜色、强度、作用范围和是否投射阴影。
+
+## 枚举
+
+### LightType
+
+| 枚举值 | 描述 |
+|--------|------|
+| `Directional` | 方向光，从无穷远处照射 |
+| `Point` | 点光，从一个点向所有方向照射 |
+| `Spot` | 聚光灯，沿锥形方向照射 |
+
+## 公共方法
+
+### 光源类型
+
+| 方法 | 描述 |
+|------|------|
+| [`GetLightType`](get-light-type.md) | 获取光源类型 |
+| [`SetLightType`](set-light-type.md) | 设置光源类型 |
+
+### 光源属性
+
+| 方法 | 描述 |
+|------|------|
+| [`GetColor`](get-color.md) | 获取光源颜色 |
+| [`SetColor`](set-color.md) | 设置光源颜色 |
+| [`GetIntensity`](get-intensity.md) | 获取光源强度 |
+| [`SetIntensity`](set-intensity.md) | 设置光源强度 |
+| [`GetRange`](get-range.md) | 获取作用范围（点光/聚光灯） |
+| [`SetRange`](set-range.md) | 设置作用范围 |
+
+### 聚光灯属性
+
+| 方法 | 描述 |
+|------|------|
+| [`GetSpotAngle`](get-spot-angle.md) | 获取聚光灯角度 |
+| [`SetSpotAngle`](set-spot-angle.md) | 设置聚光灯角度 |
+
+### 阴影
+
+| 方法 | 描述 |
+|------|------|
+| [`GetCastsShadows`](get-casts-shadows.md) | 检查是否投射阴影 |
+| [`SetCastsShadows`](set-casts-shadows.md) | 设置是否投射阴影 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Components/LightComponent.h>
+#include <XCEngine/Components/GameObject.h>
+
+using namespace XCEngine::Components;
+
+void SetupLighting(GameObject* lightObject) {
+    auto light = lightObject->AddComponent<LightComponent>();
+    
+    light->SetLightType(LightType::Directional);
+    light->SetColor(Math::Color::White());
+    light->SetIntensity(1.0f);
+    light->SetCastsShadows(true);
+}
+
+void SetupPointLight(GameObject* pointLightObject) {
+    auto pointLight = pointLightObject->AddComponent<LightComponent>();
+    
+    pointLight->SetLightType(LightType::Point);
+    pointLight->SetColor(Math::Color(1.0f, 0.8f, 0.6f, 1.0f));
+    pointLight->SetIntensity(2.0f);
+    pointLight->SetRange(10.0f);
+}
+```
+
+## 相关文档
+
+- [Components 模块总览](../components.md) - Components 模块总览
+- [Component](../component/component.md) - 组件基类
+- [TransformComponent](../transform-component/transform-component.md) - 变换组件
--- a/docs/api/components/transform-component/get-position.md
+++ b/docs/api/components/transform-component/get-position.md
@@ -1,33 +1,34 @@
-# GetPosition
+# TransformComponent::GetPosition

-Get the world position of this transform.
-
-## Syntax
+获取变换的世界空间位置。

 ```cpp
 Math::Vector3 GetPosition() const;
 ```

-## Returns
+返回变换的世界空间位置。如果变换有父对象，世界位置由局部位置与父对象世界位置组合计算得出。

-Returns the world position as a `Math::Vector3`.
+**返回：** `Math::Vector3` - 世界空间位置向量

-## Remarks
+**线程安全：** ✅ (只读操作)

-Returns the world-space position of this transform. If this transform has a parent, the world position is computed by combining the local position with the parent's world position.
-
-## See Also
-
- [GetLocalPosition](get-local-position)
- [SetLocalPosition](set-local-position)
- [SetPosition](set-position)
-
-## Examples
+**示例：**

 ```cpp
+#include <XCEngine/Components/TransformComponent.h>
+
+using namespace XCEngine::Components;
+
 void Example(TransformComponent* transform) {
    Math::Vector3 worldPos = transform->GetPosition();
-    XC_LOG_INFO("World position: ({}, {}, {})", 
+    printf("World position: (%f, %f, %f)\n", 
        worldPos.x, worldPos.y, worldPos.z);
 }
 ```
+
+## 相关文档
+
+- [TransformComponent 总览](transform-component.md) - 返回类总览
+- [GetLocalPosition](get-local-position.md) - 获取局部位置
+- [SetPosition](set-position.md) - 设置世界位置
+- [SetLocalPosition](set-local-position.md) - 设置局部位置
--- a/docs/api/components/transform-component/transform-component.md
+++ b/docs/api/components/transform-component/transform-component.md
@@ -122,5 +122,5 @@ void TransformExample(TransformComponent* transform) {
 ## 相关文档

 - [Components 模块总览](../components.md) - Components 模块总览
- [Component](component/component.md) - 组件基类
- [GameObject](game-object/game-object.md) - 游戏对象
+- [Component](../component/component.md) - 组件基类
+- [GameObject](../game-object/game-object.md) - 游戏对象