docs: rebuild Rendering API content

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`
 
 ## 相关文档

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)

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=<path>`。
+4. 若路径非空，则调用 `ResourceManager::Get().Load<Resources::Mesh>()` 尝试重新加载。
+
+## 当前实现说明
+
+- 如果资源加载失败，`m_mesh` 可能仍然为空，但 `m_meshPath` 会保留反序列化得到的路径。
+- 当前序列化格式很轻量，适合人类可读文本，但没有更强的容错与版本化机制。
+
+## 相关文档
+
+- [返回类型总览](MeshFilterComponent.md)
+- [Serialize](Serialize.md)

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)

docs/api/XCEngine/Components/MeshFilterComponent/GetMeshHandle.md

@@ -0,0 +1,16 @@
+# MeshFilterComponent::GetMeshHandle
+
+获取当前 mesh 资源句柄。
+
+```cpp
+const Resources::ResourceHandle<Resources::Mesh>& GetMeshHandle() const;
+```
+
+## 返回值
+
+- 当前保存的 mesh `ResourceHandle` 常量引用。
+
+## 相关文档
+
+- [返回类型总览](MeshFilterComponent.md)
+- [GetMesh](GetMesh.md)

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)

docs/api/XCEngine/Components/MeshFilterComponent/GetName.md

@@ -0,0 +1,15 @@
+# MeshFilterComponent::GetName
+
+返回组件名字。
+
+```cpp
+std::string GetName() const override;
+```
+
+## 返回值
+
+- 当前固定返回 `"MeshFilter"`。
+
+## 相关文档
+
+- [返回类型总览](MeshFilterComponent.md)

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<Mesh>` 和一个字符串路径。
+- [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)

docs/api/XCEngine/Components/MeshFilterComponent/Serialize.md

@@ -0,0 +1,22 @@
+# MeshFilterComponent::Serialize
+
+序列化当前 mesh 信息。
+
+```cpp
+void Serialize(std::ostream& os) const override;
+```
+
+## 行为说明
+
+当前实现会输出：
+
+```text
+mesh=<path>;
+```
+
+这里只序列化路径，不会序列化 mesh 二进制内容本身。
+
+## 相关文档
+
+- [返回类型总览](MeshFilterComponent.md)
+- [Deserialize](Deserialize.md)

docs/api/XCEngine/Components/MeshFilterComponent/SetMesh.md

@@ -0,0 +1,26 @@
+# MeshFilterComponent::SetMesh
+
+设置当前 mesh。
+
+```cpp
+void SetMesh(const Resources::ResourceHandle<Resources::Mesh>& mesh);
+void SetMesh(Resources::Mesh* mesh);
+```
+
+## 行为说明
+
+无论使用哪种重载，当前实现都会：
+
+- 更新内部 `ResourceHandle`
+- 如果 mesh 非空，则把其 `GetPath()` 转成 `std::string` 写入 `m_meshPath`
+- 否则清空路径
+
+## 参数
+
+- `mesh` - 要设置的 mesh 句柄或裸指针。
+
+## 相关文档
+
+- [返回类型总览](MeshFilterComponent.md)
+- [GetMesh](GetMesh.md)
+- [ClearMesh](ClearMesh.md)

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)

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<Resources::Material>()` 尝试重新加载。
+
+## 当前实现说明
+
+- 如果某个材质加载失败，对应路径仍会保留，但句柄可能为空。
+- 默认值是：`castShadows = true`、`receiveShadows = true`、`renderLayer = 0`。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)
+- [Serialize](Serialize.md)

docs/api/XCEngine/Components/MeshRendererComponent/GetCastShadows.md

@@ -0,0 +1,20 @@
+# MeshRendererComponent::GetCastShadows
+
+获取投射阴影标志。
+
+```cpp
+bool GetCastShadows() const;
+```
+
+## 返回值
+
+- 当前 `m_castShadows` 值。
+
+## 当前实现说明
+
+- 当前渲染路径还没有真正消费这个标志。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)
+- [SetCastShadows](SetCastShadows.md)

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)

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)

docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialHandle.md

