From 8de68c0fc9dbbcf8c45d9a3a6f679f47a30ee3a1 Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Sat, 4 Apr 2026 01:10:38 +0800
Subject: [PATCH] docs: sync rendering builtin pass docs

---
 .../BuildInfiniteGridParameters.md            |  2 +-
 .../BuiltinInfiniteGridPass.md                | 34 +++++++++---
 .../BuiltinInfiniteGridPass/Constructor.md    | 52 +++++++++++++++++++
 .../BuiltinInfiniteGridPass/Destructor.md     | 28 ++++++++++
 .../BuiltinInfiniteGridPass/GetShaderPath.md  | 28 ++++++++++
 .../Passes/BuiltinInfiniteGridPass/Render.md  | 32 ++++++++----
 .../BuiltinInfiniteGridPass/SetShaderPath.md  | 37 +++++++++++++
 .../BuiltinInfiniteGridPass/Shutdown.md       | 33 +++++++++---
 .../BuiltinObjectIdOutlinePass.md             | 28 ++++++++--
 .../BuiltinObjectIdOutlinePass/Constructor.md | 12 +++--
 .../GetShaderPath.md                          | 28 ++++++++++
 .../BuiltinObjectIdOutlinePass/Render.md      |  4 +-
 .../SetShaderPath.md                          | 37 +++++++++++++
 .../BuiltinObjectIdOutlinePass/Shutdown.md    |  2 +-
 .../BuiltinObjectIdPass.md                    |  2 +-
 docs/api/XCEngine/Rendering/Passes/Passes.md  |  4 +-
 16 files changed, 326 insertions(+), 37 deletions(-)
 create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Constructor.md
 create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Destructor.md
 create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/GetShaderPath.md
 create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/SetShaderPath.md
 create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/GetShaderPath.md
 create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/SetShaderPath.md

diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/BuildInfiniteGridParameters.md b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/BuildInfiniteGridParameters.md
index d895256f..40aabba6 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/BuildInfiniteGridParameters.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/BuildInfiniteGridParameters.md
@@ -22,7 +22,7 @@ InfiniteGridParameters BuildInfiniteGridParameters(const InfiniteGridPassData& d
 
 ## 测试覆盖
 
-`tests/editor/test_scene_viewport_overlay_renderer.cpp` 当前验证了：
+`tests/Editor/test_scene_viewport_overlay_renderer.cpp` 当前验证了：
 
 - 间距始终落在十进制尺度上。
 - 水平平移不影响参数。
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md
index d78f32da..272efa2a 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md
@@ -6,13 +6,24 @@
 
 **头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
 
-**描述**: 在场景颜色目标上叠加编辑器无限地面网格的内建全屏 pass。
+**描述**: 在场景颜色目标上叠加无限地面网格的底层全屏 pass；真正使用哪份 shader 由调用方通过 `shaderPath` 注入。
 
 ## 概述
 
 `BuiltinInfiniteGridPass` 是当前 Scene View 里“地面参考网格”效果的实际执行者。
 
-它消费一份 [InfiniteGridPassData](InfiniteGridPassData.md)，在运行时先推导 [InfiniteGridParameters](InfiniteGridParameters.md)，再用 builtin shader 把网格直接混合到目标颜色附件上。
+它消费一份 [InfiniteGridPassData](InfiniteGridPassData.md)，在运行时先推导
+[InfiniteGridParameters](InfiniteGridParameters.md)，再用当前配置的 shader 资源把网格直接混合到目标颜色附件上。
+
+这个类当前不再自己决定“Scene View grid shader 到底是哪一份资源”。源码里的职责边界已经变成：
+
+- `BuiltinInfiniteGridPass`
+  只负责资源创建、常量写入和一次全屏三角形执行。
+- editor 调用方
+  通过 [SetShaderPath](SetShaderPath.md) 或构造函数参数注入具体 shader 路径。
+- `SceneViewportGridPass`
+  负责把 [SceneViewportShaderPaths](../../../Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md)
+  生成的 editor 资源路径传进来。
 
 ## 关键输入
 
@@ -23,14 +34,15 @@
 ## 当前实现流程
 
 1. 先校验 `data.valid`、`RenderContext::IsValid()` 和 `backendType == D3D12`。
-2. 通过 `EnsureInitialized()` 惰性创建 pipeline layout、pipeline state 和常量描述符。
+2. 通过 `EnsureInitialized()` 惰性创建 pipeline layout、pipeline state 和常量描述符；这一步要求 `shaderPath` 非空且可成功加载。
 3. 从相机姿态推导网格参数，并构建 view-projection 常量。
 4. 把第一个颜色附件和深度附件绑定为渲染目标。
 5. 以全屏三角形方式发出一次 `Draw(3, 1, 0, 0)`。
 
 ## 当前实现边界
 
-- 当前只支持 `D3D12` builtin shader variant。
+- 当前只支持 `D3D12` shader variant。
+- 在第一次创建资源之前必须先提供有效 `shaderPath`；空路径会记录错误并返回 `false`。
 - 只写入 `surface` 的第一个颜色附件。
 - 视口和裁剪矩形使用 `surface.GetWidth()` / `GetHeight()`，不是自定义 render area。
 - 网格参数完全由当前相机高度与朝向启发式推导，还没有暴露成更完整的编辑器样式配置。
@@ -39,6 +51,10 @@
 
 | 成员 | 说明 |
 |------|------|
+| [Constructor](Constructor.md) | 创建 pass，并可选地预置 shader 路径。 |
+| [Destructor](Destructor.md) | 默认析构；不会自动代替 `Shutdown()` 释放内部 RHI 资源。 |
+| [SetShaderPath](SetShaderPath.md) | 更新当前要加载的 shader 路径，并清空已创建资源。 |
+| [GetShaderPath](GetShaderPath.md) | 返回当前记录的 shader 路径。 |
 | [InfiniteGridPassData](InfiniteGridPassData.md) | 输入相机数据。 |
 | [InfiniteGridParameters](InfiniteGridParameters.md) | 推导后的网格尺度参数。 |
 | [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) | 从输入相机数据生成当前网格参数。 |
@@ -47,14 +63,20 @@
 
 ## 真实使用位置
 
-- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` 用 `SceneViewportGridPassRenderer` 包装它，并把它挂进 Scene View 的 `postScenePasses`。
+- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` 用 `SceneViewportGridPassRenderer` 包装它，
+  并通过 `GetSceneViewportInfiniteGridShaderPath()` 注入 editor-owned shader 路径，再把它挂进 Scene View 的 `postScenePasses`。
 - [SceneViewportRenderPlan](../../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) 决定当前帧是否需要创建这条 pass。
-- `tests/editor/test_scene_viewport_overlay_renderer.cpp` 固定了网格参数推导规则。
+- `tests/Editor/test_scene_viewport_overlay_renderer.cpp` 固定了网格参数推导规则。
 
 ## 相关文档
 
 - [Passes](../Passes.md)
+- [Constructor](Constructor.md)
+- [Destructor](Destructor.md)
+- [SetShaderPath](SetShaderPath.md)
+- [GetShaderPath](GetShaderPath.md)
 - [InfiniteGridPassData](InfiniteGridPassData.md)
 - [InfiniteGridParameters](InfiniteGridParameters.md)
 - [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md)
 - [SceneViewportRenderPlan](../../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md)
+- [SceneViewportShaderPaths](../../../Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Constructor.md b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Constructor.md
new file mode 100644
index 00000000..92d54b8d
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Constructor.md
@@ -0,0 +1,52 @@
+# BuiltinInfiniteGridPass::Constructor
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `constructor`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
+
+## 签名
+
+```cpp
+BuiltinInfiniteGridPass(Containers::String shaderPath = Containers::String());
+```
+
+## 作用
+
+创建一个尚未分配 GPU 资源的 grid pass 对象，并可选地预置 shader 路径。
+
+## 当前实现行为
+
+当前构造函数只做一件事：
+
+```cpp
+m_shaderPath = std::move(shaderPath);
+```
+
+这意味着：
+
+- 不会在构造阶段加载 shader。
+- 不会提前创建 pipeline layout、pipeline state 或 descriptor set。
+- 所有真实 GPU 资源都延迟到第一次 [Render](Render.md) 成功进入初始化路径时创建。
+- 如果构造时传入空路径，后续初始化会要求调用方先补 [SetShaderPath](SetShaderPath.md)。
+
+## 初始化后状态
+
+构造后对象处于“空缓存”状态：
+
+- `m_device == nullptr`
+- `m_pipelineLayout == nullptr`
+- `m_pipelineState == nullptr`
+- `m_constantPool == nullptr`
+- `m_constantSet == nullptr`
+- `m_builtinInfiniteGridShader` 为空
+- `m_shaderPath` 保留构造函数传入值
+
+## 相关文档
+
+- [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass.md)
+- [SetShaderPath](SetShaderPath.md)
+- [GetShaderPath](GetShaderPath.md)
+- [Render](Render.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Destructor.md b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Destructor.md
new file mode 100644
index 00000000..fbba34fd
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Destructor.md
@@ -0,0 +1,28 @@
+# BuiltinInfiniteGridPass::Destructor
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `destructor`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
+
+## 签名
+
+```cpp
+~BuiltinInfiniteGridPass() = default;
+```
+
+## 作用
+
+销毁 `BuiltinInfiniteGridPass` 对象本身。
+
+## 当前语义
+
+- 当前是默认析构函数，不会自动代替 [Shutdown](Shutdown.md) 释放内部 RHI 资源。
+- 如果这个类被长期持有为 renderer 成员，调用方应在销毁前显式执行 `Shutdown()`。
+- 析构不会清空或验证 `m_shaderPath`；路径只影响后续初始化，而不是对象生命期终结。
+
+## 相关文档
+
+- [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/GetShaderPath.md b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/GetShaderPath.md
new file mode 100644
index 00000000..ff95e2e2
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/GetShaderPath.md
@@ -0,0 +1,28 @@
+# BuiltinInfiniteGridPass::GetShaderPath
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
+
+## 签名
+
+```cpp
+const Containers::String& GetShaderPath() const;
+```
+
+## 作用
+
+返回这个 grid pass 当前记录的 shader 路径。
+
+## 当前语义
+
+- 返回的是内部 `m_shaderPath` 的常量引用。
+- 构造后或调用 [SetShaderPath](SetShaderPath.md) 后，这里反映的就是下一次初始化将使用的路径。
+- 当前值允许为空；空路径本身不是非法状态，但后续资源创建会失败。
+
+## 相关文档
+
+- [SetShaderPath](SetShaderPath.md)
+- [Render](Render.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Render.md b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Render.md
index eeabece4..3d86e809 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Render.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Render.md
@@ -1,5 +1,13 @@
 # BuiltinInfiniteGridPass::Render
 
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
+
+## 签名
+
 ```cpp
 bool Render(
     const RenderContext& renderContext,
@@ -7,26 +15,30 @@ bool Render(
     const InfiniteGridPassData& data);
 ```
 
-## 行为说明
+## 作用
 
-当前实现会：
+把当前无限网格效果绘制到 `surface` 的第一个颜色附件上。
 
-1. 要求 `data.valid`、`renderContext.IsValid()`，且后端必须是 `D3D12`。
-2. 惰性初始化 shader、pipeline layout、pipeline state 和常量 descriptor。
-3. 校验颜色附件与深度附件。
-4. 调用 [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) 生成网格参数。
-5. 构建 view-projection 常量并写入 descriptor set。
+## 当前实现流程
+
+1. 如果 `data.valid == false`、`renderContext` 无效或后端不是 `D3D12`，直接返回 `false`。
+2. 调用 `EnsureInitialized(renderContext)`；如果当前 `shaderPath` 为空，或配置路径下的 shader 无法加载，也会在这里失败。
+3. 检查颜色附件和深度附件，要求 grid pass 具备完整的颜色与深度目标。
+4. 调用 [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) 生成网格参数，并构建 view-projection 常量。
+5. 把常量写入 descriptor set。
 6. 绑定第一个颜色附件和深度附件。
 7. 以全屏三角形方式执行一次 `Draw(3, 1, 0, 0)`。
 
-## 当前限制
+## 关键语义
 
-- 视口与 scissor 总是覆盖整张 surface，不读取 `surface.GetRenderArea()`。
+- 这条路径不再隐式依赖 engine builtin shader；调用方必须先通过构造函数或 [SetShaderPath](SetShaderPath.md) 提供有效 shader 路径。
 - pass 本身不做资源状态切换。
-- 只写第一个颜色附件。
+- viewport 与 scissor 总是覆盖整张 surface，不读取 `surface.GetRenderArea()`。
+- 当前只写第一个颜色附件。
 
 ## 相关文档
 
 - [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass.md)
+- [SetShaderPath](SetShaderPath.md)
 - [InfiniteGridPassData](InfiniteGridPassData.md)
 - [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/SetShaderPath.md b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/SetShaderPath.md
new file mode 100644
index 00000000..464b5a21
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/SetShaderPath.md
@@ -0,0 +1,37 @@
+# BuiltinInfiniteGridPass::SetShaderPath
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
+
+## 签名
+
+```cpp
+void SetShaderPath(const Containers::String& shaderPath);
+```
+
+## 作用
+
+更新这个 grid pass 后续初始化要加载的 shader 路径。
+
+## 当前实现行为
+
+当前实现按下面顺序处理：
+
+1. 如果新旧路径完全相同，直接返回。
+2. 调用 `DestroyResources()`，释放当前缓存的 pipeline、descriptor 和 shader handle。
+3. 把 `m_shaderPath` 更新为传入值。
+
+## 关键语义
+
+- 改路径会立刻丢弃当前已创建的 GPU 资源，等待下一次 [Render](Render.md) 重新初始化。
+- 允许传入空路径；但之后第一次创建资源会因为缺少注入路径而失败。
+- 这个方法只改“后续要加载哪份 shader”，不立即触发加载。
+
+## 相关文档
+
+- [GetShaderPath](GetShaderPath.md)
+- [Render](Render.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Shutdown.md b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Shutdown.md
index 3da5ae39..e10d8d52 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Shutdown.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/Shutdown.md
@@ -1,19 +1,40 @@
 # BuiltinInfiniteGridPass::Shutdown
 
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
+
+## 签名
+
 ```cpp
 void Shutdown();
 ```
 
-## 行为说明
+## 作用
 
-当前实现直接销毁内部缓存的：
+释放这个 grid pass 已创建的内部 GPU 资源和当前配置路径对应的 shader handle。
 
-- pipeline state
-- 常量 descriptor pool / set
-- pipeline layout
-- builtin infinite-grid shader handle
+## 当前实现行为
+
+当前实现直接调用 `DestroyResources()`，并按顺序销毁：
+
+1. `m_pipelineState`
+2. `m_constantSet`
+3. `m_constantPool`
+4. `m_pipelineLayout`
+5. `m_builtinInfiniteGridShader`
+6. `m_device` / `m_backendType` 等缓存状态
+
+## 关键语义
+
+- 对尚未初始化过的对象调用 `Shutdown()` 是安全的。
+- `Shutdown()` 不会清空 `m_shaderPath`；后续仍可重新 [Render](Render.md) 并按当前路径懒创建资源。
+- 默认析构函数不会自动代替它执行清理。
 
 ## 相关文档
 
 - [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass.md)
+- [Destructor](Destructor.md)
 - [Render](Render.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md
index a341dc91..ee858a49 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md
@@ -6,7 +6,7 @@
 
 **头文件**: `XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h`
 
-**描述**: 内建的全屏后处理 pass，读取 object-id 纹理并把选中对象轮廓或调试 selection mask 合成到当前颜色目标。
+**描述**: 内建的全屏后处理 pass，读取 object-id 纹理并把选中对象轮廓或调试 selection mask 合成到当前颜色目标；真正使用哪份 shader 由调用方通过 `shaderPath` 注入。
 
 ## 概览
 
@@ -18,6 +18,16 @@
 
 因此它更接近一个“builtin selection feedback compositor”，而不是一个通用 post-process 框架。
 
+和早期实现不同，当前类已经不再把 outline shader 写死为 engine builtin 资源。源码里的职责边界是：
+
+- `BuiltinObjectIdOutlinePass`
+  只负责资源创建、object-id 采样、常量编码和一次全屏三角形执行。
+- editor 调用方
+  通过 [SetShaderPath](SetShaderPath.md) 或构造函数参数注入具体 shader 路径。
+- `SceneViewportSelectionOutlinePass`
+  当前用 [SceneViewportShaderPaths](../../../Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md)
+  生成 editor-owned object-id outline shader 路径，再交给这里执行。
+
 ## 输入与输出契约
 
 | 输入 / 输出 | 当前要求 |
@@ -31,10 +41,10 @@
 
 ## 当前渲染算法
 
-按 `BuiltinObjectIdOutlinePass.cpp` 与 builtin shader 的当前实现，流程是：
+按 `BuiltinObjectIdOutlinePass.cpp` 与当前配置 shader 的实现，流程是：
 
 1. 校验上下文、后端、object-id SRV 和选中对象列表。
-2. 懒初始化内部资源，必要时重新创建 pipeline layout、pipeline state 和两个 descriptor set。
+2. 懒初始化内部资源，必要时重新创建 pipeline layout、pipeline state 和两个 descriptor set；这一步要求 `shaderPath` 非空且可成功加载。
 3. 从 `surface.GetWidth()` / `GetHeight()` 计算视口尺寸与 texel size。
 4. 用 `EncodeObjectIdToColor()` 把选中对象 ID 编码进常量缓冲，最多写入 `kMaxSelectedObjectCount = 256` 项。
 5. 绑定一个 CBV set 和一个 SRV set，设置目标为 `surface` 的第一个颜色附件。
@@ -43,6 +53,7 @@
 ## 生命周期
 
 - [Constructor](Constructor.md) 只做状态清零，不会立刻创建 GPU 资源。
+- [SetShaderPath](SetShaderPath.md) 更新路径时，会立刻销毁当前缓存的 RHI 资源，等待下一次 `Render()` 重新初始化。
 - 第一次 [Render](Render.md) 成功进入初始化路径时，才会真正创建 descriptor 和 PSO。
 - [Shutdown](Shutdown.md) 会显式销毁所有内部缓存对象。
 - [Destructor](Destructor.md) 当前是默认析构，因此如果把它作为长期 renderer 成员使用，调用方仍需在销毁前显式执行 `Shutdown()`。
@@ -50,6 +61,7 @@
 ## 当前实现边界
 
 - 只接受 `D3D12`，其它后端直接返回 `false`。
+- 在第一次创建资源前必须先提供有效 `shaderPath`；空路径会记录错误并返回 `false`。
 - 不处理资源状态切换，也不负责清屏；这些由调用方保证。
 - 当前完全忽略 `surface.GetRenderArea()`，viewport 和 scissor 都直接取整张 surface 的宽高。
 - 只使用第一个颜色附件；多 render target 场景不会同步写其它附件。
@@ -58,14 +70,17 @@
 
 | 方法 | 说明 |
 |------|------|
-| [Constructor](Constructor.md) | 创建一个空的 outline pass 对象。 |
+| [Constructor](Constructor.md) | 创建一个 outline pass 对象，并可选地预置 shader 路径。 |
 | [Destructor](Destructor.md) | 默认析构；不会自动释放内部 RHI 资源。 |
+| [SetShaderPath](SetShaderPath.md) | 更新当前要加载的 shader 路径，并清空已创建资源。 |
+| [GetShaderPath](GetShaderPath.md) | 返回当前记录的 shader 路径。 |
 | [Shutdown](Shutdown.md) | 销毁已创建的 pipeline、descriptor 和 shader handle。 |
 | [Render](Render.md) | 读取 object-id SRV，并把轮廓或 debug mask 写入颜色目标。 |
 
 ## 真实使用位置
 
-- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` 用 `SceneViewportSelectionOutlinePassRenderer` 包装它。
+- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` 用 `SceneViewportSelectionOutlinePassRenderer` 包装它，
+  并通过 `GetSceneViewportObjectIdOutlineShaderPath()` 注入 editor-owned shader 路径。
 - [SceneViewportRenderPlan](../../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) 决定当前帧是否要创建 selection outline pass。
 - [CameraRenderer](../../CameraRenderer/CameraRenderer.md) 在主场景与 object-id pass 之后执行这些 `postScenePasses`。
 - `editor/src/Viewport/ViewportHostRenderFlowUtils.h` 当前为 Scene View 组装默认橙色、`2px` 的 outline style。
@@ -73,6 +88,9 @@
 ## 相关文档
 
 - [Passes](../Passes.md)
+- [SetShaderPath](SetShaderPath.md)
+- [GetShaderPath](GetShaderPath.md)
 - [ObjectIdOutlineStyle](../ObjectIdOutlineStyle/ObjectIdOutlineStyle.md)
 - [CameraRenderer](../../CameraRenderer/CameraRenderer.md)
 - [RenderSurface](../../RenderSurface/RenderSurface.md)
+- [SceneViewportShaderPaths](../../../Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Constructor.md b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Constructor.md
index c2636dc9..bef49838 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Constructor.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Constructor.md
@@ -9,16 +9,16 @@
 ## 签名
 
 ```cpp
-BuiltinObjectIdOutlinePass();
+BuiltinObjectIdOutlinePass(Containers::String shaderPath = Containers::String());
 ```
 
 ## 作用
 
-创建一个尚未分配 GPU 资源的 outline pass 对象。
+创建一个尚未分配 GPU 资源的 outline pass 对象，并可选地预置 shader 路径。
 
 ## 当前实现行为
 
-当前构造函数只做一件事：
+当前构造函数会先把传入路径存进 `m_shaderPath`，再调用：
 
 ```cpp
 ResetState();
@@ -26,9 +26,10 @@ ResetState();
 
 这意味着：
 
-- 不会在构造阶段加载 builtin shader。
+- 不会在构造阶段加载 shader。
 - 不会提前创建 pipeline layout、pipeline state 或 descriptor set。
 - 所有真实的 GPU 资源准备都延迟到第一次 [Render](Render.md) 成功进入初始化路径时完成。
+- 如果构造时传入空路径，后续初始化会要求调用方先补 [SetShaderPath](SetShaderPath.md)。
 
 ## 初始化后状态
 
@@ -42,9 +43,12 @@ ResetState();
 - `m_texturePool == nullptr`
 - `m_textureSet == nullptr`
 - `m_builtinObjectIdOutlineShader` 为空
+- `m_shaderPath` 保留构造函数传入值
 
 ## 相关文档
 
 - [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass.md)
+- [SetShaderPath](SetShaderPath.md)
+- [GetShaderPath](GetShaderPath.md)
 - [Render](Render.md)
 - [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/GetShaderPath.md b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/GetShaderPath.md
new file mode 100644
index 00000000..2a0bc4e4
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/GetShaderPath.md
@@ -0,0 +1,28 @@
+# BuiltinObjectIdOutlinePass::GetShaderPath
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h`
+
+## 签名
+
+```cpp
+const Containers::String& GetShaderPath() const;
+```
+
+## 作用
+
+返回这个 outline pass 当前记录的 shader 路径。
+
+## 当前语义
+
+- 返回的是内部 `m_shaderPath` 的常量引用。
+- 构造后或调用 [SetShaderPath](SetShaderPath.md) 后，这里反映的就是下一次初始化将使用的路径。
+- 当前值允许为空；空路径本身不是非法状态，但后续资源创建会失败。
+
+## 相关文档
+
+- [SetShaderPath](SetShaderPath.md)
+- [Render](Render.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Render.md b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Render.md
index 0fa72d8a..60df1462 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Render.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Render.md
@@ -24,7 +24,7 @@ bool Render(
 ## 当前实现流程
 
 1. 如果 `renderContext` 无效、后端不是 `D3D12`、`objectIdTextureView == nullptr` 或 `selectedObjectIds` 为空，直接返回 `false`。
-2. 调用 `EnsureInitialized(renderContext)`；如果当前 device/backend 变化，会先销毁旧资源再重建。
+2. 调用 `EnsureInitialized(renderContext)`；如果当前 device/backend 变化，会先销毁旧资源再重建。若 `shaderPath` 为空或配置路径下的 shader 无法加载，也会在这里失败。
 3. 检查 `surface.GetColorAttachments()`，要求至少存在一个有效颜色附件。
 4. 构建 `OutlineConstants`，写入 viewport 尺寸、轮廓颜色、调试开关、像素宽度和最多 `256` 个选中对象编码颜色。
 5. 把常量缓冲写到 `m_constantSet`，把 `objectIdTextureView` 绑定到 `m_textureSet`。
@@ -32,6 +32,7 @@ bool Render(
 
 ## 关键语义
 
+- 这条路径不再隐式依赖 engine builtin outline shader；调用方必须先通过构造函数或 [SetShaderPath](SetShaderPath.md) 提供有效路径。
 - 当前只使用 `surface` 的第一个颜色附件。
 - pass 自己不会做 render target 清空；如果要输出 debug mask 这种“整张替换”的结果，需要由调用方先清空目标。
 - pass 自己也不负责资源状态切换；调用前应保证颜色目标已经在 `RenderTarget` 状态、object-id SRV 已经可读。
@@ -45,5 +46,6 @@ bool Render(
 ## 相关文档
 
 - [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass.md)
+- [SetShaderPath](SetShaderPath.md)
 - [ObjectIdOutlineStyle](../ObjectIdOutlineStyle/ObjectIdOutlineStyle.md)
 - [RenderSurface](../../RenderSurface/RenderSurface.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/SetShaderPath.md b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/SetShaderPath.md
new file mode 100644
index 00000000..fc47faea
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/SetShaderPath.md
@@ -0,0 +1,37 @@
+# BuiltinObjectIdOutlinePass::SetShaderPath
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h`
+
+## 签名
+
+```cpp
+void SetShaderPath(const Containers::String& shaderPath);
+```
+
+## 作用
+
+更新这个 outline pass 后续初始化要加载的 shader 路径。
+
+## 当前实现行为
+
+当前实现按下面顺序处理：
+
+1. 如果新旧路径完全相同，直接返回。
+2. 调用 `DestroyResources()`，释放当前缓存的 pipeline、descriptor 和 shader handle。
+3. 把 `m_shaderPath` 更新为传入值。
+
+## 关键语义
+
+- 改路径会立刻清空当前资源缓存，等待下一次 [Render](Render.md) 按新路径重新初始化。
+- 允许传入空路径；但之后第一次创建资源会因为缺少注入路径而失败。
+- 这个方法只更新“将要加载的路径”，不立即创建任何 GPU 资源。
+
+## 相关文档
+
+- [GetShaderPath](GetShaderPath.md)
+- [Render](Render.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Shutdown.md b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Shutdown.md
index fddb93f1..d2a9f200 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Shutdown.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Shutdown.md
@@ -14,7 +14,7 @@ void Shutdown();
 
 ## 作用
 
-释放这个 outline pass 已经创建的所有内部 GPU 资源和 shader handle。
+释放这个 outline pass 已经创建的所有内部 GPU 资源和当前配置路径对应的 shader handle。
 
 ## 当前实现行为
 
diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md
index 005d363d..09d522d0 100644
--- a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md
+++ b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md
@@ -54,7 +54,7 @@
 ## 真实使用位置
 
 - `CameraRenderer::Render()` 在主场景渲染后、`postScenePasses` 与 `overlayPasses` 前调用 `m_objectIdPass->Render(...)`。
-- `tests/editor/test_viewport_render_flow_utils.cpp` 验证了 scene viewport 会为 `CameraRenderRequest::objectId` 正确挂接颜色/深度附件，并在 render plan 侧单独处理 object-id shader view。
+- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 scene viewport 会为 `CameraRenderRequest::objectId` 正确挂接颜色/深度附件，并在 render plan 侧单独处理 object-id shader view。
 - `tests/Resources/Shader/test_shader_loader.cpp` 验证了 builtin object-id shader 的 pass tag 和多后端 variant 是否存在。
 
 ## 相关文档
diff --git a/docs/api/XCEngine/Rendering/Passes/Passes.md b/docs/api/XCEngine/Rendering/Passes/Passes.md
index f6922cea..a35a7d5f 100644
--- a/docs/api/XCEngine/Rendering/Passes/Passes.md
+++ b/docs/api/XCEngine/Rendering/Passes/Passes.md
@@ -40,8 +40,8 @@
 ## 测试与真实调用点
 
 - `tests/Rendering/unit/test_camera_scene_renderer.cpp` 验证了 `CameraRenderer` 中 object-id pass 与可选 pass sequence 的接入时机。
-- `tests/editor/test_scene_viewport_overlay_renderer.cpp` 固定了 `BuildInfiniteGridParameters(...)` 的十进制尺度、过渡和淡出语义。
-- `tests/editor/test_viewport_render_flow_utils.cpp` 验证了 Scene View render plan 如何组装 grid / selection outline / overlay pass，以及 object-id SRV 缺失时的警告路径。
+- `tests/Editor/test_scene_viewport_overlay_renderer.cpp` 固定了 `BuildInfiniteGridParameters(...)` 的十进制尺度、过渡和淡出语义。
+- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 Scene View render plan 如何组装 grid / selection outline / overlay pass，以及 object-id SRV 缺失时的警告路径。
 
 ## 当前实现边界