docs(api): align selection outline pass docs

docs/api/XCEngine/Editor/Viewport/Passes/Passes.md

@@ -8,14 +8,14 @@
 
 **描述**: Scene View 专用 GPU pass 子模块，负责把 editor-owned 的网格、选中轮廓和世界 overlay 注入场景渲染请求。
 
-## 概述
+## 概览
 
 这个子目录当前包含三类 Scene View 专用 pass：
 
 - [SceneViewportGridPass](SceneViewportGridPass/SceneViewportGridPass.md)
   - Editor 自己拥有的 post-scene 网格 pass，内部包装 [BuiltinInfiniteGridPass](../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md)。
 - [SceneViewportSelectionOutlinePass](SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md)
-  - Editor 自己拥有的 post-scene 选中轮廓 pass，内部包装 [BuiltinObjectIdOutlinePass](../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)。
+  - Editor 自己拥有的 post-scene 选中轮廓 pass，内部串联 [BuiltinSelectionMaskPass](../../../Rendering/Passes/BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md) 与 [BuiltinSelectionOutlinePass](../../../Rendering/Passes/BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)。
 - [SceneViewportEditorOverlayPass](SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md)
   - Scene View 世界 overlay pass，负责画世界线段、图标 sprite 和屏幕三角形批次。
 

docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md

@@ -11,45 +11,46 @@
 ```cpp
 std::unique_ptr<Rendering::RenderPass> CreateSceneViewportSelectionOutlinePass(
     SceneViewportSelectionOutlinePassRenderer& renderer,
-    RHI::RHIResourceView* objectIdTextureView,
+    ViewportRenderTargets* targets,
     const std::vector<uint64_t>& selectedObjectIds,
     const SceneViewportSelectionOutlineStyle& style);
 ```
 
 ## 作用
 
-创建一个本帧使用的 Scene View 选中轮廓 `RenderPass`，把 object-id 纹理、选中对象列表和样式绑定到给定 renderer。
+创建一个本帧使用的 Scene View 选中轮廓 `RenderPass`，把 viewport render targets、选中对象列表和样式绑定到给定 renderer。
 
 ## 当前实现行为
 
 当前工厂函数返回内部类 `SceneViewportSelectionOutlinePass` 的实例。这个 pass：
 
 - 持有对 `renderer` 的引用
-- 保存 `objectIdTextureView` 指针
+- 保存 `ViewportRenderTargets*`
 - 按值复制 `selectedObjectIds`
 - 按值复制 `style`
 - `GetName()` 固定返回 `"SceneViewportSelectionOutline"`
-- `Execute(...)` 时调用 `renderer.Render(...)`
+- `Execute(...)` 时调用 `renderer.Render(context.renderContext, context.surface, context.sceneData, *m_targets, m_selectedObjectIds, m_style)`
 
 ## 所有权与生命周期
 
-- 返回值拥有 pass 对象本身
+- 返回值拥有 pass 对象本身。
-- `renderer` 不被 pass 拥有，必须在 pass 执行期间保持有效
+- `renderer` 不被 pass 拥有，必须在 pass 执行期间保持有效。
-- `objectIdTextureView` 只是借用指针，不会被 pass 接管所有权
+- `targets` 只是借用指针，不会被 pass 接管所有权。
-- `selectedObjectIds` 与 `style` 会复制进 pass 内部，因此可以跨过当前调用栈延后执行
+- `selectedObjectIds` 与 `style` 会复制进 pass 内部，因此可以跨过当前调用栈延后执行。
 
 ## 当前使用位置
 
 典型调用路径是：
 
