docs: sync editor viewport host docs

docs/api/XCEngine/Editor/panels/SceneViewPanel/Render.md

@@ -0,0 +1,116 @@
+# SceneViewPanel::Render
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method`
+
+**源文件**: `editor/src/panels/SceneViewPanel.h`
+
+## 签名
+
+```cpp
+void Render() override;
+```
+
+## 作用
+
+绘制并驱动完整的 Scene View：工具栏、工具切换、视口交互、对象选择、相机导航、transform gizmo 拖拽，以及 gizmo overlay state 提交与 HUD 绘制。
+
+## 当前实现行为
+
+### 1. 工具栏与视口表面
+
+当前会先：
+
+- 绘制顶部 `Pivot / Center`、`Global / Local` toolbar
+- 调用 `RenderViewportPanelContent(...)` 申请 `Scene` 视口纹理
+- 绘制左侧工具条，并处理 `Q/W/E/R` 快捷键
+
+如果工具切换发生，还会先取消当前活动 gizmo 的拖拽状态，避免旧工具继续持有输入。
+
+### 2. 首次刷新 gizmo 上下文
+
+当视口可交互时，会先读取：
+
+- `viewportHostService->GetSceneViewOverlayData()`
+
+然后调用 `RefreshSceneViewportTransformGizmos(...)`，按当前：
+
+- selection
+- pivot mode
+- transform space
+- tool mode
+- 鼠标位置
+
+生成 move / rotate / scale 三套 gizmo context。
+
+### 3. 命中仲裁
+
+当前命中流程不是直接点击某个控件，而是先：
+
+1. 用 `BuildSceneViewportTransformGizmoHandleBuildInputs(...)` 组装本帧 gizmo 输入
+2. 用 `BuildSceneViewportTransformGizmoOverlayState(...)` 构造当前帧 gizmo state
+3. 先调用 `SetSceneViewTransformGizmoOverlayState(...)`
+4. 再从 `GetSceneViewEditorOverlayFrameData(...)` 拿到“editor overlay + gizmo handle”合成帧数据
+5. 用 `ResolveSceneViewportInteraction(...)` 做 overlay / orientation gizmo 的统一命中仲裁
+
+这一步最终会决定当前左键点击到底落到：
+
+- transform gizmo
+- orientation gizmo
+- scene icon
+- object-id picking 回退路径
+
+### 4. 选择、拖拽与导航
+
+命中结果解析完成后，当前实现会：
+
+- 命中 gizmo 时调用 `TryBeginDrag(...)`
+- 命中 orientation gizmo 时调用 `AlignSceneViewToOrientationAxis(...)`
+- 命中 scene icon 时直接改选中对象
+- 都没命中时调用 `PickSceneViewEntity(...)`
+
+导航侧则会维护：
+
+- 右键 look
+- 中键或 `ViewMove` 左键 pan
+- `WASDQE` 飞行
+- `F` focus selection
+
+并把这些状态整理成 `SceneViewportInput` 回传给 `UpdateSceneViewInput(...)`。
+
+### 5. 提交最终 gizmo state 并绘制 HUD
+
+当视口图像存在时，当前实现会再次刷新一次 gizmo 上下文，然后：
+
+1. 重新用 `BuildSceneViewportTransformGizmoHandleBuildInputs(...)` 组装最新 gizmo 输入
+2. 再次调用 `SetSceneViewTransformGizmoOverlayState(...)`
+3. 最后调用 `DrawSceneViewportHudOverlay(...)` 绘制前端 HUD / orientation gizmo
+
+这里的关键点是：第二次写回 gizmo state 后，真正的 Scene View render path 还没跑。后续 `ViewportHostService::RenderRequestedViewports(...)` 会感知 overlay cache 已变脏，并按最新 gizmo state 重建 overlay frame data，再交给 `SceneViewportEditorOverlayPass`。
+
+也就是说，transform gizmo 的最终出图已经不再走独立的 transient overlay API，而是走“提交 gizmo state -> 宿主服务重建合成 frame data -> overlay pass 渲染”的主路径。
+
+### 6. 动作观察
+
+渲染末尾会调用：
+
+```cpp
+Actions::ObserveInactiveActionRoute(*m_context);
+```
+
+保证该面板即使没有显式激活 action route，也能继续参与统一动作观察。
+
+## 当前实现边界
+
+- orbit 输入当前仍固定为 `false`
+- `Transform` 组合工具下的 scale 仍是 `uniformOnly`
+- `Render()` 仍然承担大量交互编排职责，因此它更像 Scene View 壳层主流程，而不是单纯 UI 绘制函数
+
+## 相关文档
+
+- [SceneViewPanel](SceneViewPanel.md)
+- [Constructor](Constructor.md)
+- [ViewportPanelContent](../ViewportPanelContent/ViewportPanelContent.md)
+- [IViewportHostService](../../Viewport/IViewportHostService/IViewportHostService.md)
+- [SceneView Interaction And Gizmo Model](../../../../_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md)