docs: add viewport transform gizmo frame docs
This commit is contained in:
@@ -0,0 +1,31 @@
|
||||
# BuildBeginSceneViewportTransformGizmoLifecycleCommand
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportTransformGizmoLifecycleCommand BuildBeginSceneViewportTransformGizmoLifecycleCommand(
|
||||
const SceneViewportInteractionActions& actions);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
根据点击动作生成 gizmo 拖拽 begin 命令。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 若 `actions.beginTransformGizmo == false`，返回空命令。
|
||||
- 否则返回：
|
||||
- `stage = Begin`
|
||||
- `gizmoKind = actions.hoveredGizmoKind`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md)
|
||||
- [BuildFrameSceneViewportTransformGizmoLifecycleCommand](BuildFrameSceneViewportTransformGizmoLifecycleCommand.md)
|
||||
- [SceneViewportInteractionActions](../SceneViewportInteractionActions/SceneViewportInteractionActions.md)
|
||||
@@ -0,0 +1,36 @@
|
||||
# BuildFrameSceneViewportTransformGizmoLifecycleCommand
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportTransformGizmoLifecycleCommand BuildFrameSceneViewportTransformGizmoLifecycleCommand(
|
||||
SceneViewportActiveGizmoKind activeGizmoKind,
|
||||
bool leftMouseDown);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
根据当前 active gizmo 和鼠标按键状态生成本帧的 update / end 生命周期命令。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 若 `activeGizmoKind == None`，返回空命令。
|
||||
- 否则：
|
||||
- `leftMouseDown == true` 时生成 `Update`
|
||||
- `leftMouseDown == false` 时生成 `End`
|
||||
- 返回命令中的 `gizmoKind` 直接取 `activeGizmoKind`。
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 update / end 两种映射。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
|
||||
- [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md)
|
||||
@@ -0,0 +1,37 @@
|
||||
# BuildSceneViewportTransformGizmoFrameOptions
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportTransformGizmoFrameOptions BuildSceneViewportTransformGizmoFrameOptions(
|
||||
bool useCenterPivot,
|
||||
bool localSpace,
|
||||
bool usingTransformTool,
|
||||
bool showingMoveGizmo,
|
||||
bool showingRotateGizmo,
|
||||
bool showingScaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
把 gizmo 刷新所需的离散布尔参数收口成一个 `SceneViewportTransformGizmoFrameOptions`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 当前只是把输入参数逐字段拷贝到返回结构。
|
||||
- 不做额外推导或一致性校验。
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了各布尔字段会被原样拷贝。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoFrameOptions](SceneViewportTransformGizmoFrameOptions.md)
|
||||
- [BuildSceneViewportToolState](../SceneViewportInteractionFrame/BuildSceneViewportToolState.md)
|
||||
@@ -0,0 +1,43 @@
|
||||
# BuildSceneViewportTransformGizmoOverlaySubmission
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportTransformGizmoOverlaySubmission BuildSceneViewportTransformGizmoOverlaySubmission(
|
||||
const SceneViewportTransformGizmoFrameState& frameState,
|
||||
bool showingMoveGizmo,
|
||||
const SceneViewportMoveGizmo& moveGizmo,
|
||||
bool showingRotateGizmo,
|
||||
const SceneViewportRotateGizmo& rotateGizmo,
|
||||
bool showingScaleGizmo,
|
||||
const SceneViewportScaleGizmo& scaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
从本帧 gizmo frame state 和三个 gizmo 对象构建可提交的 overlay submission。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 调用 `BuildSceneViewportTransformGizmoHandleBuildInputs(...)` 从可见 gizmo 和 frame context 提取 draw-data 输入。
|
||||
- 再调用 `BuildSceneViewportTransformGizmoOverlayState(...)` 构造 gizmo overlay state。
|
||||
- `activeGizmoKind` 则通过 `GetActiveSceneViewportGizmoKind(...)` 从三个 gizmo 当前状态求得。
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了：
|
||||
|
||||
- move gizmo 可被打包进 submission
|
||||
- `activeGizmoKind` 和 `GizmoActive()` 语义正确
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
|
||||
- [SceneViewportTransformGizmoOverlaySubmission](SceneViewportTransformGizmoOverlaySubmission.md)
|
||||
- [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md)
|
||||
@@ -0,0 +1,37 @@
|
||||
# BuildSceneViewportTransformGizmoRefreshRequest
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportTransformGizmoRefreshRequest BuildSceneViewportTransformGizmoRefreshRequest(
|
||||
IEditorContext& context,
|
||||
const SceneViewportOverlayData& overlay,
|
||||
const Math::Vector2& viewportSize,
|
||||
const Math::Vector2& mousePosition,
|
||||
const SceneViewportTransformGizmoFrameOptions& options);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
把当前帧 gizmo 刷新输入收口成 coordinator 可消费的 request。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- `context` 会以指针形式写入 `request.context`。
|
||||
- `overlay`、`viewportSize`、`mousePosition` 与 `options` 会被值拷贝到返回结构。
|
||||
- 该函数本身不做额外校验；请求是否有效由 `request.IsValid()` 判断。
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 context 指针、overlay、viewportSize、mousePosition 和 options 都会被正确拷贝。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md)
|
||||
- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md)
|
||||
@@ -0,0 +1,35 @@
|
||||
# CancelSceneViewportTransformGizmoFrame
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
void CancelSceneViewportTransformGizmoFrame(
|
||||
IEditorContext& context,
|
||||
SceneViewportMoveGizmo& moveGizmo,
|
||||
SceneViewportRotateGizmo& rotateGizmo,
|
||||
SceneViewportScaleGizmo& scaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
提供 coordinator 层的统一“取消当前 gizmo 拖拽”入口。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 当前只是转调 [CancelSceneViewportTransformGizmoDrags](../SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md)。
|
||||
- 不额外构建 frame state，也不生成 overlay submission。
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前会调用该入口，验证 coordinator 层可统一触发取消流程。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
|
||||
- [CancelSceneViewportTransformGizmoDrags](../SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md)
|
||||
@@ -0,0 +1,43 @@
|
||||
# ExecuteSceneViewportTransformGizmoLifecycleCommand
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
void ExecuteSceneViewportTransformGizmoLifecycleCommand(
|
||||
const SceneViewportTransformGizmoLifecycleCommand& command,
|
||||
IUndoManager& undoManager,
|
||||
const SceneViewportTransformGizmoFrameState& frameState,
|
||||
SceneViewportMoveGizmo& moveGizmo,
|
||||
SceneViewportRotateGizmo& rotateGizmo,
|
||||
SceneViewportScaleGizmo& scaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
把生命周期命令分发到 move / rotate / scale gizmo 对象。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 按 `command.gizmoKind` 分发：
|
||||
- `Move` -> `TryBeginDrag / UpdateDrag / EndDrag`
|
||||
- `Rotate` -> `TryBeginDrag / UpdateDrag / EndDrag`
|
||||
- `Scale` -> `TryBeginDrag / UpdateDrag / EndDrag`
|
||||
- 各分支会从 `frameState` 中取对应 context。
|
||||
- `None` 或未识别值时直接返回。
|
||||
|
||||
## 当前边界
|
||||
|
||||
- 该函数不负责生成命令，只负责执行。
|
||||
- 它也不处理 hover / selection / orientation click，那些在 `SceneViewportInteractionActions` 一侧。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
|
||||
- [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md)
|
||||
- [SceneViewportInteractionActions](../SceneViewportInteractionActions/SceneViewportInteractionActions.md)
|
||||
@@ -0,0 +1,38 @@
|
||||
# RefreshAndSubmitSceneViewportTransformGizmoFrame
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportTransformGizmoFrameUpdate RefreshAndSubmitSceneViewportTransformGizmoFrame(
|
||||
IViewportHostService& viewportHostService,
|
||||
const SceneViewportTransformGizmoRefreshRequest& request,
|
||||
SceneViewportMoveGizmo& moveGizmo,
|
||||
SceneViewportRotateGizmo& rotateGizmo,
|
||||
SceneViewportScaleGizmo& scaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
刷新一帧 transform gizmo，并立即把 overlay submission 提交给 viewport host service。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 先调用 [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) 获得 `SceneViewportTransformGizmoFrameUpdate`。
|
||||
- 再调用 [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md) 把 `update.overlaySubmission` 写回宿主服务。
|
||||
- 最终返回同一份 `update`，供调用方继续消费 `frameState`。
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了它会同时刷新 move gizmo 上下文，并把 submission 写入 `IViewportHostService`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md)
|
||||
- [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md)
|
||||
- [SceneViewportInteractionFrame](../SceneViewportInteractionFrame/SceneViewportInteractionFrame.md)
|
||||
@@ -0,0 +1,33 @@
|
||||
# RefreshSceneViewportTransformGizmoFrame
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportTransformGizmoFrameUpdate RefreshSceneViewportTransformGizmoFrame(
|
||||
const SceneViewportTransformGizmoRefreshRequest& request,
|
||||
SceneViewportMoveGizmo& moveGizmo,
|
||||
SceneViewportRotateGizmo& rotateGizmo,
|
||||
SceneViewportScaleGizmo& scaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
刷新一帧 transform gizmo，并同时生成可提交给宿主服务的 overlay submission。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 如果 `request.IsValid()` 为 `false`，当前直接返回默认构造的 `SceneViewportTransformGizmoFrameUpdate`。
|
||||
- 否则先调用 [RefreshSceneViewportTransformGizmos](../SceneViewportTransformGizmoFrameBuilder/RefreshSceneViewportTransformGizmos.md) 得到 `frameState`。
|
||||
- 然后调用 [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) 生成 `overlaySubmission`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoFrameUpdate](SceneViewportTransformGizmoFrameUpdate.md)
|
||||
- [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md)
|
||||
- [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md)
|
||||
@@ -0,0 +1,54 @@
|
||||
# SceneViewportTransformGizmoCoordinator
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `structs + enum + free functions`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
**描述**: 负责把 gizmo frame state 收口成可提交的 overlay state，并把 Scene View 中的 gizmo begin / update / end 推进收口成统一生命周期命令。
|
||||
|
||||
## 概览
|
||||
|
||||
这层 helper 位于 `SceneViewPanel` 与 `ViewportHostService` / 各 gizmo 对象之间。
|
||||
它当前解决两件事：
|
||||
|
||||
- overlay 提交：把本帧 gizmo 状态转成 `SceneViewportTransformGizmoOverlaySubmission`
|
||||
- 生命周期推进：把 begin / update / end 统一成 `SceneViewportTransformGizmoLifecycleCommand`
|
||||
|
||||
## 公开类型与函数
|
||||
|
||||
| 成员 | 说明 |
|
||||
|------|------|
|
||||
| [SceneViewportTransformGizmoFrameOptions](SceneViewportTransformGizmoFrameOptions.md) | 每帧 gizmo 刷新所需的布尔配置。 |
|
||||
| [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md) | 一次 gizmo frame 刷新的完整输入包。 |
|
||||
| [SceneViewportTransformGizmoOverlaySubmission](SceneViewportTransformGizmoOverlaySubmission.md) | 提交给宿主服务的 overlay submission。 |
|
||||
| [SceneViewportTransformGizmoLifecycleStage](SceneViewportTransformGizmoLifecycleStage.md) | gizmo 生命周期阶段枚举。 |
|
||||
| [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md) | begin / update / end 命令包。 |
|
||||
| [SceneViewportTransformGizmoFrameUpdate](SceneViewportTransformGizmoFrameUpdate.md) | 一次 gizmo frame 刷新的完整输出。 |
|
||||
| [BuildSceneViewportTransformGizmoFrameOptions](BuildSceneViewportTransformGizmoFrameOptions.md) | 构建每帧 gizmo 布尔配置。 |
|
||||
| [BuildSceneViewportTransformGizmoRefreshRequest](BuildSceneViewportTransformGizmoRefreshRequest.md) | 构建 gizmo frame 刷新请求。 |
|
||||
| [CancelSceneViewportTransformGizmoFrame](CancelSceneViewportTransformGizmoFrame.md) | 取消当前帧正在进行的 gizmo 拖拽。 |
|
||||
| [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) | 刷新 gizmo frame 并生成 overlay submission。 |
|
||||
| [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md) | 刷新 gizmo frame 并直接提交到 viewport host service。 |
|
||||
| [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) | 从 frame state 和 gizmo 对象生成 overlay submission。 |
|
||||
| [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md) | 把 overlay submission 写回 viewport host service。 |
|
||||
| [BuildBeginSceneViewportTransformGizmoLifecycleCommand](BuildBeginSceneViewportTransformGizmoLifecycleCommand.md) | 根据交互 action 生成 begin 命令。 |
|
||||
| [BuildFrameSceneViewportTransformGizmoLifecycleCommand](BuildFrameSceneViewportTransformGizmoLifecycleCommand.md) | 根据 active gizmo 和鼠标状态生成 update / end 命令。 |
|
||||
| [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md) | 把生命周期命令分发到 move / rotate / scale gizmo。 |
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前覆盖了：
|
||||
|
||||
- frame options / refresh request 构造
|
||||
- refresh + submit 包装调用
|
||||
- begin / update / end 命令生成
|
||||
- overlay submission 构造
|
||||
- overlay submission 提交到 `IViewportHostService`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Viewport](../Viewport.md)
|
||||
- [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md)
|
||||
- [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md)
|
||||
@@ -0,0 +1,30 @@
|
||||
# SceneViewportTransformGizmoFrameOptions
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `useCenterPivot` | `bool` | 是否使用中心 pivot。 |
|
||||
| `localSpace` | `bool` | 是否使用局部坐标空间。 |
|
||||
| `usingTransformTool` | `bool` | 是否处于联合 `Transform` 工具模式。 |
|
||||
| `showingMoveGizmo` | `bool` | 本帧是否显示 move gizmo。 |
|
||||
| `showingRotateGizmo` | `bool` | 本帧是否显示 rotate gizmo。 |
|
||||
| `showingScaleGizmo` | `bool` | 本帧是否显示 scale gizmo。 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 这是传给 gizmo frame refresh 的轻量布尔配置。
|
||||
- 它把工具模式、pivot 模式和空间模式压平成 gizmo 刷新层真正消费的参数。
|
||||
- [BuildSceneViewportToolState](../SceneViewportInteractionFrame/BuildSceneViewportToolState.md) 当前会构建并下发这份配置。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuildSceneViewportTransformGizmoFrameOptions](BuildSceneViewportTransformGizmoFrameOptions.md)
|
||||
- [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md)
|
||||
- [SceneViewportToolState](../SceneViewportInteractionFrame/SceneViewportToolState.md)
|
||||
@@ -0,0 +1,25 @@
|
||||
# SceneViewportTransformGizmoFrameUpdate
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `frameState` | `SceneViewportTransformGizmoFrameState` | 本帧 gizmo 刷新结果。 |
|
||||
| `overlaySubmission` | `SceneViewportTransformGizmoOverlaySubmission` | 可继续提交给宿主服务的 overlay submission。 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 这是 `RefreshSceneViewportTransformGizmoFrame(...)` 与 `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)` 的统一返回结构。
|
||||
- 它同时保留 frame builder 的原始输出和 overlay 提交层的收口结果。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md)
|
||||
- [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md)
|
||||
- [SceneViewportTransformGizmoFrameState](../SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameState.md)
|
||||
@@ -0,0 +1,25 @@
|
||||
# SceneViewportTransformGizmoLifecycleCommand
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `stage` | `SceneViewportTransformGizmoLifecycleStage` | 本帧生命周期阶段。 |
|
||||
| `gizmoKind` | `SceneViewportActiveGizmoKind` | 要执行的 gizmo 类型。 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- `HasWork()` 当前要求 `stage != None` 且 `gizmoKind != None`。
|
||||
- 这是一份轻量命令对象，真正的 begin / update / end 分发由 `ExecuteSceneViewportTransformGizmoLifecycleCommand(...)` 完成。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
|
||||
- [SceneViewportTransformGizmoLifecycleStage](SceneViewportTransformGizmoLifecycleStage.md)
|
||||
- [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md)
|
||||
@@ -0,0 +1,21 @@
|
||||
# SceneViewportTransformGizmoLifecycleStage
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `enum class`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 枚举值
|
||||
|
||||
| 值 | 含义 |
|
||||
|------|------|
|
||||
| `None` | 无工作。 |
|
||||
| `Begin` | 开始拖拽。 |
|
||||
| `Update` | 持续更新拖拽。 |
|
||||
| `End` | 结束拖拽。 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
|
||||
- [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md)
|
||||
@@ -0,0 +1,24 @@
|
||||
# SceneViewportTransformGizmoOverlaySubmission
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `overlayState` | `SceneViewportTransformGizmoOverlayState` | 本帧 gizmo overlay state。 |
|
||||
| `activeGizmoKind` | `SceneViewportActiveGizmoKind` | 当前 active gizmo 类型。 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- `GizmoActive()` 当前仅检查 `activeGizmoKind != None`。
|
||||
- 该结构把“本帧要提交给宿主服务的 overlay 数据”和“当前是否已有 gizmo 处于 active 状态”打包在一起。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md)
|
||||
- [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md)
|
||||
@@ -0,0 +1,29 @@
|
||||
# SceneViewportTransformGizmoRefreshRequest
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `context` | `IEditorContext*` | 当前 editor context。 |
|
||||
| `overlay` | `SceneViewportOverlayData` | 当前帧 Scene View overlay 基础数据。 |
|
||||
| `viewportSize` | `Math::Vector2` | 当前视口尺寸。 |
|
||||
| `mousePosition` | `Math::Vector2` | 当前鼠标位置。 |
|
||||
| `options` | `SceneViewportTransformGizmoFrameOptions` | 本帧 gizmo 刷新配置。 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 这是 coordinator 刷新一帧 gizmo 所需的完整输入包。
|
||||
- `IsValid()` 当前只要求 `context != nullptr`。
|
||||
- 其余字段即使为默认值，也允许下游继续刷新，只是会得到默认 / 空 gizmo frame state。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuildSceneViewportTransformGizmoRefreshRequest](BuildSceneViewportTransformGizmoRefreshRequest.md)
|
||||
- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md)
|
||||
- [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md)
|
||||
@@ -0,0 +1,34 @@
|
||||
# SubmitSceneViewportTransformGizmoOverlaySubmission
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
void SubmitSceneViewportTransformGizmoOverlaySubmission(
|
||||
IViewportHostService& viewportHostService,
|
||||
const SceneViewportTransformGizmoOverlaySubmission& submission);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
把构造好的 overlay submission 写入宿主服务。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
当前实现非常薄，只做一件事：
|
||||
|
||||
```cpp
|
||||
viewportHostService.SetSceneViewTransformGizmoOverlayState(submission.overlayState);
|
||||
```
|
||||
|
||||
它不会自行触发 frame data 重建；真正的重建发生在宿主服务下一次 `GetSceneViewEditorOverlayFrameData(...)` 时。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md)
|
||||
- [IViewportHostService Scene View Overlay Contracts](../IViewportHostService/SceneView-Overlay-Contracts.md)
|
||||
@@ -0,0 +1,36 @@
|
||||
# BuildMoveGizmoContext
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportMoveGizmoContext BuildMoveGizmoContext(
|
||||
const SceneViewportSelectionGizmoState& selectionState,
|
||||
const SceneViewportOverlayData& overlay,
|
||||
const Math::Vector2& viewportSize,
|
||||
const Math::Vector2& mousePosition,
|
||||
bool localSpace);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
根据当前选择状态和 Scene View overlay 信息构建 move gizmo 更新上下文。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 会写入 `overlay`、`viewportSize` 和 `mousePosition`。
|
||||
- `selectedObject` 取 `selectionState.primaryObject`。
|
||||
- `selectedObjects` 会完整带入，供 move gizmo 处理多对象平移。
|
||||
- `pivotWorldPosition` 直接复用 `selectionState.pivotWorldPosition`。
|
||||
- `axisOrientation` 在 local-space 模式下取主对象稳定世界旋转，否则取单位四元数。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md)
|
||||
- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
|
||||
- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
|
||||
@@ -0,0 +1,39 @@
|
||||
# BuildRotateGizmoContext
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportRotateGizmoContext BuildRotateGizmoContext(
|
||||
const SceneViewportSelectionGizmoState& selectionState,
|
||||
const SceneViewportOverlayData& overlay,
|
||||
const Math::Vector2& viewportSize,
|
||||
const Math::Vector2& mousePosition,
|
||||
bool localSpace,
|
||||
bool rotateAroundSharedPivot);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
根据当前选择状态和 Scene View overlay 信息构建 rotate gizmo 更新上下文。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 会写入 `overlay`、`viewportSize` 和 `mousePosition`。
|
||||
- `selectedObject` 取主对象，`selectedObjects` 也会完整带入。
|
||||
- `pivotWorldPosition` 取当前选择快照的 pivot。
|
||||
- `axisOrientation` 在 local-space 模式下取主对象稳定世界旋转，否则取单位四元数。
|
||||
- 额外写入：
|
||||
- `localSpace`
|
||||
- `rotateAroundSharedPivot`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md)
|
||||
- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
|
||||
- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
|
||||
@@ -0,0 +1,36 @@
|
||||
# BuildScaleGizmoContext
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportScaleGizmoContext BuildScaleGizmoContext(
|
||||
const SceneViewportSelectionGizmoState& selectionState,
|
||||
const SceneViewportOverlayData& overlay,
|
||||
const Math::Vector2& viewportSize,
|
||||
const Math::Vector2& mousePosition,
|
||||
bool localSpace);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
根据当前选择状态和 Scene View overlay 信息构建 scale gizmo 更新上下文。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 会写入 `overlay`、`viewportSize` 和 `mousePosition`。
|
||||
- `selectedObject` 仅绑定 `selectionState.primaryObject`。
|
||||
- `pivotWorldPosition` 取当前选择快照的 pivot。
|
||||
- `axisOrientation` 在 local-space 模式下取主对象稳定世界旋转，否则取单位四元数。
|
||||
- 当前这里不会填充 `uniformOnly`，该标志会由 [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) 后续按工具模式写入。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md)
|
||||
- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
|
||||
- [SceneViewportScaleGizmo](../SceneViewportScaleGizmo/SceneViewportScaleGizmo.md)
|
||||
@@ -0,0 +1,36 @@
|
||||
# BuildSceneViewportSelectionGizmoState
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportSelectionGizmoState BuildSceneViewportSelectionGizmoState(
|
||||
IEditorContext& context,
|
||||
bool useCenterPivot);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
从 editor 选择状态构建 transform gizmo 每帧需要的选择、pivot 和主对象朝向快照。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 从 `SelectionManager` 读取主选中实体与全选列表。
|
||||
- 通过 `SceneManager::GetEntity(...)` 过滤掉空实体 id 或无法解析的对象。
|
||||
- 如果 `primaryObject` 缺失但 `selectedObjects` 非空，当前会回退为最后一个可解析对象。
|
||||
- 如果有 `primaryObject` 但 `selectedObjects` 为空，当前会把它补进多选列表。
|
||||
- 若存在主对象，会计算并写入 `primaryWorldRotation`。
|
||||
- 若没有任何选中对象，直接返回默认状态。
|
||||
- `useCenterPivot == true` 时，会对所有选中对象的“中心世界位置”求平均。
|
||||
- `useCenterPivot == false` 时，pivot 取主对象 transform 位置。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md)
|
||||
- [GetGameObjectCenterWorldPosition](GetGameObjectCenterWorldPosition.md)
|
||||
- [ComputeStableWorldRotation](ComputeStableWorldRotation.md)
|
||||
@@ -0,0 +1,32 @@
|
||||
# CancelSceneViewportTransformGizmoDrags
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
void CancelSceneViewportTransformGizmoDrags(
|
||||
IEditorContext& context,
|
||||
SceneViewportMoveGizmo& moveGizmo,
|
||||
SceneViewportRotateGizmo& rotateGizmo,
|
||||
SceneViewportScaleGizmo& scaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
统一取消当前正在进行的 move / rotate / scale gizmo 拖拽。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 会分别检查三个 gizmo 的 `IsActive()`。
|
||||
- 对处于 active 状态的 gizmo，调用 `CancelDrag(&context.GetUndoManager())`。
|
||||
- 对未激活的 gizmo 不做处理。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
|
||||
- [CancelSceneViewportTransformGizmoFrame](../SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md)
|
||||
@@ -0,0 +1,30 @@
|
||||
# ComputeStableWorldRotation
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
Math::Quaternion ComputeStableWorldRotation(const Components::GameObject* gameObject);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
从对象及其父层级的 local rotation 计算一个稳定的世界旋转，供 gizmo 轴向使用。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- `gameObject == nullptr` 或缺少 transform 时返回 `Math::Quaternion::Identity()`。
|
||||
- 当前会从对象自身 local rotation 开始，沿父层级逐级左乘父 local rotation。
|
||||
- 返回值会调用 `Normalized()`，避免累计后出现非规范四元数。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
|
||||
- [BuildMoveGizmoContext](BuildMoveGizmoContext.md)
|
||||
- [BuildRotateGizmoContext](BuildRotateGizmoContext.md)
|
||||
- [BuildScaleGizmoContext](BuildScaleGizmoContext.md)
|
||||
@@ -0,0 +1,35 @@
|
||||
# GetActiveSceneViewportGizmoKind
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportActiveGizmoKind GetActiveSceneViewportGizmoKind(
|
||||
const SceneViewportMoveGizmo& moveGizmo,
|
||||
const SceneViewportRotateGizmo& rotateGizmo,
|
||||
const SceneViewportScaleGizmo& scaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
从三个 gizmo 当前 `IsActive()` 状态推导出本帧的 active gizmo 大类。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 按固定优先级检查：
|
||||
- `moveGizmo.IsActive()`
|
||||
- `rotateGizmo.IsActive()`
|
||||
- `scaleGizmo.IsActive()`
|
||||
- 三者都不 active 时返回 `SceneViewportActiveGizmoKind::None`。
|
||||
- 如果出现多个 gizmo 同时 active 的异常情况，当前会按上面的检查顺序返回第一个命中的类型。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportActiveGizmoKind](SceneViewportActiveGizmoKind.md)
|
||||
- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
|
||||
- [BuildSceneViewportTransformGizmoOverlaySubmission](../SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoOverlaySubmission.md)
|
||||
@@ -0,0 +1,28 @@
|
||||
# GetGameObjectCenterWorldPosition
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
Math::Vector3 GetGameObjectCenterWorldPosition(const Components::GameObject* gameObject);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
计算对象的“中心世界位置”，供 center-pivot 模式聚合多选 pivot。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- `gameObject == nullptr` 或缺少 transform 时返回 `Math::Vector3::Zero()`。
|
||||
- 若对象存在有效 `MeshFilterComponent`，且 mesh 非空并 `IsValid()`，则返回 `mesh->GetBounds().center` 经 transform 后的世界位置。
|
||||
- 否则回退到对象 transform 位置。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
|
||||
- [GetGameObjectPivotWorldPosition](GetGameObjectPivotWorldPosition.md)
|
||||
@@ -0,0 +1,27 @@
|
||||
# GetGameObjectPivotWorldPosition
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
Math::Vector3 GetGameObjectPivotWorldPosition(const Components::GameObject* gameObject);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
读取对象 transform 的世界位置，作为非 center-pivot 模式下的 gizmo pivot。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- `gameObject == nullptr` 或缺少 transform 时返回 `Math::Vector3::Zero()`。
|
||||
- 其余情况下直接返回 `gameObject->GetTransform()->GetPosition()`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
|
||||
- [GetGameObjectCenterWorldPosition](GetGameObjectCenterWorldPosition.md)
|
||||
@@ -0,0 +1,50 @@
|
||||
# RefreshSceneViewportTransformGizmos
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportTransformGizmoFrameState RefreshSceneViewportTransformGizmos(
|
||||
IEditorContext& context,
|
||||
const SceneViewportOverlayData& overlay,
|
||||
const Math::Vector2& viewportSize,
|
||||
const Math::Vector2& mousePosition,
|
||||
bool useCenterPivot,
|
||||
bool localSpace,
|
||||
bool usingTransformTool,
|
||||
bool showingMoveGizmo,
|
||||
SceneViewportMoveGizmo& moveGizmo,
|
||||
bool showingRotateGizmo,
|
||||
SceneViewportRotateGizmo& rotateGizmo,
|
||||
bool showingScaleGizmo,
|
||||
SceneViewportScaleGizmo& scaleGizmo);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
完成一帧 transform gizmo 刷新，返回本帧 gizmo frame state。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
1. 先通过 [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) 生成选择快照。
|
||||
2. 按显示开关构建 move / rotate / scale 三类 context。
|
||||
3. 如果某个 gizmo 正在拖拽，但当前对象已失效、主选中对象已切换，或该 gizmo 本帧被隐藏，则会调用 `CancelDrag(...)`。
|
||||
4. 对 scale gizmo，当前会把 `state.scaleContext.uniformOnly` 设为 `usingTransformTool`。
|
||||
5. 通过 [GetActiveSceneViewportGizmoKind](GetActiveSceneViewportGizmoKind.md) 求出当前 active gizmo 类型。
|
||||
6. 更新所有可见 gizmo；如果已有别的 gizmo active，则把非活动 gizmo 的 `mousePosition` 改成 `(-1, -1)` 再调用 `Update(...)`，显式屏蔽 hover 竞争。
|
||||
|
||||
## 当前使用位置
|
||||
|
||||
- [RefreshSceneViewportTransformGizmoFrame](../SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md) 会直接包装这一步，并继续构建 overlay submission。
|
||||
- `SceneViewPanel.cpp` 当前通过 coordinator 间接使用它。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoFrameState](SceneViewportTransformGizmoFrameState.md)
|
||||
- [GetActiveSceneViewportGizmoKind](GetActiveSceneViewportGizmoKind.md)
|
||||
- [RefreshSceneViewportTransformGizmoFrame](../SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md)
|
||||
@@ -0,0 +1,28 @@
|
||||
# SceneViewportActiveGizmoKind
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `enum class`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 枚举值
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `None` | 当前没有 gizmo 处于 active 拖拽态。 |
|
||||
| `Move` | 当前由 move gizmo 持有拖拽。 |
|
||||
| `Rotate` | 当前由 rotate gizmo 持有拖拽。 |
|
||||
| `Scale` | 当前由 scale gizmo 持有拖拽。 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 这是 Scene View transform gizmo 系统内部用来表达“谁正在持有交互”的统一枚举。
|
||||
- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) 会用它屏蔽非活动 gizmo 的 hover 竞争。
|
||||
- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) 也会用它驱动 begin / update / end 生命周期命令。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoFrameBuilder](SceneViewportTransformGizmoFrameBuilder.md)
|
||||
- [GetActiveSceneViewportGizmoKind](GetActiveSceneViewportGizmoKind.md)
|
||||
- [SceneViewportTransformGizmoLifecycleCommand](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md)
|
||||
@@ -0,0 +1,30 @@
|
||||
# SceneViewportSelectionGizmoState
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `primaryObject` | `Components::GameObject*` | 当前主选中对象。 |
|
||||
| `selectedObjects` | `std::vector<Components::GameObject*>` | 当前可解析的选中对象集合。 |
|
||||
| `pivotWorldPosition` | `Math::Vector3` | 本帧 gizmo 应使用的世界 pivot。 |
|
||||
| `primaryWorldRotation` | `Math::Quaternion` | 主对象稳定世界旋转。 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 这是 [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) 的输出结构。
|
||||
- 当前实现会尽量保持 `primaryObject` 与 `selectedObjects` 自洽：
|
||||
- 有多选但主对象缺失时，会回退到最后一个可解析对象。
|
||||
- 只有主对象时，会把它补进 `selectedObjects`。
|
||||
- `pivotWorldPosition` 会按当前是否使用 center pivot 决定来源。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoFrameBuilder](SceneViewportTransformGizmoFrameBuilder.md)
|
||||
- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md)
|
||||
- [SceneViewportTransformGizmoFrameState](SceneViewportTransformGizmoFrameState.md)
|
||||
@@ -0,0 +1,61 @@
|
||||
# SceneViewportTransformGizmoFrameBuilder
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `utility-header`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
**描述**: 统一组装 Scene View 每帧的 transform gizmo 选择状态、pivot、局部/全局朝向和三类 gizmo context，并负责在选择变化时取消失效拖拽。
|
||||
|
||||
## 概述
|
||||
|
||||
`SceneViewportTransformGizmoFrameBuilder.h` 处在当前 Scene View gizmo 交互链路的中间层。
|
||||
它不直接绘制 gizmo，也不直接处理 ImGui 输入，而是把“本帧该拿什么上下文去更新 move / rotate / scale gizmo”这件事集中到一个头文件里。
|
||||
|
||||
它主要解决四类问题：
|
||||
|
||||
1. 从 `SelectionManager + SceneManager` 还原当前选中对象集合。
|
||||
2. 计算本帧 gizmo 应使用的 pivot 与主对象世界朝向。
|
||||
3. 组装 move / rotate / scale 各自的 context。
|
||||
4. 在 gizmo 被隐藏、选择切换或实体失效时，及时取消旧拖拽。
|
||||
|
||||
## 公开类型与函数
|
||||
|
||||
| 成员 | 说明 |
|
||||
|------|------|
|
||||
| [SceneViewportActiveGizmoKind](SceneViewportActiveGizmoKind.md) | 当前处于 active 拖拽态的 gizmo 大类。 |
|
||||
| [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md) | 当前选择、pivot 和主对象朝向的聚合快照。 |
|
||||
| [SceneViewportTransformGizmoFrameState](SceneViewportTransformGizmoFrameState.md) | 每帧 gizmo 刷新后的完整输出。 |
|
||||
| [GetActiveSceneViewportGizmoKind](GetActiveSceneViewportGizmoKind.md) | 从三个 gizmo 当前状态推断 active gizmo 类型。 |
|
||||
| [ComputeStableWorldRotation](ComputeStableWorldRotation.md) | 计算主对象稳定世界旋转。 |
|
||||
| [GetGameObjectPivotWorldPosition](GetGameObjectPivotWorldPosition.md) | 读取对象 pivot 世界位置。 |
|
||||
| [GetGameObjectCenterWorldPosition](GetGameObjectCenterWorldPosition.md) | 读取对象中心世界位置，优先使用 mesh bounds center。 |
|
||||
| [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) | 构建本帧选择与 pivot 快照。 |
|
||||
| [BuildMoveGizmoContext](BuildMoveGizmoContext.md) | 构建 move gizmo 本帧上下文。 |
|
||||
| [BuildRotateGizmoContext](BuildRotateGizmoContext.md) | 构建 rotate gizmo 本帧上下文。 |
|
||||
| [BuildScaleGizmoContext](BuildScaleGizmoContext.md) | 构建 scale gizmo 本帧上下文。 |
|
||||
| [CancelSceneViewportTransformGizmoDrags](CancelSceneViewportTransformGizmoDrags.md) | 统一取消正在进行的 gizmo 拖拽。 |
|
||||
| [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) | 完成一帧 gizmo context 刷新、拖拽校验和 gizmo 更新。 |
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 这是 header-only helper，不持有持久状态。
|
||||
- 它解决的是“每帧上下文装配”，不是 gizmo overlay 提交或生命周期命令分发。
|
||||
- gizmo overlay state 的收口由 [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) 负责。
|
||||
- 当前多选中心 pivot 只按对象中心平均，不做包围盒并集或加权计算。
|
||||
|
||||
## 当前使用位置
|
||||
|
||||
- `SceneViewPanel.cpp` 会按本帧工具状态、pivot 模式和坐标空间调用这组 helper。
|
||||
- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) 会继续消费这里返回的 frame state，并收口成 overlay submission。
|
||||
- [SceneViewportMoveGizmo](../SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)、[SceneViewportRotateGizmo](../SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)、[SceneViewportScaleGizmo](../SceneViewportScaleGizmo/SceneViewportScaleGizmo.md) 都依赖这里生成的 context。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前模块](../Viewport.md)
|
||||
- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.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)
|
||||
@@ -0,0 +1,30 @@
|
||||
# SceneViewportTransformGizmoFrameState
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h`
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `overlay` | `SceneViewportOverlayData` | 当前帧 Scene View 相机 / overlay 基础数据。 |
|
||||
| `selectionState` | `SceneViewportSelectionGizmoState` | 当前帧选中对象与 pivot 快照。 |
|
||||
| `moveContext` | `SceneViewportMoveGizmoContext` | move gizmo 本帧上下文。 |
|
||||
| `rotateContext` | `SceneViewportRotateGizmoContext` | rotate gizmo 本帧上下文。 |
|
||||
| `scaleContext` | `SceneViewportScaleGizmoContext` | scale gizmo 本帧上下文。 |
|
||||
| `activeGizmoKind` | `SceneViewportActiveGizmoKind` | 当前实际 active 的 gizmo 大类。 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 这是 [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) 的完整输出。
|
||||
- 它既保留三类 gizmo 的上下文，也保留本帧 active gizmo 判断结果，供 coordinator 后续继续处理。
|
||||
- 该结构本身不持有生命周期状态，只表达当前帧刷新后的快照。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportTransformGizmoFrameBuilder](SceneViewportTransformGizmoFrameBuilder.md)
|
||||
- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md)
|
||||
- [SceneViewportTransformGizmoFrameUpdate](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md)
|
||||
Reference in New Issue
Block a user