docs: add viewport host render helper docs

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ApplySceneViewportRenderRequestSetup.md

@@ -0,0 +1,84 @@
+# ApplySceneViewportRenderRequestSetup
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+void ApplySceneViewportRenderRequestSetup(
+    const ViewportRenderTargets& targets,
+    Rendering::RenderPassSequence* postPasses,
+    Rendering::CameraRenderRequest& request);
+```
+
+## 作用
+
+把 Scene View 这一帧最基础的附加渲染设置写回 [CameraRenderRequest](../../../Rendering/CameraRenderRequest/CameraRenderRequest.md)。
+
+它负责的是“最低层 request 装配”：
+
+- 重置可能残留的 pass 指针
+- 接入 post-scene pass
+- 接入 object-id surface
+
+它并不负责更高层的 render plan 规划；那部分由 [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 负责。
+
+## 当前实现行为
+
+当前函数会按固定顺序执行：
+
+1. 清空 `request.preScenePasses`
+2. 清空 `request.postScenePasses`
+3. 清空 `request.overlayPasses`
+4. 把 `request.objectId` 重置成默认值
+5. 只有当 `postPasses != nullptr` 且 `postPasses->GetPassCount() > 0` 时，才重新挂回 `request.postScenePasses`
+6. 如果 `targets.objectIdView == nullptr`，直接返回
+7. 否则调用 `BuildViewportObjectIdSurface(targets)` 构建 object-id surface
+8. 再把 object-id surface 的 `renderArea` 强制设为 `request.surface.GetRenderArea()`
+
+## 当前语义重点
+
+- 它是“先清空，再按条件重新接线”的写法，目的是防止复用 `CameraRenderRequest` 时残留上一帧指针。
+- object-id 是否可用，只检查 `targets.objectIdView != nullptr`。
+- object-id surface 的渲染区域不会自己重新计算，而是严格跟随当前主 `request.surface` 的 render area。
+
+最后一点非常关键，因为 Scene View 可能只渲染目标纹理中的一个子矩形；如果 object-id surface 不同步 render area，拾取和轮廓描边就会与颜色结果错位。
+
+## 测试锚点
+
+- `ApplySceneRenderRequestSetupAttachesOptionalPassesAndObjectIdSurface`
+- `ApplySceneRenderRequestSetupSkipsUnavailableOptionalAttachments`
+
+这些测试确认了：
+
+- 只有非空 `postPasses` 才会接入请求
+- object-id surface 会复用深度附件
+- object-id surface 的 render area 与主 surface 完全一致
+- object-id 资源不可用时，旧配置会被正确清空
+
+## 真实使用位置
+
+- [ApplySceneViewportRenderPlan](../SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md) 会先调用本函数，再补充 overlay pass 和 clear-color override。
+- `tests/Editor/test_viewport_render_flow_utils.cpp` 直接把它当成 Scene View request 基础装配入口进行测试。
+
+## 设计说明
+
+把 Scene View request 的基础装配提炼成一个小 helper，是为了维持分层清晰：
+
+- `ViewportHostService` 决定什么时候渲染
+- `SceneViewportRenderPlan` 决定额外挂哪些 pass
+- 本函数只负责把最基础、最容易出错的 request 连接动作做对
+
+这跟很多商业引擎内部的 render request builder 很像: 先保证 attachment / sub-viewport / auxiliary buffer 对齐，再谈更高层的编辑器叠加效果。
+
+## 相关文档
+
+- [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
+- [ApplySceneViewportRenderPlan](../SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md)
+- [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
+- [CameraRenderRequest](../../../Rendering/CameraRenderRequest/CameraRenderRequest.md)
+- [ObjectIdRenderRequest](../../../Rendering/CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ApplyViewportFailureStatus.md

@@ -0,0 +1,54 @@
+# ApplyViewportFailureStatus
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+void ApplyViewportFailureStatus(
+    std::string& statusText,
+    const ViewportRenderFallbackPolicy& policy);
+```
+
+## 作用
+
+根据 [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md) 把失败文案写回视口状态字符串。
+
+它只负责“文字状态”这一件事，不处理清屏，也不处理 object-id 帧失效；这些动作由 `ViewportHostService::ApplyViewportRenderFailure(...)` 在更高一层统一执行。
+
+## 当前实现行为
+
+当前逻辑很直接：
+
+1. 如果 `policy.statusText == nullptr`，直接返回。
+2. 如果 `policy.setStatusIfEmpty == true`，调用 [SetViewportStatusIfEmpty](SetViewportStatusIfEmpty.md)。
+3. 否则直接覆盖 `statusText`。
+
+## 测试锚点
+
+`ApplyViewportFailureStatusRespectsSetIfEmptyBehavior` 明确覆盖了三种情况：
+
+- 空字符串时，`SceneRendererFailed` 可以写入 `Scene renderer failed`
+- 原本已有更具体文案时，`setStatusIfEmpty == true` 不会覆盖
+- `GameViewportRenderFailure::NoActiveScene` 这类普通失败会直接覆盖
+
+## 设计说明
+
+把“失败状态如何写文字”单独抽成 helper，有两个现实收益：
+
+- `ViewportRenderFallbackPolicy` 可以把 UI 文案策略和清屏策略一起定义，但不把执行动作塞进数据结构本身
+- Scene View 可以安全保留更具体的 warning，而 Game View 仍然可以使用覆盖式语义
+
+这类拆分和商业引擎里编辑器状态系统很像：统一回退入口负责调度，而不同反馈通道各自有单独规则。
+
+## 相关文档
+
+- [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md)
+- [SetViewportStatusIfEmpty](SetViewportStatusIfEmpty.md)
+- [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md)
+- [BuildGameViewportRenderFailurePolicy](BuildGameViewportRenderFailurePolicy.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildGameViewportRenderFailurePolicy.md

@@ -0,0 +1,72 @@
+# BuildGameViewportRenderFailurePolicy
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+ViewportRenderFallbackPolicy BuildGameViewportRenderFailurePolicy(
+    GameViewportRenderFailure failure);
+```
+
+## 作用
+
+把 [GameViewportRenderFailure](GameViewportRenderFailure.md) 枚举值转换成 Game View 的回退策略。
+
+## 当前实现行为
+
+当前实现同样会先设置：
+
+```cpp
+policy.shouldClear = true;
+```
+
+随后按失败类型填充文案与颜色：
+
+| 失败类型 | 状态文案 | 清屏颜色 |
+|------|------|------|
+| `NoActiveScene` | `No active scene` | `(0.07, 0.08, 0.10, 1.0)` |
+| `NoCameraInScene` | `No camera in scene` | `(0.10, 0.09, 0.08, 1.0)` |
+| `SceneRendererFailed` | `Scene renderer failed` | `(0.18, 0.07, 0.07, 1.0)` |
+
+其余字段保持默认值：
+
+- `setStatusIfEmpty = false`
+- `invalidateObjectIdFrame = true`
+
+## 真实使用位置
+
+`ViewportHostService::RenderGameViewportEntry(...)` 在下面三种失败路径使用本函数：
+
+- 没有活动场景
+- 场景里没有任何 `CameraComponent`
+- `m_sceneRenderer->Render(*scene, nullptr, ...)` 失败
+
+## 测试锚点
+
+`BuildFailurePoliciesExposeExpectedStatusAndClearBehavior` 验证了：
+
+- `NoCameraInScene` 的文案
+- `shouldClear == true`
+- 清屏颜色是 `(0.10, 0.09, 0.08, 1.0)`
+
+## 设计说明
+
+Game View 的目标是尽量接近运行时结果，因此失败反馈策略更像“简洁而明确的播放器错误状态”：
+
+- 没有场景
+- 没有相机
+- renderer 失败
+
+它不需要像 Scene View 那样保存更多编辑器工具 warning，也就没有 `setStatusIfEmpty` 这类优先级处理需求。
+
+## 相关文档
+
+- [GameViewportRenderFailure](GameViewportRenderFailure.md)
+- [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md)
+- [ApplyViewportFailureStatus](ApplyViewportFailureStatus.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md

@@ -0,0 +1,42 @@
+# BuildSceneViewportGridPassData
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+Rendering::Passes::InfiniteGridPassData BuildSceneViewportGridPassData(
+    const SceneViewportOverlayData& overlay);
+```
+
+## 作用
+
+从当前 Scene View overlay 数据构造 grid pass 所需的 `InfiniteGridPassData`。
+
+## 当前实现行为
+
+- 当前只做字段拷贝，不创建真正的 pass 对象。
+- 会复制：
+  - `valid`
+  - `cameraPosition`
+  - `cameraForward`
+  - `cameraRight`
+  - `cameraUp`
+  - `verticalFovDegrees`
+  - `nearClipPlane`
+  - `farClipPlane`
+  - `orbitDistance`
+
+## 测试覆盖
+
+`tests/Editor/test_viewport_render_flow_utils.cpp` 当前验证了它会正确拷贝 Scene View 相机相关字段。
+
+## 相关文档
+
+- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)
+- [SceneViewportGridPassFactory](../SceneViewportRenderPlan/SceneViewportGridPassFactory.md)
+- [CreateSceneViewportGridPass](../Passes/SceneViewportGridPass/CreateSceneViewportGridPass.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportRenderFailurePolicy.md

@@ -0,0 +1,84 @@
+# BuildSceneViewportRenderFailurePolicy
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+ViewportRenderFallbackPolicy BuildSceneViewportRenderFailurePolicy(
+    SceneViewportRenderFailure failure);
+```
+
+## 作用
+
+把 [SceneViewportRenderFailure](SceneViewportRenderFailure.md) 枚举值转换成 Scene View 专用的回退策略。
+
+返回结果不仅包含文案，还明确规定：
+
+- 是否清屏
+- 清成什么颜色
+- 是否保留已有 warning
+- 是否让 object-id 帧失效
+
+## 当前实现行为
+
+当前实现会先设置：
+
+```cpp
+policy.shouldClear = true;
+```
+
+然后按失败类型填充细节：
+
+| 失败类型 | 状态文案 | 清屏颜色 | `setStatusIfEmpty` |
+|------|------|------|------|
+| `MissingSceneViewCamera` | `Scene view camera is unavailable` | `(0.18, 0.07, 0.07, 1.0)` | `false` |
+| `NoActiveScene` | `No active scene` | `(0.07, 0.08, 0.10, 1.0)` | `false` |
+| `SceneRendererFailed` | `Scene renderer failed` | `(0.18, 0.07, 0.07, 1.0)` | `true` |
+
+`invalidateObjectIdFrame` 沿用默认值 `true`。
+
+## 真实使用位置
+
+`ViewportHostService::RenderSceneViewportEntry(...)` 在以下路径会调用本函数：
+
+- Scene View 相机不可用
+- 当前没有活动场景
+- `BuildRenderRequests(...)` 返回空
+- `m_sceneRenderer->Render(requests)` 失败
+
+生成的策略会被 `ApplyViewportRenderFailure(...)` 消费，最终落到：
+
+- 状态文字更新
+- object-id 帧失效
+- 颜色 / 深度缓冲清理
+
+## 测试锚点
+
+`BuildFailurePoliciesExposeExpectedStatusAndClearBehavior` 明确验证了：
+
+- `MissingSceneViewCamera` 的红色清屏值
+- `SceneRendererFailed` 的 `setStatusIfEmpty == true`
+
+`ApplyViewportFailureStatusRespectsSetIfEmptyBehavior` 则验证了 `SceneRendererFailed` 不会覆盖已存在的更具体 warning。
+
+## 设计说明
+
+Scene View 不是纯运行时画面，而是诊断和编辑工具本身的一部分，所以失败反馈必须同时兼顾“可见”和“可解释”：
+
+- `NoActiveScene` 用偏冷的灰蓝色，表达“当前无内容可编辑”
+- 相机缺失或 renderer 失败用偏红色，强调这是异常状态
+
+更重要的一点是 `SceneRendererFailed` 使用 `setStatusIfEmpty = true`。这允许 Scene View 先保留诸如 `Scene object id shader view is unavailable` 之类更具体的 warning，再在需要时回退到通用失败文案。这样的优先级处理，比简单覆盖式状态系统更适合编辑器。
+
+## 相关文档
+
+- [SceneViewportRenderFailure](SceneViewportRenderFailure.md)
+- [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md)
+- [ApplyViewportFailureStatus](ApplyViewportFailureStatus.md)
+- [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md

@@ -0,0 +1,56 @@
+# BuildSceneViewportSelectionOutlineStyle
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+Rendering::Passes::ObjectIdOutlineStyle BuildSceneViewportSelectionOutlineStyle(
+    bool debugSelectionMask = false);
+```
+
+## 作用
+
+生成 Scene View 选中轮廓 pass 的默认样式配置。
+
+## 当前实现行为
+
+当前实现返回的样式是固定值：
+
+- `outlineColor = (1.0, 0.4, 0.0, 1.0)`
+- `outlineWidthPixels = 2.0`
+- `debugSelectionMask =` 直接透传传入参数
+
+也就是说，当前 Scene View 默认使用橙色 `2px` 轮廓，而 debug mask 只是额外的调试开关，不会改变主样式。
+
+## 测试锚点
+
+`BuildSceneViewportSelectionOutlineStyleAppliesSceneDefaults` 验证了：
+
+- 颜色固定为橙色
+- 线宽固定为 `2.0`
+- `debugSelectionMask` 参数会被正确透传
+
+## 真实使用位置
+
+[BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 在为当前选中对象创建 selection outline pass 之前，会调用本函数构造 `ObjectIdOutlineStyle`。
+
+## 设计说明
+
+把默认轮廓样式收敛到一个 helper，而不是散落在 pass 构建代码里，有两个好处：
+
+- 编辑器主题或视觉规范后续如果要统一调整，只需要改一个入口
+- render plan 构建逻辑仍然聚焦“要不要创建这个 pass”，而不是混入具体的样式细节
+
+这种做法也符合商业引擎常见的 Editor 可视化设计思路：默认视觉语言稳定统一，调试开关单独暴露。
+
+## 相关文档
+
+- [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
+- [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md)
+- [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md)
+- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildViewportRenderTargetUnavailablePolicy.md

@@ -0,0 +1,66 @@
+# BuildViewportRenderTargetUnavailablePolicy
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+ViewportRenderFallbackPolicy BuildViewportRenderTargetUnavailablePolicy();
+```
+
+## 作用
+
+生成“视口 render target 当前不可用”时的回退策略。
+
+这条路径发生在真正进入 Scene / Game 渲染之前，因此它不是“渲染失败后的清屏策略”，而是“连可用目标都没有时的诊断策略”。
+
+## 当前返回值语义
+
+当前实现只做了一件事：
+
+- `policy.statusText = "Viewport render target is unavailable"`
+
+其余字段沿用 [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md) 的默认值，因此最终效果是：
+
+- 不清屏
+- 默认保持 `invalidateObjectIdFrame = true`
+
+## 真实使用位置
+
+`ViewportHostService::RenderViewportEntry(...)` 会在下面条件成立时直接使用这条策略：
+
+```cpp
+entry.renderTargets.colorView == nullptr || entry.renderTargets.depthView == nullptr
+```
+
+随后它会：
+
+- 调用 `ApplyViewportFailureStatus(...)`
+- 调用 `InvalidateViewportObjectIdFrame(...)`
+- 立即返回，不再尝试构建 `RenderSurface`
+
+## 测试锚点
+
+`BuildFailurePoliciesExposeExpectedStatusAndClearBehavior` 确认了：
+
+- 文案是 `Viewport render target is unavailable`
+- `shouldClear == false`
+- `invalidateObjectIdFrame == true`
+
+## 设计说明
+
+这里故意不清屏，是因为问题的本质不是“上一帧内容不对”，而是“本帧根本没有可写的目标”。
+
+如果连颜色 / 深度 view 都缺失，继续走清屏语义没有意义，甚至可能掩盖真正的资源问题。对编辑器用户而言，更重要的是尽快给出明确文案，并阻止后续 object-id 功能继续使用旧数据。
+
+## 相关文档
+
+- [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md)
+- [ApplyViewportFailureStatus](ApplyViewportFailureStatus.md)
+- [InvalidateViewportObjectIdFrame](InvalidateViewportObjectIdFrame.md)
+- [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/GameViewportRenderFailure.md

@@ -0,0 +1,62 @@
+# GameViewportRenderFailure
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `enum class`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 定义
+
+```cpp
+enum class GameViewportRenderFailure {
+    NoActiveScene,
+    NoCameraInScene,
+    SceneRendererFailed
+};
+```
+
+## 作用
+
+表达 Game View 渲染路径里会被归类为用户可见回退状态的失败类别。
+
+和 [SceneViewportRenderFailure](SceneViewportRenderFailure.md) 一样，它是编辑器层的失败分类，而不是底层渲染错误码。
+
+## 枚举值语义
+
+| 枚举值 | 含义 |
+|------|------|
+| `NoActiveScene` | 当前没有活动场景。 |
+| `NoCameraInScene` | 活动场景存在，但没有任何 `CameraComponent` 可供 Game View 使用。 |
+| `SceneRendererFailed` | `SceneRenderer` 无法成功执行当前 Game View 渲染。 |
+
+## 当前实现行为
+
+在 `ViewportHostService::RenderGameViewportEntry(...)` 中：
+
+1. `scene == nullptr` 时返回 `NoActiveScene`。
+2. `scene->FindObjectsOfType<CameraComponent>()` 为空时返回 `NoCameraInScene`。
+3. `m_sceneRenderer->Render(*scene, nullptr, ...)` 失败时返回 `SceneRendererFailed`。
+
+这些枚举值会被 [BuildGameViewportRenderFailurePolicy](BuildGameViewportRenderFailurePolicy.md) 转成对应的清屏颜色和状态文字。
+
+## 设计说明
+
+Game View 的职责比 Scene View 更接近“真实运行时预览”，因此这里的失败类别刻意保持简单：
+
+- 没场景
+- 没相机
+- renderer 失败
+
+它不承担 Scene View 那种工具链 warning 的解释任务，所以不需要 `MissingSceneViewCamera` 或 object-id 相关类别。
+
+## 真实使用位置
+
+- `ViewportHostService::RenderGameViewportEntry(...)`
+- [BuildGameViewportRenderFailurePolicy](BuildGameViewportRenderFailurePolicy.md)
+
+## 相关文档
+
+- [BuildGameViewportRenderFailurePolicy](BuildGameViewportRenderFailurePolicy.md)
+- [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/InvalidateViewportObjectIdFrame.md

@@ -0,0 +1,53 @@
+# InvalidateViewportObjectIdFrame
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+void InvalidateViewportObjectIdFrame(ViewportRenderTargets& targets);
+```
+
+## 作用
+
+把当前视口的 object-id 帧标记为无效，防止拾取、轮廓高亮或其他依赖 object-id 结果的编辑器功能继续误用上一帧数据。
+
+## 当前实现行为
+
+当前实现只有一行：
+
+```cpp
+targets.hasValidObjectIdFrame = false;
+```
+
+它不会销毁资源，也不会清空纹理内容；它只更新“这份 object-id 结果还能不能被当成有效帧使用”的状态位。
+
+## 真实使用位置
+
+- `ViewportHostService::ApplyViewportRenderFailure(...)`
+  - 当策略要求 `invalidateObjectIdFrame == true` 时调用
+- `ViewportHostService::RenderViewportEntry(...)`
+  - render target 缺失时立即调用
+
+## 设计说明
+
+编辑器里 object-id buffer 的问题通常不是“有没有纹理”，而是“纹理里的内容还是不是这一帧对应的真实结果”。
+
+单独维护 `hasValidObjectIdFrame` 的意义在于：
+
+- GPU 资源可以继续复用
+- 但交互层不会把陈旧帧误判成有效拾取结果
+
+这比每次失败都销毁 object-id 资源更稳，也更符合实时编辑器的性能要求。
+
+## 相关文档
+
+- [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
+- [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md)
+- [MarkSceneViewportRenderSuccess](MarkSceneViewportRenderSuccess.md)
+- [MarkGameViewportRenderSuccess](MarkGameViewportRenderSuccess.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/MarkGameViewportRenderSuccess.md

@@ -0,0 +1,55 @@
+# MarkGameViewportRenderSuccess
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+void MarkGameViewportRenderSuccess(ViewportRenderTargets& targets);
+```
+
+## 作用
+
+在 Game View 渲染成功后，写回最基本的资源状态，并明确让 object-id 帧失效。
+
+## 当前实现行为
+
+当前实现只做两件事：
+
+```cpp
+targets.colorState = RHI::ResourceStates::PixelShaderResource;
+targets.hasValidObjectIdFrame = false;
+```
+
+注意它不会修改 `targets.objectIdState`。这是符合当前实现语义的，因为 Game View 路径本身并不依赖 Scene View 的 object-id 结果。
+
+## 测试锚点
+
+`MarkGameRenderSuccessClearsObjectIdFrameAndUpdatesColorState` 验证了：
+
+- `colorState` 会被切到 `PixelShaderResource`
+- `hasValidObjectIdFrame` 会被强制清成 `false`
+
+## 真实使用位置
+
+`ViewportHostService::RenderGameViewportEntry(...)` 在 `m_sceneRenderer->Render(*scene, nullptr, ...)` 成功后调用本函数。
+
+## 设计说明
+
+Game View 的目标是展示运行时相机结果，而不是服务编辑器拾取工具，所以成功渲染后最合理的做法不是“沿用上一帧 Scene View 的 object-id 状态”，而是明确把它视为无效。
+
+这能避免跨视口共享状态时出现隐蔽错误，例如：
+
+- Game View 画面对了
+- 但编辑器仍然误以为有一份可用于拾取的 object-id 帧
+
+## 相关文档
+
+- [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
+- [MarkSceneViewportRenderSuccess](MarkSceneViewportRenderSuccess.md)
+- [GameViewportRenderFailure](GameViewportRenderFailure.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/MarkSceneViewportRenderSuccess.md

@@ -0,0 +1,69 @@
+# MarkSceneViewportRenderSuccess
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+void MarkSceneViewportRenderSuccess(
+    ViewportRenderTargets& targets,
+    const Rendering::CameraRenderRequest& request);
+```
+
+## 作用
+
+在 Scene View 渲染成功后，把 `ViewportRenderTargets` 的资源状态和 object-id 帧有效性更新到下一阶段可消费的状态。
+
+## 当前实现行为
+
+当前实现会写入三件事：
+
+```cpp
+targets.colorState = RHI::ResourceStates::PixelShaderResource;
+targets.objectIdState = RHI::ResourceStates::PixelShaderResource;
+targets.hasValidObjectIdFrame = request.objectId.IsRequested();
+```
+
+这意味着：
+
+- Scene View 颜色纹理会被标记成可供后续采样的 `PixelShaderResource`
+- object-id 纹理也会进入同样的采样状态
+- 只有当当前 request 实际请求了 object-id surface，`hasValidObjectIdFrame` 才会被标记为有效
+
+## 测试锚点
+
+`MarkSceneRenderSuccessMovesTargetsToShaderResourceState` 覆盖了两种情况：
+
+- object-id 已请求时，`hasValidObjectIdFrame == true`
+- object-id 未请求时，`hasValidObjectIdFrame == false`
+
+两种情况下，`colorState` 和 `objectIdState` 都会被切到 `PixelShaderResource`。
+
+## 真实使用位置
+
+`ViewportHostService::RenderSceneViewportEntry(...)` 在 `m_sceneRenderer->Render(requests)` 成功后立即调用本函数。
+
+这是 Scene View 渲染链里非常关键的“成功收尾”步骤，因为后续：
+
+- ImGui 需要采样颜色结果
+- selection outline / object-id picker 依赖 object-id 纹理
+
+## 设计说明
+
+渲染成功并不等于后续编辑器工具可以安全读取结果；还必须显式把资源状态和“本帧是否有效”这两个条件整理好。
+
+把这一步收口成 helper 的价值在于：
+
+- 渲染主流程不用重复书写状态回写代码
+- object-id 是否真的有效，始终以 request 是否请求过它为准，而不是凭资源是否存在做猜测
+
+## 相关文档
+
+- [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
+- [ApplySceneViewportRenderRequestSetup](ApplySceneViewportRenderRequestSetup.md)
+- [MarkGameViewportRenderSuccess](MarkGameViewportRenderSuccess.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/SceneViewportRenderFailure.md

@@ -0,0 +1,64 @@
+# SceneViewportRenderFailure
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `enum class`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 定义
+
+```cpp
+enum class SceneViewportRenderFailure {
+    MissingSceneViewCamera,
+    NoActiveScene,
+    SceneRendererFailed
+};
+```
+
+## 作用
+
+表达 Scene View 渲染链里当前被文档化、且会映射为用户可见回退策略的失败类别。
+
+它不是底层 renderer 错误码，也不是异常系统；它更像 Editor UI 语义层的“失败原因分类”，专门服务于 [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md)。
+
+## 枚举值语义
+
+| 枚举值 | 含义 |
+|------|------|
+| `MissingSceneViewCamera` | 编辑器内部 Scene View 相机不可用，连构建 Scene View request 的前提都不满足。 |
+| `NoActiveScene` | 当前没有活动场景，因此没有任何内容可供 Scene View 渲染。 |
+| `SceneRendererFailed` | `SceneRenderer` 没有成功产出或执行可用 request。 |
+
+## 当前实现行为
+
+在 `ViewportHostService::RenderSceneViewportEntry(...)` 中，这三个值分别对应三段失败路径：
+
+1. `EnsureSceneViewCamera()` 失败。
+2. `scene == nullptr`。
+3. `BuildRenderRequests(...)` 返回空，或 `Render(requests)` 执行失败。
+
+随后这些枚举值会交给 [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md)，转成具体的状态文案、清屏颜色和 object-id 失效策略。
+
+## 设计说明
+
+这里没有把 Scene View 的每一种技术性失败都暴露成一个独立枚举，而是只保留对编辑器用户真正有诊断价值的粗粒度类别。
+
+这种做法接近商业引擎里 Scene 视口常见的处理方式：
+
+- 用户首先需要知道“现在为什么没画出来”。
+- 但不一定需要知道底层每一个 GPU / 资源细节。
+
+更细的上下文，例如 `objectIdShaderView` 缺失这类可降级 warning，则由上层状态文字补充，而不是继续膨胀失败枚举。
+
+## 真实使用位置
+
+- `ViewportHostService::RenderSceneViewportEntry(...)`
+- [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md)
+
+## 相关文档
+
+- [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md)
+- [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)
+- [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/SetViewportStatusIfEmpty.md

@@ -0,0 +1,56 @@
+# SetViewportStatusIfEmpty
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 签名
+
+```cpp
+void SetViewportStatusIfEmpty(std::string& statusText, const char* message);
+```
+
+## 作用
+
+只在当前视口状态文字为空时写入一条消息。
+
+这是一种很小但很关键的 helper，因为编辑器视口经常会同时遇到：
+
+- 更具体的 warning
+- 更泛化的失败文案
+
+此函数允许前者优先保留。
+
+## 当前实现行为
+
+当前实现只有一个判断：
+
+- 如果 `statusText.empty()`，则写入 `message`
+- 否则保持原值不变
+
+它不会做空指针检查，也不会拼接字符串，因此调用方需要先决定“这条消息是否值得保留为首要状态”。
+
+## 真实使用位置
+
+当前至少有三类直接使用场景：
+
+- `ViewportHostService::PickSceneViewEntity(...)`
+  - object-id 读回失败时，尝试写入 `Scene object id readback failed`
+- `ViewportHostService::BuildSceneViewportRenderState(...)`
+  - render plan 返回非致命 warning 时，尝试保留该 warning
+- [ApplyViewportFailureStatus](ApplyViewportFailureStatus.md)
+  - 当策略要求 `setStatusIfEmpty == true` 时，会转而调用本函数
+
+## 设计说明
+
+编辑器状态文案的设计重点不是“最后一个错误覆盖前面的错误”，而是“尽量保留最有诊断价值的那条信息”。
+
+例如 Scene View 已经先得到了 `Scene object id shader view is unavailable` 这样的精确 warning，后续 `SceneRendererFailed` 不应该粗暴覆盖掉它；否则用户只能看到更笼统的失败结果，看不到真正值得排查的上下文。
+
+## 相关文档
+
+- [ApplyViewportFailureStatus](ApplyViewportFailureStatus.md)
+- [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

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

@@ -0,0 +1,186 @@
+# ViewportHostRenderFlowUtils
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `structs + enums + header-helper`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+**描述**: 为 `ViewportHostService` 提供视口失败回退策略、Scene View request 基础装配以及渲染成功后的状态回写 helper。
+
+## 概览
+
+`ViewportHostRenderFlowUtils.h` 处在 [ViewportHostService](../ViewportHostService/ViewportHostService.md) 的主流程中段，承担的是“把渲染流程里反复出现、但又不值得塞进 service 主体的大量小规则收拢起来”的职责。
+
+它当前主要覆盖三类问题：
+
+- 失败回退
+  - 视口应该显示什么状态文案
+  - 是否需要清屏
+  - object-id 帧是否必须作废
+- Scene View request 基础装配
+  - 如何清理旧的 pass 指针
+  - 何时接入 `postScenePasses`
+  - 何时接入 object-id surface
+- 成功后的状态回写
+  - 颜色 / object-id 资源该切回什么状态
+  - 当前 object-id 帧是否可供下一阶段消费
+
+在更早的版本里，这类逻辑很容易全部堆进 `ViewportHostService::RenderSceneViewportEntry(...)` / `RenderGameViewportEntry(...)`。但随着 Scene View 逐步加入网格、选中轮廓、overlay、object-id 和失败诊断，这种写法会迅速变成难维护的“业务大函数”。
+
+当前的拆分更接近商业级游戏引擎编辑器常见的组织方式：
+
+- service 负责总调度
+- render plan 负责附加 pass 规划
+- flow utils 负责失败策略、基础 request 接线和状态回写
+
+## 与 `SceneViewportRenderPlan` 的分工
+
+[SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 和本头文件经常一起出现，但职责并不相同：
+
+- `SceneViewportRenderPlan`
+  - 负责决定 Scene View 这一帧“额外挂哪些 pass”
+  - 例如 grid、selection outline、editor overlay
+- `ViewportHostRenderFlowUtils`
+  - 负责“失败时怎么退、请求基础接线怎么做、成功后怎么收尾”
+
+换句话说，`SceneViewportRenderPlan` 更像“内容规划层”，而这里更像“流程辅助层”。
+
+这种拆法的价值在于：
+
+- render plan 可以独立测试“要不要挂 pass”
+- flow utils 可以独立测试“失败 / 成功状态到底怎样回写”
+- `ViewportHostService` 自己保留清晰的主调用链，而不是被一堆细枝末节淹没
+
+## 公开类型与函数
+
+| 成员 | 说明 |
+|------|------|
+| [ViewportRenderFallbackPolicy](ViewportRenderFallbackPolicy.md) | 统一描述失败文案、清屏动作与 object-id 失效策略。 |
+| [SceneViewportRenderFailure](SceneViewportRenderFailure.md) | Scene View 的失败分类。 |
+| [GameViewportRenderFailure](GameViewportRenderFailure.md) | Game View 的失败分类。 |
+| [SetViewportStatusIfEmpty](SetViewportStatusIfEmpty.md) | 仅在状态文字为空时写入消息。 |
+| [ApplyViewportFailureStatus](ApplyViewportFailureStatus.md) | 按失败策略写回状态文字。 |
+| [InvalidateViewportObjectIdFrame](InvalidateViewportObjectIdFrame.md) | 让 object-id 帧标记失效。 |
+| [BuildViewportRenderTargetUnavailablePolicy](BuildViewportRenderTargetUnavailablePolicy.md) | 构建“render target 不可用”策略。 |
+| [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md) | 把 Scene View 失败分类转成回退策略。 |
+| [BuildGameViewportRenderFailurePolicy](BuildGameViewportRenderFailurePolicy.md) | 把 Game View 失败分类转成回退策略。 |
+| [BuildSceneViewportGridPassData](BuildSceneViewportGridPassData.md) | 把 Scene View overlay 相机状态转换为 `InfiniteGridPassData`。 |
+| [BuildSceneViewportSelectionOutlineStyle](BuildSceneViewportSelectionOutlineStyle.md) | 生成 Scene View 选中轮廓默认样式。 |
+| [ApplySceneViewportRenderRequestSetup](ApplySceneViewportRenderRequestSetup.md) | 为 Scene View 基础 request 接线。 |
+| [MarkSceneViewportRenderSuccess](MarkSceneViewportRenderSuccess.md) | Scene View 成功后的状态回写。 |
+| [MarkGameViewportRenderSuccess](MarkGameViewportRenderSuccess.md) | Game View 成功后的状态回写。 |
+
+## `ViewportHostService` 调用链中的位置
+
+### 视口入口
+
+`ViewportHostService::RenderViewportEntry(...)` 先检查 `colorView` / `depthView` 是否可用。
+
+如果 render target 缺失，它不会继续走渲染，而是直接：
+
+1. 调用 [BuildViewportRenderTargetUnavailablePolicy](BuildViewportRenderTargetUnavailablePolicy.md)
+2. 调用 [ApplyViewportFailureStatus](ApplyViewportFailureStatus.md)
+3. 调用 [InvalidateViewportObjectIdFrame](InvalidateViewportObjectIdFrame.md)
+
+这是一条“资源前置条件失败”路径。
+
+### Scene View 路径
+
+`ViewportHostService::RenderSceneViewportEntry(...)` 当前大致是下面这条链：
+
+1. 检查编辑器 Scene View 相机是否存在
+2. 没有活动场景时走 [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md)
+3. 构建 [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
+4. 调用 `SceneRenderer::BuildRenderRequests(...)`
+5. 调用 [ApplySceneViewportRenderPlan](../SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md)
+6. 调用 `SceneRenderer::Render(requests)`
+7. 成功后调用 [MarkSceneViewportRenderSuccess](MarkSceneViewportRenderSuccess.md)
+
+其中本头文件承担的关键细节包括：
+
+- 失败文案与清屏色如何选择
+- request 的基础 object-id / post-pass 接线如何处理
+- 成功后资源状态如何回写
+
+### Game View 路径
+
+`ViewportHostService::RenderGameViewportEntry(...)` 更短一些：
+
+1. 检查活动场景
+2. 检查场景里是否有相机
+3. 直接调用 `SceneRenderer::Render(*scene, nullptr, ...)`
+4. 成功后调用 [MarkGameViewportRenderSuccess](MarkGameViewportRenderSuccess.md)
+
+它不经过 `SceneViewportRenderPlan`，因为 Game View 不承担 Scene View 那套 editor overlay / selection outline 工作流。
+
+## 当前实现要点
+
+按 `ViewportHostRenderFlowUtils.h` 与 `tests/Editor/test_viewport_render_flow_utils.cpp` 当前实现：
+
+- `ViewportRenderFallbackPolicy` 默认不会清屏，但会默认让 object-id 帧失效。
+- `BuildViewportRenderTargetUnavailablePolicy()` 只给出文案，不执行清屏策略。
+- Scene / Game 失败策略都会要求清屏，但使用不同颜色区分“空场景”和“异常失败”。
+- `SceneRendererFailed` 的 Scene View 策略会使用 `setStatusIfEmpty = true`，以保留更具体的 warning。
+- `BuildSceneViewportGridPassData(...)` 当前只是字段复制层。
+- `BuildSceneViewportSelectionOutlineStyle(...)` 当前固定返回橙色 `2px` 轮廓。
+- `ApplySceneViewportRenderRequestSetup(...)` 会先清空 request 中旧的 pass / object-id 设置，再按条件重新挂接。
+- `MarkSceneViewportRenderSuccess(...)` 会同时更新颜色状态、object-id 状态和 object-id 帧有效标记。
+- `MarkGameViewportRenderSuccess(...)` 则只更新颜色状态，并明确让 object-id 帧无效。
+
+## 设计说明
+
+### 为什么编辑器视口不能只靠一个 `Render()` 返回值
+
+在编辑器里，“画面没出来”远远不是全部问题。用户更关心：
+
+- 现在是没场景，还是没相机
+- 是 Scene View 自己缺前置条件，还是 renderer 真的失败了
+- object-id 还能不能继续做拾取
+
+这也是为什么这里把失败反馈拆成“文案、清屏、object-id 帧有效性”三个维度，而不是用一个布尔值糊过去。
+
+### 为什么 `SceneRendererFailed` 要保留已有 warning
+
+Scene View 在构建 render plan 时，可能已经得到了更精确但非致命的 warning，例如 object-id shader view 缺失。
+
+如果后面 renderer 又失败了，直接把状态覆盖成 `Scene renderer failed`，用户就会失去更可行动的排查线索。`setStatusIfEmpty` 的设计，正是为了避免这种“后来的通用错误吃掉先来的具体 warning”。
+
+### 为什么 object-id 要有显式失效标记
+
+编辑器拾取系统最大的风险之一不是没有纹理，而是继续使用一张还存在、但其实已经过期的 object-id 结果。
+
+因此这里专门把“资源还在”和“这帧结果是否有效”拆成两个概念：
+
+- 资源可以复用
+- 但有效性必须按本帧执行结果重置
+
+这是一种非常典型的实时编辑器设计，能显著减少跨帧状态污染。
+
+## 测试锚点
+
+当前这组 helper 至少有以下直接测试覆盖：
+
+- `BuildFailurePoliciesExposeExpectedStatusAndClearBehavior`
+- `ApplyViewportFailureStatusRespectsSetIfEmptyBehavior`
+- `BuildSceneViewportGridPassDataCopiesSceneCameraState`
+- `BuildSceneViewportSelectionOutlineStyleAppliesSceneDefaults`
+- `ApplySceneRenderRequestSetupAttachesOptionalPassesAndObjectIdSurface`
+- `ApplySceneRenderRequestSetupSkipsUnavailableOptionalAttachments`
+- `MarkSceneRenderSuccessMovesTargetsToShaderResourceState`
+- `MarkGameRenderSuccessClearsObjectIdFrameAndUpdatesColorState`
+
+## 当前边界
+
+- 这里不负责 Scene View render plan 的高层组装；那部分已经移动到 [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)。
+- 这里不创建实际 pass，只创建 pass 所需的少量数据与样式，或负责 request 接线。
+- 当前 selection outline 样式仍是硬编码默认值，不是可主题化配置系统。
+
+## 相关文档
+
+- [Viewport](../Viewport.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)
+- [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md)
+- [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md)
+- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)
+- [CameraRenderRequest](../../../Rendering/CameraRenderRequest/CameraRenderRequest.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportRenderFallbackPolicy.md

@@ -0,0 +1,81 @@
+# ViewportRenderFallbackPolicy
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+
+## 定义
+
+```cpp
+struct ViewportRenderFallbackPolicy {
+    const char* statusText = nullptr;
+    Math::Color clearColor = Math::Color::Black();
+    bool shouldClear = false;
+    bool setStatusIfEmpty = false;
+    bool invalidateObjectIdFrame = true;
+};
+```
+
+## 作用
+
+把“视口这次失败以后应该怎样回退”收拢成一个明确的数据结构，供 `ViewportHostService::ApplyViewportRenderFailure(...)` 统一消费。
+
+它解决的不是单一的清屏问题，而是一次编辑器视口失败处理里经常同时出现的三件事：
+
+- 状态栏应该显示什么文字。
+- 是否要清屏，以及清成什么颜色。
+- 是否要让上一帧 object-id 结果失效。
+
+## 字段语义
+
+| 字段 | 当前默认值 | 说明 |
+|------|------|------|
+| `statusText` | `nullptr` | 失败文案；为空时代表“不改状态文字”。 |
+| `clearColor` | `Math::Color::Black()` | 当 `shouldClear == true` 时使用的清屏颜色。 |
+| `shouldClear` | `false` | 是否要主动清理颜色 / 深度缓冲。 |
+| `setStatusIfEmpty` | `false` | `true` 时仅在当前状态文字为空时写入文案。 |
+| `invalidateObjectIdFrame` | `true` | 是否让当前 object-id 帧标记失效，防止后续拾取读到陈旧数据。 |
+
+## 当前实现行为
+
+按 `ViewportHostRenderFlowUtils.h` 当前实现：
+
+- 这是所有视口失败策略 builder 的统一返回类型。
+- `BuildViewportRenderTargetUnavailablePolicy()` 只写文案，不清屏，保留默认的 `invalidateObjectIdFrame = true`。
+- `BuildSceneViewportRenderFailurePolicy(...)` 和 `BuildGameViewportRenderFailurePolicy(...)` 都会把 `shouldClear` 设为 `true`。
+- `SceneRendererFailed` 这一类 Scene View 失败会利用 `setStatusIfEmpty = true` 保留更早写入的、更具体的警告文案。
+
+## 真实使用位置
+
+- `ViewportHostService::ApplyViewportRenderFailure(...)` 会按该结构决定：
+  - 是否调用 `ApplyViewportFailureStatus(...)`
+  - 是否调用 `InvalidateViewportObjectIdFrame(...)`
+  - 是否调用 `ClearViewport(...)`
+- `RenderViewportEntry(...)` 在 render target 缺失时，直接使用 [BuildViewportRenderTargetUnavailablePolicy](BuildViewportRenderTargetUnavailablePolicy.md)。
+- `RenderSceneViewportEntry(...)` / `RenderGameViewportEntry(...)` 分别通过 Scene / Game 失败枚举生成策略。
+
+## 设计说明
+
+把失败处理先表达成“策略对象”，再交给 service 执行，是编辑器渲染链里很有价值的拆分。
+
+这样做的好处是：
+
+- 失败原因和失败动作解耦，便于测试。
+- Scene View 与 Game View 可以共享一套落地逻辑，但保留各自的失败语义。
+- 后续如果要增加更多 editor 级反馈，例如 warning icon、overlay banner、日志等级，也有明确扩展点，而不是继续往渲染主流程里堆 if/else。
+
+## 测试锚点
+
+- `BuildFailurePoliciesExposeExpectedStatusAndClearBehavior`
+- `ApplyViewportFailureStatusRespectsSetIfEmptyBehavior`
+
+## 相关文档
+
+- [ViewportHostRenderFlowUtils](ViewportHostRenderFlowUtils.md)
+- [ApplyViewportFailureStatus](ApplyViewportFailureStatus.md)
+- [BuildViewportRenderTargetUnavailablePolicy](BuildViewportRenderTargetUnavailablePolicy.md)
+- [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md)
+- [BuildGameViewportRenderFailurePolicy](BuildGameViewportRenderFailurePolicy.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderTargets/BuildViewportColorSurface.md

@@ -0,0 +1,35 @@
+# BuildViewportColorSurface
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderTargets.h`
+
+## 签名
+
+```cpp
+Rendering::RenderSurface BuildViewportColorSurface(const ViewportRenderTargets& targets);
+```
+
+## 作用
+
+基于当前颜色视图、深度视图和颜色资源状态构造颜色渲染表面。
+
+## 当前实现行为
+
+- 当前直接调用 [BuildViewportRenderSurface](../ViewportHostSurfaceUtils/BuildViewportRenderSurface.md)。
+- 传入的附件与状态为：
+  - `targets.colorView`
+  - `targets.depthView`
+  - `targets.colorState`
+- `colorStateAfter` 仍沿用底层 helper 的默认值 `PixelShaderResource`。
+
+## 测试覆盖
+
+`tests/Editor/test_viewport_render_targets.cpp` 当前验证了它会复用颜色附件、深度附件和颜色状态。
+
+## 相关文档
+
+- [ViewportRenderTargets](ViewportRenderTargets.md)
+- [BuildViewportObjectIdSurface](BuildViewportObjectIdSurface.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderTargets/BuildViewportObjectIdSurface.md

@@ -0,0 +1,36 @@
+# BuildViewportObjectIdSurface
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderTargets.h`
+
+## 签名
+
+```cpp
+Rendering::RenderSurface BuildViewportObjectIdSurface(const ViewportRenderTargets& targets);
+```
+
+## 作用
+
+基于当前 object-id 视图、深度视图和 object-id 资源状态构造 object-id 渲染表面。
+
+## 当前实现行为
+
+- 当前直接调用 [BuildViewportRenderSurface](../ViewportHostSurfaceUtils/BuildViewportRenderSurface.md)。
+- 传入的附件与状态为：
+  - `targets.objectIdView`
+  - `targets.depthView`
+  - `targets.objectIdState`
+- `colorStateAfter` 同样沿用底层 helper 的默认值 `PixelShaderResource`。
+
+## 测试覆盖
+
+`tests/Editor/test_viewport_render_targets.cpp` 当前验证了它会复用 object-id 附件、深度附件和 object-id 状态。
+
+## 相关文档
+
+- [ViewportRenderTargets](ViewportRenderTargets.md)
+- [BuildViewportColorSurface](BuildViewportColorSurface.md)
+- [ApplySceneViewportRenderRequestSetup](../ViewportHostRenderFlowUtils/ApplySceneViewportRenderRequestSetup.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderTargets/BuildViewportRenderTargetsReuseQuery.md

@@ -0,0 +1,40 @@
+# BuildViewportRenderTargetsReuseQuery
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderTargets.h`
+
+## 签名
+
+```cpp
+ViewportHostResourceReuseQuery BuildViewportRenderTargetsReuseQuery(
+    EditorViewportKind kind,
+    const ViewportRenderTargets& targets,
+    uint32_t requestedWidth,
+    uint32_t requestedHeight);
+```
+
+## 作用
+
+把当前 `ViewportRenderTargets` 的资源占用状态转成可供复用判断使用的查询结构。
+
+## 当前实现行为
+
+- 会复制 `kind`、当前宽高和请求宽高。
+- 会把各资源指针是否为空映射到 `query.resources`：
+  - `colorTexture` / `colorView`
+  - `depthTexture` / `depthView`
+  - `objectIdTexture` / `objectIdView` / `objectIdShaderView`
+- `hasTextureDescriptor` 当前通过 `targets.textureId != ImTextureID{}` 判断。
+
+## 测试覆盖
+
+`tests/Editor/test_viewport_render_targets.cpp` 当前验证了它会正确反映当前资源存在性。
+
+## 相关文档
+
+- [ViewportRenderTargets](ViewportRenderTargets.md)
+- [ViewportHostResourceReuseQuery](../ViewportHostSurfaceUtils/ViewportHostResourceReuseQuery.md)
+- [CanReuseViewportResources](../ViewportHostSurfaceUtils/CanReuseViewportResources.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderTargets/CreateViewportRenderTargets.md

@@ -0,0 +1,46 @@
+# CreateViewportRenderTargets
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderTargets.h`
+
+## 签名
+
+```cpp
+bool CreateViewportRenderTargets(
+    EditorViewportKind kind,
+    uint32_t width,
+    uint32_t height,
+    RHI::RHIDevice* device,
+    UI::ImGuiBackendBridge* backend,
+    ViewportRenderTargets& targets);
+```
+
+## 作用
+
+为指定视口类型创建完整的 render target 资源包，并写回 `targets`。
+
+## 当前实现行为
+
+- 若 `width == 0`、`height == 0`、`device == nullptr` 或 `backend == nullptr`，直接返回 `false`。
+- 开始创建前会先调用 [DestroyViewportRenderTargets](DestroyViewportRenderTargets.md) 清理旧资源。
+- 然后依次创建：
+  - 颜色纹理与颜色 RTV
+  - 深度纹理与深度 DSV
+  - 若该视口类型需要，则再创建 object-id 纹理、RTV 与 SRV
+  - ImGui 颜色纹理描述符
+- 只要任一步失败，就会再次销毁当前半成品并返回 `false`。
+- 成功时会把 `colorState`、`objectIdState` 复位为 `Common`，并把 `hasValidObjectIdFrame` 置为 `false`。
+
+## 当前边界
+
+- 创建细节被封装在 `Detail::*` 内部 helper 中，不属于当前公开 API。
+- 当前没有独立单测直接覆盖成功路径，但 `ViewportHostService` 会依赖它创建实际视口资源。
+
+## 相关文档
+
+- [ViewportRenderTargets](ViewportRenderTargets.md)
+- [DestroyViewportRenderTargets](DestroyViewportRenderTargets.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderTargets/DestroyViewportRenderTargets.md

@@ -0,0 +1,41 @@
+# DestroyViewportRenderTargets
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `function`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderTargets.h`
+
+## 签名
+
+```cpp
+void DestroyViewportRenderTargets(
+    UI::ImGuiBackendBridge* backend,
+    ViewportRenderTargets& targets);
+```
+
+## 作用
+
+释放当前视口持有的 ImGui 描述符和全部 GPU 资源，并把目标结构重置为空状态。
+
+## 当前实现行为
+
+- 如果 `backend != nullptr` 且 `targets.imguiCpuHandle.ptr != 0`，会先释放 ImGui 纹理描述符。
+- 然后按顺序 `Shutdown + delete`：
+  - `objectIdView`
+  - `objectIdShaderView`
+  - `objectIdTexture`
+  - `depthView`
+  - `depthTexture`
+  - `colorView`
+  - `colorTexture`
+- 最后会把尺寸、描述符句柄、`textureId`、资源状态和 `hasValidObjectIdFrame` 复位。
+
+## 测试覆盖
+
+`tests/Editor/test_viewport_render_targets.cpp` 当前验证了它会关闭并清空所有资源字段。
+
+## 相关文档
+
+- [ViewportRenderTargets](ViewportRenderTargets.md)
+- [CreateViewportRenderTargets](CreateViewportRenderTargets.md)

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

@@ -0,0 +1,58 @@
+# ViewportHostRenderTargets
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct + header-helper`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderTargets.h`
+
+**描述**: 定义 Editor 视口 render target 聚合结构，并负责颜色 / 深度 / object-id 目标与 ImGui 纹理描述符的创建销毁。
+
+## 概述
+
+`ViewportRenderTargets` 是 `ViewportHostService` 内部真正持有的视口资源包。当前一套资源可能包含：
+
+- 颜色纹理与 RTV。
+- 深度纹理与 DSV。
+- Scene 视口专用的 object-id 纹理、RTV 与 SRV。
+- ImGui 用于显示颜色纹理的描述符和 `ImTextureID`。
+
+这个封装的价值是把“一个视口需要哪些 GPU 资源”收拢成稳定结构，而不是把很多裸指针散在 service 主类里。
+
+## 公开类型与函数
+
+| 成员 | 说明 |
+|------|------|
+| [ViewportRenderTargets](ViewportRenderTargets.md) | 当前视口资源聚合体。 |
+| [BuildViewportRenderTargetsReuseQuery](BuildViewportRenderTargetsReuseQuery.md) | 把当前资源状态转成重用查询。 |
+| [BuildViewportColorSurface](BuildViewportColorSurface.md) | 为颜色缓冲创建 `RenderSurface`。 |
+| [BuildViewportObjectIdSurface](BuildViewportObjectIdSurface.md) | 为 object-id 缓冲创建 `RenderSurface`。 |
+| [DestroyViewportRenderTargets](DestroyViewportRenderTargets.md) | 释放描述符与全部 GPU 资源。 |
+| [CreateViewportRenderTargets](CreateViewportRenderTargets.md) | 依视口类型创建整套资源。 |
+
+## 当前实现行为
+
+- `CreateViewportRenderTargets(...)` 会先销毁旧资源，再创建新资源。
+- 只有 `Scene` 视口会额外分配 object-id texture / RTV / SRV。
+- `CreateViewportTextureDescriptor(...)` 会通过 `ImGuiBackendBridge` 给颜色纹理创建可显示描述符。
+- 资源创建任一步失败都会整体回滚并返回 `false`。
+
+## 设计说明
+
+把 `object-id` 资源和普通颜色视口一起放进一个结构体，是很典型的编辑器视口做法。因为 Scene View 不是单纯“显示颜色图像”，它还承担选择、outline、高亮等工具语义，所以需要额外缓冲。
+
+## 生命周期与所有权
+
+- 这些资源由 [ViewportHostService](../ViewportHostService/ViewportHostService.md) 拥有。
+- `DestroyViewportRenderTargets(...)` 会负责释放 ImGui 描述符，并 `Shutdown + delete` 所有关联资源对象。
+
+## 当前限制
+
+- 当前没有跨视口共享 RT 池。
+- 当前 object-id 纹理格式固定为 `R8G8B8A8_UNorm`，依赖颜色编码对象 ID。
+
+## 相关文档
+
+- [ViewportHostSurfaceUtils](../ViewportHostSurfaceUtils/ViewportHostSurfaceUtils.md)
+- [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md)
+- [ViewportHostService](../ViewportHostService/ViewportHostService.md)

docs/api/XCEngine/Editor/Viewport/ViewportHostRenderTargets/ViewportRenderTargets.md

@@ -0,0 +1,39 @@
+# ViewportRenderTargets
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Viewport/ViewportHostRenderTargets.h`
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `width` | `uint32_t` | 当前 render target 宽度。 |
+| `height` | `uint32_t` | 当前 render target 高度。 |
+| `colorTexture` | `RHI::RHITexture*` | 颜色纹理。 |
+| `colorView` | `RHI::RHIResourceView*` | 颜色 RTV。 |
+| `depthTexture` | `RHI::RHITexture*` | 深度纹理。 |
+| `depthView` | `RHI::RHIResourceView*` | 深度 DSV。 |
+| `objectIdTexture` | `RHI::RHITexture*` | Scene 视口专用 object-id 纹理。 |
+| `objectIdView` | `RHI::RHIResourceView*` | object-id RTV。 |
+| `objectIdShaderView` | `RHI::RHIResourceView*` | object-id SRV。 |
+| `imguiCpuHandle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | ImGui 颜色纹理描述符 CPU 句柄。 |
+| `imguiGpuHandle` | `D3D12_GPU_DESCRIPTOR_HANDLE` | ImGui 颜色纹理描述符 GPU 句柄。 |
+| `textureId` | `ImTextureID` | ImGui 展示颜色纹理使用的纹理 id。 |
+| `colorState` | `RHI::ResourceStates` | 当前颜色纹理状态。 |
+| `objectIdState` | `RHI::ResourceStates` | 当前 object-id 纹理状态。 |
+| `hasValidObjectIdFrame` | `bool` | 当前 object-id 帧是否可用于拾取 / outline。 |
+
+## 当前语义
+
+- 这是一份由 [ViewportHostService](../ViewportHostService/ViewportHostService.md) 持有的完整视口资源包。
+- `objectId*` 字段主要服务于 Scene View；Game View 当前不会要求它们存在。
+- `colorState` 与 `objectIdState` 由渲染流程 helper 在成功渲染后回写。
+
+## 相关文档
+
+- [ViewportHostRenderTargets](ViewportHostRenderTargets.md)
+- [BuildViewportRenderTargetsReuseQuery](BuildViewportRenderTargetsReuseQuery.md)
+- [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md)