docs: update math API docs
This commit is contained in:
42
docs/api/math/transform/inverse-transform-direction.md
Normal file
42
docs/api/math/transform/inverse-transform-direction.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Transform::InverseTransformDirection
|
||||
|
||||
```cpp
|
||||
Vector3 InverseTransformDirection(const Vector3& direction) const;
|
||||
```
|
||||
|
||||
将一个方向向量从世界空间逆变换到本地空间。计算结果为 `rotation.Inverse() * direction / scale`。
|
||||
|
||||
此方法是 `TransformDirection` 的逆操作。
|
||||
|
||||
**参数：**
|
||||
- `direction` - 世界空间中的方向向量
|
||||
|
||||
**返回：** `Vector3` - 本地空间中的逆变换后方向
|
||||
|
||||
**线程安全：** ❌（无锁，非线程安全）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Math/Transform.h"
|
||||
#include "XCEngine/Math/Vector3.h"
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
void InverseTransformDirectionExample() {
|
||||
Transform transform;
|
||||
transform.position = Vector3(10.0f, 0.0f, 0.0f);
|
||||
transform.rotation = Quaternion::Identity();
|
||||
transform.scale = Vector3(2.0f, 2.0f, 2.0f);
|
||||
|
||||
Vector3 worldDir(0.0f, 2.0f, 0.0f);
|
||||
Vector3 localDir = transform.InverseTransformDirection(worldDir);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Transform](transform.md) - 返回类总览
|
||||
- [TransformDirection](transform-direction.md) - 正向变换方向
|
||||
42
docs/api/math/transform/inverse-transform-point.md
Normal file
42
docs/api/math/transform/inverse-transform-point.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Transform::InverseTransformPoint
|
||||
|
||||
```cpp
|
||||
Vector3 InverseTransformPoint(const Vector3& point) const;
|
||||
```
|
||||
|
||||
将一个点从世界空间逆变换到本地空间。计算结果为 `(rotation.Inverse() * (point - position)) / scale`。
|
||||
|
||||
此方法是 `TransformPoint` 的逆操作。
|
||||
|
||||
**参数：**
|
||||
- `point` - 世界空间中的点
|
||||
|
||||
**返回：** `Vector3` - 本地空间中的逆变换后点
|
||||
|
||||
**线程安全：** ❌（无锁，非线程安全）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Math/Transform.h"
|
||||
#include "XCEngine/Math/Vector3.h"
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
void InverseTransformPointExample() {
|
||||
Transform transform;
|
||||
transform.position = Vector3(10.0f, 0.0f, 0.0f);
|
||||
transform.rotation = Quaternion::Identity();
|
||||
transform.scale = Vector3(2.0f, 2.0f, 2.0f);
|
||||
|
||||
Vector3 worldPoint(12.0f, 4.0f, 6.0f);
|
||||
Vector3 localPoint = transform.InverseTransformPoint(worldPoint);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Transform](transform.md) - 返回类总览
|
||||
- [TransformPoint](transform-point.md) - 正向变换点
|
||||
@@ -1,17 +1,44 @@
|
||||
# Transform::Inverse
|
||||
|
||||
```cpp
|
||||
Transform Inverse() const
|
||||
Transform Inverse() const;
|
||||
```
|
||||
|
||||
返回变换的逆。
|
||||
返回当前变换的逆变换。逆变换满足 `transform * transform.Inverse() == Identity()`。
|
||||
|
||||
**返回：** `Transform` - 逆变换
|
||||
计算方式：
|
||||
- 旋转取反：先计算旋转的逆（四元数共轭）
|
||||
- 缩放送原：取倒数
|
||||
- 位置：将原点相对于当前点的偏移，经逆旋转和逆缩放后取反
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `Transform` - 当前变换的逆变换
|
||||
|
||||
**线程安全：** ❌（无锁，非线程安全）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Transform inv = transform.Inverse();
|
||||
#include "XCEngine/Math/Transform.h"
|
||||
#include "XCEngine/Math/Vector3.h"
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
void InverseExample() {
|
||||
Transform transform;
|
||||
transform.position = Vector3(10.0f, 0.0f, 0.0f);
|
||||
transform.rotation = Quaternion::Identity();
|
||||
transform.scale = Vector3(2.0f, 2.0f, 2.0f);
|
||||
|
||||
Transform inverse = transform.Inverse();
|
||||
|
||||
Transform identity = transform * inverse;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Transform](transform.md) - 返回类总览
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
# Transform::InverseTransformDirection
|
||||
|
||||
```cpp
|
||||
Vector3 InverseTransformDirection(const Vector3& direction) const
|
||||
```
|
||||
|
||||
对方向进行逆变换（包含缩放处理）。
|
||||
|
||||
**参数：**
|
||||
- `direction` - 世界空间中的方向
|
||||
|
||||
**返回：** `Vector3` - 局部空间中的方向
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Transform t;
|
||||
Vector3 localDir = t.InverseTransformDirection(worldDir);
|
||||
```
|
||||
@@ -1,21 +0,0 @@
|
||||
# Transform::InverseTransformPoint
|
||||
|
||||
```cpp
|
||||
Vector3 InverseTransformPoint(const Vector3& point) const
|
||||
```
|
||||
|
||||
对点进行逆变换。
|
||||
|
||||
**参数：**
|
||||
- `point` - 世界空间中的点
|
||||
|
||||
**返回：** `Vector3` - 局部空间中的点
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Transform t;
|
||||
Vector3 localPos = t.InverseTransformPoint(worldPos);
|
||||
```
|
||||
47
docs/api/math/transform/operator-star.md
Normal file
47
docs/api/math/transform/operator-star.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Transform::operator*
|
||||
|
||||
```cpp
|
||||
Transform operator*(const Transform& other) const;
|
||||
```
|
||||
|
||||
组合两个变换。当 `A * B` 时，表示先应用 `B`，再应用 `A`。结果变换先对点进行 `B` 变换，再进行 `A` 变换。
|
||||
|
||||
组合计算：
|
||||
- `position = position + rotation * (scale * other.position)`
|
||||
- `rotation = rotation * other.rotation`
|
||||
- `scale = scale * other.scale`
|
||||
|
||||
**参数：**
|
||||
- `other` - 要组合的另一个变换
|
||||
|
||||
**返回：** `Transform` - 组合后的变换
|
||||
|
||||
**线程安全：** ❌（无锁，非线程安全）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Math/Transform.h"
|
||||
#include "XCEngine/Math/Vector3.h"
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
void OperatorMultiplyExample() {
|
||||
Transform parent;
|
||||
parent.position = Vector3(10.0f, 0.0f, 0.0f);
|
||||
parent.scale = Vector3(2.0f, 2.0f, 2.0f);
|
||||
|
||||
Transform child;
|
||||
child.position = Vector3(5.0f, 0.0f, 0.0f);
|
||||
|
||||
Transform combined = parent * child;
|
||||
|
||||
Vector3 worldPos = combined.TransformPoint(child.position);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Transform](transform.md) - 返回类总览
|
||||
38
docs/api/math/transform/to-matrix.md
Normal file
38
docs/api/math/transform/to-matrix.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# Transform::ToMatrix
|
||||
|
||||
```cpp
|
||||
Matrix4 ToMatrix() const;
|
||||
```
|
||||
|
||||
将当前变换转换为 4x4 变换矩阵。该矩阵通过 `Matrix4x4::TRS` 函数，使用 position、rotation 和 scale 构造，包含平移、旋转和缩放的组合变换。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `Matrix4` - 表示当前变换的 4x4 矩阵
|
||||
|
||||
**线程安全：** ❌（无锁，非线程安全）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Math/Transform.h"
|
||||
#include "XCEngine/Math/Vector3.h"
|
||||
#include "XCEngine/Math/Quaternion.h"
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
void ToMatrixExample() {
|
||||
Transform transform;
|
||||
transform.position = Vector3(1.0f, 2.0f, 3.0f);
|
||||
transform.rotation = Quaternion::Identity();
|
||||
transform.scale = Vector3(2.0f, 2.0f, 2.0f);
|
||||
|
||||
Matrix4 matrix = transform.ToMatrix();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Transform](transform.md) - 返回类总览
|
||||
@@ -1,19 +0,0 @@
|
||||
# Transform::ToMatrix
|
||||
|
||||
```cpp
|
||||
Matrix4 ToMatrix() const
|
||||
```
|
||||
|
||||
将变换转换为 4x4 变换矩阵。
|
||||
|
||||
**返回：** `Matrix4` - TRS 变换矩阵
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Transform t;
|
||||
t.position = Vector3(1.0f, 2.0f, 3.0f);
|
||||
Matrix4 matrix = t.ToMatrix();
|
||||
```
|
||||
42
docs/api/math/transform/transform-direction.md
Normal file
42
docs/api/math/transform/transform-direction.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Transform::TransformDirection
|
||||
|
||||
```cpp
|
||||
Vector3 TransformDirection(const Vector3& direction) const;
|
||||
```
|
||||
|
||||
将一个方向向量从本地空间变换到世界空间。计算结果为 `rotation * (scale * direction)`，即先缩放、再旋转，不包含平移。
|
||||
|
||||
此方法适用于变换方向向量、法线等不应当受平移影响的量。
|
||||
|
||||
**参数：**
|
||||
- `direction` - 本地空间中的方向向量
|
||||
|
||||
**返回：** `Vector3` - 世界空间中的变换后方向
|
||||
|
||||
**线程安全：** ❌（无锁，非线程安全）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Math/Transform.h"
|
||||
#include "XCEngine/Math/Vector3.h"
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
void TransformDirectionExample() {
|
||||
Transform transform;
|
||||
transform.position = Vector3(10.0f, 0.0f, 0.0f);
|
||||
transform.rotation = Quaternion::Identity();
|
||||
transform.scale = Vector3(2.0f, 2.0f, 2.0f);
|
||||
|
||||
Vector3 localDir(0.0f, 1.0f, 0.0f);
|
||||
Vector3 worldDir = transform.TransformDirection(localDir);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Transform](transform.md) - 返回类总览
|
||||
- [TransformPoint](transform-point.md) - 变换点
|
||||
42
docs/api/math/transform/transform-point.md
Normal file
42
docs/api/math/transform/transform-point.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Transform::TransformPoint
|
||||
|
||||
```cpp
|
||||
Vector3 TransformPoint(const Vector3& point) const;
|
||||
```
|
||||
|
||||
将一个点从本地空间变换到世界空间。计算结果为 `position + rotation * (scale * point)`，即先缩放、再旋转、最后平移。
|
||||
|
||||
此方法适用于变换顶点位置等考虑平移的点。
|
||||
|
||||
**参数：**
|
||||
- `point` - 本地空间中的点
|
||||
|
||||
**返回：** `Vector3` - 世界空间中的变换后点
|
||||
|
||||
**线程安全：** ❌（无锁，非线程安全）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Math/Transform.h"
|
||||
#include "XCEngine/Math/Vector3.h"
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
void TransformPointExample() {
|
||||
Transform transform;
|
||||
transform.position = Vector3(10.0f, 0.0f, 0.0f);
|
||||
transform.rotation = Quaternion::Identity();
|
||||
transform.scale = Vector3(2.0f, 2.0f, 2.0f);
|
||||
|
||||
Vector3 localPoint(1.0f, 2.0f, 3.0f);
|
||||
Vector3 worldPoint = transform.TransformPoint(localPoint);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Transform](transform.md) - 返回类总览
|
||||
- [TransformDirection](transform-direction.md) - 变换方向
|
||||
@@ -1,39 +1,71 @@
|
||||
# Transform
|
||||
|
||||
3D 变换结构体，包含位置、旋转和缩放，用于层次化变换。
|
||||
**命名空间**: `XCEngine::Math`
|
||||
|
||||
**头文件：** `#include <XCEngine/Math/Transform.h>`
|
||||
**类型**: `struct`
|
||||
|
||||
**命名空间：** `XCEngine::Math`
|
||||
**头文件**: `XCEngine/Math/Transform.h`
|
||||
|
||||
## Space 枚举
|
||||
**描述**: 变换组件，包含位置、旋转和缩放，用于层级变换计算
|
||||
|
||||
## 概述
|
||||
|
||||
`Transform` 是 XCEngine 中的核心变换组件，封装了 3D 空间中的位置（position）、旋转（rotation）和缩放（scale）信息。它支持层级变换计算，可以将点或方向从本地空间变换到世界空间，或进行逆变换。
|
||||
|
||||
该结构体设计用于游戏引擎的层级关系系统中，每个 `Transform` 可以通过 `operator*` 与父级 `Transform` 组合，实现累积变换。
|
||||
|
||||
## 结构体成员
|
||||
|
||||
| 成员 | 类型 | 描述 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| `position` | `Vector3` | 位置 | `Vector3::Zero()` |
|
||||
| `rotation` | `Quaternion` | 旋转（四元数） | `Quaternion::Identity()` |
|
||||
| `scale` | `Vector3` | 缩放 | `Vector3::One()` |
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [`ToMatrix`](to-matrix.md) | 将变换转换为 4x4 矩阵 |
|
||||
| [`Inverse`](inverse.md) | 返回变换的逆变换 |
|
||||
| [`operator*`](operator-star.md) | 组合两个变换 |
|
||||
| [`TransformPoint`](transform-point.md) | 变换一个点（考虑位置、旋转和缩放） |
|
||||
| [`TransformDirection`](transform-direction.md) | 变换一个方向（仅考虑旋转和缩放） |
|
||||
| [`InverseTransformPoint`](inverse-transform-point.md) | 逆变换一个点 |
|
||||
| [`InverseTransformDirection`](inverse-transform-direction.md) | 逆变换一个方向 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
enum class Space { Self, World };
|
||||
#include "XCEngine/Math/Transform.h"
|
||||
#include "XCEngine/Math/Vector3.h"
|
||||
#include "XCEngine/Math/Quaternion.h"
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
void TransformExample() {
|
||||
Transform parent;
|
||||
parent.position = Vector3(10.0f, 0.0f, 0.0f);
|
||||
parent.rotation = Quaternion::Identity();
|
||||
parent.scale = Vector3(2.0f, 2.0f, 2.0f);
|
||||
|
||||
Transform child;
|
||||
child.position = Vector3(5.0f, 0.0f, 0.0f);
|
||||
child.rotation = Quaternion::Identity();
|
||||
child.scale = Vector3(1.0f, 1.0f, 1.0f);
|
||||
|
||||
Transform combined = parent * child;
|
||||
|
||||
Vector3 localPoint(1.0f, 0.0f, 0.0f);
|
||||
Vector3 worldPoint = combined.TransformPoint(localPoint);
|
||||
|
||||
Vector3 worldDir(0.0f, 1.0f, 0.0f);
|
||||
Vector3 transformedDir = combined.TransformDirection(worldDir);
|
||||
|
||||
Matrix4 mat = combined.ToMatrix();
|
||||
}
|
||||
```
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Transform {
|
||||
Vector3 position = Vector3::Zero();
|
||||
Quaternion rotation = Quaternion::Identity();
|
||||
Vector3 scale = Vector3::One();
|
||||
};
|
||||
```
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| [ToMatrix()](tomatrix.md) | `Matrix4` | 转换为 4x4 变换矩阵 |
|
||||
| [Inverse()](inverse.md) | `Transform` | 逆变换 |
|
||||
| `operator*(Transform, Transform)` | `Transform` | 组合变换 |
|
||||
| [TransformPoint(point)](transformpoint.md) | `Vector3` | 变换点（带平移） |
|
||||
| [TransformDirection(direction)](transformdirection.md) | `Vector3` | 变换方向（包含旋转和缩放） |
|
||||
| [InverseTransformPoint(point)](inversetransformpoint.md) | `Vector3` | 逆变换点 |
|
||||
| [InverseTransformDirection(direction)](inversetransformdirection.md) | `Vector3` | 逆变换方向 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Math 模块总览](../math.md) - 返回 Math 模块总览
|
||||
- [Matrix4](../matrix4/matrix4.md) - 4x4 矩阵
|
||||
|
||||
@@ -1,22 +0,0 @@
|
||||
# Transform::TransformDirection
|
||||
|
||||
```cpp
|
||||
Vector3 TransformDirection(const Vector3& direction) const
|
||||
```
|
||||
|
||||
变换方向（仅旋转，包含缩放）。
|
||||
|
||||
**参数：**
|
||||
- `direction` - 要变换的方向
|
||||
|
||||
**返回：** `Vector3` - 变换后的方向
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Transform t;
|
||||
Vector3 localDir(1.0f, 0.0f, 0.0f);
|
||||
Vector3 worldDir = t.TransformDirection(localDir);
|
||||
```
|
||||
@@ -1,22 +0,0 @@
|
||||
# Transform::TransformPoint
|
||||
|
||||
```cpp
|
||||
Vector3 TransformPoint(const Vector3& point) const
|
||||
```
|
||||
|
||||
变换点（包含位置、旋转和缩放）。
|
||||
|
||||
**参数：**
|
||||
- `point` - 要变换的点
|
||||
|
||||
**返回：** `Vector3` - 变换后的点
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Transform t;
|
||||
Vector3 localPos(1.0f, 0.0f, 0.0f);
|
||||
Vector3 worldPos = t.TransformPoint(localPos);
|
||||
```
|
||||
Reference in New Issue
Block a user