6.6 KiB
6.6 KiB
Viewport
命名空间: XCEngine::Editor
类型: module
源目录: editor/src/Viewport/
描述: 编辑器视口基础设施模块，负责 Scene / Game 视口请求、隐藏编辑器相机、对象选择、overlay 构建与 gizmo 交互底层。
概述
Viewport 是当前 Editor 里最接近“场景视图内核”的一层。SceneViewPanel 和 GameViewPanel 都不直接管理渲染目标、场景相机请求或对象 ID 读回，而是通过这层完成：
- 视口纹理请求与尺寸管理。
- Scene View 专用编辑器相机控制。
- Scene View 的对象 ID picking。
- 场景图标、相机视锥、方向光辅助线等 overlay 数据构建。
- Move / Rotate / Scale gizmo 的命中、拖拽和绘制数据生成。
- Scene View GPU pass 注入。
从设计上看，这层相当于“Editor 视口宿主服务 + 交互 helper”的组合，而不是单一类。
设计要点
SceneViewPanel只负责 UI、快捷键和交互编排，真正的视口资源管理放在 ViewportHostService。- Scene View 不直接复用场景内相机，而是维护一台隐藏的编辑器相机，这和 Unity Scene View 的思路一致，能把编辑视角与游戏相机解耦。
- 当前 Scene View 的可视化链路已经拆成三段：
- editor-owned post-scene pass: SceneViewportGridPass 与 SceneViewportSelectionOutlinePass
- GPU 世界 overlay pass: SceneViewportEditorOverlayPass
- ImGui 前端 HUD / 交互 overlay: SceneViewportOverlayRenderer
- 宿主服务内部还把 Scene View overlay 再拆成:
- 可缓存的基础 editor overlay
- hit test 用的 interaction overlay
- 渲染阶段追加的 transient gizmo overlay
- gizmo 的“可视几何构建”和“鼠标命中”当前已经拆成 SceneViewportOverlayHandleBuilder 与 SceneViewportOverlayHitTester 两层。
- 当前
SceneViewPanel的点击选取主路径是对象 ID 读回，不是 CPU mesh 射线拾取；后者目前保留在 SceneViewportPicker 里作为独立 helper。
当前实现边界
Viewport是editor/src下的 Editor 私有模块，不是engine/include/XCEngine/**那种 Runtime 公共 API。- 当前 Scene View 的 GPU pass 只在
D3D12后端上真正可渲染。 SceneViewportCameraController具备 orbit 输入能力，但当前SceneViewPanel主要驱动的是 look / pan / fly / focus selection。
目录结构
| 页面 | 说明 |
|---|---|
| IViewportHostService | Scene / Game 视口宿主服务抽象，以及共享输入/输出数据结构。 |
| SceneViewportCameraController | 隐藏编辑器相机的轨道/飞行控制器。 |
| SceneViewportEditorOverlayData | 世界 overlay 基元与帧缓存数据。 |
| SceneViewportMath | 视口投影、拖拽平面、屏幕方向等数学 helper。 |
| SceneViewportMoveGizmo | 位移 gizmo。 |
| SceneViewportOrientationGizmo | 右上角朝向立方体与点击对齐 helper。 |
| SceneViewportOverlayHandleBuilder | 把 gizmo draw data 转成屏幕三角形和 handle 记录。 |
| SceneViewportOverlayHitTester | 基于 handle 记录做鼠标命中选择。 |
| SceneViewportOverlayBuilder | 构建 Scene View 世界 overlay 帧数据。 |
| SceneViewportOverlayRenderer | 在 ImGui draw list 上绘制 gizmo 与前端 overlay。 |
| SceneViewportRenderPlan | Scene View 渲染前的 post-scene passes、overlay pass 与 clear-color override 计划对象。 |
| SceneViewportShaderPaths | Scene View 专用 shader 资源路径 helper。 |
| SceneViewportPicker | CPU 射线拾取 helper。 |
| SceneViewportRotateGizmo | 旋转 gizmo。 |
| SceneViewportScaleGizmo | 缩放 gizmo。 |
| SceneViewportTransformGizmoFrameBuilder | 组装每帧 transform gizmo 选择状态、pivot 和三类 gizmo context。 |
| ViewportHostRenderFlowUtils | Scene / Game 视口渲染流程辅助函数。 |
| ViewportHostRenderTargets | 视口颜色 / 深度 / object-id 目标创建与销毁。 |
| ViewportHostService | IViewportHostService 的当前实现。 |
| ViewportHostSurfaceUtils | render surface、重用判断和像素坐标工具。 |
| ViewportObjectIdPicker | object-id 读回与颜色解码 helper。 |
| Passes | Scene View editor-owned post-scene / overlay pass 子目录。 |
与上层面板的关系
- SceneViewPanel 是当前
Viewport模块最主要的调用方。 SceneViewPanel通过 ViewportPanelContent 统一请求纹理并建立交互表面。GameViewPanel也会复用IViewportHostService::RequestViewport(...)这条链路，但不会进入 Scene gizmo / picking 流程。