docs: add builtin depth pass docs

docs/api/XCEngine/Rendering/Passes/BuiltinDepthOnlyPass/BuildInputLayout.md

@@ -0,0 +1,21 @@
+# BuiltinDepthOnlyPass::BuildInputLayout
+
+返回 builtin depth-only pass 使用的顶点布局。
+
+```cpp
+static RHI::InputLayoutDesc BuildInputLayout();
+```
+
+## 当前语义
+
+- 当前实现直接返回 [BuiltinDepthStylePassBase::BuildCommonInputLayout](../BuiltinDepthStylePassBase/BuildCommonInputLayout.md)。
+- 因此布局包含 `POSITION / NORMAL / TEXCOORD0` 三个输入元素，并匹配 `Resources::StaticMeshVertex`。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 显式验证了这里返回的 3 个输入元素及其 offset。
+
+## 相关文档
+
+- [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass.md)
+- [BuiltinDepthStylePassBase::BuildCommonInputLayout](../BuiltinDepthStylePassBase/BuildCommonInputLayout.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md

@@ -0,0 +1,32 @@
+# BuiltinDepthOnlyPass
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinDepthOnlyPass.h`
+
+**描述**: `BuiltinDepthStylePassBase` 的 `DepthOnly` 特化，使用 builtin depth-only shader 执行只写深度的场景重绘。
+
+## 概览
+
+`BuiltinDepthOnlyPass` 当前没有新增渲染流程；它主要做两件事：
+
+- 在构造时把基类 pass 类型固定为 `BuiltinMaterialPass::DepthOnly`，并注入 builtin depth-only shader 路径。
+- 通过 [GetName](GetName.md) 和 [BuildInputLayout](BuildInputLayout.md) 暴露当前 pass 的公开身份与顶点布局。
+
+真正的初始化、执行和资源释放逻辑仍由 [BuiltinDepthStylePassBase](../BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) 提供。
+
+## 公开方法
+
+| 成员 | 说明 |
+|------|------|
+| [Constructor](Constructor.md) | 构造 depth-only pass。 |
+| [Destructor](Destructor.md) | 默认析构，实际 teardown 由基类析构兜底。 |
+| [BuildInputLayout](BuildInputLayout.md) | 返回共用 `StaticMeshVertex` 布局。 |
+| [GetName](GetName.md) | 返回固定名字 `"BuiltinDepthOnlyPass"`。 |
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](../BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md)
+- [BuiltinShadowCasterPass](../BuiltinShadowCasterPass/BuiltinShadowCasterPass.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthOnlyPass/Constructor.md

@@ -0,0 +1,19 @@
+# BuiltinDepthOnlyPass::BuiltinDepthOnlyPass
+
+构造 builtin depth-only pass。
+
+```cpp
+BuiltinDepthOnlyPass();
+```
+
+## 当前语义
+
+- 当前实现会把基类构造参数固定为：
+  - `BuiltinMaterialPass::DepthOnly`
+  - `Resources::GetBuiltinDepthOnlyShaderPath()`
+- 构造阶段不会立刻创建 GPU 资源；真正初始化仍延后到执行路径。
+
+## 相关文档
+
+- [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass.md)
+- [BuiltinDepthStylePassBase::Constructor](../BuiltinDepthStylePassBase/Constructor.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthOnlyPass/Destructor.md

@@ -0,0 +1,17 @@
+# BuiltinDepthOnlyPass::~BuiltinDepthOnlyPass
+
+销毁 builtin depth-only pass。
+
+```cpp
+~BuiltinDepthOnlyPass() override = default;
+```
+
+## 当前语义
+
+- 当前类本身没有自定义析构逻辑。
+- 实际 teardown 由 [BuiltinDepthStylePassBase::Destructor](../BuiltinDepthStylePassBase/Destructor.md) 负责，它会调用基类 [Shutdown](../BuiltinDepthStylePassBase/Shutdown.md)。
+
+## 相关文档
+
+- [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass.md)
+- [BuiltinDepthStylePassBase::Destructor](../BuiltinDepthStylePassBase/Destructor.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthOnlyPass/GetName.md

@@ -0,0 +1,16 @@
+# BuiltinDepthOnlyPass::GetName
+
+返回当前 pass 的固定名称。
+
+```cpp
+const char* GetName() const override;
+```
+
+## 返回值
+
+- 当前实现始终返回 `"BuiltinDepthOnlyPass"`。
+
+## 相关文档
+
+- [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass.md)
+- [BuiltinShadowCasterPass::GetName](../BuiltinShadowCasterPass/GetName.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase/BuildCommonInputLayout.md

@@ -0,0 +1,30 @@
+# BuiltinDepthStylePassBase::BuildCommonInputLayout
+
+返回深度风格 pass 共用的静态顶点布局。
+
+```cpp
+static RHI::InputLayoutDesc BuildCommonInputLayout();
+```
+
+## 当前实现返回值
+
+当前实现会返回 3 个输入元素，按 `Resources::StaticMeshVertex` 的字段顺序排列：
+
+1. `POSITION` -> `offsetof(Resources::StaticMeshVertex, position)`
+2. `NORMAL` -> `offsetof(Resources::StaticMeshVertex, normal)`
+3. `TEXCOORD` -> `offsetof(Resources::StaticMeshVertex, uv0)`
+
+## 当前语义
+
+- 这组布局由 [BuiltinDepthOnlyPass::BuildInputLayout](../BuiltinDepthOnlyPass/BuildInputLayout.md) 和 [BuiltinShadowCasterPass::BuildInputLayout](../BuiltinShadowCasterPass/BuildInputLayout.md) 直接复用。
+- 它匹配 `RenderResourceCache` 上传的 `StaticMeshVertex` 顶点流，而不是只保留位置的极简布局。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 验证了 depth-only 与 shadow-caster 两个派生类返回的布局都包含这 3 个元素。
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase.md)
+- [BuiltinDepthOnlyPass::BuildInputLayout](../BuiltinDepthOnlyPass/BuildInputLayout.md)
+- [BuiltinShadowCasterPass::BuildInputLayout](../BuiltinShadowCasterPass/BuildInputLayout.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md

@@ -0,0 +1,43 @@
+# BuiltinDepthStylePassBase
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinDepthStylePassBase.h`
+
+**描述**: `BuiltinDepthOnlyPass` 与 `BuiltinShadowCasterPass` 共享的深度风格 pass 基类，负责懒初始化 shader / pipeline / per-object descriptor，并按 `RenderPass` 约定执行一次只写深度的场景重绘。
+
+## 概览
+
+`BuiltinDepthStylePassBase` 把两类 pass 的公共逻辑集中在一起：
+
+- 按 `BuiltinMaterialPass` 解析可兼容的 shader pass。
+- 复用 [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md) 上传 mesh GPU 副本。
+- 只接受“单个 `PerObject` 常量缓冲”这一类资源绑定计划。
+- 在 [Execute](Execute.md) 中统一处理 `RenderSurface` 检查、viewport/scissor、清屏、绘制循环和颜色附件状态切换。
+
+派生类当前只负责决定：
+
+- 构造时注入哪种 builtin shader 路径。
+- `GetName()` 返回什么名字。
+- 是否通过 [ShouldRenderVisibleItem](ShouldRenderVisibleItem.md) 进一步过滤可见物体。
+
+## 公开与受保护方法
+
+| 成员 | 说明 |
+|------|------|
+| [Constructor](Constructor.md) | 受保护构造函数，保存 pass 类型与 builtin shader 路径。 |
+| [Destructor](Destructor.md) | 析构时调用 [Shutdown](Shutdown.md)。 |
+| [BuildCommonInputLayout](BuildCommonInputLayout.md) | 返回深度风格 pass 共用的 `StaticMeshVertex` 输入布局。 |
+| [Initialize](Initialize.md) | 懒初始化资源。 |
+| [Shutdown](Shutdown.md) | 释放缓存的 shader、pipeline、descriptor 和 mesh GPU 副本。 |
+| [Execute](Execute.md) | 执行一次深度风格场景重绘。 |
+| [ShouldRenderVisibleItem](ShouldRenderVisibleItem.md) | 派生类可覆写的可见物体过滤点。 |
+
+## 相关文档
+
+- [BuiltinDepthOnlyPass](../BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md)
+- [BuiltinShadowCasterPass](../BuiltinShadowCasterPass/BuiltinShadowCasterPass.md)
+- [RenderPass](../../RenderPass/RenderPass.md)
+- [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase/Constructor.md

@@ -0,0 +1,26 @@
+# BuiltinDepthStylePassBase::Constructor
+
+构造一个深度风格 pass 基类子对象。
+
+```cpp
+BuiltinDepthStylePassBase(
+    BuiltinMaterialPass passType,
+    Containers::String builtinShaderPath);
+```
+
+## 参数
+
+- `passType` - 当前派生 pass 对应的 builtin material pass 类型。
+- `builtinShaderPath` - 初始化时要加载的 builtin shader 路径。
+
+## 当前语义
+
+- 当前实现只保存 `m_passType` 和 `m_builtinShaderPath`。
+- 构造阶段不会立刻创建 shader、pipeline state、descriptor set 或 mesh GPU 缓存。
+- 真正的资源创建会延后到 [Initialize](Initialize.md) 或 [Execute](Execute.md) 首次走到 `EnsureInitialized(...)` 时发生。
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase.md)
+- [Initialize](Initialize.md)
+- [Execute](Execute.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase/Destructor.md

@@ -0,0 +1,17 @@
+# BuiltinDepthStylePassBase::~BuiltinDepthStylePassBase
+
+销毁深度风格 pass 基类对象。
+
+```cpp
+~BuiltinDepthStylePassBase() override;
+```
+
+## 当前语义
+
+- 当前析构函数会直接调用 [Shutdown](Shutdown.md)。
+- 因此即使调用方忘记提前手动 shutdown，基类析构时也会兜底释放内部 shader、pipeline、descriptor 和 mesh GPU 缓存。
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase/Execute.md

@@ -0,0 +1,31 @@
+# BuiltinDepthStylePassBase::Execute
+
+执行一次深度风格场景重绘。
+
+```cpp
+bool Execute(const RenderPassContext& context) override;
+```
+
+## 当前流程
+
+1. 校验 `renderContext`、第一个颜色附件、深度附件和 `surface.GetRenderArea()`
+2. 懒初始化 shader / pipeline / descriptor 资源
+3. 必要时把第一个颜色附件从 `colorStateBefore` 过渡到 `RenderTarget`
+4. 绑定 `colorAttachments[0]` 与深度附件
+5. 以 `surface.GetRenderArea()` 设置 viewport / scissor
+6. 按 `cameraData.clearFlags` 清颜色与深度
+7. 遍历 `visibleItems`，先经 [ShouldRenderVisibleItem](ShouldRenderVisibleItem.md) 过滤，再绘制可接受项
+8. `EndRenderPass()`，并在需要时把第一个颜色附件过渡到 `colorStateAfter`
+
+## 当前语义
+
+- 当前实现只处理第一个颜色附件和一个深度附件。
+- 清颜色使用的是 `sceneData.cameraData.clearColor`，不会读取 `RenderSurface` 自己的 clear-color override。
+- 物体真正能否绘制，还取决于 mesh 是否有效、shader pass 是否可解析、descriptor set 是否能成功创建等后续条件。
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase.md)
+- [Initialize](Initialize.md)
+- [ShouldRenderVisibleItem](ShouldRenderVisibleItem.md)
+- [RenderSurface](../../RenderSurface/RenderSurface.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase/Initialize.md

@@ -0,0 +1,19 @@
+# BuiltinDepthStylePassBase::Initialize
+
+初始化深度风格 pass 所需资源。
+
+```cpp
+bool Initialize(const RenderContext& context) override;
+```
+
+## 当前语义
+
+- 当前实现直接转发到内部 `EnsureInitialized(context)`。
+- 如果资源已经为同一 `device / backendType` 初始化完成，则会复用现有状态并返回 `true`。
+- 如果上下文无效，或 shader 加载失败，则返回 `false`。
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase.md)
+- [Execute](Execute.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase/ShouldRenderVisibleItem.md

@@ -0,0 +1,19 @@
+# BuiltinDepthStylePassBase::ShouldRenderVisibleItem
+
+判断某个可见物体是否应进入当前深度风格 pass。
+
+```cpp
+virtual bool ShouldRenderVisibleItem(const VisibleRenderItem& visibleItem) const;
+```
+
+## 当前语义
+
+- 基类默认实现始终返回 `true`。
+- 派生类可通过覆写这里，在正式 draw 之前先做一层轻量过滤。
+- [BuiltinShadowCasterPass](../BuiltinShadowCasterPass/ShouldRenderVisibleItem.md) 当前就利用这个扩展点过滤掉 `GetCastShadows() == false` 的物体。
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase.md)
+- [Execute](Execute.md)
+- [BuiltinShadowCasterPass::ShouldRenderVisibleItem](../BuiltinShadowCasterPass/ShouldRenderVisibleItem.md)

docs/api/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase/Shutdown.md

@@ -0,0 +1,29 @@
+# BuiltinDepthStylePassBase::Shutdown
+
+释放当前缓存的深度风格 pass 资源。
+
+```cpp
+void Shutdown() override;
+```
+
+## 当前语义
+
+- 当前实现直接调用内部 `DestroyResources()`。
+- 它会清理：
+  - [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md)
+  - 按 object ID 缓存的 per-object descriptor set / pool
+  - pipeline state 缓存
+  - pass resource layout 缓存
+  - builtin shader handle
+- 同时会把 `m_device`、`m_backendType` 等运行时状态重置回未初始化状态。
+
+## 调用后效果
+
+- 之后再次 [Execute](Execute.md) 时，会重新走初始化路径。
+- 当前实现支持重复调用。
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase.md)
+- [Destructor](Destructor.md)
+- [Execute](Execute.md)