-1. [BuildSceneViewportRenderPlan](../../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 检查 `selectedObjectIds` 非空
+1. [BuildSceneViewportRenderPlan](../../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 检查 `selectedObjectIds` 非空。
-2. 要求 `targets.objectIdShaderView` 可用，并用 `BuildSceneViewportSelectionOutlineStyle(...)` 生成样式
+2. 要求 selection-outline 相关 render targets 齐备，并用 `BuildSceneViewportSelectionOutlineStyle(...)` 生成样式。
-3. 通过这个工厂把结果加入 `plan.postScenePasses`
+3. 通过这个工厂把结果加入 `plan.postScenePasses`。
 
 ## 相关文档
 
 - [SceneViewportSelectionOutlinePass](SceneViewportSelectionOutlinePass.md)
 - [Render](Render.md)
 - [Shutdown](Shutdown.md)
+- [ViewportHostRenderTargets](../../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
 - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
 - [SceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md)

docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Render.md

@@ -12,43 +12,47 @@
 bool Render(
     const Rendering::RenderContext& renderContext,
     const Rendering::RenderSurface& surface,
-    RHI::RHIResourceView* objectIdTextureView,
+    const Rendering::RenderSceneData& sceneData,
+    ViewportRenderTargets& targets,
     const std::vector<uint64_t>& selectedObjectIds,
     const SceneViewportSelectionOutlineStyle& style);
 ```
 
 ## 作用
 
-执行 Scene View 的选中轮廓绘制，把 object-id 纹理、选中对象列表和 editor 侧轮廓样式转交给底层 outline pass。
+执行 Scene View 的选中轮廓绘制，先重绘 selection mask，再把 editor 侧轮廓样式转交给 fullscreen outline pass。
 
 ## 当前实现行为
 
-当前实现没有额外包装逻辑，直接调用：
+当前实现分两段执行：
 
-```cpp
+1. 通过 `BuildViewportSelectionMaskSurface(targets)` 构建 selection-mask surface，并把 render area 对齐到主 surface。
-return m_outlinePass.Render(
+2. 调用 `m_selectionMaskPass.Render(renderContext, selectionMaskSurface, sceneData, selectedObjectIds)`，只重绘当前选中对象。
-    renderContext,
+3. 若 mask pass 成功，把 `targets.selectionMaskState` 更新为 `RHI::ResourceStates::PixelShaderResource`。
-    surface,
+4. 调用 `m_outlinePass.Render(...)`，输入为：
-    objectIdTextureView,
+   - `targets.selectionMaskShaderView`
-    selectedObjectIds,
+   - `targets.selectionMaskState`
-    ToBuiltinSceneViewportSelectionOutlineStyle(style));
+   - `targets.depthShaderView`
-```
+   - `surface.GetDepthStateAfter()`
+   - `ToBuiltinSceneViewportSelectionOutlineStyle(style)`
 
 因此：
 
-- Editor 层不会在这里重新编码 object-id，但会在最后一步把 editor wrapper 样式转换成 runtime outline 样式
+- Editor 层不会在这里重新绘制 fullscreen outline 算法本体，但会负责串联 mask surface、depth 纹理和样式转换。
-- 资源初始化、shader 选择、绘制与失败条件都由 [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) 决定
+- 真正的 GPU 工作分别落在 [BuiltinSelectionMaskPass](../../../../Rendering/Passes/BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md) 与 [BuiltinSelectionOutlinePass](../../../../Rendering/Passes/BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)。
 
 ## 返回值语义
 
-- 底层 outline pass 执行成功时返回 `true`
+- 只有 mask 重绘和 outline 合成都成功时才返回 `true`。
-- 当 object-id 视图、上下文或后端条件不满足时，可能返回 `false`
+- 当 selection render target、depth 视图、上下文或底层 pass 条件不满足时，会返回 `false`。
 
 ## 相关文档
 
 - [SceneViewportSelectionOutlinePass](SceneViewportSelectionOutlinePass.md)
 - [Shutdown](Shutdown.md)
 - [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md)
+- [ViewportHostRenderTargets](../../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
 - [SceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md)
 - [ToBuiltinSceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md)
-- [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)
+- [BuiltinSelectionMaskPass](../../../../Rendering/Passes/BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md)
+- [BuiltinSelectionOutlinePass](../../../../Rendering/Passes/BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)

docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md

@@ -6,56 +6,63 @@
 
 **源文件**: `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.h`
 
-**描述**: Scene View 选中轮廓的 Editor 侧 `RenderPass` 适配层，把基于 object-id 的 outline 绘制接入 viewport 的 `postScenePasses`。
+**描述**: Scene View 选中轮廓的 Editor 侧 `RenderPass` 适配层，把“selection-mask 重绘 + fullscreen outline 合成”接入 viewport 的 `postScenePasses`。
+
 ## 概览
 
-`SceneViewportSelectionOutlinePass.h` 同样不是轮廓算法本体，而是对 [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) 的 Editor 封装：
+`SceneViewportSelectionOutlinePass.h` 当前提供两个入口：
 
 - `SceneViewportSelectionOutlinePassRenderer`
+  - 长生命周期 renderer，内部持有 `BuiltinSelectionMaskPass` 与 `BuiltinSelectionOutlinePass`
 - `CreateSceneViewportSelectionOutlinePass(...)`
+  - 构建当前帧使用的 `RenderPass`，把 `ViewportRenderTargets`、选中对象列表和样式绑定到 renderer
 
-它让 [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 可以把：
+与旧版 object-id outline 方案不同，当前链路不再直接把 `objectIdTextureView` 交给 runtime outline pass；它会先为当前选中对象生成 `selection mask`，再以 `selectionMask + depth` 做 fullscreen compositing。
-
-- `objectIdTextureView`
-- `selectedObjectIds`
-- `SceneViewportSelectionOutlineStyle`
-
-组装成一个标准 `RenderPass`，随后插到 Scene View 的主场景绘制之后执行。
 
 ## 当前实现行为
 
 按 `SceneViewportSelectionOutlinePass.cpp` 的当前实现：
 
-- renderer 内部只持有一个 `BuiltinObjectIdOutlinePass m_outlinePass`
+- renderer 内部持有：
-- [Render](Render.md) 会把 `SceneViewportSelectionOutlineStyle` 转成 runtime `ObjectIdOutlineStyle` 后，再转发给 `BuiltinObjectIdOutlinePass`
+  - `BuiltinSelectionMaskPass m_selectionMaskPass`
-- [Shutdown](Shutdown.md) 只调用 `m_outlinePass.Shutdown()`
+  - `BuiltinSelectionOutlinePass m_outlinePass`
-- [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md) 会创建内部 `SceneViewportSelectionOutlinePass`：
+- [Render](Render.md) 会先用 `BuildViewportSelectionMaskSurface(targets)` 构建 selection-mask surface，并把 render area 对齐到主 surface。
+- 然后调用 `m_selectionMaskPass.Render(...)`，只重绘 `selectedObjectIds` 对应的可见对象。
+- 若 mask pass 成功，会把 `targets.selectionMaskState` 切换为 `PixelShaderResource`。
+- 最后调用 `m_outlinePass.Render(...)`，输入为：
+  - `targets.selectionMaskShaderView`
+  - `targets.selectionMaskState`
+  - `targets.depthShaderView`
+  - `surface.GetDepthStateAfter()`
+  - `ToBuiltinSceneViewportSelectionOutlineStyle(style)`
+- [Shutdown](Shutdown.md) 会同时关闭 `m_selectionMaskPass` 与 `m_outlinePass`。
+- [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md) 会创建内部 `SceneViewportSelectionOutlinePass`，它：
   - 持有对 `renderer` 的引用
-  - 保存 `objectIdTextureView` 指针
+  - 保存 `ViewportRenderTargets*`
   - 按值保存 `selectedObjectIds` 与 `style`
   - `GetName()` 固定返回 `"SceneViewportSelectionOutline"`
 
 ## 当前使用位置
 
-- [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 的 `SceneViewportSelectionOutlinePassFactory` 会在“有选中对象且 `objectIdShaderView` 可用”时创建这个 pass
+- [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 会在 Scene View 存在选中对象且 render targets 齐备时创建这条链路。
-- [SceneViewportRenderPassBundle](../../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) 当前把该 factory 绑定到 `CreateSceneViewportSelectionOutlinePass(m_selectionOutlineRenderer, ...)`，再由 [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 通过 bundle 调用
+- [SceneViewportRenderPassBundle](../../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) 当前把该 factory 绑定到 `CreateSceneViewportSelectionOutlinePass(m_selectionOutlineRenderer, ...)`，再由 [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 通过 bundle 调用。
 - `tests/Editor/test_viewport_render_flow_utils.cpp` 覆盖了：
   - 选中对象存在时 factory 被调用
   - `outlineWidthPixels == 2.0f`
-  - object-id 纹理缺失时返回警告文案
+  - 相关 render target 不完整时返回警告文案
 
 ## 设计含义
 
 这样拆层的好处是：
 
-- object-id 轮廓的真正 GPU 实现仍留在 Rendering 模块
+- mask 重绘与 fullscreen outline 的真正 GPU 实现仍留在 Rendering 模块。
-- Editor 侧只负责把 Scene View 的 object-id 纹理和选中列表接到正确的 pass 序列
+- Editor 侧只负责把 Scene View 的 render targets、选中列表和样式转换接到正确的 pass 序列。
-- `SceneViewportRenderPlan` 可以统一控制 grid、selection-outline 与 overlay 三条附加渲染链路
+- `SceneViewportRenderPlan` 可以统一控制 grid、selection-outline 与 overlay 三条附加渲染链路。
 
 ## 当前限制
 
-- 返回的 pass 不拥有 `renderer`，也不拥有 `objectIdTextureView` 指向的资源
+- 返回的 pass 不拥有 `renderer`，也不拥有 `ViewportRenderTargets` 指向的资源。
-- 选中轮廓能否成功执行，仍取决于 `objectIdTextureView` 生命周期与底层 `BuiltinObjectIdOutlinePass` 的约束
+- 选中轮廓能否成功执行，取决于 `selectionMaskShaderView`、`depthShaderView`、mask render target 和主 surface 状态是否齐备。
 
 ## 相关文档
 
@@ -65,6 +72,8 @@
 - [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md)
 - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
 - [SceneViewportRenderPassBundle](../../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md)
-- [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)
+- [ViewportHostRenderTargets](../../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
+- [BuiltinSelectionMaskPass](../../../../Rendering/Passes/BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md)
+- [BuiltinSelectionOutlinePass](../../../../Rendering/Passes/BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)
 - [SceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md)
 - [ToBuiltinSceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md)

docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Shutdown.md

@@ -14,26 +14,28 @@ void Shutdown();
 
 ## 作用
 
-释放 `SceneViewportSelectionOutlinePassRenderer` 内部持有的底层 outline pass 资源。
+释放 `SceneViewportSelectionOutlinePassRenderer` 内部持有的 selection-mask 与 outline pass 资源。
 
 ## 当前实现行为
 
-当前实现只有一行：
+当前实现会顺序关闭两段 runtime pass：
 
 ```cpp
+m_selectionMaskPass.Shutdown();
 m_outlinePass.Shutdown();
 ```
 
-这说明 `SceneViewportSelectionOutlinePassRenderer` 自己并不维护额外的 editor-only GPU 状态；生命周期管理完全委托给 `BuiltinObjectIdOutlinePass`。
+这说明 `SceneViewportSelectionOutlinePassRenderer` 自己并不维护额外的 editor-only GPU 状态；生命周期管理完全委托给底层两个 builtin pass。
 
 ## 使用时机
 
-- [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 在整体 shutdown 路径中调用它
+- [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 在整体 shutdown 路径中调用它。
-- 不需要每帧调用；它属于 Scene View renderer 的长期资源回收步骤
+- 不需要每帧调用；它属于 Scene View renderer 的长期资源回收步骤。
 
 ## 相关文档
 
 - [SceneViewportSelectionOutlinePass](SceneViewportSelectionOutlinePass.md)
 - [Render](Render.md)
 - [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md)
-- [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)
+- [BuiltinSelectionMaskPass](../../../../Rendering/Passes/BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md)
+- [BuiltinSelectionOutlinePass](../../../../Rendering/Passes/BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)