@@ -0,0 +1,25 @@
+# MeshRendererComponent::GetMaterialHandle
+
+获取指定槽位的材质句柄。
+
+```cpp
+const Resources::ResourceHandle<Resources::Material>& GetMaterialHandle(size_t index) const;
+```
+
+## 参数
+
+- `index` - 材质槽索引。
+
+## 返回值
+
+- 若索引有效则返回对应句柄引用。
+- 否则返回一个静态空句柄引用。
+
+## 注意事项
+
+- 越界时返回的是共享的静态空句柄，而不是临时对象。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)
+- [GetMaterial](GetMaterial.md)

docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialPaths.md

@@ -0,0 +1,17 @@
+# MeshRendererComponent::GetMaterialPaths
+
+获取当前材质路径数组。
+
+```cpp
+const std::vector<std::string>& GetMaterialPaths() const;
+```
+
+## 返回值
+
+- 当前缓存的材质路径数组引用。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)
+- [Serialize](Serialize.md)
+- [Deserialize](Deserialize.md)

docs/api/XCEngine/Components/MeshRendererComponent/GetName.md

@@ -0,0 +1,15 @@
+# MeshRendererComponent::GetName
+
+返回组件名字。
+
+```cpp
+std::string GetName() const override;
+```
+
+## 返回值
+
+- 当前固定返回 `"MeshRenderer"`。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)

docs/api/XCEngine/Components/MeshRendererComponent/GetReceiveShadows.md

@@ -0,0 +1,20 @@
+# MeshRendererComponent::GetReceiveShadows
+
+获取接收阴影标志。
+
+```cpp
+bool GetReceiveShadows() const;
+```
+
+## 返回值
+
+- 当前 `m_receiveShadows` 值。
+
+## 当前实现说明
+
+- 当前渲染路径还没有真正消费这个标志。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)
+- [SetReceiveShadows](SetReceiveShadows.md)

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)

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)

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)

docs/api/XCEngine/Components/MeshRendererComponent/SetCastShadows.md

@@ -0,0 +1,20 @@
+# MeshRendererComponent::SetCastShadows
+
+设置投射阴影标志。
+
+```cpp
+void SetCastShadows(bool value);
+```
+
+## 参数
+
+- `value` - 是否投射阴影。
+
+## 当前实现说明
+
+- 当前只是存储这个布尔值，还没有接入实际阴影渲染流程。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)
+- [GetCastShadows](GetCastShadows.md)

docs/api/XCEngine/Components/MeshRendererComponent/SetMaterial.md

