From c2354530b9dcf511c549cbe721d8a2e7f8a9ddbe Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Thu, 26 Mar 2026 02:02:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20light-component=20?= =?UTF-8?q?=E5=85=A8=E9=83=A8=E6=96=B9=E6=B3=95=E6=96=87=E6=A1=A3=E5=8F=8A?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=85=B6=E4=BB=96=E6=A8=A1=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - components: 新增 light-component 全部12个方法文档 - resources: 更新 audio-loader, resource-file-system 文档 - rhi: 更新 opengl/fence 文档 --- .../light-component/get-casts-shadows.md | 38 ++++++++++++++++ .../components/light-component/get-color.md | 37 ++++++++++++++++ .../light-component/get-intensity.md | 37 ++++++++++++++++ .../light-component/get-light-type.md | 42 ++++++++++++++++++ .../components/light-component/get-range.md | 37 ++++++++++++++++ .../light-component/get-spot-angle.md | 37 ++++++++++++++++ .../light-component/set-casts-shadows.md | 40 +++++++++++++++++ .../components/light-component/set-color.md | 43 +++++++++++++++++++ .../light-component/set-intensity.md | 43 +++++++++++++++++++ .../light-component/set-light-type.md | 43 +++++++++++++++++++ .../components/light-component/set-range.md | 37 ++++++++++++++++ .../light-component/set-spot-angle.md | 37 ++++++++++++++++ docs/api/resources/audio-loader/index.md | 2 +- .../api/resources/audioclip/get-audio-data.md | 2 +- .../resources/resource-file-system/index.md | 2 +- docs/api/rhi/opengl/fence/fence.md | 42 +++--------------- 16 files changed, 480 insertions(+), 39 deletions(-) create mode 100644 docs/api/components/light-component/get-casts-shadows.md create mode 100644 docs/api/components/light-component/get-color.md create mode 100644 docs/api/components/light-component/get-intensity.md create mode 100644 docs/api/components/light-component/get-light-type.md create mode 100644 docs/api/components/light-component/get-range.md create mode 100644 docs/api/components/light-component/get-spot-angle.md create mode 100644 docs/api/components/light-component/set-casts-shadows.md create mode 100644 docs/api/components/light-component/set-color.md create mode 100644 docs/api/components/light-component/set-intensity.md create mode 100644 docs/api/components/light-component/set-light-type.md create mode 100644 docs/api/components/light-component/set-range.md create mode 100644 docs/api/components/light-component/set-spot-angle.md diff --git a/docs/api/components/light-component/get-casts-shadows.md b/docs/api/components/light-component/get-casts-shadows.md new file mode 100644 index 00000000..553188f1 --- /dev/null +++ b/docs/api/components/light-component/get-casts-shadows.md @@ -0,0 +1,38 @@ +# GetCastsShadows + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 检查光源是否投射阴影。 + +## 函数签名 + +```cpp +bool GetCastsShadows() const; +``` + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `bool` | true 表示投射阴影，false 表示不投射阴影 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void CheckShadowCasting(LightComponent* light) { + if (light->GetCastsShadows()) { + printf("This light casts shadows\n"); + } +} +``` + +## 相关文档 + +- [LightComponent](./light-component.md) - 光源组件 +- [SetCastsShadows](./set-casts-shadows.md) - 设置阴影投射 diff --git a/docs/api/components/light-component/get-color.md b/docs/api/components/light-component/get-color.md new file mode 100644 index 00000000..2a6cb3b1 --- /dev/null +++ b/docs/api/components/light-component/get-color.md @@ -0,0 +1,37 @@ +# GetColor + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 获取光源的颜色。 + +## 函数签名 + +```cpp +const Math::Color& GetColor() const; +``` + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `const Math::Color&` | 光源颜色引用 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void PrintLightColor(LightComponent* light) { + const auto& color = light->GetColor(); + printf("Light color: (%.2f, %.2f, %.2f)\n", color.r, color.g, color.b); +} +``` + +## 相关文档 + +- [LightComponent](light-component.md) - 光源组件 +- [SetColor](set-color.md) - 设置光源颜色 diff --git a/docs/api/components/light-component/get-intensity.md b/docs/api/components/light-component/get-intensity.md new file mode 100644 index 00000000..191c7e88 --- /dev/null +++ b/docs/api/components/light-component/get-intensity.md @@ -0,0 +1,37 @@ +# GetIntensity + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 获取光源的强度。 + +## 函数签名 + +```cpp +float GetIntensity() const; +``` + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `float` | 光源强度，默认值为 1.0 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void PrintLightIntensity(LightComponent* light) { + float intensity = light->GetIntensity(); + printf("Light intensity: %.2f\n", intensity); +} +``` + +## 相关文档 + +- [LightComponent](./light-component.md) - 光源组件 +- [SetIntensity](./set-intensity.md) - 设置光源强度 diff --git a/docs/api/components/light-component/get-light-type.md b/docs/api/components/light-component/get-light-type.md new file mode 100644 index 00000000..f8e0b33e --- /dev/null +++ b/docs/api/components/light-component/get-light-type.md @@ -0,0 +1,42 @@ +# GetLightType + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 获取光源的类型。 + +## 函数签名 + +```cpp +LightType GetLightType() const; +``` + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `LightType` | 光源类型：`Directional`（定向光）、`Point`（点光源）或 `Spot`（聚光灯） | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void CheckLightType(LightComponent* light) { + if (light->GetLightType() == LightType::Directional) { + printf("Directional light\n"); + } else if (light->GetLightType() == LightType::Point) { + printf("Point light\n"); + } else { + printf("Spot light\n"); + } +} +``` + +## 相关文档 + +- [LightComponent](light-component.md) - 光源组件 +- [SetLightType](set-light-type.md) - 设置光源类型 diff --git a/docs/api/components/light-component/get-range.md b/docs/api/components/light-component/get-range.md new file mode 100644 index 00000000..0875a8ba --- /dev/null +++ b/docs/api/components/light-component/get-range.md @@ -0,0 +1,37 @@ +# GetRange + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 获取光源的作用范围（仅对点光源和聚光灯有效）。 + +## 函数签名 + +```cpp +float GetRange() const; +``` + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `float` | 作用范围（米），默认值为 10.0 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void PrintLightRange(LightComponent* light) { + float range = light->GetRange(); + printf("Light range: %.2f meters\n", range); +} +``` + +## 相关文档 + +- [LightComponent](./light-component.md) - 光源组件 +- [SetRange](./set-range.md) - 设置作用范围 diff --git a/docs/api/components/light-component/get-spot-angle.md b/docs/api/components/light-component/get-spot-angle.md new file mode 100644 index 00000000..601cefda --- /dev/null +++ b/docs/api/components/light-component/get-spot-angle.md @@ -0,0 +1,37 @@ +# GetSpotAngle + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 获取聚光灯的角度（仅对聚光灯有效）。 + +## 函数签名 + +```cpp +float GetSpotAngle() const; +``` + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `float` | 聚光灯角度（度），默认值为 30.0 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void PrintSpotAngle(LightComponent* light) { + float angle = light->GetSpotAngle(); + printf("Spot angle: %.1f degrees\n", angle); +} +``` + +## 相关文档 + +- [LightComponent](./light-component.md) - 光源组件 +- [SetSpotAngle](./set-spot-angle.md) - 设置聚光灯角度 diff --git a/docs/api/components/light-component/set-casts-shadows.md b/docs/api/components/light-component/set-casts-shadows.md new file mode 100644 index 00000000..a5ed36d3 --- /dev/null +++ b/docs/api/components/light-component/set-casts-shadows.md @@ -0,0 +1,40 @@ +# SetCastsShadows + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 设置光源是否投射阴影。 + +## 函数签名 + +```cpp +void SetCastsShadows(bool value); +``` + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `value` | `bool` | true 启用阴影投射，false 禁用阴影投射 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void SetupShadowCasting(LightComponent* light) { + // 启用阴影 + light->SetCastsShadows(true); + + // 禁用阴影（性能优化） + light->SetCastsShadows(false); +} +``` + +## 相关文档 + +- [LightComponent](./light-component.md) - 光源组件 +- [GetCastsShadows](./get-casts-shadows.md) - 检查阴影投射 diff --git a/docs/api/components/light-component/set-color.md b/docs/api/components/light-component/set-color.md new file mode 100644 index 00000000..12fb97e5 --- /dev/null +++ b/docs/api/components/light-component/set-color.md @@ -0,0 +1,43 @@ +# SetColor + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 设置光源的颜色。 + +## 函数签名 + +```cpp +void SetColor(const Math::Color& value); +``` + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `value` | `const Math::Color&` | 光源颜色 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void SetupLightColor(LightComponent* light) { + // 白色光源 + light->SetColor(Math::Color::White()); + + // 暖色光源 + light->SetColor(Math::Color(1.0f, 0.9f, 0.7f, 1.0f)); + + // 蓝色光源 + light->SetColor(Math::Color(0.5f, 0.7f, 1.0f, 1.0f)); +} +``` + +## 相关文档 + +- [LightComponent](light-component.md) - 光源组件 +- [GetColor](get-color.md) - 获取光源颜色 diff --git a/docs/api/components/light-component/set-intensity.md b/docs/api/components/light-component/set-intensity.md new file mode 100644 index 00000000..081d43ff --- /dev/null +++ b/docs/api/components/light-component/set-intensity.md @@ -0,0 +1,43 @@ +# SetIntensity + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 设置光源的强度。 + +## 函数签名 + +```cpp +void SetIntensity(float value); +``` + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `value` | `float` | 光源强度，值越大光线越亮 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void SetupLightIntensity(LightComponent* light) { + // 标准强度 + light->SetIntensity(1.0f); + + // 高强度（太阳光） + light->SetIntensity(3.0f); + + // 低强度（月光） + light->SetIntensity(0.2f); +} +``` + +## 相关文档 + +- [LightComponent](./light-component.md) - 光源组件 +- [GetIntensity](./get-intensity.md) - 获取光源强度 diff --git a/docs/api/components/light-component/set-light-type.md b/docs/api/components/light-component/set-light-type.md new file mode 100644 index 00000000..01cd991f --- /dev/null +++ b/docs/api/components/light-component/set-light-type.md @@ -0,0 +1,43 @@ +# SetLightType + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 设置光源的类型。 + +## 函数签名 + +```cpp +void SetLightType(LightType value); +``` + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `value` | `LightType` | 光源类型：`Directional`（定向光）、`Point`（点光源）或 `Spot`（聚光灯） | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void SetupLightType(LightComponent* light) { + // 定向光（太阳光） + light->SetLightType(LightType::Directional); + + // 点光源（灯泡） + light->SetLightType(LightType::Point); + + // 聚光灯（手电筒） + light->SetLightType(LightType::Spot); +} +``` + +## 相关文档 + +- [LightComponent](light-component.md) - 光源组件 +- [GetLightType](get-light-type.md) - 获取光源类型 diff --git a/docs/api/components/light-component/set-range.md b/docs/api/components/light-component/set-range.md new file mode 100644 index 00000000..86129ce6 --- /dev/null +++ b/docs/api/components/light-component/set-range.md @@ -0,0 +1,37 @@ +# SetRange + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 设置光源的作用范围（仅对点光源和聚光灯有效）。 + +## 函数签名 + +```cpp +void SetRange(float value); +``` + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `value` | `float` | 作用范围（米） | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void SetupLightRange(LightComponent* light) { + light->SetLightType(LightType::Point); + light->SetRange(15.0f); // 15米范围 +} +``` + +## 相关文档 + +- [LightComponent](./light-component.md) - 光源组件 +- [GetRange](./get-range.md) - 获取作用范围 diff --git a/docs/api/components/light-component/set-spot-angle.md b/docs/api/components/light-component/set-spot-angle.md new file mode 100644 index 00000000..31282557 --- /dev/null +++ b/docs/api/components/light-component/set-spot-angle.md @@ -0,0 +1,37 @@ +# SetSpotAngle + +**所属类**: `LightComponent` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 设置聚光灯的角度（仅对聚光灯有效）。 + +## 函数签名 + +```cpp +void SetSpotAngle(float value); +``` + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `value` | `float` | 聚光灯角度（度），通常在 1.0 到 90.0 之间 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void SetupSpotLight(LightComponent* light) { + light->SetLightType(LightType::Spot); + light->SetSpotAngle(45.0f); // 45度锥角 +} +``` + +## 相关文档 + +- [LightComponent](./light-component.md) - 光源组件 +- [GetSpotAngle](./get-spot-angle.md) - 获取聚光灯角度 diff --git a/docs/api/resources/audio-loader/index.md b/docs/api/resources/audio-loader/index.md index cf56deab..fd8feb01 100644 --- a/docs/api/resources/audio-loader/index.md +++ b/docs/api/resources/audio-loader/index.md @@ -22,7 +22,7 @@ |------|--------|------| | [AudioLoader](constructor.md) | - | 构造函数 | | [~AudioLoader](destructor.md) | - | 析构函数 | -| [GetResourceType](methods/get-resource-type.md) | `ResourceType` | 返回资源类型 `AudioClip` | +| `GetResourceType()` | `ResourceType` | 返回资源类型 `AudioClip`（继承自 IResourceLoader） | | [GetSupportedExtensions](get-supported-extensions.md) | `Array` | 获取支持的扩展名列表 | | [CanLoad](can-load.md) | `bool` | 检查是否能够加载指定路径的资源 | | [Load](load.md) | `LoadResult` | 加载音频资源 | diff --git a/docs/api/resources/audioclip/get-audio-data.md b/docs/api/resources/audioclip/get-audio-data.md index 38b86f7e..a4a79a56 100644 --- a/docs/api/resources/audioclip/get-audio-data.md +++ b/docs/api/resources/audioclip/get-audio-data.md @@ -25,5 +25,5 @@ size_t dataSize = data.Size(); ## 相关文档 -- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [AudioClip 总览](audioclip.md) - 返回类总览 - [SetAudioData](setaudiodata.md) - 设置音频数据 diff --git a/docs/api/resources/resource-file-system/index.md b/docs/api/resources/resource-file-system/index.md index 83ebbbc4..3a7ecd4d 100644 --- a/docs/api/resources/resource-file-system/index.md +++ b/docs/api/resources/resource-file-system/index.md @@ -47,7 +47,7 @@ ## 使用示例 ```cpp -#include "Resources/ResourceFileSystem.h" +#include using namespace XCEngine; using namespace XCEngine::Resources; diff --git a/docs/api/rhi/opengl/fence/fence.md b/docs/api/rhi/opengl/fence/fence.md index f55e142f..2c3154dc 100644 --- a/docs/api/rhi/opengl/fence/fence.md +++ b/docs/api/rhi/opengl/fence/fence.md @@ -8,38 +8,16 @@ `OpenGLFence` 提供基于 OpenGL 同步对象（`GLsync`）的栅栏实现，用于 CPU-GPU 同步。当 GPU 完成特定操作后，栅栏会被设置为 signaled 状态，CPU 可以通过 `Wait` 方法等待该状态。 -### FenceStatus 枚举 - -```cpp -enum class FenceStatus { - Signaled, // 栅栏已signaled，操作已完成 - Unsignaled, // 栅栏未signaled，操作未完成 - Error // 发生错误 -}; -``` - -### 私有成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_sync` | `void*` | OpenGL GLsync 句柄 | -| `m_fenceValue` | `uint64_t` | 当前栅栏值 | -| `m_completedValue` | `uint64_t` | 已完成的栅栏值 | -| `m_signaled` | `bool` | 软件层面的signaled状态标志 | - ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](initialize.md) | 初始化栅栏，设置初始值和状态 | +| [`OpenGLFence`](constructor.md) | 构造函数 | +| [`Initialize`](initialize.md) | 初始化栅栏，设置初始值 | | [`Shutdown`](shutdown.md) | 关闭栅栏，释放 GLsync 资源 | -| [`Signal`](signal.md) | 信号栅栏，创建/更新同步对象 | -| [`Wait`](wait.md) | 等待栅栏达到 signaled 状态 | -| [`Reset`](reset.md) | 重置栅栏，删除同步对象 | -| [`IsSignaled`](is-signaled.md) | 检查软件层面的signaled状态 | -| [`GetStatus`](get-status.md) | 获取 OpenGL 层面的同步状态 | +| [`Signal`](signal.md) | 信号栅栏（重载：有无参数版本） | +| [`Wait`](wait.md) | 等待栅栏达到指定值 | | [`GetCompletedValue`](get-completed-value.md) | 获取已完成的栅栏值 | -| [`GetCurrentValue`](get-current-value.md) | 获取当前栅栏值 | | [`GetNativeHandle`](get-native-handle.md) | 获取原生 GLsync 句柄 | ## 使用示例 @@ -51,21 +29,13 @@ using namespace XCEngine::RHI; // 创建并初始化栅栏 OpenGLFence fence; -fence.Initialize(false); +fence.Initialize(0); // 执行 GPU 操作后信号栅栏 fence.Signal(); // 等待栅栏，最多等待 1 秒 -fence.Wait(1000000000); - -// 检查状态 -if (fence.IsSignaled()) { - // 操作已完成 -} - -// 重置并复用 -fence.Reset(); +fence.Wait(1); ``` ## 相关文档