From 5c8042775c1bf195c999002d2631c38d04e6bbd2 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Thu, 26 Mar 2026 21:32:43 +0800 Subject: [PATCH] docs: rebuild Rendering API content --- docs/api/XCEngine/Components/Components.md | 2 + .../MeshFilterComponent/ClearMesh.md | 17 ++ .../MeshFilterComponent/Deserialize.md | 26 +++ .../Components/MeshFilterComponent/GetMesh.md | 17 ++ .../MeshFilterComponent/GetMeshHandle.md | 16 ++ .../MeshFilterComponent/GetMeshPath.md | 21 +++ .../Components/MeshFilterComponent/GetName.md | 15 ++ .../MeshFilterComponent.md | 47 ++++++ .../MeshFilterComponent/Serialize.md | 22 +++ .../Components/MeshFilterComponent/SetMesh.md | 26 +++ .../MeshRendererComponent/ClearMaterials.md | 20 +++ .../MeshRendererComponent/Deserialize.md | 25 +++ .../MeshRendererComponent/GetCastShadows.md | 20 +++ .../MeshRendererComponent/GetMaterial.md | 21 +++ .../MeshRendererComponent/GetMaterialCount.md | 17 ++ .../GetMaterialHandle.md | 25 +++ .../MeshRendererComponent/GetMaterialPaths.md | 17 ++ .../MeshRendererComponent/GetName.md | 15 ++ .../GetReceiveShadows.md | 20 +++ .../MeshRendererComponent/GetRenderLayer.md | 20 +++ .../MeshRendererComponent.md | 55 +++++++ .../MeshRendererComponent/Serialize.md | 25 +++ .../MeshRendererComponent/SetCastShadows.md | 20 +++ .../MeshRendererComponent/SetMaterial.md | 27 ++++ .../MeshRendererComponent/SetMaterials.md | 21 +++ .../SetReceiveShadows.md | 20 +++ .../MeshRendererComponent/SetRenderLayer.md | 20 +++ .../BuiltinForwardPipeline.md | 61 +++++++ .../BuiltinForwardPipeline/Destructor.md | 16 ++ .../BuiltinForwardPipeline/Initialize.md | 31 ++++ .../BuiltinForwardPipeline/Render.md | 46 ++++++ .../BuiltinForwardPipeline/Shutdown.md | 23 +++ .../XCEngine/Rendering/Pipelines/Pipelines.md | 30 ++++ .../RenderCameraData/RenderCameraData.md | 46 ++++++ .../Rendering/RenderContext/IsValid.md | 32 ++++ .../Rendering/RenderContext/RenderContext.md | 47 ++++++ .../Rendering/RenderPipeline/Destructor.md | 16 ++ .../Rendering/RenderPipeline/Initialize.md | 26 +++ .../Rendering/RenderPipeline/Render.md | 31 ++++ .../RenderPipeline/RenderPipeline.md | 52 ++++++ .../Rendering/RenderPipeline/Shutdown.md | 16 ++ .../RenderPipelineAsset/CreatePipeline.md | 24 +++ .../RenderPipelineAsset/Destructor.md | 16 ++ .../RenderPipelineAsset.md | 39 +++++ .../RenderResourceCache/Destructor.md | 16 ++ .../RenderResourceCache/GetOrCreateMesh.md | 38 +++++ .../RenderResourceCache/GetOrCreateTexture.md | 38 +++++ .../RenderResourceCache.md | 70 ++++++++ .../Rendering/RenderResourceCache/Shutdown.md | 28 ++++ .../Rendering/RenderSceneExtractor/Extract.md | 42 +++++ .../RenderSceneExtractor.md | 67 ++++++++ .../RenderSurface/ClearClearColorOverride.md | 17 ++ .../Rendering/RenderSurface/Constructor.md | 18 +++ .../RenderSurface/GetClearColorOverride.md | 20 +++ .../RenderSurface/GetColorAttachments.md | 22 +++ .../RenderSurface/GetColorStateAfter.md | 16 ++ .../RenderSurface/GetColorStateBefore.md | 16 ++ .../RenderSurface/GetDepthAttachment.md | 16 ++ .../Rendering/RenderSurface/GetHeight.md | 17 ++ .../Rendering/RenderSurface/GetWidth.md | 17 ++ .../RenderSurface/HasClearColorOverride.md | 18 +++ .../RenderSurface/IsAutoTransitionEnabled.md | 17 ++ .../Rendering/RenderSurface/RenderSurface.md | 70 ++++++++ .../RenderSurface/SetAutoTransitionEnabled.md | 22 +++ .../RenderSurface/SetClearColorOverride.md | 22 +++ .../RenderSurface/SetColorAttachment.md | 26 +++ .../RenderSurface/SetColorAttachments.md | 26 +++ .../RenderSurface/SetColorStateAfter.md | 21 +++ .../RenderSurface/SetColorStateBefore.md | 21 +++ .../RenderSurface/SetDepthAttachment.md | 20 +++ .../Rendering/RenderSurface/SetSize.md | 22 +++ docs/api/XCEngine/Rendering/Rendering.md | 88 +++++++++++ .../Rendering/SceneRenderer/Constructor.md | 19 +++ .../Rendering/SceneRenderer/Destructor.md | 22 +++ .../Rendering/SceneRenderer/GetPipeline.md | 21 +++ .../Rendering/SceneRenderer/Render.md | 38 +++++ .../Rendering/SceneRenderer/SceneRenderer.md | 46 ++++++ .../Rendering/SceneRenderer/SetPipeline.md | 25 +++ .../VisibleRenderObject.md | 37 +++++ ...Extraction-And-Builtin-Forward-Pipeline.md | 149 ++++++++++++++++++ docs/api/_meta/rebuild-status.md | 40 ++--- 81 files changed, 2350 insertions(+), 27 deletions(-) create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/ClearMesh.md create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/Deserialize.md create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/GetMesh.md create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/GetMeshHandle.md create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/GetMeshPath.md create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/GetName.md create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/MeshFilterComponent.md create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/Serialize.md create mode 100644 docs/api/XCEngine/Components/MeshFilterComponent/SetMesh.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/ClearMaterials.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/Deserialize.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/GetCastShadows.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/GetMaterial.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialCount.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialHandle.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialPaths.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/GetName.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/GetReceiveShadows.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/GetRenderLayer.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/MeshRendererComponent.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/Serialize.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/SetCastShadows.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/SetMaterial.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/SetMaterials.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/SetReceiveShadows.md create mode 100644 docs/api/XCEngine/Components/MeshRendererComponent/SetRenderLayer.md create mode 100644 docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md create mode 100644 docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Destructor.md create mode 100644 docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Initialize.md create mode 100644 docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Render.md create mode 100644 docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Shutdown.md create mode 100644 docs/api/XCEngine/Rendering/Pipelines/Pipelines.md create mode 100644 docs/api/XCEngine/Rendering/RenderCameraData/RenderCameraData.md create mode 100644 docs/api/XCEngine/Rendering/RenderContext/IsValid.md create mode 100644 docs/api/XCEngine/Rendering/RenderContext/RenderContext.md create mode 100644 docs/api/XCEngine/Rendering/RenderPipeline/Destructor.md create mode 100644 docs/api/XCEngine/Rendering/RenderPipeline/Initialize.md create mode 100644 docs/api/XCEngine/Rendering/RenderPipeline/Render.md create mode 100644 docs/api/XCEngine/Rendering/RenderPipeline/RenderPipeline.md create mode 100644 docs/api/XCEngine/Rendering/RenderPipeline/Shutdown.md create mode 100644 docs/api/XCEngine/Rendering/RenderPipelineAsset/CreatePipeline.md create mode 100644 docs/api/XCEngine/Rendering/RenderPipelineAsset/Destructor.md create mode 100644 docs/api/XCEngine/Rendering/RenderPipelineAsset/RenderPipelineAsset.md create mode 100644 docs/api/XCEngine/Rendering/RenderResourceCache/Destructor.md create mode 100644 docs/api/XCEngine/Rendering/RenderResourceCache/GetOrCreateMesh.md create mode 100644 docs/api/XCEngine/Rendering/RenderResourceCache/GetOrCreateTexture.md create mode 100644 docs/api/XCEngine/Rendering/RenderResourceCache/RenderResourceCache.md create mode 100644 docs/api/XCEngine/Rendering/RenderResourceCache/Shutdown.md create mode 100644 docs/api/XCEngine/Rendering/RenderSceneExtractor/Extract.md create mode 100644 docs/api/XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/ClearClearColorOverride.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/Constructor.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/GetClearColorOverride.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/GetColorAttachments.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/GetColorStateAfter.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/GetColorStateBefore.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/GetDepthAttachment.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/GetHeight.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/GetWidth.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/HasClearColorOverride.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/IsAutoTransitionEnabled.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/RenderSurface.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/SetAutoTransitionEnabled.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/SetClearColorOverride.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachment.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachments.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/SetColorStateAfter.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/SetColorStateBefore.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/SetDepthAttachment.md create mode 100644 docs/api/XCEngine/Rendering/RenderSurface/SetSize.md create mode 100644 docs/api/XCEngine/Rendering/Rendering.md create mode 100644 docs/api/XCEngine/Rendering/SceneRenderer/Constructor.md create mode 100644 docs/api/XCEngine/Rendering/SceneRenderer/Destructor.md create mode 100644 docs/api/XCEngine/Rendering/SceneRenderer/GetPipeline.md create mode 100644 docs/api/XCEngine/Rendering/SceneRenderer/Render.md create mode 100644 docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md create mode 100644 docs/api/XCEngine/Rendering/SceneRenderer/SetPipeline.md create mode 100644 docs/api/XCEngine/Rendering/VisibleRenderObject/VisibleRenderObject.md create mode 100644 docs/api/_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md diff --git a/docs/api/XCEngine/Components/Components.md b/docs/api/XCEngine/Components/Components.md index 975a8638..a1ca6d33 100644 --- a/docs/api/XCEngine/Components/Components.md +++ b/docs/api/XCEngine/Components/Components.md @@ -19,6 +19,8 @@ - [ComponentFactoryRegistry](ComponentFactoryRegistry/ComponentFactoryRegistry.md) - `ComponentFactoryRegistry.h` - [GameObject](GameObject/GameObject.md) - `GameObject.h` - [LightComponent](LightComponent/LightComponent.md) - `LightComponent.h` +- [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md) - `MeshFilterComponent.h` +- [MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md) - `MeshRendererComponent.h` - [TransformComponent](TransformComponent/TransformComponent.md) - `TransformComponent.h` ## 相关文档 diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/ClearMesh.md b/docs/api/XCEngine/Components/MeshFilterComponent/ClearMesh.md new file mode 100644 index 00000000..6a63b19e --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/ClearMesh.md @@ -0,0 +1,17 @@ +# MeshFilterComponent::ClearMesh + +清空当前 mesh。 + +```cpp +void ClearMesh(); +``` + +## 行为说明 + +当前实现会重置内部 handle，并清空缓存路径。 + +## 相关文档 + +- [返回类型总览](MeshFilterComponent.md) +- [SetMesh](SetMesh.md) +- [GetMeshPath](GetMeshPath.md) diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/Deserialize.md b/docs/api/XCEngine/Components/MeshFilterComponent/Deserialize.md new file mode 100644 index 00000000..210b8e31 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/Deserialize.md @@ -0,0 +1,26 @@ +# MeshFilterComponent::Deserialize + +反序列化 mesh 信息。 + +```cpp +void Deserialize(std::istream& is) override; +``` + +## 行为说明 + +当前实现会： + +1. 先清空现有 handle 和路径。 +2. 按 `;` 分割 token。 +3. 识别 `mesh=`。 +4. 若路径非空，则调用 `ResourceManager::Get().Load()` 尝试重新加载。 + +## 当前实现说明 + +- 如果资源加载失败，`m_mesh` 可能仍然为空，但 `m_meshPath` 会保留反序列化得到的路径。 +- 当前序列化格式很轻量，适合人类可读文本，但没有更强的容错与版本化机制。 + +## 相关文档 + +- [返回类型总览](MeshFilterComponent.md) +- [Serialize](Serialize.md) diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/GetMesh.md b/docs/api/XCEngine/Components/MeshFilterComponent/GetMesh.md new file mode 100644 index 00000000..2b43312d --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/GetMesh.md @@ -0,0 +1,17 @@ +# MeshFilterComponent::GetMesh + +获取当前 mesh 指针。 + +```cpp +Resources::Mesh* GetMesh() const; +``` + +## 返回值 + +- 当前 mesh 指针；如果没有设置则返回 `nullptr`。 + +## 相关文档 + +- [返回类型总览](MeshFilterComponent.md) +- [GetMeshHandle](GetMeshHandle.md) +- [SetMesh](SetMesh.md) diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/GetMeshHandle.md b/docs/api/XCEngine/Components/MeshFilterComponent/GetMeshHandle.md new file mode 100644 index 00000000..bec74c8e --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/GetMeshHandle.md @@ -0,0 +1,16 @@ +# MeshFilterComponent::GetMeshHandle + +获取当前 mesh 资源句柄。 + +```cpp +const Resources::ResourceHandle& GetMeshHandle() const; +``` + +## 返回值 + +- 当前保存的 mesh `ResourceHandle` 常量引用。 + +## 相关文档 + +- [返回类型总览](MeshFilterComponent.md) +- [GetMesh](GetMesh.md) diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/GetMeshPath.md b/docs/api/XCEngine/Components/MeshFilterComponent/GetMeshPath.md new file mode 100644 index 00000000..6f078733 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/GetMeshPath.md @@ -0,0 +1,21 @@ +# MeshFilterComponent::GetMeshPath + +获取当前 mesh 路径字符串。 + +```cpp +const std::string& GetMeshPath() const; +``` + +## 返回值 + +- 当前缓存的 mesh 路径。 + +## 注意事项 + +- 当前路径只是组件内部缓存值，不保证文件一定存在。 + +## 相关文档 + +- [返回类型总览](MeshFilterComponent.md) +- [Serialize](Serialize.md) +- [Deserialize](Deserialize.md) diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/GetName.md b/docs/api/XCEngine/Components/MeshFilterComponent/GetName.md new file mode 100644 index 00000000..9ad868d7 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/GetName.md @@ -0,0 +1,15 @@ +# MeshFilterComponent::GetName + +返回组件名字。 + +```cpp +std::string GetName() const override; +``` + +## 返回值 + +- 当前固定返回 `"MeshFilter"`。 + +## 相关文档 + +- [返回类型总览](MeshFilterComponent.md) diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/MeshFilterComponent.md b/docs/api/XCEngine/Components/MeshFilterComponent/MeshFilterComponent.md new file mode 100644 index 00000000..fbe558c8 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/MeshFilterComponent.md @@ -0,0 +1,47 @@ +# MeshFilterComponent + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/MeshFilterComponent.h` + +**描述**: 持有一个 `Mesh` 资源引用，负责告诉渲染系统“这个对象要画哪一个网格”。 + +## 概述 + +`MeshFilterComponent` 和 [MeshRendererComponent](../MeshRendererComponent/MeshRendererComponent.md) 的拆分，很像 Unity 经典的 `MeshFilter + MeshRenderer` 设计： + +- `MeshFilterComponent` 决定几何体是什么。 +- `MeshRendererComponent` 决定材质槽和渲染设置是什么。 + +这种拆分的好处是很明确的： + +- 同一个 mesh 可以搭配不同材质策略。 +- 渲染系统在提取阶段可以清楚地区分“几何数据”和“绘制配置”。 + +## 当前实现边界 + +- 内部同时保存 `ResourceHandle` 和一个字符串路径。 +- [SetMesh](SetMesh.md) 会同步更新 `m_meshPath`。 +- [ClearMesh](ClearMesh.md) 会同时清空 handle 和路径。 +- [Deserialize](Deserialize.md) 会尝试通过 `ResourceManager` 重新加载 mesh。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [GetName](GetName.md) | 返回组件名字。 | +| [GetMesh](GetMesh.md) | 获取当前 mesh 指针。 | +| [GetMeshHandle](GetMeshHandle.md) | 获取当前 mesh handle。 | +| [GetMeshPath](GetMeshPath.md) | 获取当前 mesh 路径。 | +| [SetMesh](SetMesh.md) | 设置 mesh 资源。 | +| [ClearMesh](ClearMesh.md) | 清空当前 mesh。 | +| [Serialize](Serialize.md) | 序列化 mesh 路径。 | +| [Deserialize](Deserialize.md) | 反序列化并尝试重新加载 mesh。 | + +## 相关文档 + +- [Components](../Components.md) +- [MeshRendererComponent](../MeshRendererComponent/MeshRendererComponent.md) +- [RenderSceneExtractor](../../Rendering/RenderSceneExtractor/RenderSceneExtractor.md) diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/Serialize.md b/docs/api/XCEngine/Components/MeshFilterComponent/Serialize.md new file mode 100644 index 00000000..66531084 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/Serialize.md @@ -0,0 +1,22 @@ +# MeshFilterComponent::Serialize + +序列化当前 mesh 信息。 + +```cpp +void Serialize(std::ostream& os) const override; +``` + +## 行为说明 + +当前实现会输出： + +```text +mesh=; +``` + +这里只序列化路径，不会序列化 mesh 二进制内容本身。 + +## 相关文档 + +- [返回类型总览](MeshFilterComponent.md) +- [Deserialize](Deserialize.md) diff --git a/docs/api/XCEngine/Components/MeshFilterComponent/SetMesh.md b/docs/api/XCEngine/Components/MeshFilterComponent/SetMesh.md new file mode 100644 index 00000000..cee01665 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshFilterComponent/SetMesh.md @@ -0,0 +1,26 @@ +# MeshFilterComponent::SetMesh + +设置当前 mesh。 + +```cpp +void SetMesh(const Resources::ResourceHandle& mesh); +void SetMesh(Resources::Mesh* mesh); +``` + +## 行为说明 + +无论使用哪种重载，当前实现都会： + +- 更新内部 `ResourceHandle` +- 如果 mesh 非空，则把其 `GetPath()` 转成 `std::string` 写入 `m_meshPath` +- 否则清空路径 + +## 参数 + +- `mesh` - 要设置的 mesh 句柄或裸指针。 + +## 相关文档 + +- [返回类型总览](MeshFilterComponent.md) +- [GetMesh](GetMesh.md) +- [ClearMesh](ClearMesh.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/ClearMaterials.md b/docs/api/XCEngine/Components/MeshRendererComponent/ClearMaterials.md new file mode 100644 index 00000000..67b98fe6 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/ClearMaterials.md @@ -0,0 +1,20 @@ +# MeshRendererComponent::ClearMaterials + +清空所有材质槽。 + +```cpp +void ClearMaterials(); +``` + +## 行为说明 + +当前实现会同时清空： + +- `m_materials` +- `m_materialPaths` + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [SetMaterial](SetMaterial.md) +- [SetMaterials](SetMaterials.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/Deserialize.md b/docs/api/XCEngine/Components/MeshRendererComponent/Deserialize.md new file mode 100644 index 00000000..7c1dfd7e --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/Deserialize.md @@ -0,0 +1,25 @@ +# MeshRendererComponent::Deserialize + +反序列化材质槽和渲染标志。 + +```cpp +void Deserialize(std::istream& is) override; +``` + +## 行为说明 + +当前实现会： + +1. 先清空材质并重置默认标志。 +2. 解析 `materials`、`castShadows`、`receiveShadows` 和 `renderLayer`。 +3. 对每个非空材质路径调用 `ResourceManager::Get().Load()` 尝试重新加载。 + +## 当前实现说明 + +- 如果某个材质加载失败，对应路径仍会保留，但句柄可能为空。 +- 默认值是：`castShadows = true`、`receiveShadows = true`、`renderLayer = 0`。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [Serialize](Serialize.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/GetCastShadows.md b/docs/api/XCEngine/Components/MeshRendererComponent/GetCastShadows.md new file mode 100644 index 00000000..7fe6533d --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/GetCastShadows.md @@ -0,0 +1,20 @@ +# MeshRendererComponent::GetCastShadows + +获取投射阴影标志。 + +```cpp +bool GetCastShadows() const; +``` + +## 返回值 + +- 当前 `m_castShadows` 值。 + +## 当前实现说明 + +- 当前渲染路径还没有真正消费这个标志。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [SetCastShadows](SetCastShadows.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterial.md b/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterial.md new file mode 100644 index 00000000..70145f78 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterial.md @@ -0,0 +1,21 @@ +# MeshRendererComponent::GetMaterial + +获取指定槽位的材质指针。 + +```cpp +Resources::Material* GetMaterial(size_t index) const; +``` + +## 参数 + +- `index` - 材质槽索引。 + +## 返回值 + +- 若索引有效则返回对应材质。 +- 否则返回 `nullptr`。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [GetMaterialHandle](GetMaterialHandle.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialCount.md b/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialCount.md new file mode 100644 index 00000000..4363fb4d --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialCount.md @@ -0,0 +1,17 @@ +# MeshRendererComponent::GetMaterialCount + +获取当前材质槽数量。 + +```cpp +size_t GetMaterialCount() const; +``` + +## 返回值 + +- 当前 `m_materials.size()`。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [SetMaterial](SetMaterial.md) +- [SetMaterials](SetMaterials.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialHandle.md b/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialHandle.md new file mode 100644 index 00000000..fc2ffd50 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialHandle.md @@ -0,0 +1,25 @@ +# MeshRendererComponent::GetMaterialHandle + +获取指定槽位的材质句柄。 + +```cpp +const Resources::ResourceHandle& GetMaterialHandle(size_t index) const; +``` + +## 参数 + +- `index` - 材质槽索引。 + +## 返回值 + +- 若索引有效则返回对应句柄引用。 +- 否则返回一个静态空句柄引用。 + +## 注意事项 + +- 越界时返回的是共享的静态空句柄，而不是临时对象。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [GetMaterial](GetMaterial.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialPaths.md b/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialPaths.md new file mode 100644 index 00000000..73b26a3d --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialPaths.md @@ -0,0 +1,17 @@ +# MeshRendererComponent::GetMaterialPaths + +获取当前材质路径数组。 + +```cpp +const std::vector& GetMaterialPaths() const; +``` + +## 返回值 + +- 当前缓存的材质路径数组引用。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [Serialize](Serialize.md) +- [Deserialize](Deserialize.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/GetName.md b/docs/api/XCEngine/Components/MeshRendererComponent/GetName.md new file mode 100644 index 00000000..dd9451b5 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/GetName.md @@ -0,0 +1,15 @@ +# MeshRendererComponent::GetName + +返回组件名字。 + +```cpp +std::string GetName() const override; +``` + +## 返回值 + +- 当前固定返回 `"MeshRenderer"`。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/GetReceiveShadows.md b/docs/api/XCEngine/Components/MeshRendererComponent/GetReceiveShadows.md new file mode 100644 index 00000000..a937287f --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/GetReceiveShadows.md @@ -0,0 +1,20 @@ +# MeshRendererComponent::GetReceiveShadows + +获取接收阴影标志。 + +```cpp +bool GetReceiveShadows() const; +``` + +## 返回值 + +- 当前 `m_receiveShadows` 值。 + +## 当前实现说明 + +- 当前渲染路径还没有真正消费这个标志。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [SetReceiveShadows](SetReceiveShadows.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/GetRenderLayer.md b/docs/api/XCEngine/Components/MeshRendererComponent/GetRenderLayer.md new file mode 100644 index 00000000..bb4a26d4 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/GetRenderLayer.md @@ -0,0 +1,20 @@ +# MeshRendererComponent::GetRenderLayer + +获取渲染层。 + +```cpp +uint32_t GetRenderLayer() const; +``` + +## 返回值 + +- 当前 `m_renderLayer` 值。 + +## 当前实现说明 + +- 当前 `RenderSceneExtractor` 不会根据这个值过滤对象。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [SetRenderLayer](SetRenderLayer.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/MeshRendererComponent.md b/docs/api/XCEngine/Components/MeshRendererComponent/MeshRendererComponent.md new file mode 100644 index 00000000..891569cd --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/MeshRendererComponent.md @@ -0,0 +1,55 @@ +# MeshRendererComponent + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/MeshRendererComponent.h` + +**描述**: 保存材质槽、阴影标志和渲染层信息，负责告诉渲染系统“这个 mesh 应该如何被绘制”。 + +## 概述 + +`MeshRendererComponent` 承担的是“绘制配置”这一半职责： + +- 材质槽数组 +- 阴影开关 +- 渲染层 + +和 [MeshFilterComponent](../MeshFilterComponent/MeshFilterComponent.md) 配合后，场景提取器就能把几何和材质信息一起整理成 [VisibleRenderObject](../../Rendering/VisibleRenderObject/VisibleRenderObject.md)。 + +## 当前实现边界 + +- 内部同时维护 `m_materials` 和 `m_materialPaths` 两套数组。 +- [SetMaterial](SetMaterial.md) 会在需要时自动扩容材质槽。 +- [SetMaterials](SetMaterials.md) 会整体替换材质数组。 +- [Deserialize](Deserialize.md) 会尝试通过 `ResourceManager` 重新加载材质。 +- 当前 `castShadows`、`receiveShadows` 和 `renderLayer` 还没有真正接入 [RenderSceneExtractor](../../Rendering/RenderSceneExtractor/RenderSceneExtractor.md) 或 [BuiltinForwardPipeline](../../Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [GetName](GetName.md) | 返回组件名字。 | +| [GetMaterialCount](GetMaterialCount.md) | 获取材质槽数量。 | +| [GetMaterial](GetMaterial.md) | 获取指定槽位材质。 | +| [GetMaterialHandle](GetMaterialHandle.md) | 获取指定槽位材质句柄。 | +| [GetMaterialPaths](GetMaterialPaths.md) | 获取序列化路径数组。 | +| [SetMaterial](SetMaterial.md) | 设置单个材质槽。 | +| [SetMaterials](SetMaterials.md) | 批量设置材质槽。 | +| [ClearMaterials](ClearMaterials.md) | 清空所有材质槽。 | +| [GetCastShadows](GetCastShadows.md) | 查询投射阴影标志。 | +| [SetCastShadows](SetCastShadows.md) | 设置投射阴影标志。 | +| [GetReceiveShadows](GetReceiveShadows.md) | 查询接收阴影标志。 | +| [SetReceiveShadows](SetReceiveShadows.md) | 设置接收阴影标志。 | +| [GetRenderLayer](GetRenderLayer.md) | 获取渲染层。 | +| [SetRenderLayer](SetRenderLayer.md) | 设置渲染层。 | +| [Serialize](Serialize.md) | 序列化材质路径与标志位。 | +| [Deserialize](Deserialize.md) | 反序列化材质路径与标志位。 | + +## 相关文档 + +- [Components](../Components.md) +- [MeshFilterComponent](../MeshFilterComponent/MeshFilterComponent.md) +- [RenderSceneExtractor](../../Rendering/RenderSceneExtractor/RenderSceneExtractor.md) +- [BuiltinForwardPipeline](../../Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/Serialize.md b/docs/api/XCEngine/Components/MeshRendererComponent/Serialize.md new file mode 100644 index 00000000..49fec516 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/Serialize.md @@ -0,0 +1,25 @@ +# MeshRendererComponent::Serialize + +序列化材质槽和渲染标志。 + +```cpp +void Serialize(std::ostream& os) const override; +``` + +## 行为说明 + +当前实现会输出类似： + +```text +materials=Mat0|Mat1; +castShadows=1; +receiveShadows=0; +renderLayer=3; +``` + +其中材质路径使用 `|` 分隔。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [Deserialize](Deserialize.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/SetCastShadows.md b/docs/api/XCEngine/Components/MeshRendererComponent/SetCastShadows.md new file mode 100644 index 00000000..caba595f --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/SetCastShadows.md @@ -0,0 +1,20 @@ +# MeshRendererComponent::SetCastShadows + +设置投射阴影标志。 + +```cpp +void SetCastShadows(bool value); +``` + +## 参数 + +- `value` - 是否投射阴影。 + +## 当前实现说明 + +- 当前只是存储这个布尔值，还没有接入实际阴影渲染流程。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [GetCastShadows](GetCastShadows.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/SetMaterial.md b/docs/api/XCEngine/Components/MeshRendererComponent/SetMaterial.md new file mode 100644 index 00000000..ef8c46b8 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/SetMaterial.md @@ -0,0 +1,27 @@ +# MeshRendererComponent::SetMaterial + +设置单个材质槽。 + +```cpp +void SetMaterial(size_t index, const Resources::ResourceHandle& material); +void SetMaterial(size_t index, Resources::Material* material); +``` + +## 行为说明 + +当前实现会： + +1. 通过 `EnsureMaterialSlot()` 保证数组至少扩容到 `index + 1`。 +2. 写入 `m_materials[index]`。 +3. 根据句柄中的资源路径同步更新 `m_materialPaths[index]`。 + +## 参数 + +- `index` - 材质槽索引。 +- `material` - 要设置的材质句柄或裸指针。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [SetMaterials](SetMaterials.md) +- [ClearMaterials](ClearMaterials.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/SetMaterials.md b/docs/api/XCEngine/Components/MeshRendererComponent/SetMaterials.md new file mode 100644 index 00000000..63abd887 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/SetMaterials.md @@ -0,0 +1,21 @@ +# MeshRendererComponent::SetMaterials + +批量设置整组材质槽。 + +```cpp +void SetMaterials(const std::vector>& materials); +``` + +## 行为说明 + +当前实现会整体替换 `m_materials`，并把 `m_materialPaths` 调整为相同大小，然后逐项同步路径。 + +## 参数 + +- `materials` - 新的材质句柄数组。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [SetMaterial](SetMaterial.md) +- [GetMaterialCount](GetMaterialCount.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/SetReceiveShadows.md b/docs/api/XCEngine/Components/MeshRendererComponent/SetReceiveShadows.md new file mode 100644 index 00000000..c05295d4 --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/SetReceiveShadows.md @@ -0,0 +1,20 @@ +# MeshRendererComponent::SetReceiveShadows + +设置接收阴影标志。 + +```cpp +void SetReceiveShadows(bool value); +``` + +## 参数 + +- `value` - 是否接收阴影。 + +## 当前实现说明 + +- 当前只是存储这个布尔值，还没有接入实际阴影渲染流程。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [GetReceiveShadows](GetReceiveShadows.md) diff --git a/docs/api/XCEngine/Components/MeshRendererComponent/SetRenderLayer.md b/docs/api/XCEngine/Components/MeshRendererComponent/SetRenderLayer.md new file mode 100644 index 00000000..531236fa --- /dev/null +++ b/docs/api/XCEngine/Components/MeshRendererComponent/SetRenderLayer.md @@ -0,0 +1,20 @@ +# MeshRendererComponent::SetRenderLayer + +设置渲染层。 + +```cpp +void SetRenderLayer(uint32_t value); +``` + +## 参数 + +- `value` - 新的渲染层值。 + +## 当前实现说明 + +- 当前只是记录数值，还没有接入 culling mask 或 render queue 过滤。 + +## 相关文档 + +- [返回类型总览](MeshRendererComponent.md) +- [GetRenderLayer](GetRenderLayer.md) diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md new file mode 100644 index 00000000..4144ddba --- /dev/null +++ b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md @@ -0,0 +1,61 @@ +# BuiltinForwardPipeline + +**命名空间**: `XCEngine::Rendering::Pipelines` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h` + +**描述**: 当前内建的默认前向渲染管线，实现基础纹理采样、深度测试和 mesh 绘制。 + +## 概述 + +`BuiltinForwardPipeline` 是当前引擎真正能跑起来的默认渲染管线。 + +它的工作路径大致是： + +1. 基于 `RenderContext` 创建 pipeline state、descriptor pool、sampler 和 fallback texture。 +2. 使用 [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md) 把 `Mesh` / `Texture` 上传成 GPU 资源。 +3. 读取 [VisibleRenderObject](../../VisibleRenderObject/VisibleRenderObject.md) 列表。 +4. 为每个物体写常量缓冲、绑定纹理和采样器，然后发出 draw call。 + +## 当前实现能力 + +- 支持 D3D12 与 OpenGL 两套内嵌 shader 路径。 +- 支持颜色附件和深度附件。 +- 支持 mesh section 绘制。 +- 支持从 `Material` 上按若干常见名字查找基础颜色纹理。 +- 当材质或纹理缺失时，使用 1x1 白纹理作为 fallback。 + +## 当前实现限制 + +- 当前是非常基础的 forward path，不包含光照、阴影、法线贴图、后处理或多 pass。 +- 只画当前提取结果中的 mesh；没有 skybox、UI、粒子或透明物体排序。 +- 纹理查找采用名字启发式，当前会依次尝试 `baseColorTexture`、`_BaseColorTexture`、`_MainTex` 等键名。 +- 当前 input layout 把位置声明成 `R32G32B32A32_Float`，而 `StaticMeshVertex::position` 是 `Vector3`；现有集成测试能跑通，但这说明顶点布局约定仍需要更严格校准。 +- 当前 pipeline resource 生命周期完全由这条管线对象自己管理，还没有被更高层渲染框架统一接管。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Destructor](Destructor.md) | 析构时关闭管线资源。 | +| [Initialize](Initialize.md) | 初始化这条内建前向管线。 | +| [Shutdown](Shutdown.md) | 释放内部创建的所有 RHI 资源。 | +| [Render](Render.md) | 把 `RenderSceneData` 绘制到目标表面。 | + +## 设计说明 + +即便当前实现很轻量，把默认管线拆成独立类仍然是对的： + +- `SceneRenderer` 不必硬编码具体 draw 逻辑。 +- 未来想加 deferred、shadow pass 或 editor preview pipeline 时，接口上有扩展空间。 + +这和商业引擎里保留 builtin pipeline 作为“默认可用实现”的思路是一致的。 + +## 相关文档 + +- [Pipelines](../Pipelines.md) +- [RenderPipeline](../../RenderPipeline/RenderPipeline.md) +- [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md) +- [Scene Extraction And Builtin Forward Pipeline](../../../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md) diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Destructor.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Destructor.md new file mode 100644 index 00000000..0b8f5d93 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Destructor.md @@ -0,0 +1,16 @@ +# BuiltinForwardPipeline::~BuiltinForwardPipeline + +销毁内建前向管线对象。 + +```cpp +~BuiltinForwardPipeline() override; +``` + +## 行为说明 + +当前析构函数会调用 [Shutdown](Shutdown.md)。 + +## 相关文档 + +- [返回类型总览](BuiltinForwardPipeline.md) +- [Shutdown](Shutdown.md) diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Initialize.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Initialize.md new file mode 100644 index 00000000..e5753c9f --- /dev/null +++ b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Initialize.md @@ -0,0 +1,31 @@ +# BuiltinForwardPipeline::Initialize + +初始化内建前向管线。 + +```cpp +bool Initialize(const RenderContext& context) override; +``` + +## 行为说明 + +当前实现直接转发到内部 `EnsureInitialized(context)`。 + +## 参数 + +- `context` - 当前渲染上下文。 + +## 返回值 + +- 初始化成功返回 `true`。 +- 否则返回 `false`。 + +## 当前实现说明 + +- 若当前设备与 backend 和已初始化状态匹配，内部会复用现有资源。 +- 若上下文变化，会先销毁旧资源，再重新创建。 + +## 相关文档 + +- [返回类型总览](BuiltinForwardPipeline.md) +- [Render](Render.md) +- [Shutdown](Shutdown.md) diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Render.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Render.md new file mode 100644 index 00000000..298b21f0 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Render.md @@ -0,0 +1,46 @@ +# BuiltinForwardPipeline::Render + +执行一次内建前向渲染。 + +```cpp +bool Render( + const RenderContext& context, + const RenderSurface& surface, + const RenderSceneData& sceneData) override; +``` + +## 行为说明 + +当前实现会： + +1. 确保管线资源已初始化。 +2. 检查颜色附件是否存在。 +3. 在需要时把颜色附件从 `stateBefore` 转成 `RenderTarget`。 +4. 绑定 render target、viewport 和 scissor。 +5. 清颜色和深度。 +6. 设置 pipeline state 与 primitive topology。 +7. 遍历 `sceneData.visibleObjects`，逐个发出 draw call。 +8. 在需要时把颜色附件从 `RenderTarget` 转回 `stateAfter`。 + +## 参数 + +- `context` - 当前渲染上下文。 +- `surface` - 当前目标表面。 +- `sceneData` - 提取好的相机和可见对象数据。 + +## 返回值 + +- 成功返回 `true`。 +- 初始化失败或没有颜色附件时返回 `false`。 + +## 当前实现限制 + +- 当前不会因为某个单独物体绘制失败而整体返回 `false`；内部 `DrawVisibleObject()` 的失败结果并没有汇总成整帧失败。 +- 当前没有多 pass 结构。 +- 当前默认总会清颜色；没有“只加载不清除”的 load/store 策略配置。 + +## 相关文档 + +- [返回类型总览](BuiltinForwardPipeline.md) +- [RenderSurface](../../RenderSurface/RenderSurface.md) +- [VisibleRenderObject](../../VisibleRenderObject/VisibleRenderObject.md) diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Shutdown.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Shutdown.md new file mode 100644 index 00000000..13280b4d --- /dev/null +++ b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/Shutdown.md @@ -0,0 +1,23 @@ +# BuiltinForwardPipeline::Shutdown + +关闭内建前向管线并释放其资源。 + +```cpp +void Shutdown() override; +``` + +## 行为说明 + +当前实现直接调用内部 `DestroyPipelineResources()`，释放： + +- resource cache +- fallback texture / view +- sampler +- pipeline state +- pipeline layout +- descriptor set / descriptor pool + +## 相关文档 + +- [返回类型总览](BuiltinForwardPipeline.md) +- [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md) diff --git a/docs/api/XCEngine/Rendering/Pipelines/Pipelines.md b/docs/api/XCEngine/Rendering/Pipelines/Pipelines.md new file mode 100644 index 00000000..8f8664e7 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Pipelines/Pipelines.md @@ -0,0 +1,30 @@ +# Pipelines + +**命名空间**: `XCEngine::Rendering::Pipelines` + +**类型**: `submodule` + +**描述**: 承载具体渲染管线实现，当前公开的是内建前向渲染管线。 + +## 概述 + +把具体渲染实现放在 `Rendering::Pipelines` 子命名空间，而不是直接塞进 `SceneRenderer`，是很合理的架构选择： + +- `SceneRenderer` 只负责组织渲染流程。 +- 具体怎么画，由管线对象决定。 + +这和商业引擎里“renderer 负责 orchestration，pipeline 负责 actual rendering”的分层是相通的。 + +## 当前实现 + +当前公开的具体管线只有一个： + +- [BuiltinForwardPipeline](BuiltinForwardPipeline/BuiltinForwardPipeline.md) + +它承担的角色更像“默认可跑通的内建前向管线”，而不是覆盖完整 PBR、光照、阴影和后处理的成熟渲染框架。 + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderPipeline](../RenderPipeline/RenderPipeline.md) +- [RenderPipelineAsset](../RenderPipelineAsset/RenderPipelineAsset.md) diff --git a/docs/api/XCEngine/Rendering/RenderCameraData/RenderCameraData.md b/docs/api/XCEngine/Rendering/RenderCameraData/RenderCameraData.md new file mode 100644 index 00000000..cf6906ff --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderCameraData/RenderCameraData.md @@ -0,0 +1,46 @@ +# RenderCameraData + +**命名空间**: `XCEngine::Rendering` + +**类型**: `struct` + +**头文件**: `XCEngine/Rendering/RenderCameraData.h` + +**描述**: 保存渲染阶段实际使用的相机矩阵、清屏色和视口尺寸。 + +## 概述 + +`RenderCameraData` 是“场景组件层的相机”向“渲染层可直接消费的数据块”之间的桥接结构。 + +这种拆分很有价值，因为渲染层通常不应该直接依赖完整 `CameraComponent` 行为，而是应该消费一份已经拍平的渲染数据： + +- 视图矩阵 +- 投影矩阵 +- 组合矩阵 +- 相机世界位置 +- 清屏色 +- 视口尺寸 + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `view` | `Math::Matrix4x4` | 视图矩阵。 | +| `projection` | `Math::Matrix4x4` | 投影矩阵。 | +| `viewProjection` | `Math::Matrix4x4` | `projection * view` 组合矩阵。 | +| `worldPosition` | `Math::Vector3` | 相机世界坐标。 | +| `clearColor` | `Math::Color` | 默认清屏色。 | +| `viewportWidth` | `uint32_t` | 当前视口宽度。 | +| `viewportHeight` | `uint32_t` | 当前视口高度。 | + +## 当前实现说明 + +- 这组矩阵由 [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) 构造。 +- 当前 extractor 会在写入这里之前对 `view`、`projection` 和 `viewProjection` 做转置。 +- 这说明当前渲染路径是按“尽量让 shader 直接消费统一矩阵布局”的思路设计的。 + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) +- [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md) diff --git a/docs/api/XCEngine/Rendering/RenderContext/IsValid.md b/docs/api/XCEngine/Rendering/RenderContext/IsValid.md new file mode 100644 index 00000000..4dd74e62 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderContext/IsValid.md @@ -0,0 +1,32 @@ +# RenderContext::IsValid + +检查当前渲染上下文是否具备最基础的执行条件。 + +```cpp +bool IsValid() const; +``` + +## 行为说明 + +当前实现直接检查： + +```cpp +return device != nullptr && commandList != nullptr && commandQueue != nullptr; +``` + +## 返回值 + +- 当 `device`、`commandList` 和 `commandQueue` 都非空时返回 `true`。 +- 否则返回 `false`。 + +## 当前实现限制 + +- 当前不会检查这些对象之间是否匹配同一后端。 +- 当前不会检查命令列表是否已 `Reset()`、命令队列是否可提交，或设备是否已正确初始化。 +- `backendType` 不参与这个判定。 + +## 相关文档 + +- [返回类型总览](RenderContext.md) +- [SceneRenderer::Render](../SceneRenderer/Render.md) +- [RenderPipeline::Initialize](../RenderPipeline/Initialize.md) diff --git a/docs/api/XCEngine/Rendering/RenderContext/RenderContext.md b/docs/api/XCEngine/Rendering/RenderContext/RenderContext.md new file mode 100644 index 00000000..f49e1605 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderContext/RenderContext.md @@ -0,0 +1,47 @@ +# RenderContext + +**命名空间**: `XCEngine::Rendering` + +**类型**: `struct` + +**头文件**: `XCEngine/Rendering/RenderContext.h` + +**描述**: 把当前渲染帧所需的 RHI 设备、命令列表、命令队列和后端类型打包成一个轻量上下文。 + +## 概述 + +`RenderContext` 的作用，是把“渲染执行阶段真正必需的底层对象”集中起来传给管线： + +- `device` +- `commandList` +- `commandQueue` +- `backendType` + +这种设计比让每个管线自己去全局查找 RHI 单例更健康，也更接近商业引擎常见的显式依赖传递风格。 + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `device` | `RHI::RHIDevice*` | 用于创建管线资源和 GPU 资源。 | +| `commandList` | `RHI::RHICommandList*` | 当前帧实际记录 draw call 的命令列表。 | +| `commandQueue` | `RHI::RHICommandQueue*` | 提交命令列表的队列。 | +| `backendType` | `RHI::RHIType` | 当前后端类型，默认 `D3D12`。 | + +## 当前实现边界 + +- 这是一个纯数据结构，不拥有这些 RHI 对象。 +- 当前 [IsValid](IsValid.md) 只检查三个指针是否非空，不会验证它们是否来自同一个 backend。 +- `backendType` 当前完全依赖调用方填写正确值。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [IsValid](IsValid.md) | 判断这份上下文是否具备最基础的渲染执行条件。 | + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderPipeline](../RenderPipeline/RenderPipeline.md) +- [SceneRenderer](../SceneRenderer/SceneRenderer.md) diff --git a/docs/api/XCEngine/Rendering/RenderPipeline/Destructor.md b/docs/api/XCEngine/Rendering/RenderPipeline/Destructor.md new file mode 100644 index 00000000..db8d1ff9 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPipeline/Destructor.md @@ -0,0 +1,16 @@ +# RenderPipeline::~RenderPipeline + +销毁渲染管线对象。 + +```cpp +virtual ~RenderPipeline() = default; +``` + +## 行为说明 + +这是一个虚析构函数，确保通过 `RenderPipeline*` 删除派生对象时行为正确。 + +## 相关文档 + +- [返回类型总览](RenderPipeline.md) +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Rendering/RenderPipeline/Initialize.md b/docs/api/XCEngine/Rendering/RenderPipeline/Initialize.md new file mode 100644 index 00000000..76a8a4a5 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPipeline/Initialize.md @@ -0,0 +1,26 @@ +# RenderPipeline::Initialize + +初始化渲染管线资源。 + +```cpp +virtual bool Initialize(const RenderContext& context) = 0; +``` + +## 行为说明 + +派生类应在这里创建 shader、descriptor set、pipeline state、sampler 等与具体管线相关的资源。 + +## 参数 + +- `context` - 当前渲染上下文。 + +## 返回值 + +- 初始化成功返回 `true`。 +- 否则返回 `false`。 + +## 相关文档 + +- [返回类型总览](RenderPipeline.md) +- [RenderContext](../RenderContext/RenderContext.md) +- [BuiltinForwardPipeline::Initialize](../Pipelines/BuiltinForwardPipeline/Initialize.md) diff --git a/docs/api/XCEngine/Rendering/RenderPipeline/Render.md b/docs/api/XCEngine/Rendering/RenderPipeline/Render.md new file mode 100644 index 00000000..0c932973 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPipeline/Render.md @@ -0,0 +1,31 @@ +# RenderPipeline::Render + +执行一次渲染。 + +```cpp +virtual bool Render( + const RenderContext& context, + const RenderSurface& surface, + const RenderSceneData& sceneData) = 0; +``` + +## 行为说明 + +派生类应在这里把已经提取好的 `sceneData` 绘制到 `surface`。 + +## 参数 + +- `context` - 当前渲染上下文。 +- `surface` - 本次渲染的目标表面。 +- `sceneData` - 已经提取好的相机和可见对象数据。 + +## 返回值 + +- 成功返回 `true`。 +- 失败返回 `false`。 + +## 相关文档 + +- [返回类型总览](RenderPipeline.md) +- [RenderSurface](../RenderSurface/RenderSurface.md) +- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) diff --git a/docs/api/XCEngine/Rendering/RenderPipeline/RenderPipeline.md b/docs/api/XCEngine/Rendering/RenderPipeline/RenderPipeline.md new file mode 100644 index 00000000..1910f9ef --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPipeline/RenderPipeline.md @@ -0,0 +1,52 @@ +# RenderPipeline + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class (abstract)` + +**头文件**: `XCEngine/Rendering/RenderPipeline.h` + +**描述**: 定义渲染管线的统一接口，负责初始化、关闭和把 `RenderSceneData` 绘制到 `RenderSurface`。 + +## 概述 + +`RenderPipeline` 是当前渲染模块最关键的扩展点之一。它把真正的绘制实现抽象成三个阶段： + +- 初始化管线资源 +- 关闭并释放资源 +- 执行一次渲染 + +这类接口和商业引擎里常见的 render pipeline abstraction 很接近，因为上层的 scene renderer 不应该知道具体是前向、延迟还是自定义渲染路径。 + +## 当前实现 + +当前公开的具体实现是： + +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) + +`SceneRenderer` 默认也会创建这个内建前向管线。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Destructor](Destructor.md) | 虚析构函数。 | +| [Initialize](Initialize.md) | 初始化这条渲染管线需要的底层资源。 | +| [Shutdown](Shutdown.md) | 释放管线资源。 | +| [Render](Render.md) | 把场景数据绘制到指定表面。 | + +## 设计说明 + +把 `RenderContext`、`RenderSurface` 和 `RenderSceneData` 分开传入，是一个很好的职责拆分： + +- `RenderContext` 代表底层执行环境。 +- `RenderSurface` 代表当前目标表面。 +- `RenderSceneData` 代表已经提取好的高层场景数据。 + +这样做能让同一条管线更容易在不同目标和不同场景上复用。 + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderPipelineAsset](../RenderPipelineAsset/RenderPipelineAsset.md) +- [SceneRenderer](../SceneRenderer/SceneRenderer.md) diff --git a/docs/api/XCEngine/Rendering/RenderPipeline/Shutdown.md b/docs/api/XCEngine/Rendering/RenderPipeline/Shutdown.md new file mode 100644 index 00000000..9377f4d7 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPipeline/Shutdown.md @@ -0,0 +1,16 @@ +# RenderPipeline::Shutdown + +关闭渲染管线并释放其资源。 + +```cpp +virtual void Shutdown() = 0; +``` + +## 行为说明 + +派生类应在这里释放这条管线持有的 RHI 资源、缓存和临时对象。 + +## 相关文档 + +- [返回类型总览](RenderPipeline.md) +- [BuiltinForwardPipeline::Shutdown](../Pipelines/BuiltinForwardPipeline/Shutdown.md) diff --git a/docs/api/XCEngine/Rendering/RenderPipelineAsset/CreatePipeline.md b/docs/api/XCEngine/Rendering/RenderPipelineAsset/CreatePipeline.md new file mode 100644 index 00000000..20235a5a --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPipelineAsset/CreatePipeline.md @@ -0,0 +1,24 @@ +# RenderPipelineAsset::CreatePipeline + +创建一个新的渲染管线实例。 + +```cpp +virtual std::unique_ptr CreatePipeline() const = 0; +``` + +## 行为说明 + +派生类应根据自身配置返回一个具体 `RenderPipeline` 实例。 + +## 返回值 + +- 一个拥有独占所有权的 `RenderPipeline` 对象。 + +## 设计说明 + +把返回值设计成 `std::unique_ptr` 是合理的，因为渲染管线往往具有明确的独占生命周期，不适合共享所有权。 + +## 相关文档 + +- [返回类型总览](RenderPipelineAsset.md) +- [RenderPipeline](../RenderPipeline/RenderPipeline.md) diff --git a/docs/api/XCEngine/Rendering/RenderPipelineAsset/Destructor.md b/docs/api/XCEngine/Rendering/RenderPipelineAsset/Destructor.md new file mode 100644 index 00000000..18cadbc4 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPipelineAsset/Destructor.md @@ -0,0 +1,16 @@ +# RenderPipelineAsset::~RenderPipelineAsset + +销毁渲染管线资产对象。 + +```cpp +virtual ~RenderPipelineAsset() = default; +``` + +## 行为说明 + +这是一个虚析构函数，用于保证通过基类指针销毁派生资产对象时行为正确。 + +## 相关文档 + +- [返回类型总览](RenderPipelineAsset.md) +- [CreatePipeline](CreatePipeline.md) diff --git a/docs/api/XCEngine/Rendering/RenderPipelineAsset/RenderPipelineAsset.md b/docs/api/XCEngine/Rendering/RenderPipelineAsset/RenderPipelineAsset.md new file mode 100644 index 00000000..372acbbc --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderPipelineAsset/RenderPipelineAsset.md @@ -0,0 +1,39 @@ +# RenderPipelineAsset + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class (abstract)` + +**头文件**: `XCEngine/Rendering/RenderPipelineAsset.h` + +**描述**: 定义渲染管线工厂接口，用于创建具体 `RenderPipeline` 实例。 + +## 概述 + +`RenderPipelineAsset` 体现的是“数据/配置对象负责生成运行时管线实例”的设计方向。 + +这和商业引擎里常见的 pipeline asset / renderer asset 思路很接近： + +- asset 负责描述“要创建哪条渲染管线” +- runtime pipeline 负责真正执行渲染 + +## 当前实现边界 + +- 当前它只是抽象接口。 +- 当前公开 API 里没有看到对应的具体 asset 派生类型。 +- `SceneRenderer` 目前也没有直接接入这个抽象，而是默认直接创建 [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)。 + +这说明接口方向已经铺好，但 asset-driven pipeline 切换还没有完全接上。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Destructor](Destructor.md) | 虚析构函数。 | +| [CreatePipeline](CreatePipeline.md) | 创建一个具体渲染管线实例。 | + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderPipeline](../RenderPipeline/RenderPipeline.md) +- [SceneRenderer](../SceneRenderer/SceneRenderer.md) diff --git a/docs/api/XCEngine/Rendering/RenderResourceCache/Destructor.md b/docs/api/XCEngine/Rendering/RenderResourceCache/Destructor.md new file mode 100644 index 00000000..70eb6fe1 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderResourceCache/Destructor.md @@ -0,0 +1,16 @@ +# RenderResourceCache::~RenderResourceCache + +销毁资源缓存对象。 + +```cpp +~RenderResourceCache(); +``` + +## 行为说明 + +当前析构函数会调用 [Shutdown](Shutdown.md)，释放 mesh 与 texture cache 中的所有 RHI 资源。 + +## 相关文档 + +- [返回类型总览](RenderResourceCache.md) +- [Shutdown](Shutdown.md) diff --git a/docs/api/XCEngine/Rendering/RenderResourceCache/GetOrCreateMesh.md b/docs/api/XCEngine/Rendering/RenderResourceCache/GetOrCreateMesh.md new file mode 100644 index 00000000..1e4ec4a0 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderResourceCache/GetOrCreateMesh.md @@ -0,0 +1,38 @@ +# RenderResourceCache::GetOrCreateMesh + +获取或创建某个 `Mesh` 的 GPU 缓存。 + +```cpp +const CachedMesh* GetOrCreateMesh(RHI::RHIDevice* device, const Resources::Mesh* mesh); +``` + +## 行为说明 + +当前实现会： + +1. 检查 `device`、`mesh` 和 `mesh->IsValid()`。 +2. 若缓存已存在，直接返回。 +3. 否则上传顶点/索引数据并创建对应 view。 +4. 把结果放入 `m_meshCache` 并返回。 + +## 参数 + +- `device` - 用于创建 GPU buffer 与 view 的设备。 +- `mesh` - 要缓存的网格资源。 + +## 返回值 + +- 成功时返回 `CachedMesh*`。 +- 失败时返回 `nullptr`。 + +## 当前实现限制 + +- 当前不会检测 mesh 数据后续是否被修改。 +- 当前要求顶点数据非空、`vertexStride > 0`。 +- 若上传过程中途失败，会清理当前临时创建的资源，但不会记录失败原因。 + +## 相关文档 + +- [返回类型总览](RenderResourceCache.md) +- [GetOrCreateTexture](GetOrCreateTexture.md) +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Rendering/RenderResourceCache/GetOrCreateTexture.md b/docs/api/XCEngine/Rendering/RenderResourceCache/GetOrCreateTexture.md new file mode 100644 index 00000000..366a4531 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderResourceCache/GetOrCreateTexture.md @@ -0,0 +1,38 @@ +# RenderResourceCache::GetOrCreateTexture + +获取或创建某个 `Texture` 的 GPU 缓存。 + +```cpp +const CachedTexture* GetOrCreateTexture(RHI::RHIDevice* device, const Resources::Texture* texture); +``` + +## 行为说明 + +当前实现会： + +1. 检查 `device`、`texture` 和 `texture->IsValid()`。 +2. 若缓存已存在，直接返回。 +3. 否则把纹理上传成 RHI texture，并创建 shader resource view。 +4. 把结果放入 `m_textureCache` 并返回。 + +## 参数 + +- `device` - 用于创建 GPU 纹理与 SRV 的设备。 +- `texture` - 要缓存的纹理资源。 + +## 返回值 + +- 成功时返回 `CachedTexture*`。 +- 失败时返回 `nullptr`。 + +## 当前实现限制 + +- 当前仅支持很少的纹理格式映射。 +- 当前默认创建 `Texture2D` 维度的 SRV。 +- 纹理缓存同样不具备内容变更失效机制。 + +## 相关文档 + +- [返回类型总览](RenderResourceCache.md) +- [GetOrCreateMesh](GetOrCreateMesh.md) +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Rendering/RenderResourceCache/RenderResourceCache.md b/docs/api/XCEngine/Rendering/RenderResourceCache/RenderResourceCache.md new file mode 100644 index 00000000..89434e8a --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderResourceCache/RenderResourceCache.md @@ -0,0 +1,70 @@ +# RenderResourceCache + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/RenderResourceCache.h` + +**描述**: 负责把 `Mesh` 和 `Texture` 上传成 RHI 资源，并在渲染阶段按资源指针缓存这些 GPU 对象。 + +## 概述 + +`RenderResourceCache` 解决的是一个典型渲染层问题：场景与资源系统持有的是 CPU 侧 `Mesh` / `Texture` 对象，但绘制时真正需要的是 GPU 侧 buffer、texture 和 resource view。 + +当前缓存分成两类： + +- `CachedMesh` +- `CachedTexture` + +## `CachedMesh` + +| 字段 | 说明 | +|------|------| +| `vertexBuffer` | 顶点缓冲对象。 | +| `vertexBufferView` | 顶点缓冲视图。 | +| `indexBuffer` | 索引缓冲对象。 | +| `indexBufferView` | 索引缓冲视图。 | +| `vertexCount` | 顶点数量。 | +| `indexCount` | 索引数量。 | +| `vertexStride` | 顶点步长。 | +| `uses32BitIndices` | 是否使用 32 位索引。 | + +## `CachedTexture` + +| 字段 | 说明 | +|------|------| +| `texture` | GPU 纹理对象。 | +| `shaderResourceView` | 着色器资源视图。 | +| `width` | 纹理宽度。 | +| `height` | 纹理高度。 | + +## 当前实现边界 + +- cache key 是 `const Resources::Mesh*` 和 `const Resources::Texture*` 裸指针。 +- 当前没有脏标记或版本号，因此资源内容发生变化后，缓存不会自动失效。 +- 当前不是线程安全的。 +- 纹理格式映射目前只覆盖 `RGBA8_UNORM` 和 `RGBA8_SRGB`。 +- 上传纹理时当前固定按 `width * 4` 计算 `rowPitch`，因此只适用于当前支持的 4 字节每像素路径。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Destructor](Destructor.md) | 析构时清空缓存。 | +| [Shutdown](Shutdown.md) | 释放所有已缓存 GPU 资源。 | +| [GetOrCreateMesh](GetOrCreateMesh.md) | 获取或创建网格缓存。 | +| [GetOrCreateTexture](GetOrCreateTexture.md) | 获取或创建纹理缓存。 | + +## 设计说明 + +把上传和缓存放在渲染层，而不是资源层，是个务实选择： + +- 资源层可以保持对具体 RHI 后端无感。 +- 渲染层可以根据当前 backend 和管线需要决定上传方式。 + +## 相关文档 + +- [当前模块](../Rendering.md) +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) +- [RenderContext](../RenderContext/RenderContext.md) diff --git a/docs/api/XCEngine/Rendering/RenderResourceCache/Shutdown.md b/docs/api/XCEngine/Rendering/RenderResourceCache/Shutdown.md new file mode 100644 index 00000000..360a3cf4 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderResourceCache/Shutdown.md @@ -0,0 +1,28 @@ +# RenderResourceCache::Shutdown + +释放所有已缓存的 GPU 资源。 + +```cpp +void Shutdown(); +``` + +## 行为说明 + +当前实现会： + +- 逐个关闭并删除 `CachedMesh` 中的 buffer / view。 +- 清空 `m_meshCache`。 +- 逐个关闭并删除 `CachedTexture` 中的 texture / SRV。 +- 清空 `m_textureCache`。 + +## 注意事项 + +- 当前不会通知上层资源系统。 +- 当前不会保留缓存统计信息。 +- 调用后之前返回的 `CachedMesh*` / `CachedTexture*` 都会失效。 + +## 相关文档 + +- [返回类型总览](RenderResourceCache.md) +- [GetOrCreateMesh](GetOrCreateMesh.md) +- [GetOrCreateTexture](GetOrCreateTexture.md) diff --git a/docs/api/XCEngine/Rendering/RenderSceneExtractor/Extract.md b/docs/api/XCEngine/Rendering/RenderSceneExtractor/Extract.md new file mode 100644 index 00000000..ad05b6b2 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSceneExtractor/Extract.md @@ -0,0 +1,42 @@ +# RenderSceneExtractor::Extract + +从场景中提取当前帧要渲染的数据。 + +```cpp +RenderSceneData Extract( + const Components::Scene& scene, + Components::CameraComponent* overrideCamera, + uint32_t viewportWidth, + uint32_t viewportHeight) const; +``` + +## 行为说明 + +当前实现会： + +1. 选择一台可用相机。 +2. 根据相机和视口尺寸构造 `RenderCameraData`。 +3. 从场景根对象开始递归遍历层级。 +4. 收集符合条件的 mesh 对象，输出 `VisibleRenderObject` 数组。 + +## 参数 + +- `scene` - 要提取的场景。 +- `overrideCamera` - 显式指定的相机；若可用则优先级最高。 +- `viewportWidth` - 当前视口宽度。 +- `viewportHeight` - 当前视口高度。 + +## 返回值 + +- 一份 `RenderSceneData`。 + +## 当前实现说明 + +- 当没有可用相机时，返回的 `RenderSceneData` 里 `camera == nullptr`。 +- 透视相机使用 `Matrix4x4::Perspective`，正交相机使用 `Matrix4x4::Orthographic`。 +- 当前把 `view`、`projection` 和 `viewProjection` 都以转置形式写入结果。 + +## 相关文档 + +- [返回类型总览](RenderSceneExtractor.md) +- [SceneRenderer::Render](../SceneRenderer/Render.md) diff --git a/docs/api/XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md b/docs/api/XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md new file mode 100644 index 00000000..733fcf95 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md @@ -0,0 +1,67 @@ +# RenderSceneExtractor + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class + struct` + +**头文件**: `XCEngine/Rendering/RenderSceneExtractor.h` + +**描述**: 从 `Scene` 中挑选相机并收集可渲染 mesh 对象，输出渲染层使用的 `RenderSceneData`。 + +## 概述 + +`RenderSceneExtractor` 是当前渲染架构里最接近“scene extraction”阶段的对象。 + +它的职责不是绘制，而是把面向 gameplay / scene graph 的对象整理成渲染层更容易消费的数据： + +- 一台要使用的相机 +- 一份拍平后的 [RenderCameraData](../RenderCameraData/RenderCameraData.md) +- 一组 [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md) + +这和商业引擎里把 scene traversal、visibility building、render packet generation 放在真正 draw submission 之前的设计是一致的。 + +## `RenderSceneData` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `camera` | `Components::CameraComponent*` | 选中的相机。 | +| `cameraData` | `RenderCameraData` | 渲染阶段使用的拍平相机数据。 | +| `visibleObjects` | `std::vector` | 当前提取到的可见对象列表。 | + +`RenderSceneData::HasCamera()` 当前只是检查 `camera != nullptr`。 + +## 当前提取规则 + +相机选择当前按以下顺序执行： + +1. 如果 `overrideCamera` 可用，直接使用它。 +2. 否则从场景里找出 `IsPrimary()` 的可用相机，取 `depth` 最大者。 +3. 如果仍没有，则退回到第一个可用相机。 + +对象提取当前只要求： + +- `GameObject` 处于 `IsActiveInHierarchy()` +- 同时有 `MeshFilterComponent` 和 `MeshRendererComponent` +- 两个组件都启用 +- `MeshFilterComponent` 提供的 mesh 非空且 `IsValid()` + +## 当前实现限制 + +- 当前没有 frustum culling。 +- 当前没有 render layer 过滤。 +- 当前没有透明/不透明分类、排序或 batching。 +- 当前不会读取 `castShadows` / `receiveShadows`。 +- 当前把“visible”理解为“满足基本组件条件且在激活层级中”，而不是严格意义上的屏幕可见。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Extract](Extract.md) | 从场景中提取渲染数据。 | + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderCameraData](../RenderCameraData/RenderCameraData.md) +- [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md) +- [SceneRenderer](../SceneRenderer/SceneRenderer.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/ClearClearColorOverride.md b/docs/api/XCEngine/Rendering/RenderSurface/ClearClearColorOverride.md new file mode 100644 index 00000000..a51f558f --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/ClearClearColorOverride.md @@ -0,0 +1,17 @@ +# RenderSurface::ClearClearColorOverride + +清除清屏色覆盖标记。 + +```cpp +void ClearClearColorOverride(); +``` + +## 行为说明 + +当前实现只会把 `m_hasClearColorOverride` 设为 `false`，不会重置保存的颜色值。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetClearColorOverride](SetClearColorOverride.md) +- [HasClearColorOverride](HasClearColorOverride.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/Constructor.md b/docs/api/XCEngine/Rendering/RenderSurface/Constructor.md new file mode 100644 index 00000000..420f6786 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/Constructor.md @@ -0,0 +1,18 @@ +# RenderSurface::RenderSurface + +构造渲染表面。 + +```cpp +RenderSurface() = default; +RenderSurface(uint32_t width, uint32_t height); +``` + +## 行为说明 + +- 默认构造会得到一个空尺寸表面，宽高初始为 `0`。 +- 带参数构造会直接把宽高设为给定值。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetSize](SetSize.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetClearColorOverride.md b/docs/api/XCEngine/Rendering/RenderSurface/GetClearColorOverride.md new file mode 100644 index 00000000..35368f55 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/GetClearColorOverride.md @@ -0,0 +1,20 @@ +# RenderSurface::GetClearColorOverride + +获取当前清屏色覆盖值。 + +```cpp +const Math::Color& GetClearColorOverride() const; +``` + +## 返回值 + +- 返回内部保存的清屏色覆盖值引用。 + +## 注意事项 + +- 即便 [HasClearColorOverride](HasClearColorOverride.md) 为 `false`，内部仍然保留最近一次写入过的颜色值。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [HasClearColorOverride](HasClearColorOverride.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetColorAttachments.md b/docs/api/XCEngine/Rendering/RenderSurface/GetColorAttachments.md new file mode 100644 index 00000000..66dbc5f8 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/GetColorAttachments.md @@ -0,0 +1,22 @@ +# RenderSurface::GetColorAttachments + +获取颜色附件数组。 + +```cpp +const std::vector& GetColorAttachments() const; +``` + +## 返回值 + +- 对内部颜色附件数组的常量引用。 + +## 注意事项 + +- 当前返回的是内部容器引用，不是拷贝。 +- 调用方需要自己保证其中指针的生命周期有效。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetColorAttachment](SetColorAttachment.md) +- [SetColorAttachments](SetColorAttachments.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetColorStateAfter.md b/docs/api/XCEngine/Rendering/RenderSurface/GetColorStateAfter.md new file mode 100644 index 00000000..3b28ef27 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/GetColorStateAfter.md @@ -0,0 +1,16 @@ +# RenderSurface::GetColorStateAfter + +获取颜色附件渲染后状态。 + +```cpp +RHI::ResourceStates GetColorStateAfter() const; +``` + +## 返回值 + +- 当前记录的渲染后颜色状态。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetColorStateAfter](SetColorStateAfter.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetColorStateBefore.md b/docs/api/XCEngine/Rendering/RenderSurface/GetColorStateBefore.md new file mode 100644 index 00000000..ad3341b5 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/GetColorStateBefore.md @@ -0,0 +1,16 @@ +# RenderSurface::GetColorStateBefore + +获取颜色附件渲染前状态。 + +```cpp +RHI::ResourceStates GetColorStateBefore() const; +``` + +## 返回值 + +- 当前记录的渲染前颜色状态。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetColorStateBefore](SetColorStateBefore.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetDepthAttachment.md b/docs/api/XCEngine/Rendering/RenderSurface/GetDepthAttachment.md new file mode 100644 index 00000000..b41db816 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/GetDepthAttachment.md @@ -0,0 +1,16 @@ +# RenderSurface::GetDepthAttachment + +获取当前深度附件。 + +```cpp +RHI::RHIResourceView* GetDepthAttachment() const; +``` + +## 返回值 + +- 当前记录的深度附件指针。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetDepthAttachment](SetDepthAttachment.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetHeight.md b/docs/api/XCEngine/Rendering/RenderSurface/GetHeight.md new file mode 100644 index 00000000..0fbf97ab --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/GetHeight.md @@ -0,0 +1,17 @@ +# RenderSurface::GetHeight + +获取当前表面高度。 + +```cpp +uint32_t GetHeight() const; +``` + +## 返回值 + +- 当前记录的高度。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [GetWidth](GetWidth.md) +- [SetSize](SetSize.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetWidth.md b/docs/api/XCEngine/Rendering/RenderSurface/GetWidth.md new file mode 100644 index 00000000..4961bc79 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/GetWidth.md @@ -0,0 +1,17 @@ +# RenderSurface::GetWidth + +获取当前表面宽度。 + +```cpp +uint32_t GetWidth() const; +``` + +## 返回值 + +- 当前记录的宽度。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [GetHeight](GetHeight.md) +- [SetSize](SetSize.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/HasClearColorOverride.md b/docs/api/XCEngine/Rendering/RenderSurface/HasClearColorOverride.md new file mode 100644 index 00000000..23d136cc --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/HasClearColorOverride.md @@ -0,0 +1,18 @@ +# RenderSurface::HasClearColorOverride + +判断当前是否启用了清屏色覆盖。 + +```cpp +bool HasClearColorOverride() const; +``` + +## 返回值 + +- 若已设置覆盖色则返回 `true`。 +- 否则返回 `false`。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetClearColorOverride](SetClearColorOverride.md) +- [GetClearColorOverride](GetClearColorOverride.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/IsAutoTransitionEnabled.md b/docs/api/XCEngine/Rendering/RenderSurface/IsAutoTransitionEnabled.md new file mode 100644 index 00000000..23c4e075 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/IsAutoTransitionEnabled.md @@ -0,0 +1,17 @@ +# RenderSurface::IsAutoTransitionEnabled + +查询是否启用了颜色附件自动状态切换。 + +```cpp +bool IsAutoTransitionEnabled() const; +``` + +## 返回值 + +- 已启用返回 `true`。 +- 否则返回 `false`。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/RenderSurface.md b/docs/api/XCEngine/Rendering/RenderSurface/RenderSurface.md new file mode 100644 index 00000000..cebc58b8 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/RenderSurface.md @@ -0,0 +1,70 @@ +# RenderSurface + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/RenderSurface.h` + +**描述**: 描述当前渲染目标表面，包括尺寸、颜色附件、深度附件、清屏色覆盖和颜色附件自动状态切换策略。 + +## 概述 + +`RenderSurface` 的作用，是把“这一帧到底往哪里画”从具体 swap chain 或 framebuffer 管理逻辑里抽离出来。 + +当前它负责描述： + +- 宽高 +- 一组颜色附件 +- 一个深度附件 +- 可选清屏色覆盖 +- 颜色附件渲染前后状态 +- 是否自动执行颜色附件状态切换 + +这类抽象很符合商业引擎里 render target / render surface 的常见分层，因为同一条渲染管线不应该只会往窗口 back buffer 画。 + +## 当前实现边界 + +- 当前只为颜色附件维护统一的 `stateBefore` / `stateAfter`，不是每个附件单独配置。 +- 自动状态切换当前只处理颜色附件，不处理深度附件。 +- 当前不会校验附件数量、附件尺寸与 `RenderSurface` 宽高是否匹配。 +- 当前没有 load/store action、MSAA resolve、mip slice 或 array slice 等更丰富的 surface 配置。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Constructor](Constructor.md) | 构造渲染表面。 | +| [GetWidth](GetWidth.md) | 获取宽度。 | +| [GetHeight](GetHeight.md) | 获取高度。 | +| [SetSize](SetSize.md) | 设置宽高。 | +| [SetColorAttachment](SetColorAttachment.md) | 设置单个颜色附件。 | +| [SetColorAttachments](SetColorAttachments.md) | 设置多个颜色附件。 | +| [GetColorAttachments](GetColorAttachments.md) | 获取颜色附件数组。 | +| [SetDepthAttachment](SetDepthAttachment.md) | 设置深度附件。 | +| [GetDepthAttachment](GetDepthAttachment.md) | 获取深度附件。 | +| [SetClearColorOverride](SetClearColorOverride.md) | 设置清屏色覆盖。 | +| [ClearClearColorOverride](ClearClearColorOverride.md) | 清除清屏色覆盖。 | +| [HasClearColorOverride](HasClearColorOverride.md) | 判断是否启用了清屏色覆盖。 | +| [GetClearColorOverride](GetClearColorOverride.md) | 获取清屏色覆盖值。 | +| [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) | 设置是否自动切换颜色附件状态。 | +| [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) | 查询是否自动切换颜色附件状态。 | +| [SetColorStateBefore](SetColorStateBefore.md) | 设置渲染前颜色附件状态。 | +| [GetColorStateBefore](GetColorStateBefore.md) | 获取渲染前颜色附件状态。 | +| [SetColorStateAfter](SetColorStateAfter.md) | 设置渲染后颜色附件状态。 | +| [GetColorStateAfter](GetColorStateAfter.md) | 获取渲染后颜色附件状态。 | + +## 设计说明 + +把 surface 做成独立对象，而不是让 pipeline 直接吃裸 `RHIResourceView*`，好处很明确： + +- 目标尺寸和附件集合可以一起传递。 +- 清屏策略和资源状态策略可以挂在目标上，而不是散落在调用点。 +- 同一条管线更容易复用于 back buffer、离屏纹理和 editor preview surface。 + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderContext](../RenderContext/RenderContext.md) +- [RenderPipeline](../RenderPipeline/RenderPipeline.md) +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetAutoTransitionEnabled.md b/docs/api/XCEngine/Rendering/RenderSurface/SetAutoTransitionEnabled.md new file mode 100644 index 00000000..9b2bc0dd --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/SetAutoTransitionEnabled.md @@ -0,0 +1,22 @@ +# RenderSurface::SetAutoTransitionEnabled + +设置是否自动切换颜色附件资源状态。 + +```cpp +void SetAutoTransitionEnabled(bool enabled); +``` + +## 参数 + +- `enabled` - 是否启用自动状态切换。 + +## 行为说明 + +当前实现只记录这个布尔值。像 [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 这样的管线会在渲染前后读取它，决定是否调用 `TransitionBarrier()`。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) +- [SetColorStateBefore](SetColorStateBefore.md) +- [SetColorStateAfter](SetColorStateAfter.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetClearColorOverride.md b/docs/api/XCEngine/Rendering/RenderSurface/SetClearColorOverride.md new file mode 100644 index 00000000..d95352e6 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/SetClearColorOverride.md @@ -0,0 +1,22 @@ +# RenderSurface::SetClearColorOverride + +设置清屏色覆盖。 + +```cpp +void SetClearColorOverride(const Math::Color& clearColor); +``` + +## 行为说明 + +当前实现会： + +- 把 `m_hasClearColorOverride` 设为 `true` +- 保存给定颜色到内部覆盖值 + +之后像 [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 这类管线会优先使用这个颜色，而不是相机清屏色。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [ClearClearColorOverride](ClearClearColorOverride.md) +- [HasClearColorOverride](HasClearColorOverride.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachment.md b/docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachment.md new file mode 100644 index 00000000..b6515bcb --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachment.md @@ -0,0 +1,26 @@ +# RenderSurface::SetColorAttachment + +设置单个颜色附件。 + +```cpp +void SetColorAttachment(RHI::RHIResourceView* colorAttachment); +``` + +## 行为说明 + +当前实现会先清空现有颜色附件数组；如果参数非空，再把它作为唯一颜色附件压入数组。 + +## 参数 + +- `colorAttachment` - 颜色附件视图。 + +## 注意事项 + +- 这是“替换整个颜色附件列表”的语义，不是追加。 +- 传入 `nullptr` 会让颜色附件数组变为空。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetColorAttachments](SetColorAttachments.md) +- [GetColorAttachments](GetColorAttachments.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachments.md b/docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachments.md new file mode 100644 index 00000000..48a4a9fe --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachments.md @@ -0,0 +1,26 @@ +# RenderSurface::SetColorAttachments + +设置一组颜色附件。 + +```cpp +void SetColorAttachments(const std::vector& colorAttachments); +``` + +## 参数 + +- `colorAttachments` - 颜色附件数组。 + +## 行为说明 + +当前实现会直接拷贝这组指针到内部数组。 + +## 注意事项 + +- 当前不会过滤空指针。 +- 当前不会检查附件数量是否与具体管线能力匹配。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [SetColorAttachment](SetColorAttachment.md) +- [GetColorAttachments](GetColorAttachments.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetColorStateAfter.md b/docs/api/XCEngine/Rendering/RenderSurface/SetColorStateAfter.md new file mode 100644 index 00000000..782f01e7 --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/SetColorStateAfter.md @@ -0,0 +1,21 @@ +# RenderSurface::SetColorStateAfter + +设置颜色附件在渲染完成后要回到的资源状态。 + +```cpp +void SetColorStateAfter(RHI::ResourceStates state); +``` + +## 参数 + +- `state` - 渲染后状态。 + +## 行为说明 + +当前实现会把这个状态保存到内部统一字段中，供自动状态切换逻辑使用。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [GetColorStateAfter](GetColorStateAfter.md) +- [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetColorStateBefore.md b/docs/api/XCEngine/Rendering/RenderSurface/SetColorStateBefore.md new file mode 100644 index 00000000..068bb2cd --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/SetColorStateBefore.md @@ -0,0 +1,21 @@ +# RenderSurface::SetColorStateBefore + +设置颜色附件在进入渲染前被视为所处的资源状态。 + +```cpp +void SetColorStateBefore(RHI::ResourceStates state); +``` + +## 参数 + +- `state` - 渲染前状态。 + +## 行为说明 + +当前实现会把这个状态保存到内部统一字段中，供自动状态切换逻辑使用。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [GetColorStateBefore](GetColorStateBefore.md) +- [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetDepthAttachment.md b/docs/api/XCEngine/Rendering/RenderSurface/SetDepthAttachment.md new file mode 100644 index 00000000..2f33171a --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/SetDepthAttachment.md @@ -0,0 +1,20 @@ +# RenderSurface::SetDepthAttachment + +设置深度附件。 + +```cpp +void SetDepthAttachment(RHI::RHIResourceView* depthAttachment); +``` + +## 参数 + +- `depthAttachment` - 深度模板附件视图。 + +## 行为说明 + +当前实现只会记录这个指针。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [GetDepthAttachment](GetDepthAttachment.md) diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetSize.md b/docs/api/XCEngine/Rendering/RenderSurface/SetSize.md new file mode 100644 index 00000000..e3d4be5f --- /dev/null +++ b/docs/api/XCEngine/Rendering/RenderSurface/SetSize.md @@ -0,0 +1,22 @@ +# RenderSurface::SetSize + +设置当前表面尺寸。 + +```cpp +void SetSize(uint32_t width, uint32_t height); +``` + +## 参数 + +- `width` - 宽度。 +- `height` - 高度。 + +## 行为说明 + +当前实现只会更新内部记录的宽高，不会同步修改附件对象本身。 + +## 相关文档 + +- [返回类型总览](RenderSurface.md) +- [GetWidth](GetWidth.md) +- [GetHeight](GetHeight.md) diff --git a/docs/api/XCEngine/Rendering/Rendering.md b/docs/api/XCEngine/Rendering/Rendering.md new file mode 100644 index 00000000..e4fd5230 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Rendering.md @@ -0,0 +1,88 @@ +# Rendering + +**命名空间**: `XCEngine::Rendering` + +**类型**: `module` + +**描述**: 提供场景提取、渲染表面描述、渲染管线抽象、GPU 资源缓存和内建前向渲染实现。 + +## 概述 + +当前 `XCEngine::Rendering` 的公开接口可以按一条很清晰的链路来理解： + +1. [SceneRenderer](SceneRenderer/SceneRenderer.md) 接收场景、相机覆盖、RHI 上下文和目标表面。 +2. [RenderSceneExtractor](RenderSceneExtractor/RenderSceneExtractor.md) 把 `Scene` 里的相机和可渲染物体整理成 `RenderSceneData`。 +3. [RenderSurface](RenderSurface/RenderSurface.md) 描述当前帧要往哪里渲染，以及渲染前后资源状态怎么切换。 +4. [RenderPipeline](RenderPipeline/RenderPipeline.md) 负责真正把 `RenderSceneData` 变成 draw call。 +5. [Pipelines::BuiltinForwardPipeline](Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 是当前默认的具体管线实现。 +6. [RenderResourceCache](RenderResourceCache/RenderResourceCache.md) 在渲染时把 `Mesh` / `Texture` 上传成 RHI 资源并缓存。 + +这个分层思路和很多商业引擎的渲染架构是同一路数： + +- 场景系统负责维护对象和组件。 +- 渲染系统先做“提取”与“整理”。 +- 管线层再决定真正的绘制策略。 + +它和 Unity SRP、Unreal 渲染前的数据提取阶段相比还很轻量，但方向是对的。 + +## 当前实现成熟度 + +当前模块已经可以支撑基础前向渲染链路，但还明显不是完整渲染框架： + +- `SceneRenderer + BuiltinForwardPipeline` 已经有集成测试覆盖，能渲染纹理四边形和 backpack 场景。 +- `RenderSceneExtractor` 已经能选择相机并收集激活的 mesh 对象。 +- `RenderSurface` 已经能描述颜色/深度附件、清屏色覆盖和自动状态切换。 +- `RenderResourceCache` 已经能上传基础网格和 `RGBA8` 纹理。 + +但当前也有一组必须诚实写清楚的限制： + +- `RenderSceneExtractor` 当前不做视锥裁剪、遮挡裁剪或排序。 +- `MeshRendererComponent` 的 `renderLayer`、`castShadows`、`receiveShadows` 当前不会影响提取结果和绘制行为。 +- `RenderResourceCache` 以资源裸指针为 key，不跟踪资源内容变更，也不是线程安全的。 +- `RenderPipelineAsset` 只是抽象工厂入口，当前没有公开的具体 asset 类型。 +- `BuiltinForwardPipeline` 当前只覆盖非常基础的单通道前向贴图绘制。 + +## 设计要点 + +- 把“场景提取”和“渲染执行”分开，是为了给未来的排序、裁剪、批处理和多管线扩展留空间。 +- `RenderSurface` 把 framebuffer 目标和状态切换要求抽象出来，避免管线直接依赖 swap chain 细节。 +- `RenderPipeline` / `RenderPipelineAsset` 的存在，说明这套接口是按“未来可以替换渲染管线”的方向设计的，而不是把 draw 逻辑硬编码在场景类里。 +- `RenderResourceCache` 把运行时 GPU 上传集中到渲染层处理，避免场景对象直接持有 RHI 对象。 + +## 测试覆盖 + +当前能看到的直接覆盖包括： + +- `tests/Rendering/unit/test_render_scene_extractor.cpp` +- `tests/Rendering/integration/textured_quad_scene/main.cpp` +- `tests/Rendering/integration/backpack_scene/main.cpp` +- `tests/Components/test_mesh_render_components.cpp` + +这说明“场景提取 + 默认前向渲染 + mesh 组件序列化”已经有基本验证，但资源缓存和管线细节仍缺少更细的单元测试。 + +## 头文件 + +- [RenderCameraData](RenderCameraData/RenderCameraData.md) - `RenderCameraData.h` +- [RenderContext](RenderContext/RenderContext.md) - `RenderContext.h` +- [RenderPipeline](RenderPipeline/RenderPipeline.md) - `RenderPipeline.h` +- [RenderPipelineAsset](RenderPipelineAsset/RenderPipelineAsset.md) - `RenderPipelineAsset.h` +- [RenderResourceCache](RenderResourceCache/RenderResourceCache.md) - `RenderResourceCache.h` +- [RenderSceneExtractor](RenderSceneExtractor/RenderSceneExtractor.md) - `RenderSceneExtractor.h` +- [RenderSurface](RenderSurface/RenderSurface.md) - `RenderSurface.h` +- [SceneRenderer](SceneRenderer/SceneRenderer.md) - `SceneRenderer.h` +- [VisibleRenderObject](VisibleRenderObject/VisibleRenderObject.md) - `VisibleRenderObject.h` +- [Pipelines](Pipelines/Pipelines.md) - `Pipelines/` + +## 相关指南 + +- [Scene Extraction And Builtin Forward Pipeline](../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md) - 解释为什么渲染要先做 scene extraction，再交给 builtin forward pipeline 执行，以及当前实现和商业引擎常见设计相比还差什么。 + +## 相关文档 + +- [Scene](../Scene/Scene.md) +- [Components](../Components/Components.md) +- [MeshFilterComponent](../Components/MeshFilterComponent/MeshFilterComponent.md) +- [MeshRendererComponent](../Components/MeshRendererComponent/MeshRendererComponent.md) +- [RHI](../RHI/RHI.md) +- [上级目录](../XCEngine.md) +- [API 总索引](../../main.md) diff --git a/docs/api/XCEngine/Rendering/SceneRenderer/Constructor.md b/docs/api/XCEngine/Rendering/SceneRenderer/Constructor.md new file mode 100644 index 00000000..6ac2e4e4 --- /dev/null +++ b/docs/api/XCEngine/Rendering/SceneRenderer/Constructor.md @@ -0,0 +1,19 @@ +# SceneRenderer::SceneRenderer + +构造场景渲染器。 + +```cpp +SceneRenderer(); +explicit SceneRenderer(std::unique_ptr pipeline); +``` + +## 行为说明 + +- 默认构造函数会创建一个 `BuiltinForwardPipeline`。 +- 传入 `pipeline` 的重载会接管该对象所有权。 +- 如果传入空指针，当前实现会退回到 `BuiltinForwardPipeline`。 + +## 相关文档 + +- [返回类型总览](SceneRenderer.md) +- [SetPipeline](SetPipeline.md) diff --git a/docs/api/XCEngine/Rendering/SceneRenderer/Destructor.md b/docs/api/XCEngine/Rendering/SceneRenderer/Destructor.md new file mode 100644 index 00000000..64b13dce --- /dev/null +++ b/docs/api/XCEngine/Rendering/SceneRenderer/Destructor.md @@ -0,0 +1,22 @@ +# SceneRenderer::~SceneRenderer + +销毁场景渲染器。 + +```cpp +~SceneRenderer(); +``` + +## 行为说明 + +当前实现会在析构时检查当前 pipeline 是否存在；若存在，就调用其 `Shutdown()`。 + +## 注意事项 + +- 当前析构不会显式 `reset()` pipeline 之前做更多状态同步。 +- 因为 `unique_ptr` 随后会继续销毁对象，所以派生 pipeline 自身析构也会继续执行。 + +## 相关文档 + +- [返回类型总览](SceneRenderer.md) +- [SetPipeline](SetPipeline.md) +- [RenderPipeline::Shutdown](../RenderPipeline/Shutdown.md) diff --git a/docs/api/XCEngine/Rendering/SceneRenderer/GetPipeline.md b/docs/api/XCEngine/Rendering/SceneRenderer/GetPipeline.md new file mode 100644 index 00000000..7810ce34 --- /dev/null +++ b/docs/api/XCEngine/Rendering/SceneRenderer/GetPipeline.md @@ -0,0 +1,21 @@ +# SceneRenderer::GetPipeline + +获取当前渲染管线指针。 + +```cpp +RenderPipeline* GetPipeline() const; +``` + +## 返回值 + +- 返回当前持有的 `RenderPipeline*`。 + +## 注意事项 + +- 这是非拥有指针。 +- 默认构造下通常会返回 `BuiltinForwardPipeline` 实例。 + +## 相关文档 + +- [返回类型总览](SceneRenderer.md) +- [SetPipeline](SetPipeline.md) diff --git a/docs/api/XCEngine/Rendering/SceneRenderer/Render.md b/docs/api/XCEngine/Rendering/SceneRenderer/Render.md new file mode 100644 index 00000000..fe4564be --- /dev/null +++ b/docs/api/XCEngine/Rendering/SceneRenderer/Render.md @@ -0,0 +1,38 @@ +# SceneRenderer::Render + +渲染一个场景。 + +```cpp +bool Render( + const Components::Scene& scene, + Components::CameraComponent* overrideCamera, + const RenderContext& context, + const RenderSurface& surface); +``` + +## 行为说明 + +当前实现会： + +1. 检查 `context.IsValid()` 且当前 pipeline 非空。 +2. 调用 `RenderSceneExtractor::Extract()` 生成 `RenderSceneData`。 +3. 如果没有可用相机，直接返回 `false`。 +4. 调用当前 pipeline 的 `Render()` 执行真正绘制。 + +## 参数 + +- `scene` - 要渲染的场景。 +- `overrideCamera` - 可选的覆盖相机。 +- `context` - 当前渲染上下文。 +- `surface` - 当前目标表面。 + +## 返回值 + +- 渲染成功返回 `true`。 +- 若上下文无效、没有 pipeline 或没有可用相机，则返回 `false`。 + +## 相关文档 + +- [返回类型总览](SceneRenderer.md) +- [RenderSceneExtractor::Extract](../RenderSceneExtractor/Extract.md) +- [RenderPipeline::Render](../RenderPipeline/Render.md) diff --git a/docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md b/docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md new file mode 100644 index 00000000..c1718242 --- /dev/null +++ b/docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md @@ -0,0 +1,46 @@ +# SceneRenderer + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/SceneRenderer.h` + +**描述**: 组织一帧场景渲染流程，负责 scene extraction，并把结果交给当前 `RenderPipeline`。 + +## 概述 + +`SceneRenderer` 是当前渲染模块的主入口。它把“提取场景数据”和“执行具体渲染”两步串起来： + +- 内部持有一个 [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) +- 内部持有一个当前使用的 [RenderPipeline](../RenderPipeline/RenderPipeline.md) + +默认情况下，它会创建 [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)。 + +## 当前实现边界 + +- 默认构造会直接创建 `BuiltinForwardPipeline`。 +- 传入空 pipeline 时，构造函数和 [SetPipeline](SetPipeline.md) 都会退回到 `BuiltinForwardPipeline`。 +- 析构时如果持有 pipeline，会调用其 `Shutdown()`。 +- [Render](Render.md) 当前只在运行时触发 pipeline 的 `Render()`，并不会显式先调用 `Initialize()`；默认前向管线靠内部 `EnsureInitialized()` 自己兜底。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Constructor](Constructor.md) | 构造场景渲染器。 | +| [Destructor](Destructor.md) | 析构时关闭当前管线。 | +| [SetPipeline](SetPipeline.md) | 替换当前渲染管线。 | +| [GetPipeline](GetPipeline.md) | 获取当前管线指针。 | +| [Render](Render.md) | 渲染一个场景。 | + +## 设计说明 + +把 `SceneRenderer` 保持得足够薄，是一个正确方向。真正复杂的渲染逻辑应该沉到 pipeline，而不是让 renderer 主入口变成一坨硬编码流程。 + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) +- [RenderPipeline](../RenderPipeline/RenderPipeline.md) +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Rendering/SceneRenderer/SetPipeline.md b/docs/api/XCEngine/Rendering/SceneRenderer/SetPipeline.md new file mode 100644 index 00000000..47d3576a --- /dev/null +++ b/docs/api/XCEngine/Rendering/SceneRenderer/SetPipeline.md @@ -0,0 +1,25 @@ +# SceneRenderer::SetPipeline + +替换当前使用的渲染管线。 + +```cpp +void SetPipeline(std::unique_ptr pipeline); +``` + +## 行为说明 + +当前实现会： + +1. 若已有 pipeline，则先调用其 `Shutdown()`。 +2. 用新传入的 `unique_ptr` 替换当前 pipeline。 +3. 如果新指针为空，则自动退回到 `BuiltinForwardPipeline`。 + +## 参数 + +- `pipeline` - 新的渲染管线实例。 + +## 相关文档 + +- [返回类型总览](SceneRenderer.md) +- [GetPipeline](GetPipeline.md) +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Rendering/VisibleRenderObject/VisibleRenderObject.md b/docs/api/XCEngine/Rendering/VisibleRenderObject/VisibleRenderObject.md new file mode 100644 index 00000000..81fc4c6a --- /dev/null +++ b/docs/api/XCEngine/Rendering/VisibleRenderObject/VisibleRenderObject.md @@ -0,0 +1,37 @@ +# VisibleRenderObject + +**命名空间**: `XCEngine::Rendering` + +**类型**: `struct` + +**头文件**: `XCEngine/Rendering/VisibleRenderObject.h` + +**描述**: 表示经过 scene extraction 后、当前帧准备交给渲染管线处理的一个可绘制对象。 + +## 概述 + +`VisibleRenderObject` 的价值，在于把场景对象、组件引用和绘制所需的最核心数据打包在一起。 + +它当前没有变成更重的 render proxy 或 render packet，而是保持为非常轻量的桥接结构。这对当前引擎阶段是合理的。 + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `gameObject` | `Components::GameObject*` | 原始场景对象。 | +| `meshFilter` | `Components::MeshFilterComponent*` | 提供 mesh 的组件。 | +| `meshRenderer` | `Components::MeshRendererComponent*` | 提供材质与渲染设置的组件。 | +| `mesh` | `Resources::Mesh*` | 当前要绘制的 mesh。 | +| `localToWorld` | `Math::Matrix4x4` | 当前对象的局部到世界矩阵。 | + +## 当前实现说明 + +- 该结构由 [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) 填充。 +- 当前 `localToWorld` 直接来自 `GameObject->GetTransform()->GetLocalToWorldMatrix()`。 +- 当前还没有把材质、排序 key、render queue、bounds 等更完整的渲染包信息放进来。 + +## 相关文档 + +- [当前模块](../Rendering.md) +- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md b/docs/api/_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md new file mode 100644 index 00000000..2499edc7 --- /dev/null +++ b/docs/api/_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md @@ -0,0 +1,149 @@ +# Scene Extraction And Builtin Forward Pipeline + +## 先理解这套渲染架构在做什么 + +当前 XCEngine 的渲染链路，不是“场景对象自己直接调用 RHI 去画”，而是先做一次轻量的场景提取，再交给具体渲染管线执行： + +1. `Scene` 和 `GameObject` 维护对象层级与组件。 +2. `MeshFilterComponent` 提供几何数据。 +3. `MeshRendererComponent` 提供材质槽和渲染标志。 +4. `RenderSceneExtractor` 把这些信息拍平为 `RenderSceneData`。 +5. `SceneRenderer` 把提取结果交给 `BuiltinForwardPipeline`。 +6. `BuiltinForwardPipeline` 通过 RHI 发出真正 draw call。 + +这条链路和很多商业引擎的基本思路是一致的。真正成熟的区别，不在“有没有 scene extraction 这个词”，而在于提取阶段做得有多深。 + +## 为什么要把 Mesh 和 Renderer 分开 + +`MeshFilterComponent + MeshRendererComponent` 这种拆分，和 Unity 的老思路非常接近。它背后的设计理由很实用： + +- 几何数据和材质配置是两种不同维度的信息。 +- 同一个 mesh 可能被不同材质配置复用。 +- 渲染系统提取时，可以分别读取 geometry source 和 material state。 + +如果把这两层全部混在一个组件里，短期写起来更省事，但长期会让复用、序列化和编辑器展示都更别扭。 + +## 为什么需要 Scene Extraction + +对游戏对象系统来说，最自然的数据组织方式是树状层级和组件组合；但对渲染来说，最自然的数据组织方式通常是： + +- 一台相机 +- 一组可见对象 +- 每个对象对应的变换、mesh 和材质 + +所以提取阶段的意义，就是把“适合编辑和运行时逻辑”的数据形状，转换成“适合绘制”的数据形状。 + +当前 `RenderSceneExtractor` 做的是这条路线中最基础的一版： + +- 选相机 +- 算矩阵 +- 遍历层级 +- 收集 mesh 对象 + +这和商业引擎的真正可见性阶段相比还很早期，但方向没有问题。 + +## 当前 extractor 做了什么，没做什么 + +已经做的： + +- 覆盖相机优先。 +- 没有覆盖相机时，优先选择 `IsPrimary()` 且 `depth` 更高的相机。 +- 只收集激活层级中的对象。 +- 只收集同时拥有 `MeshFilterComponent` 和 `MeshRendererComponent` 的对象。 + +还没做的： + +- 视锥裁剪。 +- 遮挡裁剪。 +- 透明排序。 +- render layer 过滤。 +- 阴影 caster / receiver 分类。 +- instancing / batching。 + +所以当前 `visibleObjects` 更准确地说是“当前场景里满足基础绘制条件的对象集合”，而不是严格意义上的最终可见集。 + +## RenderSurface 为什么重要 + +很多小型引擎一开始会把“渲染目标”写死成 swap chain back buffer，但这条路很快就会卡住： + +- 离屏渲染怎么办？ +- 编辑器预览窗口怎么办？ +- 反射探针、后处理链路怎么办？ + +`RenderSurface` 的作用，就是把这些目标抽象出来。当前它虽然还很轻量，但已经能描述： + +- 尺寸 +- 颜色附件 +- 深度附件 +- 清屏色覆盖 +- 渲染前后颜色资源状态 + +这一步非常关键，因为它让 pipeline 不再只服务于窗口表面。 + +## BuiltinForwardPipeline 的定位 + +`BuiltinForwardPipeline` 当前的定位，不是“最终渲染架构”，而是“默认可用的第一条内建管线”。 + +它现在主要解决的是： + +- 把 mesh 上传成 vertex/index buffer +- 把 texture 上传成 shader resource +- 创建一套最基本的 pipeline state +- 对每个对象写常量、绑纹理、发 draw + +这和很多商业引擎早期 builtin pipeline 的定位很像：先确保有一条完整闭环，再逐步扩展能力。 + +## 为什么要有 RenderResourceCache + +场景对象和资源系统不应该直接持有具体 RHI 对象，否则很快会把层级关系搞乱： + +- 资源层会被具体后端污染。 +- 不同 backend 的资源生命周期会混到游戏对象逻辑里。 + +`RenderResourceCache` 把“CPU 资源 -> GPU 资源”的转换收口到渲染层，这是对的。 + +但当前它还只是基础版： + +- 以裸指针做 cache key。 +- 没有资源变更失效。 +- 没有线程安全。 +- 格式支持有限。 + +所以它更像“运行时上传缓存”，还不是完整的 render resource system。 + +## 当前这套设计和商业引擎相比差什么 + +如果拿商业级游戏引擎的渲染系统作参照，当前最明显的缺口包括： + +1. 没有真正的 visibility / culling pipeline。 +2. 没有 render queue、pass 分类和排序系统。 +3. 没有 lighting、shadow、post-processing 等完整渲染特性。 +4. 没有 render graph 或更强的 target dependency 管理。 +5. `RenderPipelineAsset` 还没有真正驱动运行时 pipeline 创建。 + +但从架构骨架看，当前已经把最核心的几个边界切开了： + +- scene data +- render data +- render target +- pipeline implementation +- GPU resource upload + +这恰恰是后续能继续演进的前提。 + +## 当前阶段的推荐用法 + +- 需要渲染场景时，优先通过 `SceneRenderer` 作为统一入口。 +- 几何数据放在 `MeshFilterComponent`，材质槽和渲染标志放在 `MeshRendererComponent`。 +- 把 `RenderSurface` 当作“这一帧的输出目标描述”，而不是只当附件容器。 +- 当前把 `BuiltinForwardPipeline` 看作默认可运行路径，而不是最终渲染架构。 + +## 相关 API + +- [Rendering](../../XCEngine/Rendering/Rendering.md) +- [RenderSceneExtractor](../../XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md) +- [RenderSurface](../../XCEngine/Rendering/RenderSurface/RenderSurface.md) +- [SceneRenderer](../../XCEngine/Rendering/SceneRenderer/SceneRenderer.md) +- [BuiltinForwardPipeline](../../XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) +- [MeshFilterComponent](../../XCEngine/Components/MeshFilterComponent/MeshFilterComponent.md) +- [MeshRendererComponent](../../XCEngine/Components/MeshRendererComponent/MeshRendererComponent.md) diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md index e7b51d80..51cf51f3 100644 --- a/docs/api/_meta/rebuild-status.md +++ b/docs/api/_meta/rebuild-status.md @@ -1,16 +1,16 @@ # API 文档重构状态 -**生成时间**: `2026-03-26 20:57:38` +**生成时间**: `2026-03-26 21:30:11` **来源**: `docs/api/_tools/audit_api_docs.py` ## 摘要 -- Markdown 页面数（全部）: `2456` -- Markdown 页面数（canonical）: `2446` +- Markdown 页面数（全部）: `2535` +- Markdown 页面数（canonical）: `2524` - Public headers 数: `204` -- 有效头文件引用数（全部）: `185` -- 有效头文件引用数（canonical）: `185` +- 有效头文件引用数（全部）: `197` +- 有效头文件引用数（canonical）: `197` - 无效头文件引用数: `0` - 失效 `.md` 链接数: `0` - 非 `.md` 相对链接数: `0` @@ -21,8 +21,8 @@ - Canonical 根目录: `XCEngine` - 源码目录节点数: `27` -- 已生成目录总览页节点数: `24` -- 缺失目录总览页节点数: `3` +- 已生成目录总览页节点数: `26` +- 缺失目录总览页节点数: `1` - 支撑目录: `_meta, _tools` ## 模块覆盖 @@ -30,14 +30,14 @@ | 模块 | Public headers | 已覆盖 | 未覆盖 | |------|----------------|--------|--------| | `Audio` | `11` | `11` | `0` | -| `Components` | `10` | `8` | `2` | +| `Components` | `10` | `10` | `0` | | `Core` | `42` | `42` | `0` | | `Debug` | `10` | `10` | `0` | | `Input` | `5` | `5` | `0` | | `Memory` | `5` | `5` | `0` | | `Platform` | `11` | `11` | `0` | | `RHI` | `68` | `68` | `0` | -| `Rendering` | `10` | `0` | `10` | +| `Rendering` | `10` | `10` | `0` | | `Resources` | `13` | `13` | `0` | | `Scene` | `3` | `2` | `1` | | `Scripting` | `6` | `0` | `6` | @@ -47,31 +47,17 @@ | 字段 | 页面数 | |------|--------| -| `命名空间` | `208` | -| `类型` | `208` | -| `描述` | `208` | -| `头文件` | `185` | +| `命名空间` | `222` | +| `类型` | `222` | +| `描述` | `222` | +| `头文件` | `197` | ## 缺失的平行目录总览页 -- `XCEngine/Rendering` -- `XCEngine/Rendering/Pipelines` - `XCEngine/Scripting` ## 未覆盖的 public headers -- `XCEngine/Components/MeshFilterComponent.h` -- `XCEngine/Components/MeshRendererComponent.h` -- `XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h` -- `XCEngine/Rendering/RenderCameraData.h` -- `XCEngine/Rendering/RenderContext.h` -- `XCEngine/Rendering/RenderPipeline.h` -- `XCEngine/Rendering/RenderPipelineAsset.h` -- `XCEngine/Rendering/RenderResourceCache.h` -- `XCEngine/Rendering/RenderSceneExtractor.h` -- `XCEngine/Rendering/RenderSurface.h` -- `XCEngine/Rendering/SceneRenderer.h` -- `XCEngine/Rendering/VisibleRenderObject.h` - `XCEngine/Scene/SceneRuntime.h` - `XCEngine/Scripting/IScriptRuntime.h` - `XCEngine/Scripting/NullScriptRuntime.h`