@@ -0,0 +1,27 @@
+# MeshRendererComponent::SetMaterial
+
+设置单个材质槽。
+
+```cpp
+void SetMaterial(size_t index, const Resources::ResourceHandle<Resources::Material>& 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)

docs/api/XCEngine/Components/MeshRendererComponent/SetMaterials.md

@@ -0,0 +1,21 @@
+# MeshRendererComponent::SetMaterials
+
+批量设置整组材质槽。
+
+```cpp
+void SetMaterials(const std::vector<Resources::ResourceHandle<Resources::Material>>& materials);
+```
+
+## 行为说明
+
+当前实现会整体替换 `m_materials`，并把 `m_materialPaths` 调整为相同大小，然后逐项同步路径。
+
+## 参数
+
+- `materials` - 新的材质句柄数组。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)
+- [SetMaterial](SetMaterial.md)
+- [GetMaterialCount](GetMaterialCount.md)

docs/api/XCEngine/Components/MeshRendererComponent/SetReceiveShadows.md

@@ -0,0 +1,20 @@
+# MeshRendererComponent::SetReceiveShadows
+
+设置接收阴影标志。
+
+```cpp
+void SetReceiveShadows(bool value);
+```
+
+## 参数
+
+- `value` - 是否接收阴影。
+
+## 当前实现说明
+
+- 当前只是存储这个布尔值，还没有接入实际阴影渲染流程。
+
+## 相关文档
+
+- [返回类型总览](MeshRendererComponent.md)
+- [GetReceiveShadows](GetReceiveShadows.md)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

docs/api/XCEngine/Rendering/RenderPipelineAsset/CreatePipeline.md

@@ -0,0 +1,24 @@
+# RenderPipelineAsset::CreatePipeline
+
+创建一个新的渲染管线实例。
+
+```cpp
+virtual std::unique_ptr<RenderPipeline> CreatePipeline() const = 0;
+```
+
+## 行为说明
+
+派生类应根据自身配置返回一个具体 `RenderPipeline` 实例。
+
+## 返回值
+
+- 一个拥有独占所有权的 `RenderPipeline` 对象。
+
+## 设计说明
+
+把返回值设计成 `std::unique_ptr` 是合理的，因为渲染管线往往具有明确的独占生命周期，不适合共享所有权。
+
+## 相关文档
+
+- [返回类型总览](RenderPipelineAsset.md)
+- [RenderPipeline](../RenderPipeline/RenderPipeline.md)

docs/api/XCEngine/Rendering/RenderPipelineAsset/Destructor.md

@@ -0,0 +1,16 @@
+# RenderPipelineAsset::~RenderPipelineAsset
+
+销毁渲染管线资产对象。
+
+```cpp
+virtual ~RenderPipelineAsset() = default;
+```
+
+## 行为说明
+
+这是一个虚析构函数，用于保证通过基类指针销毁派生资产对象时行为正确。
+
+## 相关文档
+
+- [返回类型总览](RenderPipelineAsset.md)
+- [CreatePipeline](CreatePipeline.md)

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)

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)

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)

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)

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)

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)

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)

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<VisibleRenderObject>` | 当前提取到的可见对象列表。 |
+
+`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)

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)

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)

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)

docs/api/XCEngine/Rendering/RenderSurface/GetColorAttachments.md

@@ -0,0 +1,22 @@
+# RenderSurface::GetColorAttachments
+
+获取颜色附件数组。
+
+```cpp
+const std::vector<RHI::RHIResourceView*>& GetColorAttachments() const;
+```
+
+## 返回值
+
+- 对内部颜色附件数组的常量引用。
+
+## 注意事项
+
+- 当前返回的是内部容器引用，不是拷贝。
+- 调用方需要自己保证其中指针的生命周期有效。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetColorAttachment](SetColorAttachment.md)
+- [SetColorAttachments](SetColorAttachments.md)

docs/api/XCEngine/Rendering/RenderSurface/GetColorStateAfter.md

@@ -0,0 +1,16 @@
+# RenderSurface::GetColorStateAfter
+
+获取颜色附件渲染后状态。
+
+```cpp
+RHI::ResourceStates GetColorStateAfter() const;
+```
+
+## 返回值
+
+- 当前记录的渲染后颜色状态。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetColorStateAfter](SetColorStateAfter.md)

docs/api/XCEngine/Rendering/RenderSurface/GetColorStateBefore.md

@@ -0,0 +1,16 @@
+# RenderSurface::GetColorStateBefore
+
+获取颜色附件渲染前状态。
+
+```cpp
+RHI::ResourceStates GetColorStateBefore() const;
+```
+
+## 返回值
+
+- 当前记录的渲染前颜色状态。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetColorStateBefore](SetColorStateBefore.md)

docs/api/XCEngine/Rendering/RenderSurface/GetDepthAttachment.md

@@ -0,0 +1,16 @@
+# RenderSurface::GetDepthAttachment
+
+获取当前深度附件。
+
+```cpp
+RHI::RHIResourceView* GetDepthAttachment() const;
+```
+
+## 返回值
+
+- 当前记录的深度附件指针。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetDepthAttachment](SetDepthAttachment.md)

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)

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)

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)

docs/api/XCEngine/Rendering/RenderSurface/IsAutoTransitionEnabled.md

@@ -0,0 +1,17 @@
+# RenderSurface::IsAutoTransitionEnabled
+
+查询是否启用了颜色附件自动状态切换。
+
+```cpp
+bool IsAutoTransitionEnabled() const;
+```
+
+## 返回值
+
+- 已启用返回 `true`。
+- 否则返回 `false`。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md)

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)

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)

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)

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)

docs/api/XCEngine/Rendering/RenderSurface/SetColorAttachments.md

@@ -0,0 +1,26 @@
+# RenderSurface::SetColorAttachments
+
+设置一组颜色附件。
+
+```cpp
+void SetColorAttachments(const std::vector<RHI::RHIResourceView*>& colorAttachments);
+```
+
+## 参数
+
+- `colorAttachments` - 颜色附件数组。
+
+## 行为说明
+
+当前实现会直接拷贝这组指针到内部数组。
+
+## 注意事项
+
+- 当前不会过滤空指针。
+- 当前不会检查附件数量是否与具体管线能力匹配。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetColorAttachment](SetColorAttachment.md)
+- [GetColorAttachments](GetColorAttachments.md)

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)

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)

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)

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)

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)

docs/api/XCEngine/Rendering/SceneRenderer/Constructor.md

@@ -0,0 +1,19 @@
+# SceneRenderer::SceneRenderer
+
+构造场景渲染器。
+
+```cpp
+SceneRenderer();
+explicit SceneRenderer(std::unique_ptr<RenderPipeline> pipeline);
+```
+
+## 行为说明
+
+- 默认构造函数会创建一个 `BuiltinForwardPipeline`。
+- 传入 `pipeline` 的重载会接管该对象所有权。
+- 如果传入空指针，当前实现会退回到 `BuiltinForwardPipeline`。
+
+## 相关文档
+
+- [返回类型总览](SceneRenderer.md)
+- [SetPipeline](SetPipeline.md)

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)

docs/api/XCEngine/Rendering/SceneRenderer/GetPipeline.md

@@ -0,0 +1,21 @@
+# SceneRenderer::GetPipeline
+
+获取当前渲染管线指针。
+
+```cpp
+RenderPipeline* GetPipeline() const;
+```
+
+## 返回值
+
+- 返回当前持有的 `RenderPipeline*`。
+
+## 注意事项
+
+- 这是非拥有指针。
+- 默认构造下通常会返回 `BuiltinForwardPipeline` 实例。
+
+## 相关文档
+
+- [返回类型总览](SceneRenderer.md)
+- [SetPipeline](SetPipeline.md)

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)

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)

docs/api/XCEngine/Rendering/SceneRenderer/SetPipeline.md

@@ -0,0 +1,25 @@
+# SceneRenderer::SetPipeline
+
+替换当前使用的渲染管线。
+
+```cpp
+void SetPipeline(std::unique_ptr<RenderPipeline> pipeline);
+```
+
+## 行为说明
+
+当前实现会：
+
+1. 若已有 pipeline，则先调用其 `Shutdown()`。
+2. 用新传入的 `unique_ptr` 替换当前 pipeline。
+3. 如果新指针为空，则自动退回到 `BuiltinForwardPipeline`。
+
+## 参数
+
+- `pipeline` - 新的渲染管线实例。
+
+## 相关文档
+
+- [返回类型总览](SceneRenderer.md)
+- [GetPipeline](GetPipeline.md)
+- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)

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)

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)

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 页面数（全部）: `2535`
-- Markdown 页面数（canonical）: `2446`
+- Markdown 页面数（canonical）: `2524`
 - Public headers 数: `204`
-- 有效头文件引用数（全部）: `185`
+- 有效头文件引用数（全部）: `197`
-- 有效头文件引用数（canonical）: `185`
+- 有效头文件引用数（canonical）: `197`
 - 无效头文件引用数: `0`
 - 失效 `.md` 链接数: `0`
 - 非 `.md` 相对链接数: `0`
@@ -21,8 +21,8 @@
 
 - Canonical 根目录: `XCEngine`
 - 源码目录节点数: `27`
-- 已生成目录总览页节点数: `24`
+- 已生成目录总览页节点数: `26`
-- 缺失目录总览页节点数: `3`
+- 缺失目录总览页节点数: `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` |
+| `命名空间` | `222` |
-| `类型` | `208` |
+| `类型` | `222` |
-| `描述` | `208` |
+| `描述` | `222` |
-| `头文件` | `185` |
+| `头文件` | `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`