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

Viewport

命名空间: XCEngine::Editor

类型: module

源目录: editor/src/Viewport/

描述: 编辑器视口基础设施模块，负责 Scene / Game 视口请求、Scene View 相机与 picking、overlay 数据装配，以及 transform gizmo 的命中与渲染辅助链路。

概览

Viewport 是当前 Editor 里最接近“Scene / Game 视口运行时”的一层。 SceneViewPanel 和 GameViewPanel 本身主要做 UI 编排；真正的视口宿主、overlay 合成和 gizmo 辅助逻辑都在这里。

当前职责拆分

• IViewportHostService 统一抽象 Scene / Game 视口宿主服务。
• ViewportHostService 当前宿主实现，持有 editor camera、render target 与 Scene View overlay 缓存。
• SceneViewportCameraController 维护 Scene View 相机的焦点、距离、朝向和飞行速度，并把结果写回隐藏相机变换。
• SceneViewportMath 提供投影、屏幕方向、拖拽平面和距离计算等几何 helper，供 gizmo / overlay / picker 共用。
• SceneViewportPicker 提供 CPU 射线选取 helper，当前更多用于辅助 gizmo 命中和保留的几何拾取路径。
• ViewportObjectIdPicker 封装 Scene View object-id 读回请求构建、像素坐标映射与颜色解码，是当前主点击选取链路的底层 helper。
• SceneViewportHudOverlay 负责前端 HUD / orientation gizmo 的构造、绘制和命中。
• SceneViewportOrientationGizmo 提供右上角朝向 gizmo 的绘制和点击命中，供 HUD overlay 复用。
• SceneViewportInteractionResolver 把 HUD 命中与 overlay handle 命中合并成统一交互结果。
• SceneViewportInteractionActions 把交互结果折叠成 hover / click action，并分发 selection / orientation 对齐。
• SceneViewportEditorModes 收口工具模式、pivot 模式与变换空间模式枚举。
• SceneViewportInteractionFrame 组装每帧 tool state、frame geometry、interaction frame state，并收口焦点决策与最终 presentation helper。
• SceneViewportNavigation 处理工具快捷键、look/pan 导航状态、输入捕获和 SceneViewportInput 构建。
• SceneViewportChrome 负责 Scene View 顶部 toolbar、左侧工具按钮 overlay，以及工具切换命令折叠与执行。
• SceneViewportEditorOverlayData 定义 world line、sprite、screen triangle 与 handle record 组成的 canonical overlay 帧协议。
• SceneViewportOverlayProviders 定义相机 / 灯光 / transform gizmo overlay provider 接口、registry 与默认工厂。
• SceneViewportOverlayBuilder 按 provider registry 聚合一帧 Scene View editor overlay 数据。
• SceneViewportOverlayHitTester 基于 overlay handleRecords 对鼠标位置做命中测试，并给 resolver 提供候选结果。
• SceneViewportMoveGizmo 处理轴向 / 平面位移 gizmo 的绘制数据、命中与多对象拖拽事务。
• SceneViewportRotateGizmo 处理旋转环、视图环、共享 pivot 旋转和交互式撤销。
• SceneViewportScaleGizmo 处理轴向缩放与 uniform 缩放，并把鼠标位移映射到局部缩放值。
• SceneViewportOverlayHandleBuilder 把 gizmo overlay state 转成 screenTriangles 与 handleRecords。
• SceneViewportTransformGizmoFrameBuilder 组装每帧 move / rotate / scale gizmo context。
• SceneViewportTransformGizmoCoordinator 在 SceneViewPanel 与宿主服务之间桥接 gizmo overlay 提交和 begin / update / end 生命周期命令。

与面板层的关系

• SceneViewPanel 是当前 Viewport 模块的主调用方。
• GameViewPanel 也会复用 RequestViewport(...) 这一层，但不会进入 Scene gizmo / picking 主链路。

当前边界

• 这里是 editor 内部模块，不是 runtime public API。
• transform gizmo 的“gizmo overlay state -> overlay frame data -> hit-test / render”目前已经拆成多层 helper，不应再按旧口径理解为某个单一 renderer 直接完成全部工作。

相关文档

• Editor
• SceneViewPanel
• SceneViewportCameraController
• SceneViewportMath
• SceneViewportPicker
• ViewportObjectIdPicker
• SceneViewportChrome
• SceneViewportHudOverlay
• SceneViewportOrientationGizmo
• SceneViewportEditorOverlayData
• SceneViewportOverlayProviders
• SceneViewportOverlayBuilder
• SceneViewportOverlayHitTester
• SceneViewportMoveGizmo
• SceneViewportRotateGizmo
• SceneViewportScaleGizmo
• SceneView Interaction And Gizmo Model
• Scene View Render Plan And Failure Flow