docs/api/XCEngine/Rendering/Passes/BuiltinShadowCasterPass/BuildInputLayout.md

@@ -0,0 +1,21 @@
+# BuiltinShadowCasterPass::BuildInputLayout
+
+返回 builtin shadow-caster pass 使用的顶点布局。
+
+```cpp
+static RHI::InputLayoutDesc BuildInputLayout();
+```
+
+## 当前语义
+
+- 当前实现直接返回 [BuiltinDepthStylePassBase::BuildCommonInputLayout](../BuiltinDepthStylePassBase/BuildCommonInputLayout.md)。
+- 因此布局包含 `POSITION / NORMAL / TEXCOORD0` 三个输入元素，并匹配 `Resources::StaticMeshVertex`。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 显式验证了这里返回的 3 个输入元素及其 offset。
+
+## 相关文档
+
+- [BuiltinShadowCasterPass](BuiltinShadowCasterPass.md)
+- [BuiltinDepthStylePassBase::BuildCommonInputLayout](../BuiltinDepthStylePassBase/BuildCommonInputLayout.md)

docs/api/XCEngine/Rendering/Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.md

@@ -0,0 +1,31 @@
+# BuiltinShadowCasterPass
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinShadowCasterPass.h`
+
+**描述**: `BuiltinDepthStylePassBase` 的 `ShadowCaster` 特化，在共享深度风格执行框架上额外过滤掉“不投射阴影”的物体。
+
+## 概览
+
+`BuiltinShadowCasterPass` 与 [BuiltinDepthOnlyPass](../BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 共享同一套基础执行逻辑，但有两点不同：
+
+- 构造时注入的是 `BuiltinMaterialPass::ShadowCaster` 与 builtin shadow-caster shader 路径。
+- 通过 [ShouldRenderVisibleItem](ShouldRenderVisibleItem.md) 过滤掉 `MeshRendererComponent::GetCastShadows() == false` 的物体。
+
+## 公开方法
+
+| 成员 | 说明 |
+|------|------|
+| [Constructor](Constructor.md) | 构造 shadow-caster pass。 |
+| [Destructor](Destructor.md) | 默认析构，实际 teardown 由基类析构兜底。 |
+| [BuildInputLayout](BuildInputLayout.md) | 返回共用 `StaticMeshVertex` 布局。 |
+| [GetName](GetName.md) | 返回固定名字 `"BuiltinShadowCasterPass"`。 |
+| [ShouldRenderVisibleItem](ShouldRenderVisibleItem.md) | 只接受允许投射阴影的物体。 |
+
+## 相关文档
+
+- [BuiltinDepthStylePassBase](../BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md)
+- [BuiltinDepthOnlyPass](../BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md)

docs/api/XCEngine/Rendering/Passes/BuiltinShadowCasterPass/Constructor.md

@@ -0,0 +1,19 @@
+# BuiltinShadowCasterPass::BuiltinShadowCasterPass
+
+构造 builtin shadow-caster pass。
+
+```cpp
+BuiltinShadowCasterPass();
+```
+
+## 当前语义
+
+- 当前实现会把基类构造参数固定为：
+  - `BuiltinMaterialPass::ShadowCaster`
+  - `Resources::GetBuiltinShadowCasterShaderPath()`
+- 构造阶段不会立刻创建 GPU 资源。
+
+## 相关文档
+
+- [BuiltinShadowCasterPass](BuiltinShadowCasterPass.md)
+- [BuiltinDepthStylePassBase::Constructor](../BuiltinDepthStylePassBase/Constructor.md)

docs/api/XCEngine/Rendering/Passes/BuiltinShadowCasterPass/Destructor.md

@@ -0,0 +1,17 @@
+# BuiltinShadowCasterPass::~BuiltinShadowCasterPass
+
+销毁 builtin shadow-caster pass。
+
+```cpp
+~BuiltinShadowCasterPass() override = default;
+```
+
+## 当前语义
+
+- 当前类本身没有自定义析构逻辑。
+- 实际资源释放由 [BuiltinDepthStylePassBase::Destructor](../BuiltinDepthStylePassBase/Destructor.md) 负责。
+
+## 相关文档
+
+- [BuiltinShadowCasterPass](BuiltinShadowCasterPass.md)
+- [BuiltinDepthStylePassBase::Destructor](../BuiltinDepthStylePassBase/Destructor.md)

docs/api/XCEngine/Rendering/Passes/BuiltinShadowCasterPass/GetName.md

@@ -0,0 +1,16 @@
+# BuiltinShadowCasterPass::GetName
+
+返回当前 pass 的固定名称。
+
+```cpp
+const char* GetName() const override;
+```
+
+## 返回值
+
+- 当前实现始终返回 `"BuiltinShadowCasterPass"`。
+
+## 相关文档
+
+- [BuiltinShadowCasterPass](BuiltinShadowCasterPass.md)
+- [BuiltinDepthOnlyPass::GetName](../BuiltinDepthOnlyPass/GetName.md)

docs/api/XCEngine/Rendering/Passes/BuiltinShadowCasterPass/ShouldRenderVisibleItem.md

@@ -0,0 +1,29 @@
+# BuiltinShadowCasterPass::ShouldRenderVisibleItem
+
+判断某个可见物体是否应参与 shadow-caster pass。
+
+```cpp
+bool ShouldRenderVisibleItem(const VisibleRenderItem& visibleItem) const override;
+```
+
+## 当前语义
+
+- 当前实现返回：
+
+```cpp
+visibleItem.meshRenderer == nullptr || visibleItem.meshRenderer->GetCastShadows();
+```
+
+- 也就是说：
+  - 没有 `meshRenderer` 指针时，这一层不会主动过滤掉该物体。
+  - 有 `meshRenderer` 时，只有 `GetCastShadows() == true` 才会继续进入绘制路径。
+
+## 调用方影响
+
+- 这是在基类 draw 前的一层早期过滤，不改变后续对 mesh、shader pass、descriptor 等有效性的检查。
+
+## 相关文档
+
+- [BuiltinShadowCasterPass](BuiltinShadowCasterPass.md)
+- [BuiltinDepthStylePassBase::ShouldRenderVisibleItem](../BuiltinDepthStylePassBase/ShouldRenderVisibleItem.md)
+- [BuiltinDepthStylePassBase::Execute](../BuiltinDepthStylePassBase/Execute.md)