# Viewport

**命名空间**: `XCEngine::Editor`

**类型**: `module`

**源目录**: `editor/src/Viewport/`

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

## 概览

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

## 当前职责拆分

- [IViewportHostService](IViewportHostService/IViewportHostService.md)
  统一抽象 Scene / Game 视口宿主服务。
- [ViewportHostService](ViewportHostService/ViewportHostService.md)
  当前宿主实现，持有 editor camera、render target 与 Scene View overlay 缓存。
- [SceneViewportCameraController](SceneViewportCameraController/SceneViewportCameraController.md)
  维护 Scene View 相机的焦点、距离、朝向和飞行速度，并把结果写回隐藏相机变换。
- [SceneViewportMath](SceneViewportMath/SceneViewportMath.md)
  提供投影、屏幕方向、拖拽平面和距离计算等几何 helper，供 gizmo / overlay / picker 共用。
- [SceneViewportPicker](SceneViewportPicker/SceneViewportPicker.md)
  提供 CPU 射线选取 helper，当前更多用于辅助 gizmo 命中和保留的几何拾取路径。
- [ViewportObjectIdPicker](ViewportObjectIdPicker/ViewportObjectIdPicker.md)
  封装 Scene View object-id 读回请求构建、像素坐标映射与颜色解码，是当前主点击选取链路的底层 helper。
- [SceneViewportHudOverlay](SceneViewportHudOverlay/SceneViewportHudOverlay.md)
  负责前端 HUD / orientation gizmo 的构造、绘制和命中。
- [SceneViewportOrientationGizmo](SceneViewportOrientationGizmo/SceneViewportOrientationGizmo.md)
  提供右上角朝向 gizmo 的绘制和点击命中，供 HUD overlay 复用。
- [SceneViewportInteractionResolver](SceneViewportInteractionResolver/SceneViewportInteractionResolver.md)
  把 HUD 命中与 overlay handle 命中合并成统一交互结果。
- [SceneViewportInteractionActions](SceneViewportInteractionActions/SceneViewportInteractionActions.md)
  把交互结果折叠成 hover / click action，并分发 selection / orientation 对齐。
- [SceneViewportEditorModes](SceneViewportEditorModes/SceneViewportEditorModes.md)
  收口工具模式、pivot 模式与变换空间模式枚举。
- [SceneViewportInteractionFrame](SceneViewportInteractionFrame/SceneViewportInteractionFrame.md)
  组装每帧 tool state、frame geometry、interaction frame state，并收口焦点决策与最终 presentation helper。
- [SceneViewportNavigation](SceneViewportNavigation/SceneViewportNavigation.md)
  处理工具快捷键、look/pan 导航状态、输入捕获和 `SceneViewportInput` 构建。
- [SceneViewportChrome](SceneViewportChrome/SceneViewportChrome.md)
  负责 Scene View 顶部 toolbar、左侧工具按钮 overlay，以及工具切换命令折叠与执行。
- [SceneViewportEditorOverlayData](SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)
  定义 world line、sprite、screen triangle 与 handle record 组成的 canonical overlay 帧协议。
- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md)
  统一 Scene View editor overlay frame 的缓存状态、内容签名与重建判定规则。
- [SceneViewportResourcePaths](SceneViewportResourcePaths/SceneViewportResourcePaths.md)
  统一解析 Scene View grid shader、outline shader 与 editor icon 的资源绝对路径。
- [SceneViewportShaderPaths](SceneViewportShaderPaths/SceneViewportShaderPaths.md)
  当前只保留为兼容 include 层，真实资源路径 owner 已收口到 `SceneViewportResourcePaths`。
- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md)
  把 `SceneViewportOverlaySpriteTextureKind` 解析为 editor icon 资源路径、RGBA 像素和可复用的纹理 descriptor set 缓存。
- [SceneViewportPassSpecs](SceneViewportPassSpecs/SceneViewportPassSpecs.md)
  定义 Scene View 网格与选中描边的 Editor 侧规格结构，并提供到 runtime pass 规格的轻量转换。
