From 3ed69aa82fc02aac3ed036d0de3c8a30039a1c6a Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 10 Apr 2026 00:00:41 +0800 Subject: [PATCH] docs(api): align selection outline pass docs --- .../XCEngine/Editor/Viewport/Passes/Passes.md | 4 +- ...CreateSceneViewportSelectionOutlinePass.md | 23 ++++---- .../Render.md | 36 ++++++------ .../SceneViewportSelectionOutlinePass.md | 55 +++++++++++-------- .../Shutdown.md | 14 +++-- 5 files changed, 74 insertions(+), 58 deletions(-) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/Passes.md b/docs/api/XCEngine/Editor/Viewport/Passes/Passes.md index 7987dcc9..00f49e5c 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/Passes.md +++ b/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 和屏幕三角形批次。 diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md index a67c7521..662de517 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md @@ -11,45 +11,46 @@ ```cpp std::unique_ptr CreateSceneViewportSelectionOutlinePass( SceneViewportSelectionOutlinePassRenderer& renderer, - RHI::RHIResourceView* objectIdTextureView, + ViewportRenderTargets* targets, const std::vector& 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 对象本身 -- `renderer` 不被 pass 拥有，必须在 pass 执行期间保持有效 -- `objectIdTextureView` 只是借用指针，不会被 pass 接管所有权 -- `selectedObjectIds` 与 `style` 会复制进 pass 内部，因此可以跨过当前调用栈延后执行 +- 返回值拥有 pass 对象本身。 +- `renderer` 不被 pass 拥有，必须在 pass 执行期间保持有效。 +- `targets` 只是借用指针，不会被 pass 接管所有权。 +- `selectedObjectIds` 与 `style` 会复制进 pass 内部，因此可以跨过当前调用栈延后执行。 ## 当前使用位置 典型调用路径是： -1. [BuildSceneViewportRenderPlan](../../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 检查 `selectedObjectIds` 非空 -2. 要求 `targets.objectIdShaderView` 可用，并用 `BuildSceneViewportSelectionOutlineStyle(...)` 生成样式 -3. 通过这个工厂把结果加入 `plan.postScenePasses` +1. [BuildSceneViewportRenderPlan](../../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 检查 `selectedObjectIds` 非空。 +2. 要求 selection-outline 相关 render targets 齐备，并用 `BuildSceneViewportSelectionOutlineStyle(...)` 生成样式。 +3. 通过这个工厂把结果加入 `plan.postScenePasses`。 ## 相关文档 - [SceneViewportSelectionOutlinePass](SceneViewportSelectionOutlinePass.md) - [Render](Render.md) - [Shutdown](Shutdown.md) +- [ViewportHostRenderTargets](../../ViewportHostRenderTargets/ViewportHostRenderTargets.md) - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) - [SceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Render.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Render.md index f5692610..4380e307 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Render.md +++ b/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& selectedObjectIds, const SceneViewportSelectionOutlineStyle& style); ``` ## 作用 -执行 Scene View 的选中轮廓绘制，把 object-id 纹理、选中对象列表和 editor 侧轮廓样式转交给底层 outline pass。 +执行 Scene View 的选中轮廓绘制，先重绘 selection mask，再把 editor 侧轮廓样式转交给 fullscreen outline pass。 ## 当前实现行为 -当前实现没有额外包装逻辑，直接调用： +当前实现分两段执行： -```cpp -return m_outlinePass.Render( - renderContext, - surface, - objectIdTextureView, - selectedObjectIds, - ToBuiltinSceneViewportSelectionOutlineStyle(style)); -``` +1. 通过 `BuildViewportSelectionMaskSurface(targets)` 构建 selection-mask surface，并把 render area 对齐到主 surface。 +2. 调用 `m_selectionMaskPass.Render(renderContext, selectionMaskSurface, sceneData, selectedObjectIds)`，只重绘当前选中对象。 +3. 若 mask pass 成功，把 `targets.selectionMaskState` 更新为 `RHI::ResourceStates::PixelShaderResource`。 +4. 调用 `m_outlinePass.Render(...)`，输入为： + - `targets.selectionMaskShaderView` + - `targets.selectionMaskState` + - `targets.depthShaderView` + - `surface.GetDepthStateAfter()` + - `ToBuiltinSceneViewportSelectionOutlineStyle(style)` 因此： -- Editor 层不会在这里重新编码 object-id，但会在最后一步把 editor wrapper 样式转换成 runtime outline 样式 -- 资源初始化、shader 选择、绘制与失败条件都由 [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) 决定 +- Editor 层不会在这里重新绘制 fullscreen outline 算法本体，但会负责串联 mask surface、depth 纹理和样式转换。 +- 真正的 GPU 工作分别落在 [BuiltinSelectionMaskPass](../../../../Rendering/Passes/BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md) 与 [BuiltinSelectionOutlinePass](../../../../Rendering/Passes/BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)。 ## 返回值语义 -- 底层 outline pass 执行成功时返回 `true` -- 当 object-id 视图、上下文或后端条件不满足时，可能返回 `false` +- 只有 mask 重绘和 outline 合成都成功时才返回 `true`。 +- 当 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) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md index c52a22bc..9b0fc200 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md +++ b/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) 可以把： - -- `objectIdTextureView` -- `selectedObjectIds` -- `SceneViewportSelectionOutlineStyle` - -组装成一个标准 `RenderPass`，随后插到 Scene View 的主场景绘制之后执行。 +与旧版 object-id outline 方案不同，当前链路不再直接把 `objectIdTextureView` 交给 runtime outline pass；它会先为当前选中对象生成 `selection mask`，再以 `selectionMask + depth` 做 fullscreen compositing。 ## 当前实现行为 按 `SceneViewportSelectionOutlinePass.cpp` 的当前实现： -- renderer 内部只持有一个 `BuiltinObjectIdOutlinePass m_outlinePass` -- [Render](Render.md) 会把 `SceneViewportSelectionOutlineStyle` 转成 runtime `ObjectIdOutlineStyle` 后，再转发给 `BuiltinObjectIdOutlinePass` -- [Shutdown](Shutdown.md) 只调用 `m_outlinePass.Shutdown()` -- [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md) 会创建内部 `SceneViewportSelectionOutlinePass`： +- renderer 内部持有： + - `BuiltinSelectionMaskPass m_selectionMaskPass` + - `BuiltinSelectionOutlinePass m_outlinePass` +- [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 -- [SceneViewportRenderPassBundle](../../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) 当前把该 factory 绑定到 `CreateSceneViewportSelectionOutlinePass(m_selectionOutlineRenderer, ...)`，再由 [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 通过 bundle 调用 +- [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 会在 Scene View 存在选中对象且 render targets 齐备时创建这条链路。 +- [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 模块 -- Editor 侧只负责把 Scene View 的 object-id 纹理和选中列表接到正确的 pass 序列 -- `SceneViewportRenderPlan` 可以统一控制 grid、selection-outline 与 overlay 三条附加渲染链路 +- mask 重绘与 fullscreen outline 的真正 GPU 实现仍留在 Rendering 模块。 +- Editor 侧只负责把 Scene View 的 render targets、选中列表和样式转换接到正确的 pass 序列。 +- `SceneViewportRenderPlan` 可以统一控制 grid、selection-outline 与 overlay 三条附加渲染链路。 ## 当前限制 -- 返回的 pass 不拥有 `renderer`，也不拥有 `objectIdTextureView` 指向的资源 -- 选中轮廓能否成功执行，仍取决于 `objectIdTextureView` 生命周期与底层 `BuiltinObjectIdOutlinePass` 的约束 +- 返回的 pass 不拥有 `renderer`，也不拥有 `ViewportRenderTargets` 指向的资源。 +- 选中轮廓能否成功执行，取决于 `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) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Shutdown.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Shutdown.md index b158c253..ea3c6891 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Shutdown.md +++ b/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 路径中调用它 -- 不需要每帧调用；它属于 Scene View renderer 的长期资源回收步骤 +- [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 在整体 shutdown 路径中调用它。 +- 不需要每帧调用；它属于 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)