refactor: reorganize docs into plan/ and add skills/
This commit is contained in:
67
docs/api/math/math-aabb.md
Normal file
67
docs/api/math/math-aabb.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# AABB / OBB
|
||||
|
||||
轴对齐包围盒 (AABB) 和有向包围盒 (OBB)。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/AABB.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## AABB - 轴对齐包围盒
|
||||
|
||||
`AABB` 在 Math 库中通过 `Bounds` 类型实现，参见 [math-bounds.md](math-bounds.md)。
|
||||
|
||||
## OBB - 有向包围盒
|
||||
|
||||
OBB 是可以任意方向旋转的包围盒。
|
||||
|
||||
```cpp
|
||||
struct OBB {
|
||||
Vector3 center;
|
||||
Vector3 extents; // 半长
|
||||
Matrix4 transform; // 变换矩阵
|
||||
};
|
||||
```
|
||||
|
||||
### 构造函数
|
||||
|
||||
- `OBB()` - 默认构造
|
||||
- `OBB(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
|
||||
|
||||
### 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `GetAxis(index)` | `Vector3` | 获取局部轴 (0=X, 1=Y, 2=Z) |
|
||||
| `GetMin()` | `Vector3` | 局部空间最小点 |
|
||||
| `GetMax()` | `Vector3` | 局部空间最大点 |
|
||||
| `Contains(point)` | `bool` | 点是否在 OBB 内 |
|
||||
| `Intersects(OBB)` | `bool` | 与另一个 OBB 相交 (SAT) |
|
||||
| `Intersects(Sphere)` | `bool` | 与球体相交 |
|
||||
|
||||
## 备注
|
||||
|
||||
- AABB 与轴对齐，检测简单但可能不够紧凑
|
||||
- OBB 可旋转，检测使用分离轴定理 (SAT)
|
||||
- OBB 适合动态旋转的物体
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// OBB
|
||||
OBB obb;
|
||||
obb.center = Vector3(0.0f);
|
||||
obb.extents = Vector3(1.0f);
|
||||
obb.transform = Matrix4::TRS(pos, rot, scale);
|
||||
|
||||
Vector3 localAxis = obb.GetAxis(0);
|
||||
|
||||
if (obb.Contains(point)) { ... }
|
||||
if (obb.Intersects(otherOBB)) { ... }
|
||||
if (obb.Intersects(sphere)) { ... }
|
||||
```
|
||||
61
docs/api/math/math-bounds.md
Normal file
61
docs/api/math/math-bounds.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Bounds
|
||||
|
||||
轴对齐包围盒 (AABB)，中心-范围表示。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Bounds.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Bounds {
|
||||
Vector3 center = Vector3::Zero();
|
||||
Vector3 extents = Vector3::Zero(); // 半长，不是最大点
|
||||
};
|
||||
```
|
||||
|
||||
## 构造函数
|
||||
|
||||
- `Bounds()` - 默认构造
|
||||
- `Bounds(const Vector3& center, const Vector3& size)` - 从中心和大小构造
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `GetMin()` | `Vector3` | 最小点: `center - extents` |
|
||||
| `GetMax()` | `Vector3` | 最大点: `center + extents` |
|
||||
| `SetMinMax(min, max)` | `void` | 从最小/最大点设置 |
|
||||
| `Contains(point)` | `bool` | 点是否在盒内 |
|
||||
| `Intersects(other)` | `bool` | 与另一个 Bounds 相交 |
|
||||
| `Encapsulate(point)` | `void` | 扩展包含点 |
|
||||
| `Encapsulate(bounds)` | `void` | 扩展包含另一个 Bounds |
|
||||
| `Expand(amount)` | `void` | 各方向扩展 amount |
|
||||
| `Expand(amount)` | `void` | 按 Vector3 扩展 |
|
||||
| `GetClosestPoint(point)` | `Vector3` | 盒上最接近给定点的点 |
|
||||
| `GetVolume()` | `float` | 体积 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Bounds bounds(center, extents);
|
||||
|
||||
// 包含点
|
||||
if (bounds.Contains(point)) { ... }
|
||||
|
||||
// 扩展包围盒
|
||||
bounds.Encapsulate(newPoint);
|
||||
|
||||
// 相交检测
|
||||
if (bounds.Intersects(other)) { ... }
|
||||
|
||||
// 设置
|
||||
bounds.SetMinMax(minPoint, maxPoint);
|
||||
```
|
||||
63
docs/api/math/math-box.md
Normal file
63
docs/api/math/math-box.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# Box
|
||||
|
||||
带变换的有向包围盒 (OBB) 结构体。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Box.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Box {
|
||||
Vector3 center = Vector3::Zero();
|
||||
Vector3 extents = Vector3::Zero(); // 半长
|
||||
Matrix4x4 transform = Matrix4x4::Identity();
|
||||
};
|
||||
```
|
||||
|
||||
OBB 由中心点、半长向量和变换矩阵定义。
|
||||
|
||||
## 构造函数
|
||||
|
||||
- `Box()` - 默认构造
|
||||
- `Box(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `GetMin()` | `Vector3` | 局部空间最小点 (-extents) |
|
||||
| `GetMax()` | `Vector3` | 局部空间最大点 (+extents) |
|
||||
| `Contains(point)` | `bool` | 点是否在盒内（变换到局部空间检测） |
|
||||
| `Intersects(Sphere)` | `bool` | 与球体相交 |
|
||||
| `Intersects(Box)` | `bool` | 与另一个 OBB 相交（SAT 算法） |
|
||||
| `Intersects(Ray, t)` | `bool` | 与射线相交，输出距离 t |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Box box(Vector3(0.0f), Vector3(1.0f)); // 2x2x2 盒子
|
||||
box.transform = Matrix4::TRS(position, rotation, scale);
|
||||
|
||||
// 点检测
|
||||
if (box.Contains(testPoint)) { ... }
|
||||
|
||||
// 球体相交
|
||||
if (box.Intersects(sphere)) { ... }
|
||||
|
||||
// OBB 相交
|
||||
if (box.Intersects(otherBox)) { ... }
|
||||
|
||||
// 射线相交
|
||||
float t;
|
||||
if (box.Intersects(ray, t)) {
|
||||
Vector3 hit = ray.GetPoint(t);
|
||||
}
|
||||
```
|
||||
72
docs/api/math/math-color.md
Normal file
72
docs/api/math/math-color.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Color
|
||||
|
||||
颜色结构体，支持 RGBA 浮点分量。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Color.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Color {
|
||||
float r = 1.0f;
|
||||
float g = 1.0f;
|
||||
float b = 1.0f;
|
||||
float a = 1.0f;
|
||||
};
|
||||
```
|
||||
|
||||
分量范围: 0.0f ~ 1.0f
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `White()` | `Color` | (1, 1, 1, 1) |
|
||||
| `Black()` | `Color` | (0, 0, 0, 1) |
|
||||
| `Red()` | `Color` | (1, 0, 0, 1) |
|
||||
| `Green()` | `Color` | (0, 1, 0, 1) |
|
||||
| `Blue()` | `Color` | (0, 0, 1, 1) |
|
||||
| `Yellow()` | `Color` | (1, 1, 0, 1) |
|
||||
| `Cyan()` | `Color` | (0, 1, 1, 1) |
|
||||
| `Magenta()` | `Color` | (1, 0, 1, 1) |
|
||||
| `Clear()` | `Color` | (0, 0, 0, 0)，透明黑 |
|
||||
|
||||
## 静态方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Lerp(a, b, t)` | `Color` | 颜色线性插值 |
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `ToRGBA()` | `uint32_t` | 转换为 32-bit RGBA (0xAABBGGRR) |
|
||||
| `ToVector3()` | `Vector3` | 转换为 RGB (丢弃 alpha) |
|
||||
| `ToVector4()` | `Vector4` | 转换为 RGBA |
|
||||
|
||||
## 运算符
|
||||
|
||||
| 运算符 | 描述 |
|
||||
|--------|------|
|
||||
| `operator+(Color, Color)` | 颜色相加 |
|
||||
| `operator-(Color, Color)` | 颜色相减 |
|
||||
| `operator*(Color, float)` | 颜色乘以标量 |
|
||||
| `operator/(Color, float)` | 颜色除以标量 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Color red = Color::Red();
|
||||
Color lerped = Color::Lerp(red, Color::Blue(), 0.5f);
|
||||
uint32_t rgba = lerped.ToRGBA();
|
||||
Vector4 v4 = lerped.ToVector4();
|
||||
```
|
||||
61
docs/api/math/math-frustum.md
Normal file
61
docs/api/math/math-frustum.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Frustum
|
||||
|
||||
视锥体，用于视锥剔除。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Frustum.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
class Frustum {
|
||||
public:
|
||||
Plane planes[6]; // 6 个裁剪平面
|
||||
|
||||
enum class PlaneIndex {
|
||||
Left = 0,
|
||||
Right = 1,
|
||||
Bottom = 2,
|
||||
Top = 3,
|
||||
Near = 4,
|
||||
Far = 5
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Contains(point)` | `bool` | 点是否在视锥内 |
|
||||
| `Contains(Sphere)` | `bool` | 球体是否在视锥内 |
|
||||
| `Contains(Bounds)` | `bool` | Bounds 是否在视锥内 |
|
||||
| `Intersects(Bounds)` | `bool` | Bounds 是否与视锥相交 |
|
||||
| `Intersects(Sphere)` | `bool` | 球体是否与视锥相交 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Frustum frustum;
|
||||
// 需要从相机矩阵构建视锥平面
|
||||
|
||||
// 视锥剔除
|
||||
for (const auto& object : objects) {
|
||||
if (frustum.Contains(object.bounds)) {
|
||||
// 物体在视锥内，渲染
|
||||
Render(object);
|
||||
}
|
||||
}
|
||||
|
||||
// 或使用相交检测
|
||||
if (frustum.Intersects(bounds)) {
|
||||
Render(object);
|
||||
}
|
||||
```
|
||||
51
docs/api/math/math-h.md
Normal file
51
docs/api/math/math-h.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Math - 数学常量
|
||||
|
||||
数学库全局常量和辅助函数。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Math.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 数学常量
|
||||
|
||||
| 常量 | 值 | 描述 |
|
||||
|------|-----|------|
|
||||
| `PI` | 3.14159265358979323846f | 圆周率 |
|
||||
| `TWO_PI` | 6.28318530717958647692f | 2π |
|
||||
| `HALF_PI` | 1.57079632679489661923f | π/2 |
|
||||
| `DEG_TO_RAD` | PI / 180.0f | 度转弧度 |
|
||||
| `RAD_TO_DEG` | 180.0f / PI | 弧度转度 |
|
||||
| `EPSILON` | 1e-6f | 浮点比较容差 |
|
||||
| `FLOAT_MAX` | 3.402823466e+38f | float 最大值 |
|
||||
|
||||
## 辅助函数
|
||||
|
||||
| 函数 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Radians(degrees)` | `float` | 度转弧度 |
|
||||
| `Degrees(radians)` | `float` | 弧度转度 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
float radians = 90.0f * DEG_TO_RAD; // 90度 -> 弧度
|
||||
float degrees = PI * RAD_TO_DEG; // 弧度 -> 度
|
||||
float rad2 = Radians(45.0f); // 使用函数
|
||||
|
||||
// 浮点比较
|
||||
if (std::abs(a - b) < EPSILON) {
|
||||
// a 和 b 相等
|
||||
}
|
||||
|
||||
// 三角函数（来自 <cmath>）
|
||||
float sinVal = std::sin(angle);
|
||||
float cosVal = std::cos(angle);
|
||||
```
|
||||
69
docs/api/math/math-matrix3.md
Normal file
69
docs/api/math/math-matrix3.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# Matrix3 / Matrix3x3
|
||||
|
||||
3x3 矩阵结构体，用于表示 3D 旋转和缩放变换。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Matrix3.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 类型别名
|
||||
|
||||
```cpp
|
||||
using Matrix3 = Matrix3x3;
|
||||
```
|
||||
|
||||
## 存储方式
|
||||
|
||||
行优先存储 (row-major)：
|
||||
```
|
||||
m[row][col]
|
||||
m[0][0] m[0][1] m[0][2]
|
||||
m[1][0] m[1][1] m[1][2]
|
||||
m[2][0] m[2][1] m[2][2]
|
||||
```
|
||||
|
||||
## 构造函数
|
||||
|
||||
- 默认构造函数初始化为零矩阵
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Identity()` | `Matrix3` | 单位矩阵 |
|
||||
| `Zero()` | `Matrix3` | 零矩阵 |
|
||||
| `RotationX(float radians)` | `Matrix3` | X 轴旋转矩阵 |
|
||||
| `RotationY(float radians)` | `Matrix3` | Y 轴旋转矩阵 |
|
||||
| `RotationZ(float radians)` | `Matrix3` | Z 轴旋转矩阵 |
|
||||
| `Scale(const Vector3& scale)` | `Matrix3` | 缩放矩阵 |
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Transpose()` | `Matrix3` | 转置矩阵 |
|
||||
| `Inverse()` | `Matrix3` | 逆矩阵 |
|
||||
| `Determinant()` | `float` | 行列式 |
|
||||
|
||||
## 运算符
|
||||
|
||||
| 运算符 | 描述 |
|
||||
|--------|------|
|
||||
| `operator*(Matrix3, Matrix3)` | 矩阵乘法 |
|
||||
| `operator*(Matrix3, Vector3)` | 矩阵-向量乘法 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Matrix3 rotX = Matrix3::RotationX(Math::HALF_PI);
|
||||
Matrix3 rotY = Matrix3::RotationY(0.0f);
|
||||
Matrix3 scale = Matrix3::Scale(Vector3(2.0f, 2.0f, 2.0f));
|
||||
Matrix3 combined = rotX * scale;
|
||||
Vector3 transformed = combined * Vector3(1.0f, 0.0f, 0.0f);
|
||||
```
|
||||
101
docs/api/math/math-matrix4.md
Normal file
101
docs/api/math/math-matrix4.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Matrix4 / Matrix4x4
|
||||
|
||||
4x4 矩阵结构体，用于表示完整的 3D 变换（平移、旋转、缩放）、视图和投影变换。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Matrix4.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 类型别名
|
||||
|
||||
```cpp
|
||||
using Matrix4 = Matrix4x4;
|
||||
```
|
||||
|
||||
## 存储方式
|
||||
|
||||
行优先存储 (row-major)：
|
||||
```
|
||||
m[0][0] m[0][1] m[0][2] m[0][3]
|
||||
m[1][0] m[1][1] m[1][2] m[1][3]
|
||||
m[2][0] m[2][1] m[2][2] m[2][3]
|
||||
m[3][0] m[3][1] m[3][2] m[3][3]
|
||||
```
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
### 基础变换
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Identity()` | `Matrix4` | 单位矩阵 |
|
||||
| `Zero()` | `Matrix4` | 零矩阵 |
|
||||
| `Translation(const Vector3& v)` | `Matrix4` | 平移矩阵 |
|
||||
| `Scale(const Vector3& v)` | `Matrix4` | 缩放矩阵 |
|
||||
| `Rotation(const Quaternion& q)` | `Matrix4` | 旋转矩阵（四元数） |
|
||||
| `TRS(translation, rotation, scale)` | `Matrix4` | 完整变换 |
|
||||
|
||||
### 旋转
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `RotationX(float radians)` | `Matrix4` | X 轴旋转 |
|
||||
| `RotationY(float radians)` | `Matrix4` | Y 轴旋转 |
|
||||
| `RotationZ(float radians)` | `Matrix4` | Z 轴旋转 |
|
||||
|
||||
### 相机变换
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `LookAt(eye, target, up)` | `Matrix4` | 视图矩阵 |
|
||||
| `Perspective(fov, aspect, near, far)` | `Matrix4` | 透视投影 |
|
||||
| `Orthographic(left, right, bottom, top, near, far)` | `Matrix4` | 正交投影 |
|
||||
|
||||
## 实例方法
|
||||
|
||||
### 乘法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `operator*(Matrix4, Matrix4)` | `Matrix4` | 矩阵乘法 |
|
||||
| `operator*(Matrix4, Vector4)` | `Vector4` | 矩阵-向量乘法 |
|
||||
| `MultiplyPoint(v)` | `Vector3` | 点变换（带平移） |
|
||||
| `MultiplyVector(v)` | `Vector3` | 方向变换（不带平移） |
|
||||
|
||||
### 分解
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Transpose()` | `Matrix4` | 转置矩阵 |
|
||||
| `Inverse()` | `Matrix4` | 逆矩阵 |
|
||||
| `Determinant()` | `float` | 行列式 |
|
||||
| `GetTranslation()` | `Vector3` | 获取平移分量 |
|
||||
| `GetRotation()` | `Quaternion` | 获取旋转分量 |
|
||||
| `GetScale()` | `Vector3` | 获取缩放分量 |
|
||||
| `Decompose(translation, rotation, scale)` | `void` | 分解所有分量 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// MVP 矩阵
|
||||
Matrix4 model = Matrix4::TRS(position, rotation, scale);
|
||||
Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up());
|
||||
Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f);
|
||||
Matrix4 mvp = proj * view * model;
|
||||
|
||||
// 变换点
|
||||
Vector3 worldPos = model.MultiplyPoint(localPos);
|
||||
Vector3 worldDir = model.MultiplyVector(localDir);
|
||||
|
||||
// 分解矩阵
|
||||
Vector3 translation;
|
||||
Quaternion rotation;
|
||||
Vector3 scale;
|
||||
model.Decompose(translation, rotation, scale);
|
||||
```
|
||||
100
docs/api/math/math-overview.md
Normal file
100
docs/api/math/math-overview.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Math 模块概览
|
||||
|
||||
**命名空间**: `XCEngine::Math`
|
||||
|
||||
**类型**: `module`
|
||||
|
||||
**描述**: XCEngine 的数学库模块，提供图形引擎常用的数学类型和函数。
|
||||
|
||||
## 概述
|
||||
|
||||
Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四元数、变换和几何类型等。
|
||||
|
||||
## 模块内容
|
||||
|
||||
### 向量类型
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [Vector2](./math-vector2.md) | `Vector2.h` | 二维向量 |
|
||||
| [Vector3](./math-vector3.md) | `Vector3.h` | 三维向量 |
|
||||
| [Vector4](./math-vector4.md) | `Vector4.h` | 四维向量 |
|
||||
|
||||
### 矩阵类型
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [Matrix3](./math-matrix3.md) | `Matrix3.h` | 3x3 矩阵 |
|
||||
| [Matrix4](./math-matrix4.md) | `Matrix4.h` | 4x4 矩阵 |
|
||||
|
||||
### 旋转/变换
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [Quaternion](./math-quaternion.md) | `Quaternion.h` | 四元数 |
|
||||
| [Transform](./math-transform.md) | `Transform.h` | 变换组件 |
|
||||
|
||||
### 几何类型
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [Color](./math-color.md) | `Color.h` | 颜色 |
|
||||
| [Ray](./math-ray.md) | `Ray.h` | 射线 |
|
||||
| [Plane](./math-plane.md) | `Plane.h` | 平面 |
|
||||
| [Sphere](./math-sphere.md) | `Sphere.h` | 球体 |
|
||||
| [Box](./math-box.md) | `Box.h` | 盒子 |
|
||||
| [Bounds](./math-bounds.md) | `Bounds.h` | 包围盒 |
|
||||
| [AABB](./math-aabb.md) | `AABB.h` | 轴对齐包围盒 |
|
||||
| [Frustum](./math-frustum.md) | `Frustum.h` | 视锥体 |
|
||||
| [Rect](./math-rect.md) | `Rect.h` | 二维矩形 |
|
||||
|
||||
## 常量定义
|
||||
|
||||
| 常量 | 值 | 描述 |
|
||||
|------|-----|------|
|
||||
| `PI` | 3.14159265358979323846f | 圆周率 |
|
||||
| `TWO_PI` | 6.28318530717958647692f | 2π |
|
||||
| `HALF_PI` | 1.57079632679489661923f | π/2 |
|
||||
| `DEG_TO_RAD` | PI / 180.0f | 度到弧度 |
|
||||
| `RAD_TO_DEG` | 180.0f / PI | 弧度到度 |
|
||||
| `EPSILON` | 1e-6f | 浮点精度 |
|
||||
| `FLOAT_MAX` | 3.402823466e+38f | 浮点最大值 |
|
||||
|
||||
详细文档: [Math.h - 常量和辅助函数](./math-h.md)
|
||||
|
||||
## 辅助函数
|
||||
|
||||
| 函数 | 描述 |
|
||||
|------|------|
|
||||
| `Radians(float degrees)` | 度转弧度 |
|
||||
| `Degrees(float radians)` | 弧度转度 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Math.h>
|
||||
#include <XCEngine/Math/Vector3.h>
|
||||
#include <XCEngine/Math/Matrix4.h>
|
||||
#include <XCEngine/Math/Quaternion.h>
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
// 向量运算
|
||||
Vector3 a(1.0f, 0.0f, 0.0f);
|
||||
Vector3 b(0.0f, 1.0f, 0.0f);
|
||||
float dot = Vector3::Dot(a, b);
|
||||
Vector3 cross = Vector3::Cross(a, b);
|
||||
Vector3 normalized = Vector3::Normalize(a);
|
||||
|
||||
// 矩阵运算
|
||||
Matrix4 model = Matrix4::TRS(position, rotation, scale);
|
||||
Matrix4 view = Matrix4::LookAt(eye, target, up);
|
||||
Matrix4 projection = Matrix4::Perspective(fov, aspect, near, far);
|
||||
Matrix4 mvp = projection * view * model;
|
||||
|
||||
// 四元数运算
|
||||
Quaternion q1 = Quaternion::FromEuler(0, 90, 0);
|
||||
Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(45.0f));
|
||||
Quaternion combined = q1 * q2;
|
||||
Vector3 rotated = q2 * Vector3::Forward();
|
||||
```
|
||||
66
docs/api/math/math-plane.md
Normal file
66
docs/api/math/math-plane.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# Plane
|
||||
|
||||
3D 平面结构体，由法线和距离表示。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Plane.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Plane {
|
||||
Vector3 normal = Vector3::Up(); // 单位法线
|
||||
float distance = 0.0f; // 原点到平面的有符号距离
|
||||
};
|
||||
```
|
||||
|
||||
平面方程: `dot(normal, X) + distance = 0`
|
||||
|
||||
## 构造函数
|
||||
|
||||
- `Plane()` - 默认构造 (y=0 平面)
|
||||
- `Plane(const Vector3& normal, float distance)` - 从法线和距离构造
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `FromPoints(a, b, c)` | `Plane` | 从三个不共线点创建 |
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `GetDistanceToPoint(point)` | `float` | 点到平面的有符号距离 |
|
||||
| `GetClosestPoint(point)` | `Vector3` | 平面上最接近给定点的点 |
|
||||
| `GetSide(point)` | `bool` | 点在平面的哪一侧 (true=正面) |
|
||||
| `Intersects(Sphere)` | `bool` | 与球体相交 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 创建平面
|
||||
Plane floor;
|
||||
floor.normal = Vector3::Up();
|
||||
floor.distance = 0.0f; // y=0 平面
|
||||
|
||||
// 或者从三点创建
|
||||
Plane plane = Plane::FromPoints(p0, p1, p2);
|
||||
|
||||
// 检测点在哪侧
|
||||
bool above = floor.GetSide(point);
|
||||
float signedDist = floor.GetDistanceToPoint(point);
|
||||
|
||||
// 投影点到平面
|
||||
Vector3 closest = floor.GetClosestPoint(point);
|
||||
|
||||
// 平面相交检测
|
||||
if (plane.Intersects(sphere)) { ... }
|
||||
```
|
||||
86
docs/api/math/math-quaternion.md
Normal file
86
docs/api/math/math-quaternion.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# Quaternion
|
||||
|
||||
四元数结构体，用于表示 3D 旋转，避免欧拉角的万向锁问题。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Quaternion.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Quaternion {
|
||||
float x = 0.0f;
|
||||
float y = 0.0f;
|
||||
float z = 0.0f;
|
||||
float w = 1.0f; // w 是标量分量
|
||||
};
|
||||
```
|
||||
|
||||
四元数格式: `(x, y, z, w)` = `(vec, w)`
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Identity()` | `Quaternion` | 返回 (0, 0, 0, 1)，恒等旋转 |
|
||||
| `FromAxisAngle(axis, radians)` | `Quaternion` | 从轴角创建 |
|
||||
| `FromEulerAngles(pitch, yaw, roll)` | `Quaternion` | 从欧拉角创建（弧度） |
|
||||
| `FromEulerAngles(euler)` | `Quaternion` | 从 Vector3 欧拉角创建 |
|
||||
| `FromRotationMatrix(matrix)` | `Quaternion` | 从旋转矩阵创建 |
|
||||
| `Slerp(a, b, t)` | `Quaternion` | 球面线性插值 |
|
||||
| `LookRotation(forward, up)` | `Quaternion` | 看向方向 |
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `ToEulerAngles()` | `Vector3` | 转换为欧拉角（弧度） |
|
||||
| `ToMatrix4x4()` | `Matrix4` | 转换为 4x4 旋转矩阵 |
|
||||
| `Inverse()` | `Quaternion` | 共轭/逆四元数 |
|
||||
| `Dot(other)` | `float` | 点积 |
|
||||
| `Magnitude()` | `float` | 模长 |
|
||||
| `Normalized()` | `Quaternion` | 归一化 |
|
||||
| `Normalize(q)` | `Quaternion` | 归一化（静态） |
|
||||
|
||||
## 运算符
|
||||
|
||||
| 运算符 | 描述 |
|
||||
|--------|------|
|
||||
| `operator*(Quaternion, Quaternion)` | 组合旋转 |
|
||||
|
||||
## 与 Vector3 的乘法
|
||||
|
||||
```cpp
|
||||
Vector3 operator*(const Quaternion& q, const Vector3& v);
|
||||
```
|
||||
用四元数旋转向量。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 创建旋转
|
||||
Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f);
|
||||
|
||||
// 组合旋转
|
||||
Quaternion combined = rot1 * rot2;
|
||||
|
||||
// 球面插值
|
||||
Quaternion lerped = Quaternion::Slerp(rot1, rot2, 0.5f);
|
||||
|
||||
// 旋转向量
|
||||
Vector3 rotated = rot * Vector3::Forward();
|
||||
|
||||
// 转换
|
||||
Vector3 euler = rot.ToEulerAngles();
|
||||
Matrix4 mat = rot.ToMatrix4x4();
|
||||
|
||||
// 看向目标
|
||||
Quaternion lookAt = Quaternion::LookRotation(target - position);
|
||||
```
|
||||
58
docs/api/math/math-ray.md
Normal file
58
docs/api/math/math-ray.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Ray
|
||||
|
||||
3D 射线结构体，用于光线投射和拾取。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Ray.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Ray {
|
||||
Vector3 origin; // 射线起点
|
||||
Vector3 direction; // 归一化方向
|
||||
};
|
||||
```
|
||||
|
||||
## 构造函数
|
||||
|
||||
- `Ray()` - 默认构造
|
||||
- `Ray(const Vector3& origin, const Vector3& direction)` - 从点和方向构造
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `GetPoint(t)` | `Vector3` | 获取射线上 t 距离处的点: `origin + direction * t` |
|
||||
|
||||
## 相交检测
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Intersects(Sphere, t)` | `bool` | 与球体相交，输出距离 t |
|
||||
| `Intersects(Box, t)` | `bool` | 与 AABB 相交，输出距离 t |
|
||||
| `Intersects(Plane, t)` | `bool` | 与平面相交，输出距离 t |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Ray ray(cameraPosition, rayDirection);
|
||||
|
||||
// 与球体相交
|
||||
float t;
|
||||
if (ray.Intersects(sphere, t)) {
|
||||
Vector3 hitPoint = ray.GetPoint(t);
|
||||
}
|
||||
|
||||
// 与平面相交
|
||||
if (ray.Intersects(plane, t)) {
|
||||
Vector3 hitPoint = ray.GetPoint(t);
|
||||
}
|
||||
```
|
||||
137
docs/api/math/math-rect.md
Normal file
137
docs/api/math/math-rect.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# Rect / RectInt / Viewport
|
||||
|
||||
2D 矩形和视口结构体。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Rect.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
---
|
||||
|
||||
## Rect - 浮点矩形
|
||||
|
||||
```cpp
|
||||
struct Rect {
|
||||
float x = 0.0f; // 左边界
|
||||
float y = 0.0f; // 上边界
|
||||
float width = 0.0f;
|
||||
float height = 0.0f;
|
||||
};
|
||||
```
|
||||
|
||||
### 构造
|
||||
|
||||
- `Rect(float x, float y, float w, float h)`
|
||||
|
||||
### 边界访问
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `GetLeft()` | `float` | x |
|
||||
| `GetRight()` | `float` | x + width |
|
||||
| `GetTop()` | `float` | y |
|
||||
| `GetBottom()` | `float` | y + height |
|
||||
| `GetPosition()` | `Vector2` | (x, y) |
|
||||
| `GetSize()` | `Vector2` | (width, height) |
|
||||
| `GetCenter()` | `Vector2` | 中心点 |
|
||||
|
||||
### 检测方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Contains(px, py)` | `bool` | 点是否在矩形内 |
|
||||
| `Contains(point)` | `bool` | Vector2 点检测 |
|
||||
| `Intersects(other)` | `bool` | 与另一矩形相交 |
|
||||
|
||||
### 静态方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Intersect(a, b)` | `Rect` | 两矩形交集 |
|
||||
| `Union(a, b)` | `Rect` | 两矩形并集 |
|
||||
|
||||
### 设置方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Set(x, y, w, h)` | `void` | 设置所有值 |
|
||||
| `SetPosition(x, y)` | `void` | 设置位置 |
|
||||
| `SetPosition(Vector2)` | `void` | 设置位置 |
|
||||
|
||||
---
|
||||
|
||||
## RectInt - 整数矩形
|
||||
|
||||
```cpp
|
||||
struct RectInt {
|
||||
int32_t x = 0;
|
||||
int32_t y = 0;
|
||||
int32_t width = 0;
|
||||
int32_t height = 0;
|
||||
};
|
||||
```
|
||||
|
||||
与 Rect 类似，但使用 int32_t 类型。
|
||||
|
||||
### 边界访问
|
||||
|
||||
`GetLeft/Right/Top/Bottom/GetPosition/GetSize/GetCenter` - 返回 int32_t 或 Vector2。
|
||||
|
||||
### 检测
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Contains(px, py)` | `bool` | 整数点检测 |
|
||||
| `Intersects(other)` | `bool` | 相交检测 |
|
||||
|
||||
---
|
||||
|
||||
## Viewport - 视口
|
||||
|
||||
用于渲染视口和屏幕映射。
|
||||
|
||||
```cpp
|
||||
struct Viewport {
|
||||
float x = 0.0f;
|
||||
float y = 0.0f;
|
||||
float width = 0.0f;
|
||||
float height = 0.0f;
|
||||
float minDepth = 0.0f;
|
||||
float maxDepth = 1.0f;
|
||||
};
|
||||
```
|
||||
|
||||
### 构造
|
||||
|
||||
- `Viewport(float x, float y, float w, float h)`
|
||||
- `Viewport(float x, float y, float w, float h, float minD, float maxD)`
|
||||
|
||||
### 方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `GetAspectRatio()` | `float` | 宽高比 (width/height) |
|
||||
| `GetRect()` | `Rect` | 转换为 Rect |
|
||||
|
||||
---
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// Rect
|
||||
Rect screenRect(0.0f, 0.0f, 1920.0f, 1080.0f);
|
||||
if (screenRect.Contains(mouseX, mouseY)) { ... }
|
||||
|
||||
// 矩形相交
|
||||
Rect overlap = Rect::Intersect(rectA, rectB);
|
||||
|
||||
// Viewport
|
||||
Viewport viewport(0, 0, 1920, 1080);
|
||||
float aspect = viewport.GetAspectRatio(); // 16:9 = 1.78
|
||||
```
|
||||
47
docs/api/math/math-sphere.md
Normal file
47
docs/api/math/math-sphere.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Sphere
|
||||
|
||||
3D 球体结构体。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Sphere.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Sphere {
|
||||
Vector3 center = Vector3::Zero();
|
||||
float radius = 0.0f;
|
||||
};
|
||||
```
|
||||
|
||||
## 构造函数
|
||||
|
||||
- `Sphere()` - 默认构造
|
||||
- `Sphere(const Vector3& center, float radius)` - 从中心和半径构造
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Contains(point)` | `bool` | 点是否在球体内（包括表面） |
|
||||
| `Intersects(other)` | `bool` | 与另一个球体是否相交 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Sphere sphere(Vector3(0.0f, 0.0f, 0.0f), 1.0f);
|
||||
|
||||
// 检测点
|
||||
if (sphere.Contains(Vector3(0.5f, 0.0f, 0.0f))) { ... }
|
||||
|
||||
// 检测球体相交
|
||||
Sphere other(Vector3(1.0f, 0.0f, 0.0f), 1.0f);
|
||||
if (sphere.Intersects(other)) { ... }
|
||||
```
|
||||
67
docs/api/math/math-transform.md
Normal file
67
docs/api/math/math-transform.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Transform
|
||||
|
||||
3D 变换结构体，包含位置、旋转和缩放，用于层次化变换。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Transform.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## Space 枚举
|
||||
|
||||
```cpp
|
||||
enum class Space { Self, World };
|
||||
```
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Transform {
|
||||
Vector3 position = Vector3::Zero();
|
||||
Quaternion rotation = Quaternion::Identity();
|
||||
Vector3 scale = Vector3::One();
|
||||
};
|
||||
```
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `ToMatrix()` | `Matrix4` | 转换为 4x4 变换矩阵 |
|
||||
| `Inverse()` | `Transform` | 逆变换 |
|
||||
| `operator*(Transform, Transform)` | `Transform` | 组合变换 |
|
||||
|
||||
### 空间变换
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `TransformPoint(point)` | `Vector3` | 变换点（带平移） |
|
||||
| `TransformDirection(direction)` | `Vector3` | 变换方向（不带平移） |
|
||||
| `InverseTransformPoint(point)` | `Vector3` | 逆变换点 |
|
||||
| `InverseTransformDirection(direction)` | `Vector3` | 逆变换方向 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Transform world;
|
||||
world.position = Vector3(10.0f, 0.0f, 0.0f);
|
||||
world.rotation = Quaternion::Identity();
|
||||
world.scale = Vector3::One();
|
||||
|
||||
Matrix4 matrix = world.ToMatrix();
|
||||
|
||||
// 组合父子变换
|
||||
Transform parent, child;
|
||||
parent.position = Vector3(5.0f, 0.0f, 0.0f);
|
||||
child.position = Vector3(2.0f, 0.0f, 0.0f);
|
||||
Transform worldTransform = parent * child;
|
||||
|
||||
// 变换点
|
||||
Vector3 localPos(1.0f, 0.0f, 0.0f);
|
||||
Vector3 worldPos = world.TransformPoint(localPos);
|
||||
```
|
||||
68
docs/api/math/math-vector2.md
Normal file
68
docs/api/math/math-vector2.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Vector2
|
||||
|
||||
2D 向量结构体，用于表示 2D 空间中的点、方向或颜色。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Vector2.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Vector2 {
|
||||
float x = 0.0f;
|
||||
float y = 0.0f;
|
||||
};
|
||||
```
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Zero()` | `Vector2` | 返回 (0, 0) |
|
||||
| `One()` | `Vector2` | 返回 (1, 1) |
|
||||
| `Up()` | `Vector2` | 返回 (0, 1)，上方向 |
|
||||
| `Down()` | `Vector2` | 返回 (0, -1)，下方向 |
|
||||
| `Right()` | `Vector2` | 返回 (1, 0)，右方向 |
|
||||
| `Left()` | `Vector2` | 返回 (-1, 0)，左方向 |
|
||||
|
||||
## 静态数学方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Dot(a, b)` | `float` | 点积 |
|
||||
| `Cross(a, b)` | `float` | 2D 叉积（返回标量） |
|
||||
| `Normalize(v)` | `Vector2` | 归一化向量 |
|
||||
| `Magnitude(v)` | `float` | 向量长度 |
|
||||
| `SqrMagnitude(v)` | `float` | 长度平方（更快） |
|
||||
| `Lerp(a, b, t)` | `Vector2` | 线性插值 |
|
||||
| `MoveTowards(current, target, maxDistance)` | `Vector2` | 朝目标移动 |
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Magnitude()` | `float` | 获取向量长度 |
|
||||
| `SqrMagnitude()` | `float` | 获取长度平方 |
|
||||
| `Normalized()` | `Vector2` | 获取归一化副本 |
|
||||
|
||||
## 运算符
|
||||
|
||||
- 算术: `+`, `-`, `*` (scalar), `/` (scalar)
|
||||
- 复合赋值: `+=`, `-=`, `*=`, `/=`
|
||||
- 比较: `==`, `!=`
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Vector2 pos(5.0f, 3.0f);
|
||||
Vector2 dir = Vector2::Normalize(pos);
|
||||
float len = pos.Magnitude();
|
||||
Vector2 lerped = Vector2::Lerp(pos, Vector2::Zero(), 0.5f);
|
||||
```
|
||||
84
docs/api/math/math-vector3.md
Normal file
84
docs/api/math/math-vector3.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Vector3
|
||||
|
||||
3D 向量结构体，用于表示 3D 空间中的点、方向、颜色或法线。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Vector3.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Vector3 {
|
||||
float x = 0.0f;
|
||||
float y = 0.0f;
|
||||
float z = 0.0f;
|
||||
};
|
||||
```
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Zero()` | `Vector3` | 返回 (0, 0, 0) |
|
||||
| `One()` | `Vector3` | 返回 (1, 1, 1) |
|
||||
| `Forward()` | `Vector3` | 返回 (0, 0, 1)，前方向（Z+） |
|
||||
| `Back()` | `Vector3` | 返回 (0, 0, -1)，后方向 |
|
||||
| `Up()` | `Vector3` | 返回 (0, 1, 0)，上方向 |
|
||||
| `Down()` | `Vector3` | 返回 (0, -1, 0)，下方向 |
|
||||
| `Right()` | `Vector3` | 返回 (1, 0, 0)，右方向 |
|
||||
| `Left()` | `Vector3` | 返回 (-1, 0, 0)，左方向 |
|
||||
|
||||
## 静态数学方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Dot(a, b)` | `float` | 点积 |
|
||||
| `Cross(a, b)` | `Vector3` | 叉积（垂直于 a 和 b） |
|
||||
| `Normalize(v)` | `Vector3` | 归一化向量 |
|
||||
| `Magnitude(v)` | `float` | 向量长度 |
|
||||
| `SqrMagnitude(v)` | `float` | 长度平方 |
|
||||
| `Lerp(a, b, t)` | `Vector3` | 线性插值 |
|
||||
| `MoveTowards(current, target, maxDistance)` | `Vector3` | 朝目标移动 |
|
||||
| `Project(vector, onNormal)` | `Vector3` | 投影到法线上 |
|
||||
| `ProjectOnPlane(vector, planeNormal)` | `Vector3` | 投影到平面上 |
|
||||
| `Angle(from, to)` | `float` | 两向量夹角（度） |
|
||||
| `Reflect(inDirection, inNormal)` | `Vector3` | 反射 |
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Magnitude()` | `float` | 获取向量长度 |
|
||||
| `SqrMagnitude()` | `float` | 获取长度平方 |
|
||||
| `Normalized()` | `Vector3` | 获取归一化副本 |
|
||||
|
||||
## 运算符
|
||||
|
||||
- 算术: `+`, `-`, `*` (scalar/memberwise), `/` (scalar/memberwise)
|
||||
- 复合赋值: `+=`, `-=`, `*=`, `/=`
|
||||
- 下标: `operator[]` (0=x, 1=y, 2=z)
|
||||
- 比较: `==`, `!=`
|
||||
|
||||
## 与 Quaternion 的乘法
|
||||
|
||||
```cpp
|
||||
Vector3 operator*(const Quaternion& q, const Vector3& v);
|
||||
```
|
||||
用四元数旋转向量。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Vector3 pos(1.0f, 2.0f, 3.0f);
|
||||
Vector3 dir = Vector3::Normalize(pos);
|
||||
float len = pos.Magnitude();
|
||||
Vector3 reflected = Vector3::Reflect(dir, Vector3::Up());
|
||||
float angle = Vector3::Angle(Vector3::Forward(), dir);
|
||||
```
|
||||
62
docs/api/math/math-vector4.md
Normal file
62
docs/api/math/math-vector4.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Vector4
|
||||
|
||||
4D 向量结构体，用于表示齐次坐标、颜色 (RGBA) 或 SIMD 操作。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Vector4.h>
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Math`
|
||||
|
||||
## 结构体定义
|
||||
|
||||
```cpp
|
||||
struct Vector4 {
|
||||
float x = 0.0f;
|
||||
float y = 0.0f;
|
||||
float z = 0.0f;
|
||||
float w = 0.0f;
|
||||
};
|
||||
```
|
||||
|
||||
## 构造方法
|
||||
|
||||
- `Vector4(float x, float y, float z, float w)` - 从四个分量构造
|
||||
- `explicit Vector4(const Vector3& v, float w = 0.0f)` - 从 Vector3 构造
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Zero()` | `Vector4` | 返回 (0, 0, 0, 0) |
|
||||
| `One()` | `Vector4` | 返回 (1, 1, 1, 1) |
|
||||
|
||||
## 静态数学方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Dot(a, b)` | `float` | 4D 点积 |
|
||||
| `Project(vector, onNormal)` | `Vector4` | 投影 |
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `ToVector3()` | `Vector3` | 转换到 Vector3（丢弃 w） |
|
||||
|
||||
## 运算符
|
||||
|
||||
- 算术: `+`, `-`, `*` (scalar)
|
||||
- 下标: `operator[]`
|
||||
- 比较: `==`, `!=`
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
Vector4 pos4(1.0f, 2.0f, 3.0f, 1.0f);
|
||||
Vector3 pos3 = pos4.ToVector3();
|
||||
```
|
||||
Reference in New Issue
Block a user