- [SceneViewportOverlayProviders](SceneViewportOverlayProviders/SceneViewportOverlayProviders.md)
  定义相机 / 灯光 / transform gizmo overlay provider 接口、registry 与默认工厂。
- [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
  按 provider registry 聚合一帧 Scene View editor overlay 数据。
- [SceneViewportRenderPlan](SceneViewportRenderPlan/SceneViewportRenderPlan.md)
  规划 Scene View 本帧要追加的 post-scene pass、overlay pass 与 clear-color override。
- [SceneViewportRenderPassBundle](SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md)
  持有 grid / outline / overlay 三类 pass renderer，并为宿主服务提供可直接调用的 render-plan 构建入口。
- [ViewportHostRenderFlowUtils](ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md)
  收口失败回退、Scene View request 基础接线和渲染成功后的状态回写规则。
- [SceneViewportOverlayHitTester](SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md)
  基于 overlay `handleRecords` 对鼠标位置做命中测试，并给 resolver 提供候选结果。
- [SceneViewportMoveGizmo](SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)
  处理轴向 / 平面位移 gizmo 的绘制数据、命中与多对象拖拽事务。
- [SceneViewportRotateGizmo](SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)
  处理旋转环、视图环、共享 pivot 旋转和交互式撤销。
- [SceneViewportScaleGizmo](SceneViewportScaleGizmo/SceneViewportScaleGizmo.md)
  处理轴向缩放与 uniform 缩放，并把鼠标位移映射到局部缩放值。
- [SceneViewportOverlayHandleBuilder](SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md)
  把 gizmo overlay state 转成 `screenTriangles` 与 `handleRecords`。
- [SceneViewportTransformGizmoFrameBuilder](SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameBuilder.md)
  组装每帧 move / rotate / scale gizmo context。
- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md)
  在 `SceneViewPanel` 与宿主服务之间桥接 gizmo overlay 提交和 begin / update / end 生命周期命令。

## 与面板层的关系

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

## 当前边界

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

## 相关文档

- [Editor](../Editor.md)
- [SceneViewPanel](../panels/SceneViewPanel/SceneViewPanel.md)
- [SceneViewportCameraController](SceneViewportCameraController/SceneViewportCameraController.md)
- [SceneViewportMath](SceneViewportMath/SceneViewportMath.md)
- [SceneViewportPicker](SceneViewportPicker/SceneViewportPicker.md)
- [ViewportObjectIdPicker](ViewportObjectIdPicker/ViewportObjectIdPicker.md)
- [SceneViewportChrome](SceneViewportChrome/SceneViewportChrome.md)
- [SceneViewportHudOverlay](SceneViewportHudOverlay/SceneViewportHudOverlay.md)
- [SceneViewportOrientationGizmo](SceneViewportOrientationGizmo/SceneViewportOrientationGizmo.md)
- [SceneViewportEditorOverlayData](SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)
- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md)
- [SceneViewportResourcePaths](SceneViewportResourcePaths/SceneViewportResourcePaths.md)
- [SceneViewportShaderPaths](SceneViewportShaderPaths/SceneViewportShaderPaths.md)
- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md)
- [SceneViewportPassSpecs](SceneViewportPassSpecs/SceneViewportPassSpecs.md)
- [SceneViewportOverlayProviders](SceneViewportOverlayProviders/SceneViewportOverlayProviders.md)
- [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md)
- [SceneViewportRenderPlan](SceneViewportRenderPlan/SceneViewportRenderPlan.md)
- [SceneViewportRenderPassBundle](SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md)
- [ViewportHostRenderFlowUtils](ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md)
- [SceneViewportOverlayHitTester](SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md)
- [SceneViewportMoveGizmo](SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)
- [SceneViewportRotateGizmo](SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)
- [SceneViewportScaleGizmo](SceneViewportScaleGizmo/SceneViewportScaleGizmo.md)
- [SceneView Interaction And Gizmo Model](../../../_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md)
- [Scene View Render Plan And Failure Flow](../../../_guides/Editor/Scene-Viewport-Render-Plan-And-Failure-Flow.md)