docs: add scene viewport interaction helper docs
This commit is contained in:
@@ -0,0 +1,39 @@
|
||||
# BuildSceneViewportAxisDragPlaneNormal
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
bool BuildSceneViewportAxisDragPlaneNormal(
|
||||
const SceneViewportOverlayData& overlay,
|
||||
const Math::Vector3& worldAxis,
|
||||
Math::Vector3& outPlaneNormal);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
为轴向拖拽推导一个尽量稳定、且不与活动轴平行的平面法线。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 若 overlay 无效或轴长度退化为零，则失败。
|
||||
- 会先把活动轴归一化。
|
||||
- 然后按如下顺序尝试候选法线：
|
||||
- 相机 `forward`
|
||||
- 相机 `up`
|
||||
- 相机 `right`
|
||||
- 世界 `up`
|
||||
- 世界 `right`
|
||||
- 世界 `forward`
|
||||
- 每个候选都会先投影到“去掉活动轴分量”的平面上；第一个非零结果会被归一化并返回。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [BuildSceneViewportPlaneFromPointNormal](BuildSceneViewportPlaneFromPointNormal.md)
|
||||
- [SceneViewportMoveGizmo](../SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)
|
||||
@@ -0,0 +1,29 @@
|
||||
# BuildSceneViewportPlaneFromPointNormal
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
Math::Plane BuildSceneViewportPlaneFromPointNormal(
|
||||
const Math::Vector3& point,
|
||||
const Math::Vector3& normal);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
根据一个点和法线构造拖拽或求交所需的平面。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 会先把法线归一化。
|
||||
- 然后使用 `Math::Plane(planeNormal, -Dot(planeNormal, point))` 构造结果。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [BuildSceneViewportAxisDragPlaneNormal](BuildSceneViewportAxisDragPlaneNormal.md)
|
||||
@@ -0,0 +1,31 @@
|
||||
# BuildSceneViewportProjectionMatrix
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
Math::Matrix4x4 BuildSceneViewportProjectionMatrix(
|
||||
const SceneViewportOverlayData& overlay,
|
||||
float viewportWidth,
|
||||
float viewportHeight);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
根据垂直 FOV、视口尺寸和裁剪面构造透视投影矩阵。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 若 `viewportHeight <= 0`，当前会把纵横比回退到 `1.0f`。
|
||||
- 其余情况下按 `viewportWidth / viewportHeight` 计算 aspect。
|
||||
- 最终调用 `Math::Matrix4x4::Perspective(...)`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [BuildSceneViewportViewProjectionMatrix](BuildSceneViewportViewProjectionMatrix.md)
|
||||
@@ -0,0 +1,28 @@
|
||||
# BuildSceneViewportViewMatrix
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
Math::Matrix4x4 BuildSceneViewportViewMatrix(const SceneViewportOverlayData& overlay);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
根据当前 Scene View 相机姿态构造视图矩阵。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 会把 `cameraRight / cameraUp / cameraForward` 全部归一化。
|
||||
- 矩阵前三行分别使用右、上、前方向和相机位置的点积偏移组装。
|
||||
- 当前实现不额外检查 `overlay.valid`，默认由调用方保证输入有效。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [BuildSceneViewportViewProjectionMatrix](BuildSceneViewportViewProjectionMatrix.md)
|
||||
@@ -0,0 +1,32 @@
|
||||
# BuildSceneViewportViewProjectionMatrix
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
Math::Matrix4x4 BuildSceneViewportViewProjectionMatrix(
|
||||
const SceneViewportOverlayData& overlay,
|
||||
float viewportWidth,
|
||||
float viewportHeight);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
组合视图矩阵与投影矩阵，得到用于世界点投影的 view-projection 矩阵。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 当前实现直接返回：
|
||||
- `Projection * View`
|
||||
- 它是 [ProjectSceneViewportWorldPoint](ProjectSceneViewportWorldPoint.md) 和 [ProjectSceneViewportAxisDirectionAtPoint](ProjectSceneViewportAxisDirectionAtPoint.md) 的基础。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [BuildSceneViewportViewMatrix](BuildSceneViewportViewMatrix.md)
|
||||
- [BuildSceneViewportProjectionMatrix](BuildSceneViewportProjectionMatrix.md)
|
||||
@@ -0,0 +1,33 @@
|
||||
# DistanceToSegmentSquared
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
float DistanceToSegmentSquared(
|
||||
const Math::Vector2& point,
|
||||
const Math::Vector2& segmentStart,
|
||||
const Math::Vector2& segmentEnd,
|
||||
float* outSegmentT = nullptr);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
计算一个二维点到线段的平方距离。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 若线段长度退化到零，会直接退回“点到起点”的平方距离。
|
||||
- 否则会计算线段参数 `t`，并在 `[0, 1]` 内钳制。
|
||||
- 若传入了 `outSegmentT`，会回写最近点在线段上的参数位置。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [SceneViewportMoveGizmo](../SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)
|
||||
- [SceneViewportRotateGizmo](../SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)
|
||||
@@ -0,0 +1,32 @@
|
||||
# ProjectSceneViewportAxisDirection
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
bool ProjectSceneViewportAxisDirection(
|
||||
const SceneViewportOverlayData& overlay,
|
||||
const Math::Vector3& worldAxis,
|
||||
Math::Vector2& outScreenDirection);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
估计一个世界轴在当前视口屏幕上的二维方向。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 若 `overlay.valid == false`，直接失败。
|
||||
- 会先把 `worldAxis` 归一化并变换到当前视图空间。
|
||||
- 最终使用 `(viewAxis.x, -viewAxis.y)` 作为屏幕方向。
|
||||
- 若结果退化到零长度，则返回 `false`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [ProjectSceneViewportAxisDirectionAtPoint](ProjectSceneViewportAxisDirectionAtPoint.md)
|
||||
@@ -0,0 +1,35 @@
|
||||
# ProjectSceneViewportAxisDirectionAtPoint
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
bool ProjectSceneViewportAxisDirectionAtPoint(
|
||||
const SceneViewportOverlayData& overlay,
|
||||
float viewportWidth,
|
||||
float viewportHeight,
|
||||
const Math::Vector3& worldPoint,
|
||||
const Math::Vector3& worldAxis,
|
||||
Math::Vector2& outScreenDirection,
|
||||
float sampleDistance = 1.0f);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
以具体世界采样点为基准，估计一个轴在屏幕上的方向。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 会先校验 overlay、视口尺寸、轴长度和 `sampleDistance`。
|
||||
- 主路径是投影 `worldPoint` 与 `worldPoint + axis * sampleDistance` 两个点，然后取它们的屏幕差向量。
|
||||
- 若任一点投影失败或结果退化到零长度，则回退到 [ProjectSceneViewportAxisDirection](ProjectSceneViewportAxisDirection.md)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [ProjectSceneViewportAxisDirection](ProjectSceneViewportAxisDirection.md)
|
||||
@@ -0,0 +1,34 @@
|
||||
# ProjectSceneViewportWorldPoint
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
SceneViewportProjectedPoint ProjectSceneViewportWorldPoint(
|
||||
const SceneViewportOverlayData& overlay,
|
||||
float viewportWidth,
|
||||
float viewportHeight,
|
||||
const Math::Vector3& worldPoint);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
把世界空间点投影到 Scene View 屏幕坐标。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 若 `overlay` 无效或视口宽高太小，会直接返回默认结果。
|
||||
- 会先计算 clip-space 点；`clipPoint.w <= epsilon` 时直接判定不可见。
|
||||
- 否则把点除以 `w` 转成 NDC，再换算到屏幕坐标。
|
||||
- `visible` 只有在 `x/y/z` 全部位于标准裁剪范围时才为真。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [SceneViewportProjectedPoint](SceneViewportProjectedPoint.md)
|
||||
- [ProjectSceneViewportWorldPointClamped](ProjectSceneViewportWorldPointClamped.md)
|
||||
@@ -0,0 +1,35 @@
|
||||
# ProjectSceneViewportWorldPointClamped
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
bool ProjectSceneViewportWorldPointClamped(
|
||||
const SceneViewportOverlayData& overlay,
|
||||
float viewportWidth,
|
||||
float viewportHeight,
|
||||
const Math::Vector3& worldPoint,
|
||||
float edgePadding,
|
||||
SceneViewportProjectedPoint& outProjectedPoint);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
投影世界点，并把屏幕坐标钳制到给定边缘内。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 会先调用 [ProjectSceneViewportWorldPoint](ProjectSceneViewportWorldPoint.md)。
|
||||
- 若 overlay 无效、视口尺寸无效或深度小于 `0`，则失败。
|
||||
- 否则按 `edgePadding` 把 `screenPosition` 钳制在视口矩形内部。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [ProjectSceneViewportWorldPoint](ProjectSceneViewportWorldPoint.md)
|
||||
- [SceneViewportProjectedPoint](SceneViewportProjectedPoint.md)
|
||||
@@ -0,0 +1,84 @@
|
||||
# SceneViewportMath
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `header-helper`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
**描述**: 为 Scene View overlay、gizmo 和 picking 提供统一的投影、屏幕方向、拖拽平面和距离计算 helper。
|
||||
|
||||
## 概述
|
||||
|
||||
`SceneViewportMath.h` 是 `Viewport` 模块里最基础的“几何工具层”。它把很多本来容易散落在 gizmo / picker / overlay builder 里的数学过程集中到一个地方，例如：
|
||||
|
||||
- 构建 view / projection / view-projection 矩阵。
|
||||
- 世界点投影到视口屏幕坐标。
|
||||
- 世界轴投影到屏幕方向。
|
||||
- 线段距离计算。
|
||||
- 基于相机方向为轴向拖拽自动求稳定拖拽平面。
|
||||
|
||||
这类 helper 的价值很像商业引擎编辑器里的 `HandleUtility` 一类基础设施。
|
||||
|
||||
## 主要能力
|
||||
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| [SceneViewportProjectedPoint](SceneViewportProjectedPoint.md) | 世界点投影后的屏幕坐标、深度和可见性结果。 |
|
||||
| [BuildSceneViewportViewMatrix](BuildSceneViewportViewMatrix.md) | 由 `cameraRight / Up / Forward / Position` 组装视图矩阵。 |
|
||||
| [BuildSceneViewportProjectionMatrix](BuildSceneViewportProjectionMatrix.md) | 基于垂直 FOV 和视口宽高创建透视投影。 |
|
||||
| [BuildSceneViewportViewProjectionMatrix](BuildSceneViewportViewProjectionMatrix.md) | 组合视图矩阵与投影矩阵。 |
|
||||
| [ProjectSceneViewportWorldPoint](ProjectSceneViewportWorldPoint.md) | 把世界点投影为屏幕坐标和 `ndcDepth`。 |
|
||||
| [ProjectSceneViewportAxisDirection](ProjectSceneViewportAxisDirection.md) | 计算世界轴在屏幕上的朝向。 |
|
||||
| [ProjectSceneViewportAxisDirectionAtPoint](ProjectSceneViewportAxisDirectionAtPoint.md) | 以具体采样点为基准估计屏幕轴方向。 |
|
||||
| [ProjectSceneViewportWorldPointClamped](ProjectSceneViewportWorldPointClamped.md) | 投影后做边缘钳制。 |
|
||||
| [DistanceToSegmentSquared](DistanceToSegmentSquared.md) | 供 gizmo hit-test 使用的二维距离 helper。 |
|
||||
| [BuildSceneViewportPlaneFromPointNormal](BuildSceneViewportPlaneFromPointNormal.md) | 由点和法线构建拖拽平面。 |
|
||||
| [BuildSceneViewportAxisDragPlaneNormal](BuildSceneViewportAxisDragPlaneNormal.md) | 为轴向拖拽推导合适的平面法线。 |
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 这些 helper 全部是 `inline` 函数，没有独立 `.cpp`。
|
||||
- [ProjectSceneViewportWorldPoint](ProjectSceneViewportWorldPoint.md) 在 `clipPoint.w <= epsilon` 时会直接判定不可见。
|
||||
- [ProjectSceneViewportAxisDirectionAtPoint](ProjectSceneViewportAxisDirectionAtPoint.md) 会优先做两点投影采样，失败时回退到纯方向投影。
|
||||
- [BuildSceneViewportAxisDragPlaneNormal](BuildSceneViewportAxisDragPlaneNormal.md) 会按相机 forward / up / right 以及世界基轴顺序寻找一个不与拖拽轴平行的候选法线。
|
||||
|
||||
## 设计说明
|
||||
|
||||
把这些数学过程集中起来有两个收益：
|
||||
|
||||
- Scene View gizmo 的 hit-test、拖拽和绘制可以共享完全一致的投影逻辑。
|
||||
- 当视口投影规则调整时，不需要分别修改 move / rotate / scale 三套代码。
|
||||
|
||||
这类“统一几何约定层”是编辑器工具质量很重要的一部分。没有它，交互往往会出现看起来能点到、实际拖起来方向不对，或者不同 gizmo 手感不一致的问题。
|
||||
|
||||
## 与测试的对应关系
|
||||
|
||||
`tests/Editor/test_scene_viewport_overlay_renderer.cpp` 当前验证了：
|
||||
|
||||
- [BuildSceneViewportViewMatrix](BuildSceneViewportViewMatrix.md) 与编辑器相机 transform 约定一致。
|
||||
- [BuildSceneViewportProjectionMatrix](BuildSceneViewportProjectionMatrix.md) 和 [ProjectSceneViewportWorldPoint](ProjectSceneViewportWorldPoint.md) 的投影结果符合 Scene View 预期。
|
||||
- [BuildSceneViewportAxisDragPlaneNormal](BuildSceneViewportAxisDragPlaneNormal.md) 会在相机 forward 与拖拽轴对齐时回退到其它稳定法线候选。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 当前投影 helper 假设的是标准透视视口语义，不是更一般化的任意裁剪空间工具库。
|
||||
- 没有对极端数值稳定性做更重的保护，例如非常接近 near plane 的大规模场景。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportProjectedPoint](SceneViewportProjectedPoint.md)
|
||||
- [BuildSceneViewportViewMatrix](BuildSceneViewportViewMatrix.md)
|
||||
- [BuildSceneViewportProjectionMatrix](BuildSceneViewportProjectionMatrix.md)
|
||||
- [BuildSceneViewportViewProjectionMatrix](BuildSceneViewportViewProjectionMatrix.md)
|
||||
- [ProjectSceneViewportWorldPoint](ProjectSceneViewportWorldPoint.md)
|
||||
- [ProjectSceneViewportAxisDirection](ProjectSceneViewportAxisDirection.md)
|
||||
- [ProjectSceneViewportAxisDirectionAtPoint](ProjectSceneViewportAxisDirectionAtPoint.md)
|
||||
- [ProjectSceneViewportWorldPointClamped](ProjectSceneViewportWorldPointClamped.md)
|
||||
- [DistanceToSegmentSquared](DistanceToSegmentSquared.md)
|
||||
- [BuildSceneViewportPlaneFromPointNormal](BuildSceneViewportPlaneFromPointNormal.md)
|
||||
- [BuildSceneViewportAxisDragPlaneNormal](BuildSceneViewportAxisDragPlaneNormal.md)
|
||||
- [SceneViewportMoveGizmo](../SceneViewportMoveGizmo/SceneViewportMoveGizmo.md)
|
||||
- [SceneViewportRotateGizmo](../SceneViewportRotateGizmo/SceneViewportRotateGizmo.md)
|
||||
- [SceneViewportScaleGizmo](../SceneViewportScaleGizmo/SceneViewportScaleGizmo.md)
|
||||
- [SceneViewportPicker](../SceneViewportPicker/SceneViewportPicker.md)
|
||||
@@ -0,0 +1,35 @@
|
||||
# SceneViewportProjectedPoint
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Viewport/SceneViewportMath.h`
|
||||
|
||||
## 定义
|
||||
|
||||
```cpp
|
||||
struct SceneViewportProjectedPoint {
|
||||
Math::Vector2 screenPosition = Math::Vector2::Zero();
|
||||
float ndcDepth = 0.0f;
|
||||
bool visible = false;
|
||||
};
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
表示一个世界点投影到 Scene View 后的屏幕坐标、深度和可见性。
|
||||
|
||||
## 字段说明
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `screenPosition` | 投影后的屏幕坐标。 |
|
||||
| `ndcDepth` | 投影后的 NDC 深度。 |
|
||||
| `visible` | 是否位于可见裁剪范围内。 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneViewportMath](SceneViewportMath.md)
|
||||
- [ProjectSceneViewportWorldPoint](ProjectSceneViewportWorldPoint.md)
|
||||
- [ProjectSceneViewportWorldPointClamped](ProjectSceneViewportWorldPointClamped.md)
|
||||
Reference in New Issue
Block a user