diff --git a/docs/api/math/aabb/aabb.md b/docs/api/math/aabb/aabb.md index 637ef6c1..acaf5b91 100644 --- a/docs/api/math/aabb/aabb.md +++ b/docs/api/math/aabb/aabb.md @@ -1,10 +1,16 @@ # AABB / OBB -轴对齐包围盒 (AABB) 和有向包围盒 (OBB)。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/AABB.h` + +**描述**: 轴对齐包围盒 (AABB) 和有向包围盒 (OBB) + +## 概述 + +`AABB` 在 Math 库中通过 `Bounds` 类型实现。OBB 是可以任意方向旋转的包围盒。 ## AABB @@ -14,30 +20,28 @@ OBB 是可以任意方向旋转的包围盒。 -```cpp -struct OBB { - Vector3 center; - Vector3 extents; - Matrix4 transform; -}; -``` +## 结构体成员 -### 构造函数 +| 成员 | 类型 | 描述 | +|------|------|------| +| `center` | `Vector3` | OBB 中心点 | +| `extents` | `Vector3` | 从中心到每个面的距离 | +| `transform` | `Matrix4` | 变换矩阵 | -- `OBB()` - 默认构造 -- `OBB(const Vector3& center, const Vector3& extents)` - 从中心和半长构造 +## 公共方法 -### 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [GetAxis(index)](getaxis.md) | `Vector3` | 获取局部轴（index 必须是 0、1 或 2） | -| [GetMin()](../box/getmin.md) | `Vector3` | 局部空间最小点 | -| [GetMax()](../box/getmax.md) | `Vector3` | 局部空间最大点 | -| [Contains(point)](../box/contains.md) | `bool` | 点是否在 OBB 内 | -| [Intersects(OBB)](intersects-obb.md) | `bool` | 与另一个 OBB 相交 | -| [Intersects(Sphere)](intersects-sphere.md) | `bool` | 与球体相交 | +| 方法 | 描述 | +|------|------| +| `OBB()` | 默认构造 | +| `OBB(const Vector3& center, const Vector3& extents)` | 从中心和半长构造 | +| [GetAxis](obb-getaxis.md) | 获取局部轴 | +| [GetMin](obb-getmin.md) | 局部空间最小点 | +| [GetMax](obb-getmax.md) | 局部空间最大点 | +| [Contains](obb-contains.md) | 点是否在 OBB 内 | +| [Intersects(OBB)](intersects-obb.md) | 与另一个 OBB 相交 | +| [Intersects(Sphere)](intersects-sphere.md) | 与球体相交 | ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Bounds](bounds/bounds.md) - 轴对齐包围盒 +- [Math 模块总览](../math.md) \ No newline at end of file diff --git a/docs/api/math/aabb/getaxis.md b/docs/api/math/aabb/getaxis.md deleted file mode 100644 index 769e6ec4..00000000 --- a/docs/api/math/aabb/getaxis.md +++ /dev/null @@ -1,23 +0,0 @@ -# OBB::GetAxis - -```cpp -Vector3 GetAxis(int index) const -``` - -获取 OBB 的局部坐标轴。 - -**参数：** -- `index` - 轴索引（0=X轴, 1=Y轴, 2=Z轴） - -**返回：** `Vector3` - 对应轴的方向向量 - -**复杂度：** O(1) - -**示例：** - -```cpp -OBB obb = ...; -Vector3 xAxis = obb.GetAxis(0); // 局部 X 轴 -Vector3 yAxis = obb.GetAxis(1); // 局部 Y 轴 -Vector3 zAxis = obb.GetAxis(2); // 局部 Z 轴 -``` diff --git a/docs/api/math/aabb/intersects-obb.md b/docs/api/math/aabb/intersects-obb.md index feeadb99..03e87ca5 100644 --- a/docs/api/math/aabb/intersects-obb.md +++ b/docs/api/math/aabb/intersects-obb.md @@ -11,6 +11,8 @@ bool Intersects(const OBB& other) const **返回：** `bool` - true 表示相交 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -22,3 +24,7 @@ if (obbA.Intersects(obbB)) { // 两个有向包围盒相交 } ``` + +## 相关文档 + +- [AABB 总览](aabb.md) - 返回 AABB/OBB 总览 \ No newline at end of file diff --git a/docs/api/math/aabb/intersects-sphere.md b/docs/api/math/aabb/intersects-sphere.md index 13d919a2..2e97ad79 100644 --- a/docs/api/math/aabb/intersects-sphere.md +++ b/docs/api/math/aabb/intersects-sphere.md @@ -11,6 +11,8 @@ bool Intersects(const Sphere& sphere) const **返回：** `bool` - true 表示相交 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -22,3 +24,7 @@ if (obb.Intersects(sphere)) { // OBB 与球体相交 } ``` + +## 相关文档 + +- [AABB 总览](aabb.md) - 返回 AABB/OBB 总览 \ No newline at end of file diff --git a/docs/api/math/aabb/obb-contains.md b/docs/api/math/aabb/obb-contains.md index 9aee18e0..49b74a41 100644 --- a/docs/api/math/aabb/obb-contains.md +++ b/docs/api/math/aabb/obb-contains.md @@ -11,6 +11,8 @@ bool Contains(const Vector3& point) const **返回：** `bool` - true 表示点在 OBB 内 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -18,3 +20,7 @@ bool Contains(const Vector3& point) const ```cpp if (obb.Contains(point)) { /* inside */ } ``` + +## 相关文档 + +- [AABB 总览](aabb.md) - 返回 AABB/OBB 总览 \ No newline at end of file diff --git a/docs/api/math/aabb/obb-getaxis.md b/docs/api/math/aabb/obb-getaxis.md index c438abcc..a9123c1b 100644 --- a/docs/api/math/aabb/obb-getaxis.md +++ b/docs/api/math/aabb/obb-getaxis.md @@ -11,6 +11,8 @@ Vector3 GetAxis(int index) const **返回：** `Vector3` - 对应的局部轴 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -18,3 +20,7 @@ Vector3 GetAxis(int index) const ```cpp Vector3 xAxis = obb.GetAxis(0); ``` + +## 相关文档 + +- [AABB 总览](aabb.md) - 返回 AABB/OBB 总览 \ No newline at end of file diff --git a/docs/api/math/aabb/obb-getmax.md b/docs/api/math/aabb/obb-getmax.md index 04e56e81..4bce2572 100644 --- a/docs/api/math/aabb/obb-getmax.md +++ b/docs/api/math/aabb/obb-getmax.md @@ -8,6 +8,8 @@ Vector3 GetMax() const **返回：** `Vector3` - center + extents +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +17,7 @@ Vector3 GetMax() const ```cpp Vector3 max = obb.GetMax(); ``` + +## 相关文档 + +- [AABB 总览](aabb.md) - 返回 AABB/OBB 总览 \ No newline at end of file diff --git a/docs/api/math/aabb/obb-getmin.md b/docs/api/math/aabb/obb-getmin.md index 34d1bf14..d99b5f59 100644 --- a/docs/api/math/aabb/obb-getmin.md +++ b/docs/api/math/aabb/obb-getmin.md @@ -8,6 +8,8 @@ Vector3 GetMin() const **返回：** `Vector3` - center - extents +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +17,7 @@ Vector3 GetMin() const ```cpp Vector3 min = obb.GetMin(); ``` + +## 相关文档 + +- [AABB 总览](aabb.md) - 返回 AABB/OBB 总览 \ No newline at end of file diff --git a/docs/api/math/aabb/obb-intersects-obb.md b/docs/api/math/aabb/obb-intersects-obb.md deleted file mode 100644 index fb06b8a1..00000000 --- a/docs/api/math/aabb/obb-intersects-obb.md +++ /dev/null @@ -1,25 +0,0 @@ -# OBB::Intersects(OBB) - -```cpp -bool Intersects(const OBB& other) const; -``` - -判断两个 OBB 是否相交（SAT 分离轴定理）。 - -**返回：** 两包围盒是否相交 - -**复杂度：** O(1) - -**示例：** - -```cpp -OBB a(centerA, extentsA); -OBB b(centerB, extentsB); -if (a.Intersects(b)) { - // 两包围盒相交 -} -``` - -## 相关文档 - -- [AABB 总览](aabb.md) - 返回 AABB 概览 diff --git a/docs/api/math/aabb/obb-intersects-sphere.md b/docs/api/math/aabb/obb-intersects-sphere.md deleted file mode 100644 index 57071efc..00000000 --- a/docs/api/math/aabb/obb-intersects-sphere.md +++ /dev/null @@ -1,28 +0,0 @@ -# OBB::Intersects(Sphere) - -```cpp -bool Intersects(const Sphere& sphere) const; -``` - -判断 OBB 与球体是否相交。 - -**参数：** -- `sphere` - 球体 - -**返回：** OBB 与球体是否相交 - -**复杂度：** O(1) - -**示例：** - -```cpp -OBB obb(center, extents); -Sphere s(sphereCenter, radius); -if (obb.Intersects(s)) { - // OBB 与球体相交 -} -``` - -## 相关文档 - -- [AABB 总览](aabb.md) - 返回 AABB 概览 diff --git a/docs/api/math/bounds/bounds.constructors.md b/docs/api/math/bounds/bounds.constructors.md new file mode 100644 index 00000000..42d84717 --- /dev/null +++ b/docs/api/math/bounds/bounds.constructors.md @@ -0,0 +1,38 @@ +# Bounds::Bounds + +```cpp +Bounds() +Bounds(const Vector3& center, const Vector3& size) +``` + +构造一个 Bounds 对象。默认构造函数创建中心为原点、范围为零的包围盒。 + +**参数：** +- `center` - 包围盒的中心点 +- `size` - 包围盒的完整尺寸（非 extents，构造时会自动除以 2） + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +// 默认构造 +Bounds empty; +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); +// center = (0,0,0), extents = (1,1,1), 实际尺寸为 2x2x2 +``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [GetMin](getmin.md) - 获取最小点 +- [GetMax](getmax.md) - 获取最大点 diff --git a/docs/api/math/bounds/bounds.md b/docs/api/math/bounds/bounds.md index ba8aaf29..9886a87f 100644 --- a/docs/api/math/bounds/bounds.md +++ b/docs/api/math/bounds/bounds.md @@ -1,40 +1,64 @@ # Bounds -轴对齐包围盒 (AABB)，中心-范围表示。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Bounds.h` -## 结构体定义 +**描述**: 轴对齐包围盒，用于场景管理中的快速剔除 + +## 概述 + +Bounds 表示一个轴对齐包围盒（AABB），使用中心点 `center` 和范围 `extents` 定义。`extents` 是从中心到包围盒每个面的距离，因此实际尺寸为 `extents * 2`。常用于视锥剔除、碰撞检测和场景管理中的快速排除不可见物体。 + +## 结构体成员 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `center` | `Vector3` | 包围盒中心点 | +| `extents` | `Vector3` | 从中心到每个面的距离（实际尺寸 = extents * 2） | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Bounds`](bounds.constructors.md) | 构造函数 | +| [`GetMin`](getmin.md) | 获取包围盒最小点 | +| [`GetMax`](getmax.md) | 获取包围盒最大点 | +| [`SetMinMax`](setminmax.md) | 从最小/最大点设置包围盒 | +| [`Intersects`](intersects.md) | 检测与另一个 Bounds 是否相交 | +| [`Contains`](contains.md) | 检测点是否在盒内 | +| [`Encapsulate`](encapsulate.md) | 扩展包围盒以包含点或另一个 Bounds | +| [`Expand`](expand.md) | 扩展包围盒 | +| [`GetClosestPoint`](getclosestpoint.md) | 获取盒上最接近给定点的点 | +| [`GetVolume`](getvolume.md) | 计算包围盒体积 | + +## 使用示例 ```cpp -struct Bounds { - Vector3 center = Vector3::Zero(); - Vector3 extents = Vector3::Zero(); -}; +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); + +Vector3 min = bounds.GetMin(); +Vector3 max = bounds.GetMax(); + +bounds.Expand(1.0f); + +if (bounds.Contains(Vector3(0.0f, 0.0f, 0.0f))) { + // point is inside +} + +Bounds other(Vector3(5.0f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f)); +if (bounds.Intersects(other)) { + // bounds intersect +} ``` -## 构造函数 - -- `Bounds()` - 默认构造 -- `Bounds(const Vector3& center, const Vector3& size)` - 从中心和大小构造 - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [GetMin()](getmin.md) | `Vector3` | 最小点 | -| [GetMax()](getmax.md) | 最大点 | -| [SetMinMax(min, max)](setminmax.md) | `void` | 从最小/最大点设置 | -| [Contains(point)](contains.md) | `bool` | 点是否在盒内 | -| [Intersects(other)](intersects.md) | `bool` | 与另一个 Bounds 相交 | -| [Encapsulate(point)](encapsulate.md) | `void` | 扩展包含点 | -| [Encapsulate(bounds)](encapsulate-bounds.md) | `void` | 扩展包含另一个 Bounds | -| [Expand(amount)](expand.md) | `void` | 扩展包围盒 | -| [GetClosestPoint(point)](getclosestpoint.md) | `Vector3` | 盒上最接近的点 | -| [GetVolume()](getvolume.md) | `float` | 体积 | - ## 相关文档 - [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/bounds/contains.md b/docs/api/math/bounds/contains.md index 12cb6eff..57886c67 100644 --- a/docs/api/math/bounds/contains.md +++ b/docs/api/math/bounds/contains.md @@ -4,17 +4,35 @@ bool Contains(const Vector3& point) const ``` -检测点是否在包围盒内。 +检测给定点是否在包围盒内部。边界上的点被视为在盒内。 **参数：** - `point` - 要检测的点 -**返回：** `bool` - true 表示点在盒内 +**返回：** `bool` - true 表示点在盒内（包括边界） + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (bounds.Contains(point)) { /* inside */ } +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); +if (bounds.Contains(Vector3(0.0f, 0.0f, 0.0f))) { + // center is inside +} +if (!bounds.Contains(Vector3(10.0f, 0.0f, 0.0f))) { + // far away point is outside +} ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [Intersects](intersects.md) - 检测与另一个 Bounds 是否相交 diff --git a/docs/api/math/bounds/encapsulate-bounds.md b/docs/api/math/bounds/encapsulate-bounds.md deleted file mode 100644 index b6286108..00000000 --- a/docs/api/math/bounds/encapsulate-bounds.md +++ /dev/null @@ -1,18 +0,0 @@ -# Bounds::Encapsulate (Bounds) - -```cpp -void Encapsulate(const Bounds& bounds) -``` - -扩展包围盒以包含另一个 Bounds。 - -**参数：** -- `bounds` - 要包含的 Bounds - -**复杂度：** O(1) - -**示例：** - -```cpp -bounds.Encapsulate(otherBounds); -``` diff --git a/docs/api/math/bounds/encapsulate.md b/docs/api/math/bounds/encapsulate.md index 5a18ed31..50d9e3fe 100644 --- a/docs/api/math/bounds/encapsulate.md +++ b/docs/api/math/bounds/encapsulate.md @@ -5,17 +5,36 @@ void Encapsulate(const Vector3& point) void Encapsulate(const Bounds& bounds) ``` -扩展包围盒以包含点或另一个 Bounds。 +扩展包围盒以包含指定的点或另一个 Bounds。调用后，包围盒的 min/max 将被更新以确保目标被完全包含。 **参数：** - `point` - 要包含的点 - `bounds` - 要包含的 Bounds +**返回：** `void` + +**线程安全：** ✅ + **复杂度：** O(1) **示例：** ```cpp -bounds.Encapsulate(point); -bounds.Encapsulate(otherBounds); +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); +bounds.Encapsulate(Vector3(10.0f, 0.0f, 0.0f)); +// bounds now spans from (-1,-1,-1) to (10,1,1) + +Bounds other(Vector3(5.0f, 5.0f, 5.0f), Vector3(1.0f, 1.0f, 1.0f)); +bounds.Encapsulate(other); +// bounds now contains both original bounds and 'other' ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [Expand](expand.md) - 均匀扩展包围盒 diff --git a/docs/api/math/bounds/expand.md b/docs/api/math/bounds/expand.md index e9f1458f..56c90bb4 100644 --- a/docs/api/math/bounds/expand.md +++ b/docs/api/math/bounds/expand.md @@ -5,15 +5,34 @@ void Expand(float amount) void Expand(const Vector3& amount) ``` -扩展包围盒。 +扩展包围盒。输入值会被除以 2 后添加到 extents 上（标量扩展时，每个轴的 extents 增加 `amount * 0.5f`，即实际尺寸增加 `amount`；向量扩展时，各分量分别处理）。 **参数：** -- `amount` - 扩展量（各方向或统一） +- `amount` - 扩展量（标量时各方向均匀扩展，向量时各分量分别扩展） + +**返回：** `void` + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); bounds.Expand(1.0f); +// extents becomes (2.0, 2.0, 2.0), size increased by 1 in each direction + +bounds.Expand(Vector3(1.0f, 0.0f, 0.0f)); +// extents becomes (2.5, 2.0, 2.0), only x extended ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [Encapsulate](encapsulate.md) - 扩展以包含点或 Bounds diff --git a/docs/api/math/bounds/getclosestpoint.md b/docs/api/math/bounds/getclosestpoint.md index 96202ce5..e1037966 100644 --- a/docs/api/math/bounds/getclosestpoint.md +++ b/docs/api/math/bounds/getclosestpoint.md @@ -4,17 +4,35 @@ Vector3 GetClosestPoint(const Vector3& point) const ``` -获取包围盒上最接近给定点的点。 +获取包围盒上最接近给定点的点。如果点在盒内，则返回该点本身；如果在盒外，则返回该点在盒面上的投影点。 **参数：** - `point` - 参考点 **返回：** `Vector3` - 盒上最接近的点 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** ```cpp -Vector3 closest = bounds.GetClosestPoint(point); +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); + +Vector3 inside = bounds.GetClosestPoint(Vector3(0.0f, 0.0f, 0.0f)); +// returns (0, 0, 0) since point is inside + +Vector3 outside = bounds.GetClosestPoint(Vector3(10.0f, 0.0f, 0.0f)); +// returns (1, 0, 0) - closest point on box surface ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [Contains](contains.md) - 检测点是否在盒内 diff --git a/docs/api/math/bounds/getmax.md b/docs/api/math/bounds/getmax.md index c41e81d7..499cc2a8 100644 --- a/docs/api/math/bounds/getmax.md +++ b/docs/api/math/bounds/getmax.md @@ -4,14 +4,28 @@ Vector3 GetMax() const ``` -获取包围盒的最大点。 +获取包围盒的最大点（最大 corner）。 -**返回：** `Vector3` - center + extents +**返回：** `Vector3` - 包围盒最大点，等于 `center + extents` + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); Vector3 max = bounds.GetMax(); +// max = (1.0f, 1.0f, 1.0f) ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [GetMin](getmin.md) - 获取最小点 diff --git a/docs/api/math/bounds/getmin.md b/docs/api/math/bounds/getmin.md index facd7fff..fcc258ca 100644 --- a/docs/api/math/bounds/getmin.md +++ b/docs/api/math/bounds/getmin.md @@ -4,14 +4,28 @@ Vector3 GetMin() const ``` -获取包围盒的最小点。 +获取包围盒的最小点（最小 corner）。 -**返回：** `Vector3` - center - extents +**返回：** `Vector3` - 包围盒最小点，等于 `center - extents` + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); Vector3 min = bounds.GetMin(); +// min = (-1.0f, -1.0f, -1.0f) ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [GetMax](getmax.md) - 获取最大点 diff --git a/docs/api/math/bounds/getvolume.md b/docs/api/math/bounds/getvolume.md index 32ad29fe..4c918345 100644 --- a/docs/api/math/bounds/getvolume.md +++ b/docs/api/math/bounds/getvolume.md @@ -4,14 +4,27 @@ float GetVolume() const ``` -计算包围盒的体积。 +计算包围盒的体积。返回 `extents.x * 2.0f * extents.y * 2.0f * extents.z * 2.0f`。 -**返回：** `float` - 体积 +**返回：** `float` - 包围盒体积 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 2.0f, 3.0f)); float vol = bounds.GetVolume(); +// vol = 2 * 4 * 6 = 48 ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 diff --git a/docs/api/math/bounds/intersects.md b/docs/api/math/bounds/intersects.md index 2bbb642d..9bd9cce4 100644 --- a/docs/api/math/bounds/intersects.md +++ b/docs/api/math/bounds/intersects.md @@ -4,17 +4,33 @@ bool Intersects(const Bounds& other) const ``` -检测两个 Bounds 是否相交。 +检测该包围盒与另一个 Bounds 是否相交（重叠）。使用简化的 AABB 重叠检测算法，通过比较两个包围盒中心距离与它们 extents 之和来判断是否相交。 **参数：** - `other` - 另一个 Bounds -**返回：** `bool` - true 表示相交 +**返回：** `bool` - true 表示两个 Bounds 相交 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (bounds.Intersects(other)) { /* collision */ } +#include +#include + +using namespace XCEngine::Math; + +Bounds a(Vector3(0.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); +Bounds b(Vector3(1.0f, 0.0f, 0.0f), Vector3(2.0f, 2.0f, 2.0f)); +if (a.Intersects(b)) { + // a and b overlap +} ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [Contains](contains.md) - 检测点是否在盒内 diff --git a/docs/api/math/bounds/setminmax.md b/docs/api/math/bounds/setminmax.md index f575367b..21c64301 100644 --- a/docs/api/math/bounds/setminmax.md +++ b/docs/api/math/bounds/setminmax.md @@ -4,16 +4,33 @@ void SetMinMax(const Vector3& min, const Vector3& max) ``` -从最小/最大点设置包围盒。 +从最小点和最大点设置包围盒。中心点和范围由输入的 min/max 计算得出。 **参数：** -- `min` - 最小点 -- `max` - 最大点 +- `min` - 包围盒的最小点 +- `max` - 包围盒的最大点 + +**返回：** `void` + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -bounds.SetMinMax(minPoint, maxPoint); +#include +#include + +using namespace XCEngine::Math; + +Bounds bounds; +bounds.SetMinMax(Vector3(-1.0f, -1.0f, -1.0f), Vector3(1.0f, 1.0f, 1.0f)); +// center = (0, 0, 0), extents = (1, 1, 1) ``` + +## 相关文档 + +- [Bounds](bounds.md) - 返回类总览 +- [GetMin](getmin.md) - 获取最小点 +- [GetMax](getmax.md) - 获取最大点 diff --git a/docs/api/math/box/box.md b/docs/api/math/box/box.md index 3f6952e2..0a6418ff 100644 --- a/docs/api/math/box/box.md +++ b/docs/api/math/box/box.md @@ -1,44 +1,65 @@ # Box -带变换的包围盒结构体（支持 OBB 语义，取决于方法）。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Box.h` -## 结构体定义 +**描述**: 轴对齐盒体，用于碰撞检测和视锥体裁剪 + +## 概述 + +`Box` 是一个轴对齐包围盒（AABB）结构体，支持可选的变换矩阵以实现定向包围盒（OBB）语义。盒体由中心点 `center` 和半长 `extents` 定义，`transform` 矩阵可用于 `Contains` 和 `Intersects(Sphere)` 方法以执行真正的 OBB 检测。 + +**注意：** +- `Contains` 和 `Intersects(Sphere)` 方法会将点/球心变换到盒体局部空间（使用 `transform` 的逆矩阵）进行检测 +- `GetMin` / `GetMax` 返回的是未应用 `transform` 的局部空间角点（即 `center ± extents`） +- `Intersects(Box)` 目前使用 AABB 简化算法，未考虑旋转 + +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `center` | `Vector3` | 盒体中心点 | `Vector3::Zero()` | +| `extents` | `Vector3` | 从中心到每个面的距离（实际尺寸 = extents * 2） | `Vector3::Zero()` | +| `transform` | `Matrix4` | 变换矩阵，用于 OBB 检测 | 单位矩阵 | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Box()`](constructor.md) | 默认构造（各量为零） | +| [`Box(center, extents)`](constructor.md) | 从中心和半长构造 | +| [`GetMin`](getmin.md) | 获取局部空间最小点 | +| [`GetMax`](getmax.md) | 获取局部空间最大点 | +| [`Contains`](contains.md) | 点是否在盒内（使用 transform） | +| [`Intersects(Sphere)`](intersects.md) | 与球体相交 | +| [`Intersects(Box)`](intersects-box.md) | 与另一个盒相交（AABB 检测） | +| [`Intersects(Ray, t)`](intersects-ray.md) | 与射线相交 | + +## 使用示例 ```cpp -struct Box { - Vector3 center = Vector3::Zero(); - Vector3 extents = Vector3::Zero(); - Matrix4x4 transform = Matrix4x4::Identity(); -}; +#include +#include +#include + +using namespace XCEngine::Math; + +Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f)); + +Vector3 min = box.GetMin(); +Vector3 max = box.GetMax(); + +if (box.Contains(Vector3(0.5f, 0.5f, 0.5f))) { +} + +Sphere sphere(Vector3(2.0f, 0.0f, 0.0f), 1.0f); +if (box.Intersects(sphere)) { +} ``` -**成员：** -- `center` - 包围盒中心点 -- `extents` - 包围盒半长（各轴向的半径） -- `transform` - 变换矩阵（用于 OBB 检测） - -**注意：** `Contains` 方法会使用 `transform` 进行真正的 OBB 检测。`Intersects(Box)` 目前使用 AABB 简化算法，未考虑旋转。 - -## 构造函数 - -- `Box()` - 默认构造 -- `Box(const Vector3& center, const Vector3& extents)` - 从中心和半长构造 - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [GetMin()](getmin.md) | `Vector3` | 局部空间最小点 | -| [GetMax()](getmax.md) | `Vector3` | 局部空间最大点 | -| [Contains(point)](contains.md) | `bool` | 点是否在盒内（使用 transform） | -| [Intersects(Sphere)](intersects.md) | `bool` | 与球体相交 | -| [Intersects(Box)](intersects-box.md) | `bool` | 与另一个盒相交（AABB 检测） | -| [Intersects(Ray, t)](intersects-ray.md) | `bool` | 与射线相交 | - ## 相关文档 - [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/box/constructor.md b/docs/api/math/box/constructor.md new file mode 100644 index 00000000..723c055d --- /dev/null +++ b/docs/api/math/box/constructor.md @@ -0,0 +1,42 @@ +# Box::Box + +## 默认构造函数 + +```cpp +Box() = default; +``` + +构造一个盒体，`center` 为原点，`extents` 为零向量，`transform` 为单位矩阵。 + +## 带参构造函数 + +```cpp +Box(const Vector3& center, const Vector3& extents) +``` + +从指定的中心和半长构造一个盒体。 + +**参数：** +- `center` - 盒体的中心点 +- `extents` - 盒体在各轴向上的半长（从中心到面的距离） + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 2.0f, 1.5f)); +``` + +## 相关文档 + +- [Box 类总览](box.md) - 返回类总览 diff --git a/docs/api/math/box/contains.md b/docs/api/math/box/contains.md index 3bac9af7..9ce9cda0 100644 --- a/docs/api/math/box/contains.md +++ b/docs/api/math/box/contains.md @@ -4,17 +4,30 @@ bool Contains(const Vector3& point) const ``` -检测点是否在盒内。 +检测点是否在盒体内。该方法使用 `transform` 矩阵将点转换到盒体局部空间进行检测，支持 OBB 语义。 **参数：** -- `point` - 要检测的点 +- `point` - 要检测的点（世界坐标） -**返回：** `bool` - true 表示点在盒内 +**返回：** `bool` - 点在盒体内返回 true，否则返回 false + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (box.Contains(point)) { /* inside */ } +#include +#include + +using namespace XCEngine::Math; + +Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f)); +if (box.Contains(Vector3(0.5f, 0.5f, 0.5f))) { +} ``` + +## 相关文档 + +- [Box 类总览](box.md) - 返回类总览 diff --git a/docs/api/math/box/getmax.md b/docs/api/math/box/getmax.md index 364e463f..fc95aea2 100644 --- a/docs/api/math/box/getmax.md +++ b/docs/api/math/box/getmax.md @@ -4,14 +4,29 @@ Vector3 GetMax() const ``` -获取局部空间最大点。 +获取盒体在局部空间中的最大点（角点）。 -**返回：** `Vector3` - (+extents) +**参数：** 无 + +**返回：** `Vector3` - 盒体最大点，即 `center + extents` + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include +#include + +using namespace XCEngine::Math; + +Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 2.0f, 1.0f)); Vector3 max = box.GetMax(); ``` + +## 相关文档 + +- [Box 类总览](box.md) - 返回类总览 +- [GetMin](getmin.md) - 获取最小点 diff --git a/docs/api/math/box/getmin.md b/docs/api/math/box/getmin.md index 6b338b9c..2188b670 100644 --- a/docs/api/math/box/getmin.md +++ b/docs/api/math/box/getmin.md @@ -4,14 +4,29 @@ Vector3 GetMin() const ``` -获取局部空间最小点。 +获取盒体在局部空间中的最小点（角点）。 -**返回：** `Vector3` - (-extents) +**参数：** 无 + +**返回：** `Vector3` - 盒体最小点，即 `center - extents` + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include +#include + +using namespace XCEngine::Math; + +Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 2.0f, 1.0f)); Vector3 min = box.GetMin(); ``` + +## 相关文档 + +- [Box 类总览](box.md) - 返回类总览 +- [GetMax](getmax.md) - 获取最大点 diff --git a/docs/api/math/box/intersects-box.md b/docs/api/math/box/intersects-box.md index 4bf9c5e0..213baf59 100644 --- a/docs/api/math/box/intersects-box.md +++ b/docs/api/math/box/intersects-box.md @@ -4,19 +4,32 @@ bool Intersects(const Box& other) const ``` -检测两个盒是否相交（使用 AABB 简化算法，暂未考虑 transform 旋转）。 +检测两个盒体是否相交。该方法使用 AABB 简化算法，通过比较两个盒体的最小点和最大点进行相交检测。 + +**注意：** 当前实现为 AABB 检测，未使用 `transform` 进行真正的 OBB-SAT 检测。 **参数：** -- `other` - 另一个盒 +- `other` - 另一个盒体 -**返回：** `bool` - true 表示相交 +**返回：** `bool` - 相交返回 true，否则返回 false -**注意：** 当前实现为 AABB 检测，未使用 transform 进行真正的 OBB-SAT 检测。 +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (box.Intersects(otherBox)) { /* collision */ } +#include + +using namespace XCEngine::Math; + +Box box1(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f)); +Box box2(Vector3(1.5f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f)); +if (box1.Intersects(box2)) { +} ``` + +## 相关文档 + +- [Box 类总览](box.md) - 返回类总览 diff --git a/docs/api/math/box/intersects-ray.md b/docs/api/math/box/intersects-ray.md index 7a4c05a7..5bd2877b 100644 --- a/docs/api/math/box/intersects-ray.md +++ b/docs/api/math/box/intersects-ray.md @@ -4,21 +4,35 @@ bool Intersects(const Ray& ray, float& t) const ``` -检测盒是否与射线相交。 +检测盒体是否与射线相交。如果相交，通过 `t` 输出射线原点到交点的距离。 **参数：** -- `ray` - 射线 -- `t` - 输出交点距离 +- `ray` - 要检测的射线 +- `t` - 输出交点距离（如果返回 true） -**返回：** `bool` - true 表示相交 +**返回：** `bool` - 相交返回 true，否则返回 false + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include +#include + +using namespace XCEngine::Math; + +Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f)); +Ray ray(Vector3(0.0f, 0.0f, -5.0f), Vector3(0.0f, 0.0f, 1.0f)); float t; if (box.Intersects(ray, t)) { - Vector3 hit = ray.GetPoint(t); + Vector3 hitPoint = ray.GetPoint(t); } ``` + +## 相关文档 + +- [Box 类总览](box.md) - 返回类总览 +- [Ray::Intersects](../ray/ray.md) - 射线相交检测 diff --git a/docs/api/math/box/intersects.md b/docs/api/math/box/intersects.md index d536651c..14f3974b 100644 --- a/docs/api/math/box/intersects.md +++ b/docs/api/math/box/intersects.md @@ -1,20 +1,34 @@ -# Box::Intersects +# Box::Intersects (Sphere) ```cpp bool Intersects(const Sphere& sphere) const ``` -检测盒是否与球体相交。 +检测盒体是否与球体相交。该方法使用 `transform` 矩阵将球体中心转换到盒体局部空间进行检测，支持 OBB 语义。 **参数：** -- `sphere` - 球体 +- `sphere` - 要检测的球体 -**返回：** `bool` - true 表示相交 +**返回：** `bool` - 相交返回 true，否则返回 false + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (box.Intersects(sphere)) { /* collision */ } +#include +#include + +using namespace XCEngine::Math; + +Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f)); +Sphere sphere(Vector3(2.0f, 0.0f, 0.0f), 1.0f); +if (box.Intersects(sphere)) { +} ``` + +## 相关文档 + +- [Box 类总览](box.md) - 返回类总览 diff --git a/docs/api/math/color/black.md b/docs/api/math/color/black.md index 002486ca..89a9080e 100644 --- a/docs/api/math/color/black.md +++ b/docs/api/math/color/black.md @@ -6,6 +6,19 @@ static Color Black() 返回黑色 (0, 0, 0, 1)。 -**返回：** `Color` +**返回：** `Color` - 黑色 -**示例：** `Color c = Color::Black();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::Black(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`White`](white.md) - 返回白色 diff --git a/docs/api/math/color/blue.md b/docs/api/math/color/blue.md index 382790f6..acb1167d 100644 --- a/docs/api/math/color/blue.md +++ b/docs/api/math/color/blue.md @@ -6,6 +6,19 @@ static Color Blue() 返回蓝色 (0, 0, 1, 1)。 -**返回：** `Color` +**返回：** `Color` - 蓝色 -**示例：** `Color c = Color::Blue();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::Blue(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`Yellow`](yellow.md) - 返回黄色 diff --git a/docs/api/math/color/clear.md b/docs/api/math/color/clear.md index ff5fc2f7..f86a0d5c 100644 --- a/docs/api/math/color/clear.md +++ b/docs/api/math/color/clear.md @@ -6,6 +6,19 @@ static Color Clear() 返回透明黑色 (0, 0, 0, 0)。 -**返回：** `Color` +**返回：** `Color` - 透明黑色 -**示例：** `Color c = Color::Clear();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::Clear(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`Black`](black.md) - 返回不透明黑色 diff --git a/docs/api/math/color/color.md b/docs/api/math/color/color.md index de20d2cc..6add2287 100644 --- a/docs/api/math/color/color.md +++ b/docs/api/math/color/color.md @@ -1,63 +1,93 @@ # Color -颜色结构体，支持 RGBA 浮点分量。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Color.h` -## 结构体定义 +**描述**: 颜色结构体，支持 RGBA 浮点分量，用于图形渲染 -```cpp -struct Color { - float r = 1.0f; - float g = 1.0f; - float b = 1.0f; - float a = 1.0f; -}; -``` +## 概述 + +`Color` 是一个简单的 RGBA 颜色结构体，每个分量使用 32 位浮点数，范围 [0, 1]。默认构造创建白色 (1, 1, 1, 1)。该结构体提供静态工厂方法创建常用颜色，以及颜色插值和格式转换功能。 + +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `r` | `float` | 红色分量，范围 [0, 1] | `1.0f` | +| `g` | `float` | 绿色分量，范围 [0, 1] | `1.0f` | +| `b` | `float` | 蓝色分量，范围 [0, 1] | `1.0f` | +| `a` | `float` | Alpha 分量，范围 [0, 1] | `1.0f` | ## 构造函数 -- `Color()` - 默认构造，初始化为白色 (1, 1, 1, 1) -- `constexpr Color(float r, float g, float b, float a = 1.0f)` - 从 RGBA 分量构造 +### 默认构造函数 -## 静态工厂方法 +```cpp +Color() = default; +``` -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [White()](white.md) | `Color` | (1, 1, 1, 1) | -| [Black()](black.md) | `Color` | (0, 0, 0, 1) | -| [Red()](red.md) | `Color` | (1, 0, 0, 1) | -| [Green()](green.md) | `Color` | (0, 1, 0, 1) | -| [Blue()](blue.md) | `Color` | (0, 0, 1, 1) | -| [Yellow()](yellow.md) | `Color` | (1, 1, 0, 1) | -| [Cyan()](cyan.md) | `Color` | (0, 1, 1, 1) | -| [Magenta()](magenta.md) | `Color` | (1, 0, 1, 1) | -| [Clear()](clear.md) | `Color` | (0, 0, 0, 0)，透明黑 | +创建白色 (1, 1, 1, 1)。 -## 静态方法 +### 带参构造函数 -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Lerp(a, b, t)](lerp.md) | `Color` | 颜色线性插值 | +```cpp +constexpr Color(float r, float g, float b, float a = 1.0f) +``` -## 实例方法 +构造指定 RGBA 值的颜色。 -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [ToRGBA()](torgba.md) | `uint32_t` | 转换为 32-bit RGBA (0xRRGGBBAA) | -| [ToVector3()](tovector3.md) | `Vector3` | 转换为 RGB (丢弃 alpha) | -| [ToVector4()](tovector4.md) | `Vector4` | 转换为 RGBA | +**参数：** +- `r` - 红色分量，范围 [0, 1] +- `g` - 绿色分量，范围 [0, 1] +- `b` - 蓝色分量，范围 [0, 1] +- `a` - Alpha 分量，范围 [0, 1]，默认值为 1.0f（完全不透明） -## 运算符 +**返回：** `Color` - 构造的颜色 -| 运算符 | 描述 | -|--------|------| -| `operator+(Color, Color)` | 颜色相加 | -| `operator-(Color, Color)` | 颜色相减 | -| `operator*(Color, float)` | 颜色乘以标量 | -| `operator/(Color, float)` | 颜色除以标量 | +**示例：** + +```cpp +Color red(1.0f, 0.0f, 0.0f, 1.0f); +Color halfAlpha(0.5f, 0.5f, 0.5f); // a = 1.0f +``` + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`White`](white.md) | 返回白色 (1, 1, 1, 1) | +| [`Black`](black.md) | 返回黑色 (0, 0, 0, 1) | +| [`Red`](red.md) | 返回红色 (1, 0, 0, 1) | +| [`Green`](green.md) | 返回绿色 (0, 1, 0, 1) | +| [`Blue`](blue.md) | 返回蓝色 (0, 0, 1, 1) | +| [`Yellow`](yellow.md) | 返回黄色 (1, 1, 0, 1) | +| [`Cyan`](cyan.md) | 返回青色 (0, 1, 1, 1) | +| [`Magenta`](magenta.md) | 返回品红色 (1, 0, 1, 1) | +| [`Clear`](clear.md) | 返回透明黑色 (0, 0, 0, 0) | +| [`Lerp`](lerp.md) | 颜色线性插值 | +| [`ToRGBA`](torgba.md) | 转换为 32-bit RGBA 整数 | +| [`ToVector3`](tovector3.md) | 转换为 Vector3（丢弃 alpha） | +| [`ToVector4`](tovector4.md) | 转换为 Vector4 | +| [`operator+`](operator-add.md) | 颜色相加 | +| [`operator-`](operator-sub.md) | 颜色相减 | +| [`operator*`](operator-mul.md) | 颜色乘以标量 | +| [`operator/`](operator-div.md) | 颜色除以标量 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Math; + +Color c1 = Color::Red(); +Color c2 = Color(0, 1, 0, 1); +Color blended = Color::Lerp(c1, c2, 0.5f); +uint32_t rgba = blended.ToRGBA(); +``` ## 相关文档 diff --git a/docs/api/math/color/cyan.md b/docs/api/math/color/cyan.md index e8051908..b68bef6c 100644 --- a/docs/api/math/color/cyan.md +++ b/docs/api/math/color/cyan.md @@ -6,6 +6,19 @@ static Color Cyan() 返回青色 (0, 1, 1, 1)。 -**返回：** `Color` +**返回：** `Color` - 青色 -**示例：** `Color c = Color::Cyan();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::Cyan(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`Magenta`](magenta.md) - 返回品红色 diff --git a/docs/api/math/color/green.md b/docs/api/math/color/green.md index 009484b5..bdc499fd 100644 --- a/docs/api/math/color/green.md +++ b/docs/api/math/color/green.md @@ -6,6 +6,19 @@ static Color Green() 返回绿色 (0, 1, 0, 1)。 -**返回：** `Color` +**返回：** `Color` - 绿色 -**示例：** `Color c = Color::Green();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::Green(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`Red`](red.md) - 返回红色 diff --git a/docs/api/math/color/lerp.md b/docs/api/math/color/lerp.md index 82f35745..4c209741 100644 --- a/docs/api/math/color/lerp.md +++ b/docs/api/math/color/lerp.md @@ -9,9 +9,11 @@ static Color Lerp(const Color& a, const Color& b, float t) **参数：** - `a` - 起始颜色 - `b` - 结束颜色 -- `t` - 插值因子 (0-1) +- `t` - 插值因子，范围 [0, 1]。超出范围的值会被 clamp 到 [0, 1] -**返回：** `Color` - 插值结果 +**返回：** `Color` - 插值结果，当 t=0 时返回 a，t=1 时返回 b + +**线程安全：** ✅ **复杂度：** O(1) @@ -20,3 +22,7 @@ static Color Lerp(const Color& a, const Color& b, float t) ```cpp Color lerped = Color::Lerp(Color::Red(), Color::Blue(), 0.5f); ``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 diff --git a/docs/api/math/color/magenta.md b/docs/api/math/color/magenta.md index 68b10816..a697c7e3 100644 --- a/docs/api/math/color/magenta.md +++ b/docs/api/math/color/magenta.md @@ -6,6 +6,19 @@ static Color Magenta() 返回品红色 (1, 0, 1, 1)。 -**返回：** `Color` +**返回：** `Color` - 品红色 -**示例：** `Color c = Color::Magenta();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::Magenta(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`Cyan`](cyan.md) - 返回青色 diff --git a/docs/api/math/color/operator-add.md b/docs/api/math/color/operator-add.md new file mode 100644 index 00000000..d60c4a56 --- /dev/null +++ b/docs/api/math/color/operator-add.md @@ -0,0 +1,29 @@ +# Color::operator+ + +```cpp +Color operator+(const Color& other) const +``` + +将两个颜色对应分量相加，返回新的颜色。 + +**参数：** +- `other` - 要加的另一个颜色 + +**返回：** `Color` - 分量相加后的新颜色 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color red = Color::Red(); +Color blue = Color::Blue(); +Color purple = red + blue; +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`operator-`](operator-sub.md) - 颜色相减 diff --git a/docs/api/math/color/operator-div.md b/docs/api/math/color/operator-div.md new file mode 100644 index 00000000..2dda0718 --- /dev/null +++ b/docs/api/math/color/operator-div.md @@ -0,0 +1,28 @@ +# Color::operator/ + +```cpp +Color operator/(float scalar) const +``` + +将颜色每个分量除以一个标量值，返回新的颜色。 + +**参数：** +- `scalar` - 非零标量除数 + +**返回：** `Color` - 缩放后的新颜色 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color red = Color::Red(); +Color dimRed = red / 2.0f; +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`operator*`](operator-mul.md) - 颜色乘以标量 diff --git a/docs/api/math/color/operator-mul.md b/docs/api/math/color/operator-mul.md new file mode 100644 index 00000000..fd5966f9 --- /dev/null +++ b/docs/api/math/color/operator-mul.md @@ -0,0 +1,28 @@ +# Color::operator* + +```cpp +Color operator*(float scalar) const +``` + +将颜色每个分量乘以一个标量值，返回新的颜色。 + +**参数：** +- `scalar` - 标量乘数 + +**返回：** `Color` - 缩放后的新颜色 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color red = Color::Red(); +Color fadedRed = red * 0.5f; +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`operator/`](operator-div.md) - 颜色除以标量 diff --git a/docs/api/math/color/operator-sub.md b/docs/api/math/color/operator-sub.md new file mode 100644 index 00000000..7bc5e848 --- /dev/null +++ b/docs/api/math/color/operator-sub.md @@ -0,0 +1,29 @@ +# Color::operator- + +```cpp +Color operator-(const Color& other) const +``` + +将两个颜色对应分量相减，返回新的颜色。 + +**参数：** +- `other` - 要减去的另一个颜色 + +**返回：** `Color` - 分量相减后的新颜色 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color red = Color::Red(); +Color purple = Color(1, 0, 1, 1); +Color blue = purple - red; +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`operator+`](operator-add.md) - 颜色相加 diff --git a/docs/api/math/color/red.md b/docs/api/math/color/red.md index ea81800b..344db771 100644 --- a/docs/api/math/color/red.md +++ b/docs/api/math/color/red.md @@ -6,6 +6,19 @@ static Color Red() 返回红色 (1, 0, 0, 1)。 -**返回：** `Color` +**返回：** `Color` - 红色 -**示例：** `Color c = Color::Red();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::Red(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`Green`](green.md) - 返回绿色 diff --git a/docs/api/math/color/torgba.md b/docs/api/math/color/torgba.md index ce9f5efe..e97f6aa5 100644 --- a/docs/api/math/color/torgba.md +++ b/docs/api/math/color/torgba.md @@ -6,7 +6,9 @@ uint32_t ToRGBA() const 将颜色转换为 32-bit RGBA 整数格式。 -**返回：** `uint32_t` - RGBA 值 (0xRRGGBBAA) +**返回：** `uint32_t` - RGBA 值，格式为 `0xRRGGBBAA`（R在最高字节，A在最低字节） + +**线程安全：** ✅ **复杂度：** O(1) @@ -16,3 +18,9 @@ uint32_t ToRGBA() const Color c(1.0f, 0.0f, 0.0f, 1.0f); uint32_t rgba = c.ToRGBA(); ``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`ToVector3`](tovector3.md) - 转换为 Vector3 +- [`ToVector4`](tovector4.md) - 转换为 Vector4 diff --git a/docs/api/math/color/tovector3.md b/docs/api/math/color/tovector3.md index ea9b3be1..efaa56c0 100644 --- a/docs/api/math/color/tovector3.md +++ b/docs/api/math/color/tovector3.md @@ -8,6 +8,8 @@ Vector3 ToVector3() const **返回：** `Vector3` - RGB 值 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +17,9 @@ Vector3 ToVector3() const ```cpp Vector3 rgb = Color::Red().ToVector3(); ``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`ToVector4`](tovector4.md) - 转换为 Vector4 +- [`ToRGBA`](torgba.md) - 转换为 RGBA 整数 diff --git a/docs/api/math/color/tovector4.md b/docs/api/math/color/tovector4.md index d7bfdd3a..bf4a5e69 100644 --- a/docs/api/math/color/tovector4.md +++ b/docs/api/math/color/tovector4.md @@ -8,6 +8,8 @@ Vector4 ToVector4() const **返回：** `Vector4` - RGBA 值 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +17,9 @@ Vector4 ToVector4() const ```cpp Vector4 rgba = Color::Red().ToVector4(); ``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`ToVector3`](tovector3.md) - 转换为 Vector3（丢弃 alpha） +- [`ToRGBA`](torgba.md) - 转换为 RGBA 整数 diff --git a/docs/api/math/color/white.md b/docs/api/math/color/white.md index 5247210f..a70485c7 100644 --- a/docs/api/math/color/white.md +++ b/docs/api/math/color/white.md @@ -6,6 +6,19 @@ static Color White() 返回白色 (1, 1, 1, 1)。 -**返回：** `Color` +**返回：** `Color` - 白色 -**示例：** `Color c = Color::White();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::White(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`Black`](black.md) - 返回黑色 diff --git a/docs/api/math/color/yellow.md b/docs/api/math/color/yellow.md index 46a349f0..a54f0a51 100644 --- a/docs/api/math/color/yellow.md +++ b/docs/api/math/color/yellow.md @@ -6,6 +6,19 @@ static Color Yellow() 返回黄色 (1, 1, 0, 1)。 -**返回：** `Color` +**返回：** `Color` - 黄色 -**示例：** `Color c = Color::Yellow();` +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c = Color::Yellow(); +``` + +## 相关文档 + +- [Color](color.md) - 返回类总览 +- [`Blue`](blue.md) - 返回蓝色 diff --git a/docs/api/math/frustum/contains-bounds.md b/docs/api/math/frustum/contains-bounds.md index 8a0da23e..19c0ac9e 100644 --- a/docs/api/math/frustum/contains-bounds.md +++ b/docs/api/math/frustum/contains-bounds.md @@ -1,25 +1,35 @@ -# Frustum::Contains (bounds) +# Frustum::Contains ```cpp bool Contains(const Bounds& bounds) const ``` -检测轴对齐包围盒是否完全在视锥体内。 +检测轴对齐包围盒（Axis-Aligned Bounding Box，AABB）是否完全位于视锥体内。判断方式为：先取出 Bounds 的 8 个顶点坐标，然后对每个裁剪平面，检查所有 8 个顶点是否都在该平面外侧（距离小于 0）。若存在某个平面使得全部 8 个顶点都在其外侧，则包围盒完全在视锥外；否则认为包围盒至少部分在视锥内。 **参数：** - `bounds` - 要检测的轴对齐包围盒 -**返回：** `bool` - Bounds 完全在视锥内返回 true +**返回：** `bool` - Bounds 完全在视锥内返回 `true`，否则返回 `false` -**复杂度：** O(1) +**线程安全：** ✅（只读操作，不修改状态） + +**复杂度：** O(48)，即遍历 6 个平面 × 8 个顶点 **示例：** ```cpp -Frustum frustum = camera.CalculateFrustum(); -Bounds objectBounds = object.GetWorldBounds(); -if (frustum.Contains(objectBounds)) { - // 包围盒完全在视锥内，需要渲染 - Render(object); +#include +#include + +void CheckBoundsInFrustum(const Frustum& frustum, const Bounds& bounds) { + if (frustum.Contains(bounds)) { + // 包围盒完全在视锥内，必须渲染 + Render(); + } } ``` + +## 相关文档 + +- [Frustum 总览](frustum.md) - 返回类总览 +- [Intersects](intersects-bounds.md) - 包围盒与视锥相交检测 diff --git a/docs/api/math/frustum/contains-point.md b/docs/api/math/frustum/contains-point.md index d72ee37c..d4b8798f 100644 --- a/docs/api/math/frustum/contains-point.md +++ b/docs/api/math/frustum/contains-point.md @@ -1,24 +1,34 @@ -# Frustum::Contains (point) +# Frustum::Contains ```cpp bool Contains(const Vector3& point) const ``` -检测点是否在视锥体内。 +检测世界空间中的点是否完全位于视锥体内。判断方式为：依次计算该点到 6 个裁剪平面的有符号距离，若任意一个距离小于 0，则点位于该平面外侧，视锥体不包含该点。 **参数：** -- `point` - 要检测的世界空间点 +- `point` - 要检测的世界空间三维点 -**返回：** `bool` - 点在视锥内返回 true +**返回：** `bool` - 点完全在视锥内返回 `true`，否则返回 `false` -**复杂度：** O(1) +**线程安全：** ✅（只读操作，不修改状态） + +**复杂度：** O(6)，即遍历 6 个裁剪平面 **示例：** ```cpp -Frustum frustum = camera.CalculateFrustum(); -Vector3 point = object.GetPosition(); -if (frustum.Contains(point)) { - // 点在视锥内 +#include +#include + +void CheckPointInFrustum(const Frustum& frustum, const Vector3& point) { + if (frustum.Contains(point)) { + // 点完全在视锥内 + } } ``` + +## 相关文档 + +- [Frustum 总览](frustum.md) - 返回类总览 +- [Intersects](intersects-bounds.md) - 视锥体相交检测 diff --git a/docs/api/math/frustum/contains-sphere.md b/docs/api/math/frustum/contains-sphere.md index 569522bc..0a444178 100644 --- a/docs/api/math/frustum/contains-sphere.md +++ b/docs/api/math/frustum/contains-sphere.md @@ -1,24 +1,34 @@ -# Frustum::Contains (sphere) +# Frustum::Contains ```cpp bool Contains(const Sphere& sphere) const ``` -检测球体是否完全在视锥体内。 +检测球体是否完全位于视锥体内。判断方式为：依次计算球心到 6 个裁剪平面的有符号距离，若任意一个距离小于 `-radius`（即球心到平面的距离小于球半径的负数，说明球体完全在平面外侧），则视锥体不包含该球体。 **参数：** -- `sphere` - 要检测的球体 +- `sphere` - 要检测的球体，包含圆心 `center` 和半径 `radius` -**返回：** `bool` - 球体完全在视锥内返回 true +**返回：** `bool` - 球体完全在视锥内返回 `true`，否则返回 `false` -**复杂度：** O(1) +**线程安全：** ✅（只读操作，不修改状态） + +**复杂度：** O(6)，即遍历 6 个裁剪平面 **示例：** ```cpp -Frustum frustum = camera.CalculateFrustum(); -Sphere collider = object.GetBoundingSphere(); -if (frustum.Contains(collider)) { - // 球体完全在视锥内 +#include +#include + +void CheckSphereInFrustum(const Frustum& frustum, const Sphere& sphere) { + if (frustum.Contains(sphere)) { + // 球体完全在视锥内 + } } ``` + +## 相关文档 + +- [Frustum 总览](frustum.md) - 返回类总览 +- [Intersects](intersects-sphere.md) - 球体与视锥相交检测 diff --git a/docs/api/math/frustum/frustum.md b/docs/api/math/frustum/frustum.md index cd24d4b0..514b226e 100644 --- a/docs/api/math/frustum/frustum.md +++ b/docs/api/math/frustum/frustum.md @@ -1,45 +1,51 @@ # Frustum -视锥体，用于视锥剔除。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `class` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Frustum.h` -## 类定义 +**描述**: 视锥体，用于 3D 裁剪和可见性判断 + +## 概述 + +Frustum 表示一个视锥体，由 6 个裁剪平面组成（左、右、底、顶、近、远）。主要用于视锥剔除（Frustum Culling），在渲染前判断场景物体是否与相机视锥相交或完全在内，从而决定是否需要渲染该物体，提升渲染性能。 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Contains(Point)`](contains-point.md) | 点是否完全在视锥内 | +| [`Contains(Sphere)`](contains-sphere.md) | 球体是否完全在视锥内 | +| [`Contains(Bounds)`](contains-bounds.md) | Bounds 是否完全在视锥内 | +| [`Intersects(Bounds)`](intersects-bounds.md) | Bounds 是否与视锥相交 | +| [`Intersects(Sphere)`](intersects-sphere.md) | 球体是否与视锥相交 | + +## 嵌套类型 + +| 类型 | 描述 | +|------|------| +| `PlaneIndex` | 平面索引枚举（Left, Right, Bottom, Top, Near, Far） | + +## 使用示例 ```cpp -class Frustum { -public: - Plane planes[6]; +Frustum frustum = camera.CalculateFrustum(); +Bounds objectBounds = object.GetWorldBounds(); - enum class PlaneIndex { - Left = 0, - Right = 1, - Bottom = 2, - Top = 3, - Near = 4, - Far = 5 - }; - - bool Contains(const Vector3& point) const; - bool Contains(const Sphere& sphere) const; - bool Contains(const Bounds& bounds) const; - bool Intersects(const Bounds& bounds) const; - bool Intersects(const Sphere& sphere) const; -}; +if (frustum.Contains(objectBounds)) { + // 物体完全在视锥内，必须渲染 + Render(object); +} else if (frustum.Intersects(objectBounds)) { + // 物体与视锥相交，可能需要渲染 + Render(object); +} ``` -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Contains(point)](contains-point.md) | `bool` | 点是否在视锥内 | -| [Contains(sphere)](contains-sphere.md) | `bool` | 球体是否完全在视锥内 | -| [Contains(bounds)](contains-bounds.md) | `bool` | Bounds 是否完全在视锥内 | -| [Intersects(bounds)](intersects-bounds.md) | `bool` | Bounds 是否与视锥相交 | -| [Intersects(sphere)](intersects-sphere.md) | `bool` | 球体是否与视锥相交 | - ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Math 模块总览](../math.md) - Math 模块总览 +- [Plane](../plane/plane.md) - 平面类型 +- [Bounds](../bounds/bounds.md) - 包围盒类型 +- [Sphere](../sphere/sphere.md) - 球体类型 diff --git a/docs/api/math/frustum/intersects-bounds.md b/docs/api/math/frustum/intersects-bounds.md index d4be8707..6797004c 100644 --- a/docs/api/math/frustum/intersects-bounds.md +++ b/docs/api/math/frustum/intersects-bounds.md @@ -1,26 +1,39 @@ -# Frustum::Intersects (bounds) +# Frustum::Intersects ```cpp bool Intersects(const Bounds& bounds) const ``` -检测轴对齐包围盒是否与视锥体相交。 +检测轴对齐包围盒（Axis-Aligned Bounding Box，AABB）是否与视锥体相交。判断方式为：对每个裁剪平面，检查 8 个顶点是否全部在该平面外侧（allNegative）或全部在内侧（allPositive）。若存在某个平面使得全部 8 个顶点都在其外侧，则视锥与包围盒不相交；否则认为两者相交。 + +注意：此方法与 `Contains(Bounds)` 的区别在于——`Contains` 要求包围盒完全在视锥内，而 `Intersects` 只要有任意重叠就返回 `true`。 **参数：** - `bounds` - 要检测的轴对齐包围盒 -**返回：** `bool` - 与视锥相交返回 true +**返回：** `bool` - 视锥与 Bounds 相交返回 `true`，否则返回 `false` -**复杂度：** O(1) +**线程安全：** ✅（只读操作，不修改状态） + +**复杂度：** O(48)，即遍历 6 个平面 × 8 个顶点 **示例：** ```cpp -Frustum frustum = camera.CalculateFrustum(); -for (const auto& object : sceneObjects) { - if (frustum.Intersects(object.bounds)) { - // 物体与视锥相交，需要渲染 - Render(object); +#include +#include + +void FrustumCullingExample(const Frustum& frustum, const std::vector& objectBounds) { + for (const auto& bounds : objectBounds) { + if (frustum.Intersects(bounds)) { + // 物体与视锥相交，需要渲染 + Render(bounds); + } } } ``` + +## 相关文档 + +- [Frustum 总览](frustum.md) - 返回类总览 +- [Contains](contains-bounds.md) - 包围盒完全包含检测 diff --git a/docs/api/math/frustum/intersects-sphere.md b/docs/api/math/frustum/intersects-sphere.md index 363b2ecb..d47d9c90 100644 --- a/docs/api/math/frustum/intersects-sphere.md +++ b/docs/api/math/frustum/intersects-sphere.md @@ -1,25 +1,37 @@ -# Frustum::Intersects (sphere) +# Frustum::Intersects ```cpp bool Intersects(const Sphere& sphere) const ``` -检测球体是否与视锥体相交。 +检测球体是否与视锥体相交。判断方式为：依次计算球心到 6 个裁剪平面的有符号距离，若任意一个距离小于 `-radius`（即球体完全在平面外侧），则两者不相交；否则认为相交。 + +注意：此方法与 `Contains(Sphere)` 的区别在于——`Contains` 要求球体完全在视锥内，而 `Intersects` 只要有任意重叠就返回 `true`。 **参数：** -- `sphere` - 要检测的球体 +- `sphere` - 要检测的球体，包含圆心 `center` 和半径 `radius` -**返回：** `bool` - 与视锥相交返回 true +**返回：** `bool` - 视锥与球体相交返回 `true`，否则返回 `false` -**复杂度：** O(1) +**线程安全：** ✅（只读操作，不修改状态） + +**复杂度：** O(6)，即遍历 6 个裁剪平面 **示例：** ```cpp -Frustum frustum = camera.CalculateFrustum(); -Sphere collider = object.GetBoundingSphere(); -if (frustum.Intersects(collider)) { - // 球体与视锥相交 - Render(object); +#include +#include + +void CheckSphereIntersection(const Frustum& frustum, const Sphere& sphere) { + if (frustum.Intersects(sphere)) { + // 球体与视锥相交 + Render(); + } } ``` + +## 相关文档 + +- [Frustum 总览](frustum.md) - 返回类总览 +- [Contains](contains-sphere.md) - 球体完全包含检测 diff --git a/docs/api/math/h/deg-to-rad.md b/docs/api/math/h/deg-to-rad.md index 9e18d430..91a2e609 100644 --- a/docs/api/math/h/deg-to-rad.md +++ b/docs/api/math/h/deg-to-rad.md @@ -1,7 +1,7 @@ # Math::DEG_TO_RAD ```cpp -constexpr float DEG_TO_RAD = Math::PI / 180.0f; +constexpr float DEG_TO_RAD = PI / 180.0f; ``` `DEG_TO_RAD` 是角度转弧度的转换系数。1 度等于 `PI / 180` 弧度，约等于 0.01745329251994329577。使用该常量将角度值乘以 `DEG_TO_RAD` 即可得到对应的弧度值。 diff --git a/docs/api/math/h/epsilon.md b/docs/api/math/h/epsilon.md index 0720ef65..75a82a7f 100644 --- a/docs/api/math/h/epsilon.md +++ b/docs/api/math/h/epsilon.md @@ -13,7 +13,7 @@ constexpr float EPSILON = 1e-6f; float a = 0.1f + 0.2f; float b = 0.3f; -if (Math::Abs(a - b) < Math::EPSILON) { +if (fabsf(a - b) < Math::EPSILON) { // a 和 b 可以视为相等 } ``` diff --git a/docs/api/math/h/float-max.md b/docs/api/math/h/float-max.md index 510b187f..af91a9cb 100644 --- a/docs/api/math/h/float-max.md +++ b/docs/api/math/h/float-max.md @@ -11,7 +11,7 @@ constexpr float FLOAT_MAX = 3.402823466e+38f; ```cpp #include -float maxDistance = Math::FLOAT_MAX; +float maxDistance = FLOAT_MAX; ``` ## 相关文档 diff --git a/docs/api/math/h/h.md b/docs/api/math/h/h.md index 08f84b44..031fa1e9 100644 --- a/docs/api/math/h/h.md +++ b/docs/api/math/h/h.md @@ -4,6 +4,8 @@ **类型**: `header` +**头文件**: `XCEngine/Math/Math.h` + **描述**: 数学库常量和辅助函数头文件。 ## 概述 @@ -41,7 +43,7 @@ float angle = 90.0f * DEG_TO_RAD; // 90度转弧度 // 使用函数 float rad = Radians(180.0f); // 180度 -> π 弧度 -float deg = Degrees(Math::PI); // π 弧度 -> 180度 +float deg = Degrees(PI); // π 弧度 -> 180度 // 比较浮点数 if (fabsf(a - b) < EPSILON) { diff --git a/docs/api/math/h/half-pi.md b/docs/api/math/h/half-pi.md index 2a6f8cdf..ac093e56 100644 --- a/docs/api/math/h/half-pi.md +++ b/docs/api/math/h/half-pi.md @@ -11,7 +11,7 @@ constexpr float HALF_PI = 1.57079632679489661923f; ```cpp #include -float ninetyDegreesRadians = Math::HALF_PI; +float ninetyDegreesRadians = HALF_PI; ``` ## 相关文档 diff --git a/docs/api/math/h/pi.md b/docs/api/math/h/pi.md index a40653ab..7ddaa2af 100644 --- a/docs/api/math/h/pi.md +++ b/docs/api/math/h/pi.md @@ -13,8 +13,8 @@ constexpr float PI = 3.14159265358979323846f; ```cpp #include -float circumference = 2.0f * Math::PI * radius; -float area = Math::PI * radius * radius; +float circumference = 2.0f * PI * radius; +float area = PI * radius * radius; ``` ## 相关文档 diff --git a/docs/api/math/h/rad-to-deg.md b/docs/api/math/h/rad-to-deg.md index ab50c13c..92b3af55 100644 --- a/docs/api/math/h/rad-to-deg.md +++ b/docs/api/math/h/rad-to-deg.md @@ -1,7 +1,7 @@ # Math::RAD_TO_DEG ```cpp -constexpr float RAD_TO_DEG = 180.0f / Math::PI; +constexpr float RAD_TO_DEG = 180.0f / PI; ``` `RAD_TO_DEG` 是弧度转角度的转换系数。1 弧度等于 `180 / PI` 度，约等于 57.29577951308232087685。使用该常量将弧度值乘以 `RAD_TO_DEG` 即可得到对应的角度值。 diff --git a/docs/api/math/h/two-pi.md b/docs/api/math/h/two-pi.md index 1efd8bc2..77b8704f 100644 --- a/docs/api/math/h/two-pi.md +++ b/docs/api/math/h/two-pi.md @@ -11,7 +11,7 @@ constexpr float TWO_PI = 6.28318530717958647692f; ```cpp #include -float fullCircleRadians = Math::TWO_PI; +float fullCircleRadians = TWO_PI; ``` ## 相关文档 diff --git a/docs/api/math/math.md b/docs/api/math/math.md index acab94b0..d4a205f7 100644 --- a/docs/api/math/math.md +++ b/docs/api/math/math.md @@ -98,3 +98,8 @@ Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(45.0f)); Quaternion combined = q1 * q2; Vector3 rotated = q2 * Vector3::Forward(); ``` + +## 相关文档 + +- [Core 模块](../core/core.md) - 核心基础模块 +- [RHI 模块](../rhi/rhi.md) - 渲染硬件接口 diff --git a/docs/api/math/matrix3/inverse.md b/docs/api/math/matrix3/inverse.md index 3a3b05ce..9f4779cd 100644 --- a/docs/api/math/matrix3/inverse.md +++ b/docs/api/math/matrix3/inverse.md @@ -6,13 +6,19 @@ Matrix3 Inverse() const 返回矩阵的逆矩阵。 -**返回：** `Matrix3` - 逆矩阵 +**返回：** `Matrix3` - 逆矩阵。如果行列式接近零（< EPSILON），则返回单位矩阵。 + +**异常：** 当矩阵奇异（行列式为零）时，返回单位矩阵而非抛出异常。 **复杂度：** O(1) **示例：** ```cpp -Matrix3 mat = ...; +Matrix3 mat = Matrix3::RotationY(0.5f); Matrix3 inv = mat.Inverse(); -``` + +// 验证：M * M⁻¹ ≈ I +Matrix3 identity = mat * inv; +// identity 应接近单位矩阵 +``` \ No newline at end of file diff --git a/docs/api/math/matrix3/matrix3.md b/docs/api/math/matrix3/matrix3.md index ebeab7eb..6b1af9eb 100644 --- a/docs/api/math/matrix3/matrix3.md +++ b/docs/api/math/matrix3/matrix3.md @@ -1,20 +1,23 @@ # Matrix3 / Matrix3x3 -3x3 矩阵结构体，用于表示 3D 旋转和缩放变换。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Matrix3.h` -## 类型别名 +**描述**: 3x3 矩阵，用于旋转变换和线性代数运算。 -```cpp -using Matrix3 = Matrix3x3; -``` +## 概述 -## 存储方式 +Matrix3（别名 Matrix3x3）是一个 3x3 浮点矩阵结构体，主要用于图形引擎中的旋转变换和线性代数运算。 -行优先存储 (row-major)： +**设计目的：** +- 旋转变换（绕 X/Y/Z 轴） +- 缩放变换 +- 矩阵运算（乘法、转置、求逆、行列式计算） + +**存储方式：** 行优先存储 (row-major) ``` m[row][col] m[0][0] m[0][1] m[0][2] @@ -22,36 +25,61 @@ m[1][0] m[1][1] m[1][2] m[2][0] m[2][1] m[2][2] ``` -## 构造函数 +**类型别名：** +```cpp +using Matrix3 = Matrix3x3; +``` -- 默认构造函数初始化为零矩阵 +## 结构体成员 -## 静态工厂方法 +| 成员 | 类型 | 描述 | +|------|------|------| +| `m[3][3]` | `float` | 矩阵元素数组，行优先存储 | -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Identity()](identity.md) | `Matrix3` | 单位矩阵 | -| [Zero()](zero.md) | `Matrix3` | 零矩阵 | -| [RotationX(radians)](rotationx.md) | `Matrix3` | X 轴旋转矩阵 | -| [RotationY(radians)](rotationy.md) | `Matrix3` | Y 轴旋转矩阵 | -| [RotationZ(radians)](rotationz.md) | `Matrix3` | Z 轴旋转矩阵 | -| [Scale(scale)](scale.md) | `Matrix3` | 缩放矩阵 | +## 公共方法 -## 实例方法 +| 方法 | 描述 | +|------|------| +| [`Identity()`](identity.md) | 获取单位矩阵 | +| [`Zero()`](zero.md) | 获取零矩阵 | +| [`RotationX()`](rotation-x.md) | 创建绕 X 轴旋转矩阵 | +| [`RotationY()`](rotation-y.md) | 创建绕 Y 轴旋转矩阵 | +| [`RotationZ()`](rotation-z.md) | 创建绕 Z 轴旋转矩阵 | +| [`Scale()`](scale.md) | 创建缩放矩阵 | +| [`operator*(Matrix3)`](operator-mul-matrix3.md) | 矩阵乘法 | +| [`operator*(Vector3)`](operator-mul-vector3.md) | 矩阵-向量乘法 | +| [`Transpose()`](transpose.md) | 转置矩阵 | +| [`Inverse()`](inverse.md) | 逆矩阵 | +| [`Determinant()`](determinant.md) | 行列式 | +| [`operator[]`](./operator-subscript.md) | 访问矩阵元素 | -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Transpose()](transpose.md) | `Matrix3` | 转置矩阵 | -| [Inverse()](inverse.md) | `Matrix3` | 逆矩阵 | -| [Determinant()](determinant.md) | `float` | 行列式 | +## 使用示例 -## 运算符 +```cpp +#include +#include -| 运算符 | 描述 | -|--------|------| -| `operator*(Matrix3, Matrix3)` | 矩阵乘法 | -| `operator*(Matrix3, Vector3)` | 矩阵-向量乘法 | +using namespace XCEngine::Math; + +// 创建绕 Y 轴旋转 45 度的矩阵 +Matrix3 rotation = Matrix3::RotationY(0.785f); // PI/4 + +// 对向量进行变换 +Vector3 v(1.0f, 0.0f, 0.0f); +Vector3 rotated = rotation * v; + +// 矩阵运算 +Matrix3 m1 = Matrix3::RotationX(0.5f); +Matrix3 m2 = Matrix3::RotationY(0.3f); +Matrix3 combined = m1 * m2; + +// 求逆矩阵 +Matrix3 inv = combined.Inverse(); +float det = combined.Determinant(); +``` ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Matrix4](../matrix4/matrix4.md) - 4x4 矩阵 +- [Vector3](../vector3/vector3.md) - 三维向量 +- [Math 模块总览](../math.md) - 返回模块总览 \ No newline at end of file diff --git a/docs/api/math/matrix3/operator-mul-matrix3.md b/docs/api/math/matrix3/operator-mul-matrix3.md new file mode 100644 index 00000000..8609d9bd --- /dev/null +++ b/docs/api/math/matrix3/operator-mul-matrix3.md @@ -0,0 +1,24 @@ +# Matrix3::operator* (Matrix3) + +```cpp +Matrix3 operator*(const Matrix3& other) const +``` + +矩阵乘法运算，将当前矩阵与另一个矩阵相乘。 + +**参数：** +- `other` - 另一个矩阵 + +**返回：** `Matrix3` - 乘积矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 rot = Matrix3::RotationZ(Math::Radians(45.0f)); +Matrix3 scale = Matrix3::Scale(Vector3(2.0f, 2.0f, 1.0f)); + +// 先缩放后旋转 +Matrix3 transform = rot * scale; +``` diff --git a/docs/api/math/matrix3/operator-mul-vector3.md b/docs/api/math/matrix3/operator-mul-vector3.md new file mode 100644 index 00000000..d7aa8f16 --- /dev/null +++ b/docs/api/math/matrix3/operator-mul-vector3.md @@ -0,0 +1,24 @@ +# Matrix3::operator* (Vector3) + +```cpp +Vector3 operator*(const Vector3& v) const +``` + +矩阵-向量乘法运算，将矩阵应用于向量。 + +**参数：** +- `v` - 三维向量 + +**返回：** `Vector3` - 变换后的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 rotation = Matrix3::RotationZ(Math::Radians(90.0f)); +Vector3 v(1.0f, 0.0f, 0.0f); + +Vector3 rotated = rotation * v; +// 结果: approximately (0, 1, 0) +``` diff --git a/docs/api/math/matrix3/operator-subscript.md b/docs/api/math/matrix3/operator-subscript.md new file mode 100644 index 00000000..6460d66b --- /dev/null +++ b/docs/api/math/matrix3/operator-subscript.md @@ -0,0 +1,27 @@ +# Matrix3::operator[] + +```cpp +float* operator[](int row) +const float* operator[](int row) const +``` + +访问矩阵指定行的元素。 + +**参数：** +- `row` - 行索引（0-2） + +**返回：** `float*` / `const float*` - 指向该行首元素的指针 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 m; +m[0][0] = 1; m[0][1] = 2; m[0][2] = 3; +m[1][0] = 4; m[1][1] = 5; m[1][2] = 6; +m[2][0] = 7; m[2][1] = 8; m[2][2] = 9; + +// 访问元素 +float val = m[1][2]; // 6 +``` diff --git a/docs/api/math/matrix3/rotation-x.md b/docs/api/math/matrix3/rotation-x.md new file mode 100644 index 00000000..ea8a51f3 --- /dev/null +++ b/docs/api/math/matrix3/rotation-x.md @@ -0,0 +1,24 @@ +# Matrix3::RotationX + +```cpp +static Matrix3 RotationX(float radians) +``` + +返回绕 X 轴旋转的 3x3 旋转矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix3` - 绕 X 轴旋转的矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 rotX = Matrix3::RotationX(Math::Radians(90.0f)); +// 结果（绕 X 轴旋转 90 度）: +// [1 0 0] +// [0 0 -1] +// [0 1 0] +``` diff --git a/docs/api/math/matrix3/rotation-y.md b/docs/api/math/matrix3/rotation-y.md new file mode 100644 index 00000000..73bc81cf --- /dev/null +++ b/docs/api/math/matrix3/rotation-y.md @@ -0,0 +1,24 @@ +# Matrix3::RotationY + +```cpp +static Matrix3 RotationY(float radians) +``` + +返回绕 Y 轴旋转的 3x3 旋转矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix3` - 绕 Y 轴旋转的矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 rotY = Matrix3::RotationY(Math::Radians(90.0f)); +// 结果（绕 Y 轴旋转 90 度）: +// [0 0 1] +// [0 1 0] +// [-1 0 0] +``` diff --git a/docs/api/math/matrix3/rotation-z.md b/docs/api/math/matrix3/rotation-z.md new file mode 100644 index 00000000..f94009a2 --- /dev/null +++ b/docs/api/math/matrix3/rotation-z.md @@ -0,0 +1,24 @@ +# Matrix3::RotationZ + +```cpp +static Matrix3 RotationZ(float radians) +``` + +返回绕 Z 轴旋转的 3x3 旋转矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix3` - 绕 Z 轴旋转的矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 rotZ = Matrix3::RotationZ(Math::Radians(45.0f)); +// 结果（绕 Z 轴旋转 45 度）: +// [ 0.707 -0.707 0] +// [ 0.707 0.707 0] +// [ 0 0 1] +``` diff --git a/docs/api/math/matrix3/rotationx.md b/docs/api/math/matrix3/rotationx.md deleted file mode 100644 index 90888bb7..00000000 --- a/docs/api/math/matrix3/rotationx.md +++ /dev/null @@ -1,20 +0,0 @@ -# Matrix3::RotationX - -```cpp -static Matrix3 RotationX(float radians) -``` - -创建绕 X 轴旋转的矩阵。 - -**参数：** -- `radians` - 旋转角度（弧度） - -**返回：** `Matrix3` - 旋转矩阵 - -**复杂度：** O(1) - -**示例：** - -```cpp -Matrix3 rotX = Matrix3::RotationX(Math::HALF_PI); -``` diff --git a/docs/api/math/matrix3/rotationy.md b/docs/api/math/matrix3/rotationy.md deleted file mode 100644 index 3874843a..00000000 --- a/docs/api/math/matrix3/rotationy.md +++ /dev/null @@ -1,20 +0,0 @@ -# Matrix3::RotationY - -```cpp -static Matrix3 RotationY(float radians) -``` - -创建绕 Y 轴旋转的矩阵。 - -**参数：** -- `radians` - 旋转角度（弧度） - -**返回：** `Matrix3` - 旋转矩阵 - -**复杂度：** O(1) - -**示例：** - -```cpp -Matrix3 rotY = Matrix3::RotationY(Math::HALF_PI); -``` diff --git a/docs/api/math/matrix3/rotationz.md b/docs/api/math/matrix3/rotationz.md deleted file mode 100644 index 2626ee4b..00000000 --- a/docs/api/math/matrix3/rotationz.md +++ /dev/null @@ -1,20 +0,0 @@ -# Matrix3::RotationZ - -```cpp -static Matrix3 RotationZ(float radians) -``` - -创建绕 Z 轴旋转的矩阵。 - -**参数：** -- `radians` - 旋转角度（弧度） - -**返回：** `Matrix3` - 旋转矩阵 - -**复杂度：** O(1) - -**示例：** - -```cpp -Matrix3 rotZ = Matrix3::RotationZ(Math::HALF_PI); -``` diff --git a/docs/api/math/matrix4/decompose.md b/docs/api/math/matrix4/decompose.md index 3173c5c6..4bf2e234 100644 --- a/docs/api/math/matrix4/decompose.md +++ b/docs/api/math/matrix4/decompose.md @@ -1,24 +1,50 @@ -# Matrix4::Decompose +# Matrix4x4::Decompose ```cpp void Decompose(Vector3& translation, Quaternion& rotation, Vector3& scale) const ``` -将矩阵分解为平移、旋转和缩放分量。 +将变换矩阵分解为平移、旋转和缩放三个独立分量。 **参数：** -- `translation` - 输出平移向量 -- `rotation` - 输出旋转四元数 -- `scale` - 输出缩放向量 +- `translation` - 输出参数，接收平移向量 +- `rotation` - 输出参数，接收旋转四元数 +- `scale` - 输出参数，接收缩放向量 + +**返回：** （无） + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 m = ...; +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" +#include "XCEngine/Math/Quaternion.h" + +using namespace XCEngine::Math; + +Matrix4 transform = Matrix4::TRS( + Vector3(1.0f, 2.0f, 3.0f), + Quaternion::FromEuler(45.0f, 0.0f, 0.0f), + Vector3(2.0f, 2.0f, 2.0f) +); + Vector3 translation; Quaternion rotation; Vector3 scale; -m.Decompose(translation, rotation, scale); +transform.Decompose(translation, rotation, scale); +// translation = (1.0f, 2.0f, 3.0f) +// rotation 表示 45 度 X 轴旋转 +// scale = (2.0f, 2.0f, 2.0f) ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [TRS](trs.md) - 组合变换矩阵 +- [GetTranslation](gettranslation.md) - 获取平移分量 +- [GetRotation](getrotation.md) - 获取旋转分量 +- [GetScale](getscale.md) - 获取缩放分量 \ No newline at end of file diff --git a/docs/api/math/matrix4/determinant.md b/docs/api/math/matrix4/determinant.md index 52ca8ac0..29a510e7 100644 --- a/docs/api/math/matrix4/determinant.md +++ b/docs/api/math/matrix4/determinant.md @@ -1,18 +1,36 @@ -# Matrix4::Determinant +# Matrix4x4::Determinant ```cpp float Determinant() const ``` -计算矩阵的行列式。 +计算矩阵的行列式。行列式为零的矩阵不可逆。 -**返回：** `float` - 行列式值 +**参数：** （无） -**复杂度：** O(1) +**返回：** 矩阵的行列式值 + +**线程安全：** ✅ + +**复杂度：** O(n³) - O(64) **示例：** ```cpp -Matrix4 m = ...; +#include "XCEngine/Math/Matrix4.h" + +using namespace XCEngine::Math; + +Matrix4 m = Matrix4::Identity(); float det = m.Determinant(); +// det = 1.0f + +Matrix4 singular; +float det2 = singular.Determinant(); +// det2 = 0.0f ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Inverse](inverse.md) - 矩阵求逆 \ No newline at end of file diff --git a/docs/api/math/matrix4/getrotation.md b/docs/api/math/matrix4/getrotation.md index 720a7563..99767958 100644 --- a/docs/api/math/matrix4/getrotation.md +++ b/docs/api/math/matrix4/getrotation.md @@ -1,18 +1,42 @@ -# Matrix4::GetRotation +# Matrix4x4::GetRotation ```cpp Quaternion GetRotation() const ``` -从矩阵中提取旋转分量。 +从变换矩阵中提取旋转分量。将矩阵转换为对应的四元数表示。 -**返回：** `Quaternion` - 旋转四元数 +**参数：** （无） + +**返回：** 旋转四元数 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 m = ...; -Quaternion rotation = m.GetRotation(); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Quaternion.h" + +using namespace XCEngine::Math; + +Quaternion expected = Quaternion::FromEuler(0.0f, 90.0f, 0.0f); +Matrix4 transform = Matrix4::TRS( + Vector3(0.0f, 0.0f, 0.0f), + expected, + Vector3(1.0f, 1.0f, 1.0f) +); + +Quaternion rotation = transform.GetRotation(); +// rotation 表示相同的旋转 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Quaternion](../quaternion/quaternion.md) - 四元数类 +- [GetTranslation](gettranslation.md) - 获取平移分量 +- [GetScale](getscale.md) - 获取缩放分量 +- [Decompose](decompose.md) - 分解矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/getscale.md b/docs/api/math/matrix4/getscale.md index 660ec649..2c22afbe 100644 --- a/docs/api/math/matrix4/getscale.md +++ b/docs/api/math/matrix4/getscale.md @@ -1,18 +1,40 @@ -# Matrix4::GetScale +# Matrix4x4::GetScale ```cpp Vector3 GetScale() const ``` -从矩阵中提取缩放分量。 +从变换矩阵中提取缩放分量。计算各列向量的长度作为缩放因子。 -**返回：** `Vector3` - 缩放向量 +**参数：** （无） + +**返回：** 缩放向量 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 m = ...; -Vector3 scale = m.GetScale(); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 transform = Matrix4::TRS( + Vector3(0.0f, 0.0f, 0.0f), + Quaternion::Identity(), + Vector3(2.0f, 3.0f, 4.0f) +); + +Vector3 scale = transform.GetScale(); +// scale = (2.0f, 3.0f, 4.0f) ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [GetTranslation](gettranslation.md) - 获取平移分量 +- [GetRotation](getrotation.md) - 获取旋转分量 +- [Decompose](decompose.md) - 分解矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/gettranslation.md b/docs/api/math/matrix4/gettranslation.md index adede5d4..99f784eb 100644 --- a/docs/api/math/matrix4/gettranslation.md +++ b/docs/api/math/matrix4/gettranslation.md @@ -1,18 +1,40 @@ -# Matrix4::GetTranslation +# Matrix4x4::GetTranslation ```cpp Vector3 GetTranslation() const ``` -从矩阵中提取平移分量。 +从变换矩阵中提取平移分量。读取矩阵的最后一列前三个元素。 -**返回：** `Vector3` - 平移向量 +**参数：** （无） + +**返回：** 平移向量 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 m = ...; -Vector3 translation = m.GetTranslation(); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 transform = Matrix4::TRS( + Vector3(5.0f, 3.0f, 2.0f), + Quaternion::Identity(), + Vector3(1.0f, 1.0f, 1.0f) +); + +Vector3 translation = transform.GetTranslation(); +// translation = (5.0f, 3.0f, 2.0f) ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [GetRotation](getrotation.md) - 获取旋转分量 +- [GetScale](getscale.md) - 获取缩放分量 +- [Decompose](decompose.md) - 分解矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/identity.md b/docs/api/math/matrix4/identity.md index 5609574f..625de5c6 100644 --- a/docs/api/math/matrix4/identity.md +++ b/docs/api/math/matrix4/identity.md @@ -1,17 +1,31 @@ -# Matrix4::Identity +# Matrix4x4::Identity ```cpp -static Matrix4 Identity() +static Matrix4x4 Identity() ``` -返回 4x4 单位矩阵。 +返回单位矩阵。单位矩阵是对角线元素为 1，其他元素为 0 的特殊矩阵。 -**返回：** `Matrix4` - 单位矩阵 +**参数：** （无） + +**返回：** 单位矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include "XCEngine/Math/Matrix4.h" + +using namespace XCEngine::Math; + Matrix4 identity = Matrix4::Identity(); +// identity.m[0][0] = 1, identity.m[1][1] = 1, identity.m[2][2] = 1, identity.m[3][3] = 1 +// 所有其他元素为 0 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/math/matrix4/inverse.md b/docs/api/math/matrix4/inverse.md index a0ce7f5f..3185ac3e 100644 --- a/docs/api/math/matrix4/inverse.md +++ b/docs/api/math/matrix4/inverse.md @@ -1,18 +1,39 @@ -# Matrix4::Inverse +# Matrix4x4::Inverse ```cpp -Matrix4 Inverse() const +Matrix4x4 Inverse() const ``` -返回矩阵的逆矩阵。 +返回矩阵的逆矩阵。如果矩阵的行列式接近零（不可逆），则返回单位矩阵。 -**返回：** `Matrix4` - 逆矩阵 +**参数：** （无） -**复杂度：** O(1) +**返回：** 逆矩阵；如果矩阵不可逆则返回单位矩阵 + +**线程安全：** ✅ + +**复杂度：** O(n³)，对于 4x4 矩阵固定为 64 次基本运算 **示例：** ```cpp -Matrix4 m = ...; -Matrix4 inv = m.Inverse(); +#include "XCEngine/Math/Matrix4.h" + +using namespace XCEngine::Math; + +Matrix4 transform = Matrix4::TRS( + Vector3(1.0f, 2.0f, 3.0f), + Quaternion::FromEuler(0.0f, 45.0f, 0.0f), + Vector3(2.0f, 2.0f, 2.0f) +); + +Matrix4 inv = transform.Inverse(); +Matrix4 identity = transform * inv; +// identity 接近单位矩阵 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Determinant](determinant.md) - 计算行列式 +- [Transpose](transpose.md) - 矩阵转置 \ No newline at end of file diff --git a/docs/api/math/matrix4/lookat.md b/docs/api/math/matrix4/lookat.md index d8e8d004..24bc99b6 100644 --- a/docs/api/math/matrix4/lookat.md +++ b/docs/api/math/matrix4/lookat.md @@ -1,22 +1,39 @@ -# Matrix4::LookAt +# Matrix4x4::LookAt ```cpp -static Matrix4 LookAt(const Vector3& eye, const Vector3& target, const Vector3& up) +static Matrix4x4 LookAt(const Vector3& eye, const Vector3& target, const Vector3& up) ``` -创建视图矩阵（观察矩阵）。 +创建视图矩阵（观察矩阵）。用于将世界空间中的点转换到摄像机视角。 **参数：** -- `eye` - 相机位置 +- `eye` - 摄像机位置 - `target` - 观察目标点 -- `up` - 世界空间中的上方向 +- `up` - 摄像机上方向向量 -**返回：** `Matrix4` - 视图矩阵 +**返回：** 视图矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up()); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 view = Matrix4::LookAt( + Vector3(0.0f, 1.0f, 5.0f), + Vector3(0.0f, 0.0f, 0.0f), + Vector3(0.0f, 1.0f, 0.0f) +); ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Perspective](perspective.md) - 透视投影 +- [Orthographic](orthographic.md) - 正交投影 \ No newline at end of file diff --git a/docs/api/math/matrix4/matrix4.md b/docs/api/math/matrix4/matrix4.md index c5e90c6a..6b3bbb6a 100644 --- a/docs/api/math/matrix4/matrix4.md +++ b/docs/api/math/matrix4/matrix4.md @@ -1,79 +1,77 @@ -# Matrix4 / Matrix4x4 +# Matrix4 -4x4 矩阵结构体，用于表示完整的 3D 变换（平移、旋转、缩放）、视图和投影变换。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Matrix4.h` -## 类型别名 +**描述**: 4x4 矩阵，用于 3D 变换（平移、旋转、缩放）、视图和投影计算 + +## 概述 + +`Matrix4` (别名 `Matrix4x4`) 是 XCEngine 中用于表示 4x4 变换矩阵的结构体。它支持标准的 3D 图形变换操作，包括平移、旋转、缩放，以及视图矩阵和投影矩阵的构建。该结构体采用列主序存储方式，适用于 GPU 渲染和物理计算场景。 + +## 结构体成员 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `m[4][4]` | `float` | 矩阵元素数组 | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Identity`](identity.md) | 返回单位矩阵 | +| [`Zero`](zero.md) | 返回零矩阵 | +| [`Translation`](translation.md) | 创建平移矩阵 | +| [`Rotation`](rotation.md) | 从四元数创建旋转矩阵 | +| [`Scale`](scale.md) | 创建缩放矩阵 | +| [`TRS`](trs.md) | 创建组合变换矩阵 | +| [`LookAt`](lookat.md) | 创建视图矩阵 | +| [`Perspective`](perspective.md) | 创建透视投影矩阵 | +| [`Orthographic`](orthographic.md) | 创建正交投影矩阵 | +| [`RotationX`](rotationx.md) | 创建绕 X 轴旋转矩阵 | +| [`RotationY`](rotationy.md) | 创建绕 Y 轴旋转矩阵 | +| [`RotationZ`](rotationz.md) | 创建绕 Z 轴旋转矩阵 | +| [`operator*`](operator_mul.md) | 矩阵乘法 | +| [`MultiplyPoint`](multiplypoint.md) | 变换点（w=1） | +| [`MultiplyVector`](multiplyvector.md) | 变换向量（w=0） | +| [`Transpose`](transpose.md) | 转置矩阵 | +| [`Inverse`](inverse.md) | 求逆矩阵 | +| [`Determinant`](determinant.md) | 计算行列式 | +| [`GetTranslation`](gettranslation.md) | 获取平移分量 | +| [`GetRotation`](getrotation.md) | 获取旋转分量 | +| [`GetScale`](getscale.md) | 获取缩放分量 | +| [`Decompose`](decompose.md) | 分解矩阵为变换分量 | +| [`operator[]`](operator_index.md) | 访问矩阵行数据 | + +## 使用示例 ```cpp -using Matrix4 = Matrix4x4; +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" +#include "XCEngine/Math/Quaternion.h" + +using namespace XCEngine::Math; + +void MatrixExample() { + Matrix4 mat = Matrix4::TRS( + Vector3(1.0f, 2.0f, 3.0f), + Quaternion::FromEuler(0.0f, 90.0f, 0.0f), + Vector3(1.5f, 1.5f, 1.5f) + ); + + Vector3 point(1.0f, 0.0f, 0.0f); + Vector3 transformed = mat.MultiplyPoint(point); + + Matrix4 inv = mat.Inverse(); + Matrix4 result = mat * inv; +} ``` -## 存储方式 - -行优先存储 (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()](identity.md) | `Matrix4` | 单位矩阵 | -| [Zero()](zero.md) | `Matrix4` | 零矩阵 | -| [Translation(v)](translation.md) | `Matrix4` | 平移矩阵 | -| [Scale(v)](scale.md) | `Matrix4` | 缩放矩阵 | -| [Rotation(q)](rotation.md) | `Matrix4` | 旋转矩阵（四元数） | -| [TRS(translation, rotation, scale)](trs.md) | `Matrix4` | 完整变换 | - -### 旋转 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [RotationX(radians)](rotationx.md) | `Matrix4` | X 轴旋转 | -| [RotationY(radians)](rotationy.md) | `Matrix4` | Y 轴旋转 | -| [RotationZ(radians)](rotationz.md) | `Matrix4` | Z 轴旋转 | - -### 相机变换 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [LookAt(eye, target, up)](lookat.md) | `Matrix4` | 视图矩阵 | -| [Perspective(fov, aspect, near, far)](perspective.md) | `Matrix4` | 透视投影 | -| [Orthographic(left, right, bottom, top, near, far)](orthographic.md) | `Matrix4` | 正交投影 | - -## 实例方法 - -### 乘法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `operator*(Matrix4, Matrix4)` | `Matrix4` | 矩阵乘法 | -| `operator*(Matrix4, Vector4)` | `Vector4` | 矩阵-向量乘法 | -| [MultiplyPoint(v)](multiplypoint.md) | `Vector3` | 点变换（带平移） | -| [MultiplyVector(v)](multiplyvector.md) | `Vector3` | 方向变换（不带平移） | - -### 分解 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Transpose()](transpose.md) | `Matrix4` | 转置矩阵 | -| [Inverse()](inverse.md) | `Matrix4` | 逆矩阵 | -| [Determinant()](determinant.md) | `float` | 行列式 | -| [GetTranslation()](gettranslation.md) | `Vector3` | 获取平移分量 | -| [GetRotation()](getrotation.md) | `Quaternion` | 获取旋转分量 | -| [GetScale()](getscale.md) | `Vector3` | 获取缩放分量 | -| [Decompose(translation, rotation, scale)](decompose.md) | `void` | 分解所有分量 | - ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Vector3](../vector3/vector3.md) - 三维向量 +- [Quaternion](../quaternion/quaternion.md) - 四元数 +- [Matrix3](../matrix3/matrix3.md) - 3x3 矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/multiplypoint.md b/docs/api/math/matrix4/multiplypoint.md index 059f1c9f..e164e337 100644 --- a/docs/api/math/matrix4/multiplypoint.md +++ b/docs/api/math/matrix4/multiplypoint.md @@ -1,21 +1,41 @@ -# Matrix4::MultiplyPoint +# Matrix4x4::MultiplyPoint ```cpp Vector3 MultiplyPoint(const Vector3& v) const ``` -使用矩阵变换点（包含平移）。 +使用矩阵变换一个点。会自动处理 w=1 的齐次坐标变换，适用于位置变换。 **参数：** -- `v` - 要变换的点 +- `v` - 待变换的三维点 -**返回：** `Vector3` - 变换后的点 +**返回：** 变换后的三维点 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 model = Matrix4::TRS(pos, rot, scale); -Vector3 worldPos = model.MultiplyPoint(localPos); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 transform = Matrix4::TRS( + Vector3(1.0f, 2.0f, 3.0f), + Quaternion::Identity(), + Vector3(1.0f, 1.0f, 1.0f) +); + +Vector3 point(1.0f, 0.0f, 0.0f); +Vector3 transformed = transform.MultiplyPoint(point); +// transformed = (2.0f, 2.0f, 3.0f) ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [MultiplyVector](multiplyvector.md) - 向量变换 +- [operator*](operator_mul.md) - 矩阵乘法 \ No newline at end of file diff --git a/docs/api/math/matrix4/multiplyvector.md b/docs/api/math/matrix4/multiplyvector.md index a0fa4f5b..87ca5a7e 100644 --- a/docs/api/math/matrix4/multiplyvector.md +++ b/docs/api/math/matrix4/multiplyvector.md @@ -1,21 +1,36 @@ -# Matrix4::MultiplyVector +# Matrix4x4::MultiplyVector ```cpp Vector3 MultiplyVector(const Vector3& v) const ``` -使用矩阵变换方向向量（不包含平移）。 +使用矩阵变换一个方向向量。会自动处理 w=0 的齐次坐标变换，适用于方向变换，不受平移影响。 **参数：** -- `v` - 要变换的方向向量 +- `v` - 待变换的三维方向向量 -**返回：** `Vector3` - 变换后的方向 +**返回：** 变换后的三维方向向量 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 model = Matrix4::TRS(pos, rot, scale); -Vector3 worldDir = model.MultiplyVector(localDir); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 rotation = Matrix4::RotationY(3.14159265f / 2.0f); +Vector3 direction(1.0f, 0.0f, 0.0f); +Vector3 rotated = rotation.MultiplyVector(direction); +// rotated = (0.0f, 0.0f, -1.0f) ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [MultiplyPoint](multiplypoint.md) - 点变换 +- [operator*](operator_mul.md) - 矩阵乘法 \ No newline at end of file diff --git a/docs/api/math/matrix4/operator_index.md b/docs/api/math/matrix4/operator_index.md new file mode 100644 index 00000000..013908c7 --- /dev/null +++ b/docs/api/math/matrix4/operator_index.md @@ -0,0 +1,35 @@ +# Matrix4x4::operator[] + +```cpp +float* operator[](int row) +const float* operator[](int row) const +``` + +通过行索引访问矩阵元素。返回指向该行第一列元素的指针。 + +**参数：** +- `row` - 行索引（0-3） + +**返回：** 指向该行数据的指针 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Matrix4.h" + +using namespace XCEngine::Math; + +Matrix4 m = Matrix4::Identity(); +m[0][0] = 5.0f; // 设置第一行第一列 +m[1][2] = 3.0f; // 设置第二行第三列 + +float val = m[0][1]; // 读取第一行第二列 +``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/math/matrix4/operator_mul.md b/docs/api/math/matrix4/operator_mul.md new file mode 100644 index 00000000..e72f4e45 --- /dev/null +++ b/docs/api/math/matrix4/operator_mul.md @@ -0,0 +1,44 @@ +# Matrix4x4::operator* + +```cpp +Matrix4x4 operator*(const Matrix4x4& other) const +Vector4 operator*(const Vector4& v) const +``` + +两个重载分别用于矩阵与矩阵乘法，以及矩阵与四维向量的乘法。 + +**参数（矩阵乘法）：** +- `other` - 右侧矩阵 + +**参数（向量乘法）：** +- `v` - 四维向量 + +**返回：** +- 矩阵乘法：结果矩阵 +- 向量乘法：变换后的四维向量 + +**线程安全：** ✅ + +**复杂度：** O(n²) - 矩阵乘法为 O(4³)，向量乘法为 O(4) + +**示例：** + +```cpp +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector4.h" + +using namespace XCEngine::Math; + +Matrix4 m1 = Matrix4::RotationY(1.0f); +Matrix4 m2 = Matrix4::Translation(Vector3(1.0f, 0.0f, 0.0f)); +Matrix4 combined = m1 * m2; + +Vector4 v(1.0f, 0.0f, 0.0f, 1.0f); +Vector4 transformed = m1 * v; +``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [MultiplyPoint](multiplypoint.md) - 点变换 +- [MultiplyVector](multiplyvector.md) - 向量变换 \ No newline at end of file diff --git a/docs/api/math/matrix4/orthographic.md b/docs/api/math/matrix4/orthographic.md index f8b156a8..742869d4 100644 --- a/docs/api/math/matrix4/orthographic.md +++ b/docs/api/math/matrix4/orthographic.md @@ -1,25 +1,36 @@ -# Matrix4::Orthographic +# Matrix4x4::Orthographic ```cpp -static Matrix4 Orthographic(float left, float right, float bottom, float top, float near, float far) +static Matrix4x4 Orthographic(float left, float right, float bottom, float top, float near, float far) ``` -创建正交投影矩阵。 +创建正交投影矩阵。用于 2D UI 或建筑制图等需要保持物体实际大小的场景。 **参数：** -- `left` - 左裁剪面 -- `right` - 右裁剪面 -- `bottom` - 下裁剪面 -- `top` - 上裁剪面 -- `near` - 近裁剪面距离 -- `far` - 远裁剪面距离 +- `left` - 左裁切面 x 坐标 +- `right` - 右裁切面 x 坐标 +- `bottom` - 下裁切面 y 坐标 +- `top` - 上裁切面 y 坐标 +- `near` - 近裁切面 z 坐标 +- `far` - 远裁切面 z 坐标 -**返回：** `Matrix4` - 正交投影矩阵 +**返回：** 正交投影矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 ortho = Matrix4::Orthographic(-aspect, aspect, -1.0f, 1.0f, 0.1f, 100.0f); +#include "XCEngine/Math/Matrix4.h" + +using namespace XCEngine::Math; + +Matrix4 ortho = Matrix4::Orthographic(-10.0f, 10.0f, -5.0f, 5.0f, 0.1f, 100.0f); ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Perspective](perspective.md) - 透视投影 \ No newline at end of file diff --git a/docs/api/math/matrix4/perspective.md b/docs/api/math/matrix4/perspective.md index 8316a8c7..deefe534 100644 --- a/docs/api/math/matrix4/perspective.md +++ b/docs/api/math/matrix4/perspective.md @@ -1,23 +1,37 @@ -# Matrix4::Perspective +# Matrix4x4::Perspective ```cpp -static Matrix4 Perspective(float fov, float aspect, float near, float far) +static Matrix4x4 Perspective(float fov, float aspect, float near, float far) ``` -创建透视投影矩阵。 +创建透视投影矩阵。用于将 3D 场景投影到 2D 视口，产生近大远小的效果。 **参数：** - `fov` - 垂直视野角度（弧度） -- `aspect` - 宽高比 -- `near` - 近裁剪面距离 -- `far` - 远裁剪面距离 +- `aspect` - 宽高比（width / height） +- `near` - 近裁切面距离 +- `far` - 远裁切面距离 -**返回：** `Matrix4` - 透视投影矩阵 +**返回：** 透视投影矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f); +#include "XCEngine/Math/Matrix4.h" + +using namespace XCEngine::Math; + +float fov = 60.0f * 3.14159265f / 180.0f; +float aspect = 16.0f / 9.0f; +Matrix4 proj = Matrix4::Perspective(fov, aspect, 0.1f, 100.0f); ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Orthographic](orthographic.md) - 正交投影 +- [LookAt](lookat.md) - 视图矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/rotation.md b/docs/api/math/matrix4/rotation.md index b0b0b7b2..c9cdeb74 100644 --- a/docs/api/math/matrix4/rotation.md +++ b/docs/api/math/matrix4/rotation.md @@ -1,21 +1,39 @@ -# Matrix4::Rotation +# Matrix4x4::Rotation ```cpp -static Matrix4 Rotation(const Quaternion& q) +static Matrix4x4 Rotation(const Quaternion& q) ``` -从四元数创建旋转矩阵。 +从四元数创建旋转矩阵。用于将旋转变换应用到点或向量。 **参数：** -- `q` - 四元数 +- `q` - 表示旋转的四元数 -**返回：** `Matrix4` - 旋转矩阵 +**返回：** 旋转矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); -Matrix4 rotation = Matrix4::Rotation(rot); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Quaternion.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::FromEuler(0.0f, 90.0f, 0.0f); +Matrix4 rotate = Matrix4::Rotation(q); + +Vector3 point(1.0f, 0.0f, 0.0f); +Vector3 rotated = rotate.MultiplyVector(point); +// point 绕 Y 轴旋转 90 度 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Quaternion](../quaternion/quaternion.md) - 四元数类 +- [TRS](trs.md) - 组合变换矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/rotationx.md b/docs/api/math/matrix4/rotationx.md index 1cf1fc7e..4e08e6b3 100644 --- a/docs/api/math/matrix4/rotationx.md +++ b/docs/api/math/matrix4/rotationx.md @@ -1,20 +1,36 @@ -# Matrix4::RotationX +# Matrix4x4::RotationX ```cpp -static Matrix4 RotationX(float radians) +static Matrix4x4 RotationX(float radians) ``` -创建绕 X 轴旋转的矩阵。 +创建绕 X 轴旋转的矩阵。角度为正时，按右手定则逆时针旋转。 **参数：** - `radians` - 旋转角度（弧度） -**返回：** `Matrix4` - 旋转矩阵 +**返回：** 绕 X 轴旋转的矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 rotX = Matrix4::RotationX(Math::HALF_PI); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 rotX = Matrix4::RotationX(3.14159265f / 2.0f); // 90 度 +Vector3 point(1.0f, 0.0f, 0.0f); +Vector3 rotated = rotX.MultiplyVector(point); +// point 绕 X 轴旋转 90 度 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [RotationY](rotationy.md) - 绕 Y 轴旋转 +- [RotationZ](rotationz.md) - 绕 Z 轴旋转 \ No newline at end of file diff --git a/docs/api/math/matrix4/rotationy.md b/docs/api/math/matrix4/rotationy.md index 039c703d..4caa54e7 100644 --- a/docs/api/math/matrix4/rotationy.md +++ b/docs/api/math/matrix4/rotationy.md @@ -1,20 +1,36 @@ -# Matrix4::RotationY +# Matrix4x4::RotationY ```cpp -static Matrix4 RotationY(float radians) +static Matrix4x4 RotationY(float radians) ``` -创建绕 Y 轴旋转的矩阵。 +创建绕 Y 轴旋转的矩阵。角度为正时，按右手定则逆时针旋转。 **参数：** - `radians` - 旋转角度（弧度） -**返回：** `Matrix4` - 旋转矩阵 +**返回：** 绕 Y 轴旋转的矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 rotY = Matrix4::RotationY(Math::HALF_PI); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 rotY = Matrix4::RotationY(3.14159265f / 2.0f); // 90 度 +Vector3 point(1.0f, 0.0f, 0.0f); +Vector3 rotated = rotY.MultiplyVector(point); +// point 绕 Y 轴旋转 90 度 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [RotationX](rotationx.md) - 绕 X 轴旋转 +- [RotationZ](rotationz.md) - 绕 Z 轴旋转 \ No newline at end of file diff --git a/docs/api/math/matrix4/rotationz.md b/docs/api/math/matrix4/rotationz.md index 67748363..effc1e24 100644 --- a/docs/api/math/matrix4/rotationz.md +++ b/docs/api/math/matrix4/rotationz.md @@ -1,20 +1,36 @@ -# Matrix4::RotationZ +# Matrix4x4::RotationZ ```cpp -static Matrix4 RotationZ(float radians) +static Matrix4x4 RotationZ(float radians) ``` -创建绕 Z 轴旋转的矩阵。 +创建绕 Z 轴旋转的矩阵。角度为正时，按右手定则逆时针旋转。 **参数：** - `radians` - 旋转角度（弧度） -**返回：** `Matrix4` - 旋转矩阵 +**返回：** 绕 Z 轴旋转的矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 rotZ = Matrix4::RotationZ(Math::HALF_PI); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 rotZ = Matrix4::RotationZ(3.14159265f / 2.0f); // 90 度 +Vector3 point(1.0f, 0.0f, 0.0f); +Vector3 rotated = rotZ.MultiplyVector(point); +// point 绕 Z 轴旋转 90 度 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [RotationX](rotationx.md) - 绕 X 轴旋转 +- [RotationY](rotationy.md) - 绕 Y 轴旋转 \ No newline at end of file diff --git a/docs/api/math/matrix4/scale.md b/docs/api/math/matrix4/scale.md index 80477603..fcd014bc 100644 --- a/docs/api/math/matrix4/scale.md +++ b/docs/api/math/matrix4/scale.md @@ -1,20 +1,35 @@ -# Matrix4::Scale +# Matrix4x4::Scale ```cpp -static Matrix4 Scale(const Vector3& v) +static Matrix4x4 Scale(const Vector3& v) ``` -创建缩放矩阵。 +创建缩放矩阵。用于沿各轴方向对点或向量进行缩放变换。 **参数：** -- `v` - 各轴缩放因子 +- `v` - 缩放向量，指定 x、y、z 方向上的缩放因子 -**返回：** `Matrix4` - 缩放矩阵 +**返回：** 缩放矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 scale = Matrix4::Scale(Vector3(2.0f, 2.0f, 2.0f)); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 scale = Matrix4::Scale(Vector3(2.0f, 0.5f, 1.0f)); +Vector3 point(2.0f, 4.0f, 2.0f); +Vector3 scaled = scale.MultiplyVector(point); +// scaled = (4.0f, 2.0f, 2.0f) ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [TRS](trs.md) - 组合变换矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/translation.md b/docs/api/math/matrix4/translation.md index 8b8b3edb..a7c87442 100644 --- a/docs/api/math/matrix4/translation.md +++ b/docs/api/math/matrix4/translation.md @@ -1,20 +1,35 @@ -# Matrix4::Translation +# Matrix4x4::Translation ```cpp -static Matrix4 Translation(const Vector3& v) +static Matrix4x4 Translation(const Vector3& v) ``` -创建平移矩阵。 +创建平移矩阵。生成的矩阵用于沿指定方向移动点或向量。 **参数：** -- `v` - 平移向量 +- `v` - 平移向量 (x, y, z 方向上的平移量) -**返回：** `Matrix4` - 平移矩阵 +**返回：** 平移矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Matrix4 translation = Matrix4::Translation(Vector3(1.0f, 2.0f, 3.0f)); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +Matrix4 translate = Matrix4::Translation(Vector3(5.0f, 3.0f, 2.0f)); +Vector3 point(1.0f, 1.0f, 1.0f); +Vector3 moved = translate.MultiplyPoint(point); +// moved = (6.0f, 4.0f, 3.0f) ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [TRS](trs.md) - 组合变换矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/transpose.md b/docs/api/math/matrix4/transpose.md index ad490342..1713b52c 100644 --- a/docs/api/math/matrix4/transpose.md +++ b/docs/api/math/matrix4/transpose.md @@ -1,18 +1,32 @@ -# Matrix4::Transpose +# Matrix4x4::Transpose ```cpp -Matrix4 Transpose() const +Matrix4x4 Transpose() const ``` -返回矩阵的转置。 +返回矩阵的转置。转置操作将矩阵的行和列互换。 -**返回：** `Matrix4` - 转置矩阵 +**参数：** （无） -**复杂度：** O(1) +**返回：** 转置后的矩阵 + +**线程安全：** ✅ + +**复杂度：** O(n²) - O(16) **示例：** ```cpp -Matrix4 m = ...; -Matrix4 transposed = m.Transpose(); +#include "XCEngine/Math/Matrix4.h" + +using namespace XCEngine::Math; + +Matrix4 m = Matrix4::Identity(); +Matrix4 t = m.Transpose(); +// 转置后仍为单位矩阵 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Inverse](inverse.md) - 矩阵求逆 \ No newline at end of file diff --git a/docs/api/math/matrix4/trs.md b/docs/api/math/matrix4/trs.md index 3d0a3348..d524e207 100644 --- a/docs/api/math/matrix4/trs.md +++ b/docs/api/math/matrix4/trs.md @@ -1,22 +1,45 @@ -# Matrix4::TRS +# Matrix4x4::TRS ```cpp -static Matrix4 TRS(const Vector3& translation, const Quaternion& rotation, const Vector3& scale) +static Matrix4x4 TRS(const Vector3& translation, const Quaternion& rotation, const Vector3& scale) ``` -创建完整的 TRS（平移、旋转、缩放）变换矩阵。 +创建组合变换矩阵。等价于先缩放、再旋转、最后平移的组合效果。 **参数：** - `translation` - 平移向量 - `rotation` - 旋转四元数 - `scale` - 缩放向量 -**返回：** `Matrix4` - 组合变换矩阵 +**返回：** 组合变换矩阵 T * R * S -**复杂度：** O(1) +**线程安全：** ✅ + +**复杂度：** O(n²) - 涉及多次 4x4 矩阵运算 **示例：** ```cpp -Matrix4 transform = Matrix4::TRS(position, rotation, Vector3::One()); +#include "XCEngine/Math/Matrix4.h" +#include "XCEngine/Math/Vector3.h" +#include "XCEngine/Math/Quaternion.h" + +using namespace XCEngine::Math; + +Matrix4 transform = Matrix4::TRS( + Vector3(1.0f, 2.0f, 3.0f), + Quaternion::FromEuler(0.0f, 90.0f, 0.0f), + Vector3(2.0f, 2.0f, 2.0f) +); + +Vector3 point(1.0f, 0.0f, 0.0f); +Vector3 transformed = transform.MultiplyPoint(point); ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 +- [Translation](translation.md) - 平移矩阵 +- [Rotation](rotation.md) - 旋转矩阵 +- [Scale](scale.md) - 缩放矩阵 +- [Decompose](decompose.md) - 分解矩阵 \ No newline at end of file diff --git a/docs/api/math/matrix4/zero.md b/docs/api/math/matrix4/zero.md index 133c16d4..38ea17df 100644 --- a/docs/api/math/matrix4/zero.md +++ b/docs/api/math/matrix4/zero.md @@ -1,17 +1,30 @@ -# Matrix4::Zero +# Matrix4x4::Zero ```cpp -static Matrix4 Zero() +static Matrix4x4 Zero() ``` -返回零矩阵。 +返回零矩阵。所有元素初始化为 0 的矩阵。 -**返回：** `Matrix4` - 零矩阵 +**参数：** （无） + +**返回：** 零矩阵 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include "XCEngine/Math/Matrix4.h" + +using namespace XCEngine::Math; + Matrix4 zero = Matrix4::Zero(); +// 所有元素均为 0 ``` + +## 相关文档 + +- [Matrix4](matrix4.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/math/obb/contains.md b/docs/api/math/obb/contains.md new file mode 100644 index 00000000..77610193 --- /dev/null +++ b/docs/api/math/obb/contains.md @@ -0,0 +1,35 @@ +# OBB::Contains + +```cpp +bool Contains(const Vector3& point) const; +``` + +检测给定点是否位于 OBB 包围盒内部。通过将点变换到局部坐标系，然后检查其坐标分量是否在半长向量范围内。 + +**参数：** +- `point` - 待检测的三维点 + +**返回：** 点在包围盒内返回 `true`，否则返回 `false` + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "AABB.h" +#include "Vector3.h" + +using namespace XCEngine::Math; + +OBB obb(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); + +Vector3 insidePoint(0.0f, 0.0f, 0.0f); +Vector3 outsidePoint(2.0f, 0.0f, 0.0f); + +bool isInside = obb.Contains(insidePoint); +bool isOutside = obb.Contains(outsidePoint); +``` diff --git a/docs/api/math/obb/get-axis.md b/docs/api/math/obb/get-axis.md new file mode 100644 index 00000000..aac57d84 --- /dev/null +++ b/docs/api/math/obb/get-axis.md @@ -0,0 +1,33 @@ +# OBB::GetAxis + +```cpp +Vector3 GetAxis(int index) const; +``` + +获取 OBB 在指定索引处的局部轴方向。index 取值为 0、1、2，分别对应局部坐标系的 X、Y、Z 轴。 + +**参数：** +- `index` - 轴索引（0=X轴，1=Y轴，2=Z轴） + +**返回：** 对应索引处的轴方向向量（已归一化） + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "AABB.h" +#include "Vector3.h" + +using namespace XCEngine::Math; + +OBB obb(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); + +Vector3 axisX = obb.GetAxis(0); +Vector3 axisY = obb.GetAxis(1); +Vector3 axisZ = obb.GetAxis(2); +``` diff --git a/docs/api/math/obb/get-max.md b/docs/api/math/obb/get-max.md new file mode 100644 index 00000000..6b7aacdf --- /dev/null +++ b/docs/api/math/obb/get-max.md @@ -0,0 +1,30 @@ +# OBB::GetMax + +```cpp +Vector3 GetMax() const; +``` + +获取 OBB 包围盒在局部坐标系下的最大顶点。该点是中心点加上半长向量计算得出。 + +**参数：** 无 + +**返回：** 包围盒的最大顶点 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "AABB.h" +#include "Vector3.h" + +using namespace XCEngine::Math; + +OBB obb(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); + +Vector3 maxPoint = obb.GetMax(); +``` diff --git a/docs/api/math/obb/get-min.md b/docs/api/math/obb/get-min.md new file mode 100644 index 00000000..7d65afc3 --- /dev/null +++ b/docs/api/math/obb/get-min.md @@ -0,0 +1,30 @@ +# OBB::GetMin + +```cpp +Vector3 GetMin() const; +``` + +获取 OBB 包围盒在局部坐标系下的最小顶点。该点是中心点减去半长向量计算得出。 + +**参数：** 无 + +**返回：** 包围盒的最小顶点 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "AABB.h" +#include "Vector3.h" + +using namespace XCEngine::Math; + +OBB obb(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); + +Vector3 minPoint = obb.GetMin(); +``` diff --git a/docs/api/math/obb/intersects-obb.md b/docs/api/math/obb/intersects-obb.md new file mode 100644 index 00000000..933fe8cd --- /dev/null +++ b/docs/api/math/obb/intersects-obb.md @@ -0,0 +1,34 @@ +# OBB::Intersects (OBB) + +```cpp +bool Intersects(const OBB& other) const; +``` + +检测该 OBB 与另一个 OBB 是否相交。采用分离轴定理（SAT）进行检测，通过测试 15 条可能的分离轴来判断两个盒子是否重叠。 + +**参数：** +- `other` - 另一个 OBB 包围盒 + +**返回：** 两 OBB 相交返回 `true`，否则返回 `false` + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "AABB.h" +#include "Vector3.h" +#include "Matrix4.h" + +using namespace XCEngine::Math; + +OBB obb1(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); +OBB obb2(Vector3(1.5f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); + +if (obb1.Intersects(obb2)) { +} +``` diff --git a/docs/api/math/obb/intersects-sphere.md b/docs/api/math/obb/intersects-sphere.md new file mode 100644 index 00000000..ecbc0be9 --- /dev/null +++ b/docs/api/math/obb/intersects-sphere.md @@ -0,0 +1,34 @@ +# OBB::Intersects (Sphere) + +```cpp +bool Intersects(const Sphere& sphere) const; +``` + +检测该 OBB 与球体是否相交。将球心变换到 OBB 的局部坐标系，然后在局部空间中计算球心到盒子的最近点，最后判断距离是否小于球体半径。 + +**参数：** +- `sphere` - 待检测的球体 + +**返回：** OBB 与球体相交返回 `true`，否则返回 `false` + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "AABB.h" +#include "Vector3.h" +#include "Sphere.h" + +using namespace XCEngine::Math; + +OBB obb(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); +Sphere sphere(Vector3(0.5f, 0.0f, 0.0f), 0.5f); + +if (obb.Intersects(sphere)) { +} +``` diff --git a/docs/api/math/obb/obb.md b/docs/api/math/obb/obb.md new file mode 100644 index 00000000..0feea902 --- /dev/null +++ b/docs/api/math/obb/obb.md @@ -0,0 +1,52 @@ +# OBB + +**命名空间**: `XCEngine::Math` + +**类型**: `struct` + +**头文件**: `XCEngine/Math/OBB.h` + +**描述**: 定向包围盒，支持任意方向旋转的盒状包围体 + +## 概述 + +OBB（Oriented Bounding Box）是一种包围盒类型，与轴对齐包围盒（AABB）不同，OBB 可以任意旋转，因此能够更紧凑地包围复杂形状的对象。OBB 由一个中心点、半长向量（extents）和一个变换矩阵组成，变换矩阵定义了盒子的朝向。 + +OBB 常用于碰撞检测、剔除运算和物理模拟等场景。 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`GetAxis`](get-axis.md) | 获取指定索引处的局部轴方向 | +| [`GetMin`](get-min.md) | 获取包围盒最小顶点 | +| [`GetMax`](get-max.md) | 获取包围盒最大顶点 | +| [`Contains`](contains.md) | 检测点是否在包围盒内 | +| [`Intersects`](intersects-obb.md) | 检测与另一个 OBB 是否相交 | +| [`Intersects`](intersects-sphere.md) | 检测与球体是否相交 | + +## 使用示例 + +```cpp +#include "AABB.h" +#include "Vector3.h" +#include "Matrix4.h" + +using namespace XCEngine::Math; + +OBB obb(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); + +Vector3 point(0.5f, 0.25f, 0.5f); +if (obb.Contains(point)) { +} + +Vector3 axis = obb.GetAxis(0); +Vector3 min = obb.GetMin(); +Vector3 max = obb.GetMax(); +``` + +## 相关文档 + +- [Vector3](../vector3/vector3.md) - 三维向量 +- [Matrix4](../matrix4/matrix4.md) - 4x4 变换矩阵 +- [Sphere](../sphere/sphere.md) - 球体 diff --git a/docs/api/math/plane/constructor-default.md b/docs/api/math/plane/constructor-default.md new file mode 100644 index 00000000..78b176e1 --- /dev/null +++ b/docs/api/math/plane/constructor-default.md @@ -0,0 +1,29 @@ +# Plane::Plane + +```cpp +Plane() +``` + +默认构造函数，创建一个朝上（Y 轴正方向）的单位平面，等价于 `Plane(Vector3::Up(), 0.0f)`。 + +**参数：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +using namespace XCEngine::Math; + +void DefaultConstructorExample() { + Plane plane; +} +``` + +## 相关文档 + +- [Plane 类总览](plane.md) - 返回类总览 diff --git a/docs/api/math/plane/constructor.md b/docs/api/math/plane/constructor.md new file mode 100644 index 00000000..7a381950 --- /dev/null +++ b/docs/api/math/plane/constructor.md @@ -0,0 +1,35 @@ +# Plane::Plane + +```cpp +Plane(const Vector3& normal, float distance) +``` + +从法线向量和距离值构造平面。输入的法线会自动归一化。 + +**参数：** +- `normal` - 平面法线向量（会被归一化） +- `distance` - 原点到平面的有符号距离 + +**返回：** 无（构造函数） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +void ConstructorExample() { + Plane plane(Vector3::Up(), 0.0f); + Plane tiltedPlane(Vector3(1.0f, 1.0f, 0.0f), 5.0f); +} +``` + +## 相关文档 + +- [Plane 类总览](plane.md) - 返回类总览 diff --git a/docs/api/math/plane/frompoints.md b/docs/api/math/plane/frompoints.md index a9503a63..2656a2cf 100644 --- a/docs/api/math/plane/frompoints.md +++ b/docs/api/math/plane/frompoints.md @@ -4,7 +4,7 @@ static Plane FromPoints(const Vector3& a, const Vector3& b, const Vector3& c) ``` -从三个不共线点创建平面。 +从三个不共线点创建平面。平面法线通过叉积计算并归一化，距离为原点到平面的有符号距离。 **参数：** - `a` - 第一个点 @@ -13,10 +13,29 @@ static Plane FromPoints(const Vector3& a, const Vector3& b, const Vector3& c) **返回：** `Plane` - 由三点定义的平面 +**异常：** 如果三点共线，叉积结果为零向量，行为未定义。 + +**线程安全：** ✅ + **复杂度：** O(1) **示例：** ```cpp -Plane plane = Plane::FromPoints(p0, p1, p2); +#include +#include + +using namespace XCEngine::Math; + +void FromPointsExample() { + Vector3 p0(0.0f, 0.0f, 0.0f); + Vector3 p1(1.0f, 0.0f, 0.0f); + Vector3 p2(0.0f, 1.0f, 0.0f); + + Plane plane = Plane::FromPoints(p0, p1, p2); +} ``` + +## 相关文档 + +- [Plane 类总览](plane.md) - 返回类总览 diff --git a/docs/api/math/plane/getclosestpoint.md b/docs/api/math/plane/getclosestpoint.md index 17dfcc26..6b5b55b0 100644 --- a/docs/api/math/plane/getclosestpoint.md +++ b/docs/api/math/plane/getclosestpoint.md @@ -4,17 +4,34 @@ Vector3 GetClosestPoint(const Vector3& point) const ``` -计算平面上最接近给定点的点。 +计算平面上最接近给定点的点。通过将点沿平面法线方向投影到平面上得到。 **参数：** - `point` - 参考点 -**返回：** `Vector3` - 平面上最接近的点 +**返回：** `Vector3` - 平面上最接近给定点的点 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Vector3 closest = plane.GetClosestPoint(point); +#include +#include + +using namespace XCEngine::Math; + +void GetClosestPointExample() { + Plane plane(Vector3::Up(), 0.0f); + + Vector3 point(5.0f, 10.0f, 0.0f); + Vector3 closest = plane.GetClosestPoint(point); +} ``` + +## 相关文档 + +- [Plane 类总览](plane.md) - 返回类总览 +- [GetDistanceToPoint](getdistancetopoint.md) - 计算有符号距离 diff --git a/docs/api/math/plane/getdistancetopoint.md b/docs/api/math/plane/getdistancetopoint.md index 6e797236..2bcb9027 100644 --- a/docs/api/math/plane/getdistancetopoint.md +++ b/docs/api/math/plane/getdistancetopoint.md @@ -4,17 +4,39 @@ float GetDistanceToPoint(const Vector3& point) const ``` -计算点到平面的有符号距离。 +计算点到平面的有符号距离。正值表示点在法线方向一侧，负值表示点在法线相反方向一侧，零值表示点在平面上。 **参数：** - `point` - 要计算的点 -**返回：** `float` - 有符号距离 +**返回：** `float` - 点到平面的有符号距离 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -float dist = plane.GetDistanceToPoint(point); +#include +#include +#include + +using namespace XCEngine::Math; + +void GetDistanceToPointExample() { + Plane plane(Vector3::Up(), 0.0f); + + Vector3 point1(0.0f, 2.0f, 0.0f); + float dist1 = plane.GetDistanceToPoint(point1); + + Vector3 point2(0.0f, -3.0f, 0.0f); + float dist2 = plane.GetDistanceToPoint(point2); +} ``` + +## 相关文档 + +- [Plane 类总览](plane.md) - 返回类总览 +- [GetClosestPoint](getclosestpoint.md) - 计算平面上最接近点 +- [GetSide](getside.md) - 判断点在哪一侧 diff --git a/docs/api/math/plane/getside.md b/docs/api/math/plane/getside.md index b6948520..b9c1d321 100644 --- a/docs/api/math/plane/getside.md +++ b/docs/api/math/plane/getside.md @@ -4,17 +4,39 @@ bool GetSide(const Vector3& point) const ``` -判断点在平面的哪一侧。 +判断点在平面的哪一侧。返回值 `true` 表示点在法线方向一侧，`false` 表示点在法线相反方向或平面上。 **参数：** - `point` - 要测试的点 -**返回：** `bool` - true 表示点在法线方向一侧 +**返回：** `bool` - `true` 表示点在法线方向一侧，`false` 表示另一侧或平面上 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (plane.GetSide(point)) { /* point is on normal side */ } +#include +#include + +using namespace XCEngine::Math; + +void GetSideExample() { + Plane plane(Vector3::Up(), 0.0f); + + Vector3 pointOnNormalSide(0.0f, 1.0f, 0.0f); + if (plane.GetSide(pointOnNormalSide)) { + } + + Vector3 pointOnOppositeSide(0.0f, -1.0f, 0.0f); + if (!plane.GetSide(pointOnOppositeSide)) { + } +} ``` + +## 相关文档 + +- [Plane 类总览](plane.md) - 返回类总览 +- [GetDistanceToPoint](getdistancetopoint.md) - 计算有符号距离 diff --git a/docs/api/math/plane/intersects.md b/docs/api/math/plane/intersects.md index 03c88551..d05ea593 100644 --- a/docs/api/math/plane/intersects.md +++ b/docs/api/math/plane/intersects.md @@ -4,17 +4,38 @@ bool Intersects(const Sphere& sphere) const ``` -检测平面是否与球体相交。 +检测平面是否与球体相交。球体与平面相交的条件是：球心到平面的有符号距离的绝对值小于等于球体半径。 **参数：** - `sphere` - 要检测的球体 -**返回：** `bool` - true 表示相交 +**返回：** `bool` - `true` 表示相交，`false` 表示不相交 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (plane.Intersects(sphere)) { /* collision */ } +#include +#include +#include + +using namespace XCEngine::Math; + +void IntersectsExample() { + Plane plane(Vector3::Up(), 0.0f); + + Sphere sphere1(Vector3(0.0f, 0.5f, 0.0f), 1.0f); + bool intersects1 = plane.Intersects(sphere1); + + Sphere sphere2(Vector3(0.0f, 5.0f, 0.0f), 1.0f); + bool intersects2 = plane.Intersects(sphere2); +} ``` + +## 相关文档 + +- [Plane 类总览](plane.md) - 返回类总览 +- [Sphere](../sphere/sphere.md) - 球体类 diff --git a/docs/api/math/plane/plane.md b/docs/api/math/plane/plane.md index 89782320..6d8ebb33 100644 --- a/docs/api/math/plane/plane.md +++ b/docs/api/math/plane/plane.md @@ -1,40 +1,64 @@ # Plane -3D 平面结构体，由法线和距离表示。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Plane.h` -## 结构体定义 +**描述**: 平面，用于 3D 空间中的平面表示和相交测试 + +## 概述 + +`Plane` 结构体用于表示 3D 空间中的平面，通过法线向量（normal）和距离值（distance）定义。平面方程为 `dot(normal, point) + distance = 0`。常用于碰撞检测、视锥体裁剪、射线投射等图形学基础运算。 + +默认构造创建一个朝上（y 轴正方向）的单位平面。 + +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `normal` | `Vector3` | 平面法线向量 | `Vector3::Up()` | +| `distance` | `float` | 原点到平面的有符号距离 | `0.0f` | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Plane()`](constructor-default.md) | 默认构造函数，创建 y=0 平面 | +| [`Plane(normal, distance)`](constructor.md) | 从法线和距离构造平面 | +| [`FromPoints`](frompoints.md) | 从三个不共线点创建平面 | +| [`GetDistanceToPoint`](getdistancetopoint.md) | 计算点到平面的有符号距离 | +| [`GetClosestPoint`](getclosestpoint.md) | 计算平面上最接近给定点的点 | +| [`GetSide`](getside.md) | 判断点在平面的哪一侧 | +| [`Intersects`](intersects.md) | 检测与球体是否相交 | + +## 使用示例 ```cpp -struct Plane { - Vector3 normal = Vector3::Up(); - float distance = 0.0f; -}; +#include +#include +#include + +using namespace XCEngine::Math; + +void PlaneExample() { + Plane plane(Vector3::Up(), 0.0f); + + Vector3 point(1.0f, 2.0f, 0.0f); + float dist = plane.GetDistanceToPoint(point); + + Vector3 closest = plane.GetClosestPoint(point); + + bool onNormalSide = plane.GetSide(point); + + Sphere sphere(Vector3(1.0f, 0.5f, 0.0f), 1.0f); + bool intersects = plane.Intersects(sphere); +} ``` -## 构造函数 - -- `Plane()` - 默认构造 (y=0 平面) -- `Plane(const Vector3& normal, float distance)` - 从法线和距离构造 - -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [FromPoints(a, b, c)](frompoints.md) | `Plane` | 从三个不共线点创建 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [GetDistanceToPoint(point)](getdistancetopoint.md) | `float` | 点到平面的有符号距离 | -| [GetClosestPoint(point)](getclosestpoint.md) | `Vector3` | 平面上最接近给定点的点 | -| [GetSide(point)](getside.md) | `bool` | 点在平面的哪一侧 | -| [Intersects(sphere)](intersects.md) | `bool` | 与球体相交 | - ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Math 模块总览](../math.md) - Math 模块总览 +- [Sphere](../sphere/sphere.md) - 球体 +- [Vector3](../vector3/vector3.md) - 三维向量 diff --git a/docs/api/math/quaternion/dot.md b/docs/api/math/quaternion/dot.md index 8daf0d70..15f15921 100644 --- a/docs/api/math/quaternion/dot.md +++ b/docs/api/math/quaternion/dot.md @@ -1,20 +1,34 @@ # Quaternion::Dot ```cpp -float Dot(const Quaternion& other) const +float Dot(const Quaternion& other) const; ``` -计算两个四元数的点积。 +计算两个四元数的点积（各分量相乘后求和）。 **参数：** - `other` - 另一个四元数 -**返回：** `float` - 点积结果 +**返回：** 点积结果 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -float dot = quat1.Dot(quat2); +#include + +using namespace XCEngine::Math; + +Quaternion q1 = Quaternion::Identity(); +Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(90.0f)); + +float dot = q1.Dot(q2); ``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [Magnitude](magnitude.md) - 求模长 diff --git a/docs/api/math/quaternion/from-axis-angle.md b/docs/api/math/quaternion/from-axis-angle.md new file mode 100644 index 00000000..bdc7e3a1 --- /dev/null +++ b/docs/api/math/quaternion/from-axis-angle.md @@ -0,0 +1,35 @@ +# Quaternion::FromAxisAngle + +```cpp +static Quaternion FromAxisAngle(const Vector3& axis, float radians); +``` + +从轴角表示创建四元数。使用半角公式进行转换。 + +**参数：** +- `axis` - 旋转轴（会被归一化） +- `radians` - 旋转角度（弧度） + +**返回：** 表示该旋转的四元数 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include +#include + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(90.0f)); +``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [FromEulerAngles](from-euler-angles.md) - 从欧拉角创建 +- [LookRotation](look-rotation.md) - 创建看向目标的旋转 diff --git a/docs/api/math/quaternion/from-euler-angles.md b/docs/api/math/quaternion/from-euler-angles.md new file mode 100644 index 00000000..f5afd4e4 --- /dev/null +++ b/docs/api/math/quaternion/from-euler-angles.md @@ -0,0 +1,44 @@ +# Quaternion::FromEulerAngles + +```cpp +static Quaternion FromEulerAngles(float pitch, float yaw, float roll); +static Quaternion FromEulerAngles(const Vector3& euler); +``` + +从欧拉角创建四元数。使用 YXZ 顺序（先绕 Y 轴 yaw，再绕 X 轴 pitch，最后绕 Z 轴 roll）。 + +**参数：** +- `pitch` - 绕 X 轴旋转角度（弧度） +- `yaw` - 绕 Y 轴旋转角度（弧度） +- `roll` - 绕 Z 轴旋转角度（弧度） +- `euler` - 欧拉角向量 (pitch, yaw, roll) + +**返回：** 表示该旋转的四元数 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include +#include + +using namespace XCEngine::Math; + +Quaternion q1 = Quaternion::FromEulerAngles( + Math::Radians(45.0f), + Math::Radians(30.0f), + Math::Radians(60.0f) +); + +Quaternion q2 = Quaternion::FromEulerAngles(Vector3(45, 30, 60) * DEG_TO_RAD); +``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [FromAxisAngle](from-axis-angle.md) - 从轴角创建 +- [ToEulerAngles](to-euler-angles.md) - 转换为欧拉角 diff --git a/docs/api/math/quaternion/from-rotation-matrix.md b/docs/api/math/quaternion/from-rotation-matrix.md new file mode 100644 index 00000000..59c2bfe8 --- /dev/null +++ b/docs/api/math/quaternion/from-rotation-matrix.md @@ -0,0 +1,37 @@ +# Quaternion::FromRotationMatrix + +```cpp +static Quaternion FromRotationMatrix(const Matrix4x4& matrix); +``` + +从 4x4 旋转矩阵创建四元数。矩阵必须是正交矩阵且行列式为 1。 + +**参数：** +- `matrix` - 旋转矩阵 + +**返回：** 对应的四元数 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +Matrix4 rotMatrix; +rotMatrix.m[0][0] = 1; rotMatrix.m[0][1] = 0; rotMatrix.m[0][2] = 0; +rotMatrix.m[1][0] = 0; rotMatrix.m[1][1] = 0; rotMatrix.m[1][2] = -1; +rotMatrix.m[2][0] = 0; rotMatrix.m[2][1] = 1; rotMatrix.m[2][2] = 0; + +Quaternion q = Quaternion::FromRotationMatrix(rotMatrix); +``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [ToMatrix4x4](to-matrix4x4.md) - 转换为矩阵 diff --git a/docs/api/math/quaternion/fromaxisangle.md b/docs/api/math/quaternion/fromaxisangle.md deleted file mode 100644 index 0db57dff..00000000 --- a/docs/api/math/quaternion/fromaxisangle.md +++ /dev/null @@ -1,21 +0,0 @@ -# Quaternion::FromAxisAngle - -```cpp -static Quaternion FromAxisAngle(const Vector3& axis, float radians) -``` - -从轴角创建四元数。 - -**参数：** -- `axis` - 旋转轴（应为单位向量） -- `radians` - 旋转角度（弧度） - -**返回：** `Quaternion` - 表示旋转的四元数 - -**复杂度：** O(1) - -**示例：** - -```cpp -Quaternion rot = Quaternion::FromAxisAngle(Vector3::Up(), 90.0f * DEG_TO_RAD); -``` diff --git a/docs/api/math/quaternion/fromeulerangles.md b/docs/api/math/quaternion/fromeulerangles.md deleted file mode 100644 index b3d3c3be..00000000 --- a/docs/api/math/quaternion/fromeulerangles.md +++ /dev/null @@ -1,25 +0,0 @@ -# Quaternion::FromEulerAngles - -```cpp -static Quaternion FromEulerAngles(float pitch, float yaw, float roll) -static Quaternion FromEulerAngles(const Vector3& euler) -``` - -从欧拉角创建四元数。角度以弧度为单位。 - -**参数：** -- `pitch` - 俯仰角（X 轴旋转） -- `yaw` - 偏航角（Y 轴旋转） -- `roll` - 翻滚角（Z 轴旋转） -- `euler` - 欧拉角向量 (pitch, yaw, roll) - -**返回：** `Quaternion` - 表示旋转的四元数 - -**复杂度：** O(1) - -**示例：** - -```cpp -Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); -Quaternion rot2 = Quaternion::FromEulerAngles(Vector3(0.0f, 90.0f * DEG_TO_RAD, 0.0f)); -``` diff --git a/docs/api/math/quaternion/fromrotationmatrix.md b/docs/api/math/quaternion/fromrotationmatrix.md deleted file mode 100644 index 82c45e53..00000000 --- a/docs/api/math/quaternion/fromrotationmatrix.md +++ /dev/null @@ -1,21 +0,0 @@ -# Quaternion::FromRotationMatrix - -```cpp -static Quaternion FromRotationMatrix(const Matrix4x4& matrix) -``` - -从旋转矩阵创建四元数。 - -**参数：** -- `matrix` - 旋转矩阵 - -**返回：** `Quaternion` - 表示相同旋转的四元数 - -**复杂度：** O(1) - -**示例：** - -```cpp -Matrix4 rotMat = Matrix4::RotationY(90.0f * DEG_TO_RAD); -Quaternion quat = Quaternion::FromRotationMatrix(rotMat); -``` diff --git a/docs/api/math/quaternion/identity.md b/docs/api/math/quaternion/identity.md index 965437a4..1715110d 100644 --- a/docs/api/math/quaternion/identity.md +++ b/docs/api/math/quaternion/identity.md @@ -1,17 +1,28 @@ # Quaternion::Identity ```cpp -static Quaternion Identity() +static Quaternion Identity(); ``` -返回恒等四元数（无旋转）。 +返回单位四元数 (0, 0, 0, 1)，表示无旋转。 -**返回：** `Quaternion` - 值为 (0, 0, 0, 1) 的四元数 +**返回：** 单位四元数 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp +#include + +using namespace XCEngine::Math; + Quaternion identity = Quaternion::Identity(); +// identity = (0, 0, 0, 1) ``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 diff --git a/docs/api/math/quaternion/inverse.md b/docs/api/math/quaternion/inverse.md index a9e1aa9c..8b393f01 100644 --- a/docs/api/math/quaternion/inverse.md +++ b/docs/api/math/quaternion/inverse.md @@ -1,17 +1,31 @@ # Quaternion::Inverse ```cpp -Quaternion Inverse() const +Quaternion Inverse() const; ``` -返回四元数的逆（对于单位四元数就是共轭）。 +求四元数的逆。如果四元数已归一化，逆等于共轭。 -**返回：** `Quaternion` - 逆四元数 +**返回：** 四元数的逆 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Quaternion inv = quat.Inverse(); +#include + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(90.0f)); +Quaternion inv = q.Inverse(); + +Quaternion identity = q * inv; ``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [Normalized](normalized.md) - 归一化四元数 diff --git a/docs/api/math/quaternion/look-rotation.md b/docs/api/math/quaternion/look-rotation.md new file mode 100644 index 00000000..c1c9ff39 --- /dev/null +++ b/docs/api/math/quaternion/look-rotation.md @@ -0,0 +1,33 @@ +# Quaternion::LookRotation + +```cpp +static Quaternion LookRotation(const Vector3& forward, const Vector3& up = Vector3::Up()); +``` + +创建使 forward 方向朝向目标的旋转四元数。 + +**参数：** +- `forward` - 前向方向（会被归一化） +- `up` - 向上方向，默认为 Y 轴正方向 + +**返回：** 使 forward 朝向目标的旋转四元数 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::LookRotation(Vector3(1, 0, 0)); +``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [FromAxisAngle](from-axis-angle.md) - 从轴角创建 diff --git a/docs/api/math/quaternion/lookrotation.md b/docs/api/math/quaternion/lookrotation.md deleted file mode 100644 index 59de421f..00000000 --- a/docs/api/math/quaternion/lookrotation.md +++ /dev/null @@ -1,21 +0,0 @@ -# Quaternion::LookRotation - -```cpp -static Quaternion LookRotation(const Vector3& forward, const Vector3& up = Vector3::Up()) -``` - -创建使 forward 方向朝向目标的旋转四元数。 - -**参数：** -- `forward` - 前方向向量 -- `up` - 上方向向量（默认 Y 轴向上） - -**返回：** `Quaternion` - 看向方向的旋转 - -**复杂度：** O(1) - -**示例：** - -```cpp -Quaternion lookAt = Quaternion::LookRotation(target - position); -``` diff --git a/docs/api/math/quaternion/magnitude.md b/docs/api/math/quaternion/magnitude.md index a17b42bc..32409009 100644 --- a/docs/api/math/quaternion/magnitude.md +++ b/docs/api/math/quaternion/magnitude.md @@ -1,17 +1,30 @@ # Quaternion::Magnitude ```cpp -float Magnitude() const +float Magnitude() const; ``` -计算四元数的模长。 +计算四元数的模长（欧几里得范数）。 -**返回：** `float` - 四元数的模长 +**返回：** 四元数的模长 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -float mag = quat.Magnitude(); +#include + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(90.0f)); +float mag = q.Magnitude(); ``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [Normalized](normalized.md) - 返回归一化四元数 +- [Dot](dot.md) - 点积 diff --git a/docs/api/math/quaternion/normalize.md b/docs/api/math/quaternion/normalize.md new file mode 100644 index 00000000..40b1e330 --- /dev/null +++ b/docs/api/math/quaternion/normalize.md @@ -0,0 +1,32 @@ +# Quaternion::Normalize + +```cpp +static Quaternion Normalize(const Quaternion& q); +``` + +静态归一化方法，返回给定四元数的归一化副本。如果模长接近 0，返回单位四元数。 + +**参数：** +- `q` - 要归一化的四元数 + +**返回：** 归一化后的四元数 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(90.0f)); +Quaternion normalized = Quaternion::Normalize(q); +``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [Normalized](normalized.md) - 实例归一化方法 diff --git a/docs/api/math/quaternion/normalized.md b/docs/api/math/quaternion/normalized.md index db4822bc..1220ee5c 100644 --- a/docs/api/math/quaternion/normalized.md +++ b/docs/api/math/quaternion/normalized.md @@ -1,40 +1,30 @@ -# Quaternion::Normalized / Normalize - -## 实例方法 +# Quaternion::Normalized ```cpp -Quaternion Normalized() const +Quaternion Normalized() const; ``` -返回当前四元数的归一化副本（不修改原四元数）。 +返回归一化（单位化）后的四元数。如果模长接近 0，返回单位四元数。 -**返回：** `Quaternion` - 归一化后的四元数副本 +**返回：** 归一化后的四元数 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Quaternion unit = quat.Normalized(); // quat 保持不变 +#include + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(90.0f)); +Quaternion normalized = q.Normalized(); ``` -## 静态方法 +## 相关文档 -```cpp -static Quaternion Normalize(const Quaternion& q) -``` - -归一化四元数。 - -**参数：** -- `q` - 要归一化的四元数 - -**返回：** `Quaternion` - 归一化后的四元数 - -**复杂度：** O(1) - -**示例：** - -```cpp -Quaternion unit = Quaternion::Normalize(quat); -``` +- [Quaternion](quaternion.md) - 返回类总览 +- [Normalize](normalize.md) - 静态归一化方法 +- [Magnitude](magnitude.md) - 求模长 diff --git a/docs/api/math/quaternion/operator-mul.md b/docs/api/math/quaternion/operator-mul.md new file mode 100644 index 00000000..79f7c071 --- /dev/null +++ b/docs/api/math/quaternion/operator-mul.md @@ -0,0 +1,40 @@ +# Quaternion::operator* + +```cpp +Quaternion operator*(const Quaternion& other) const; +Vector3 operator*(const Quaternion& q, const Vector3& v); +``` + +四元数乘法运算符。 + +**成员函数版本（四元数 * 四元数）：** +- `other` - 另一个四元数 +- **返回：** 组合旋转后的四元数 + +**全局函数版本（四元数 * 向量）：** +- `q` - 四元数 +- `v` - 要旋转的三维向量 +- **返回：** 旋转后的向量 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +Quaternion q1 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(90.0f)); +Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Right(), Math::Radians(90.0f)); + +Quaternion combined = q1 * q2; +Vector3 rotated = q1 * Vector3::Forward(); +``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 diff --git a/docs/api/math/quaternion/quaternion-multiply.md b/docs/api/math/quaternion/quaternion-multiply.md deleted file mode 100644 index 7dc4ebfb..00000000 --- a/docs/api/math/quaternion/quaternion-multiply.md +++ /dev/null @@ -1,23 +0,0 @@ -# Quaternion * Vector3 - -```cpp -Vector3 operator*(const Quaternion& q, const Vector3& v) -``` - -用四元数旋转向量。 - -**参数：** -- `q` - 旋转四元数 -- `v` - 要旋转的向量 - -**返回：** `Vector3` - 旋转后的向量 - -**复杂度：** O(1) - -**示例：** - -```cpp -Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); -Vector3 forward = Vector3::Forward(); -Vector3 rotated = rot * forward; -``` diff --git a/docs/api/math/quaternion/quaternion.md b/docs/api/math/quaternion/quaternion.md index 2b2fb1d8..fe429444 100644 --- a/docs/api/math/quaternion/quaternion.md +++ b/docs/api/math/quaternion/quaternion.md @@ -1,61 +1,72 @@ # Quaternion -四元数结构体，用于表示 3D 旋转，避免欧拉角的万向锁问题。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Quaternion.h` -## 结构体定义 +**描述**: 四元数，用于表示三维旋转 + +## 概述 + +Quaternion 提供了一套完整的三维旋转表示和操作方法。四元数可以避免欧拉角的万向节锁问题，并提供平滑的旋转插值（Slerp）。 + +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `x` | `float` | X 分量 | `0.0f` | +| `y` | `float` | Y 分量 | `0.0f` | +| `z` | `float` | Z 分量 | `0.0f` | +| `w` | `float` | W 分量（标量部分） | `1.0f` | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Identity`](identity.md) | 返回单位四元数 | +| [`FromAxisAngle`](from-axis-angle.md) | 从轴角创建四元数 | +| [`FromEulerAngles`](from-euler-angles.md) | 从欧拉角创建四元数 | +| [`FromRotationMatrix`](from-rotation-matrix.md) | 从旋转矩阵创建四元数 | +| [`Slerp`](slerp.md) | 球面线性插值 | +| [`LookRotation`](look-rotation.md) | 创建看向目标的旋转 | +| [`ToEulerAngles`](to-euler-angles.md) | 转换为欧拉角 | +| [`ToMatrix4x4`](to-matrix4x4.md) | 转换为 4x4 矩阵 | +| [`operator*`](operator-mul.md) | 四元数乘法 | +| [`Inverse`](inverse.md) | 求四元数逆 | +| [`Dot`](dot.md) | 点积 | +| [`Magnitude`](magnitude.md) | 求模长 | +| [`Normalized`](normalized.md) | 返回归一化四元数 | +| [`Normalize`](normalize.md) | 归一化四元数（静态） | + +## 使用示例 ```cpp -struct Quaternion { - float x = 0.0f; - float y = 0.0f; - float z = 0.0f; - float w = 1.0f; -}; +#include +#include +#include + +using namespace XCEngine::Math; + +// 从欧拉角创建 +Quaternion q1 = Quaternion::FromEulerAngles(0, Math::Radians(90.0f), 0); + +// 从轴角创建 +Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(45.0f)); + +// 组合旋转 +Quaternion combined = q1 * q2; + +// 旋转向量 +Vector3 rotated = q2 * Vector3::Forward(); + +// 球面插值 +Quaternion result = Quaternion::Slerp(q1, q2, 0.5f); ``` -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Identity()](identity.md) | `Quaternion` | 返回 (0, 0, 0, 1)，恒等旋转 | -| [FromAxisAngle(axis, radians)](fromaxisangle.md) | `Quaternion` | 从轴角创建 | -| [FromEulerAngles(pitch, yaw, roll)](fromeulerangles.md) | `Quaternion` | 从欧拉角创建（弧度） | -| [FromEulerAngles(euler)](fromeulerangles.md) | `Quaternion` | 从 Vector3 欧拉角创建 | -| [FromRotationMatrix(matrix)](fromrotationmatrix.md) | `Quaternion` | 从旋转矩阵创建 | -| [Slerp(a, b, t)](slerp.md) | `Quaternion` | 球面线性插值 | -| [LookRotation(forward, up)](lookrotation.md) | `Quaternion` | 看向方向 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [ToEulerAngles()](toeulerangles.md) | `Vector3` | 转换为欧拉角（弧度） | -| [ToMatrix4x4()](tomatrix4x4.md) | `Matrix4` | 转换为 4x4 旋转矩阵 | -| [Inverse()](inverse.md) | `Quaternion` | 共轭/逆四元数 | -| [Dot(other)](dot.md) | `float` | 点积 | -| [Magnitude()](magnitude.md) | `float` | 模长 | -| [Normalized()](normalized.md) | `Quaternion` | 归一化副本 | - -## 静态方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Normalize(q)](normalized.md) | `Quaternion` | 归一化四元数 | - -## 运算符 - -| 运算符 | 描述 | -|--------|------| -| `operator*(Quaternion, Quaternion)` | 组合旋转 | - -## 与 Vector3 的乘法 - -[Vector3 * Quaternion](quaternion-multiply.md) - 用四元数旋转向量 - ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Math 模块总览](../math.md) - Math 模块概览 +- [Vector3](../vector3/vector3.md) - 三维向量 +- [Matrix4](../matrix4/matrix4.md) - 4x4 矩阵 diff --git a/docs/api/math/quaternion/slerp.md b/docs/api/math/quaternion/slerp.md index a2e058fb..4532d426 100644 --- a/docs/api/math/quaternion/slerp.md +++ b/docs/api/math/quaternion/slerp.md @@ -1,22 +1,38 @@ # Quaternion::Slerp ```cpp -static Quaternion Slerp(const Quaternion& a, const Quaternion& b, float t) +static Quaternion Slerp(const Quaternion& a, const Quaternion& b, float t); ``` -在两个四元数之间进行球面线性插值。 +球面线性插值，在两个四元数之间进行平滑旋转插值。参数 t 会被 clamp 到 [0, 1] 范围。 **参数：** - `a` - 起始四元数 -- `b` - 结束四元数 -- `t` - 插值因子（0-1） +- `b` - 目标四元数 +- `t` - 插值参数 [0, 1]，0 返回 a，1 返回 b -**返回：** `Quaternion` - 插值结果 +**返回：** 插值结果四元数 + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -Quaternion lerped = Quaternion::Slerp(rot1, rot2, 0.5f); +#include +#include +#include + +using namespace XCEngine::Math; + +Quaternion q1 = Quaternion::FromAxisAngle(Vector3::Up(), 0); +Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(180.0f)); + +Quaternion result = Quaternion::Slerp(q1, q2, 0.5f); ``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [Normalized](normalized.md) - 归一化四元数 diff --git a/docs/api/math/quaternion/to-euler-angles.md b/docs/api/math/quaternion/to-euler-angles.md new file mode 100644 index 00000000..1231bc90 --- /dev/null +++ b/docs/api/math/quaternion/to-euler-angles.md @@ -0,0 +1,37 @@ +# Quaternion::ToEulerAngles + +```cpp +Vector3 ToEulerAngles() const; +``` + +将四元数转换为欧拉角。返回顺序为 (pitch, yaw, roll)，单位为弧度。 + +**返回：** 欧拉角向量 (pitch, yaw, roll)，单位为弧度 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include +#include + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::FromEulerAngles( + Math::Radians(45.0f), + Math::Radians(30.0f), + Math::Radians(60.0f) +); + +Vector3 euler = q.ToEulerAngles(); +// euler.x ≈ 45°, euler.y ≈ 30°, euler.z ≈ 60° +``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [FromEulerAngles](from-euler-angles.md) - 从欧拉角创建 diff --git a/docs/api/math/quaternion/to-matrix4x4.md b/docs/api/math/quaternion/to-matrix4x4.md new file mode 100644 index 00000000..947804ec --- /dev/null +++ b/docs/api/math/quaternion/to-matrix4x4.md @@ -0,0 +1,30 @@ +# Quaternion::ToMatrix4x4 + +```cpp +Matrix4x4 ToMatrix4x4() const; +``` + +将四元数转换为 4x4 旋转矩阵。 + +**返回：** 4x4 旋转矩阵 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +Quaternion q = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(90.0f)); +Matrix4 m = q.ToMatrix4x4(); +``` + +## 相关文档 + +- [Quaternion](quaternion.md) - 返回类总览 +- [FromRotationMatrix](from-rotation-matrix.md) - 从矩阵创建 diff --git a/docs/api/math/quaternion/toeulerangles.md b/docs/api/math/quaternion/toeulerangles.md deleted file mode 100644 index 13ba405d..00000000 --- a/docs/api/math/quaternion/toeulerangles.md +++ /dev/null @@ -1,18 +0,0 @@ -# Quaternion::ToEulerAngles - -```cpp -Vector3 ToEulerAngles() const -``` - -将四元数转换为欧拉角（弧度）。 - -**返回：** `Vector3` - 欧拉角 (pitch, yaw, roll) - -**复杂度：** O(1) - -**示例：** - -```cpp -Quaternion rot = ...; -Vector3 euler = rot.ToEulerAngles(); -``` diff --git a/docs/api/math/quaternion/tomatrix4x4.md b/docs/api/math/quaternion/tomatrix4x4.md deleted file mode 100644 index 1e98b7fa..00000000 --- a/docs/api/math/quaternion/tomatrix4x4.md +++ /dev/null @@ -1,18 +0,0 @@ -# Quaternion::ToMatrix4x4 - -```cpp -Matrix4x4 ToMatrix4x4() const -``` - -将四元数转换为 4x4 旋转矩阵。 - -**返回：** `Matrix4x4` - 旋转矩阵 - -**复杂度：** O(1) - -**示例：** - -```cpp -Quaternion rot = ...; -Matrix4 mat = rot.ToMatrix4x4(); -``` diff --git a/docs/api/math/ray/getpoint.md b/docs/api/math/ray/getpoint.md index 5860f771..029d4755 100644 --- a/docs/api/math/ray/getpoint.md +++ b/docs/api/math/ray/getpoint.md @@ -4,19 +4,29 @@ Vector3 GetPoint(float t) const ``` -获取射线上指定距离处的点。 +获取射线上指定参数距离处的点。计算公式：`origin + direction * t` **参数：** - `t` - 沿射线方向的参数距离 **返回：** `Vector3` - 射线上的点 `origin + direction * t` +**线程安全：** ✅ + **复杂度：** O(1) **示例：** ```cpp -Ray ray(cameraPosition, mouseRayDir.Normalized()); -float t = 100.0f; -Vector3 point = ray.GetPoint(t); // 沿射线方向 100 单位处的点 +#include +#include + +using namespace XCEngine::Math; + +Ray ray(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.0f, 0.0f)); +Vector3 point = ray.GetPoint(100.0f); // point = (100, 0, 0) ``` + +## 相关文档 + +- [Ray 类总览](ray.md) - 返回类总览 diff --git a/docs/api/math/ray/intersects-box.md b/docs/api/math/ray/intersects-box.md index 9a7fb9c3..1ef4c81e 100644 --- a/docs/api/math/ray/intersects-box.md +++ b/docs/api/math/ray/intersects-box.md @@ -4,24 +4,38 @@ bool Intersects(const Box& box, float& t) const ``` -检测射线是否与 OBB（有向包围盒）相交。 +检测射线是否与有向包围盒（OBB）相交。使用 slabs 方法计算交点。 **参数：** -- `box` - 要检测的 OBB 盒体 -- `t` - 输出交点的参数距离 +- `box` - 要检测的有向包围盒（OBB） +- `t` - 输出交点的参数距离（仅在返回 true 时有效） **返回：** `bool` - 相交返回 true，否则返回 false +**线程安全：** ✅ + **复杂度：** O(1) +**异常：** 无 + **示例：** ```cpp -Ray ray(cameraPosition, rayDirection); -Box colliderBox = object.GetWorldBox(); +#include +#include +#include + +using namespace XCEngine::Math; + +Ray ray(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.0f, 0.0f)); +Box box(Vector3(10.0f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f)); float t; -if (ray.Intersects(colliderBox, t)) { +if (ray.Intersects(box, t)) { Vector3 hitPoint = ray.GetPoint(t); - // 处理命中 } ``` + +## 相关文档 + +- [Ray 类总览](ray.md) - 返回类总览 +- [Box](../box/box.md) - 包围盒类型 diff --git a/docs/api/math/ray/intersects-plane.md b/docs/api/math/ray/intersects-plane.md index 9a2a91ee..13d79ba0 100644 --- a/docs/api/math/ray/intersects-plane.md +++ b/docs/api/math/ray/intersects-plane.md @@ -4,24 +4,38 @@ bool Intersects(const Plane& plane, float& t) const ``` -检测射线是否与平面相交。 +检测射线是否与平面相交。通过计算射线与平面法线的点积判断平行，通过求交公式计算交点。 **参数：** - `plane` - 要检测的平面 -- `t` - 输出交点的参数距离 +- `t` - 输出交点的参数距离（仅在返回 true 时有效） -**返回：** `bool` - 相交返回 true（射线朝向平面），否则返回 false +**返回：** `bool` - 相交返回 true（t >= 0），否则返回 false + +**线程安全：** ✅ **复杂度：** O(1) +**异常：** 无 + **示例：** ```cpp -Ray ray(cameraPosition, rayDirection); -Plane groundPlane = Plane::FromNormalAndPoint(Vector3::Up(), Vector3::Zero()); +#include +#include +#include + +using namespace XCEngine::Math; + +Ray ray(Vector3(0.0f, 1.0f, 0.0f), Vector3(0.0f, -1.0f, 0.0f)); +Plane groundPlane(Vector3(0.0f, 1.0f, 0.0f), 0.0f); float t; if (ray.Intersects(groundPlane, t)) { Vector3 hitPoint = ray.GetPoint(t); - // 射线命中地面 } ``` + +## 相关文档 + +- [Ray 类总览](ray.md) - 返回类总览 +- [Plane](../plane/plane.md) - 平面类型 diff --git a/docs/api/math/ray/intersects-sphere.md b/docs/api/math/ray/intersects-sphere.md index 400624c6..886549e7 100644 --- a/docs/api/math/ray/intersects-sphere.md +++ b/docs/api/math/ray/intersects-sphere.md @@ -4,23 +4,38 @@ bool Intersects(const Sphere& sphere, float& t) const ``` -检测射线是否与球体相交。 +检测射线是否与球体相交。使用二次方程求根法计算交点。 **参数：** - `sphere` - 要检测的球体 -- `t` - 输出最近交点的参数距离 +- `t` - 输出最近交点的参数距离（仅在返回 true 时有效，若射线在球体内部则输出最近的出口点） **返回：** `bool` - 相交返回 true，否则返回 false +**线程安全：** ✅ + **复杂度：** O(1) +**异常：** 无 + **示例：** ```cpp -Ray ray(cameraPosition, rayDirection); +#include +#include +#include + +using namespace XCEngine::Math; + +Ray ray(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.0f, 0.0f)); +Sphere sphere(Vector3(10.0f, 0.0f, 0.0f), 1.0f); float t; if (ray.Intersects(sphere, t)) { Vector3 hitPoint = ray.GetPoint(t); - // 处理命中 } ``` + +## 相关文档 + +- [Ray 类总览](ray.md) - 返回类总览 +- [Sphere](../sphere/sphere.md) - 球体类型 diff --git a/docs/api/math/ray/ray-constructor-default.md b/docs/api/math/ray/ray-constructor-default.md new file mode 100644 index 00000000..424fc958 --- /dev/null +++ b/docs/api/math/ray/ray-constructor-default.md @@ -0,0 +1,27 @@ +# Ray::Ray (默认构造函数) + +```cpp +Ray() = default +``` + +默认构造函数，使用默认方式构造射线。 + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +using namespace XCEngine::Math; + +Ray ray; // 未初始化状态 +``` + +## 相关文档 + +- [Ray 类总览](ray.md) - 返回类总览 diff --git a/docs/api/math/ray/ray-constructor.md b/docs/api/math/ray/ray-constructor.md new file mode 100644 index 00000000..b7999553 --- /dev/null +++ b/docs/api/math/ray/ray-constructor.md @@ -0,0 +1,33 @@ +# Ray::Ray (构造函数) + +```cpp +Ray(const Vector3& origin, const Vector3& direction) +``` + +从起点和方向构造射线。 + +**参数：** +- `origin` - 射线起点 +- `direction` - 射线方向（构造时会被归一化） + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +Ray ray(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.0f, 0.0f)); +// direction 已被归一化 +``` + +## 相关文档 + +- [Ray 类总览](ray.md) - 返回类总览 diff --git a/docs/api/math/ray/ray.md b/docs/api/math/ray/ray.md index 969d10e3..e114f5ec 100644 --- a/docs/api/math/ray/ray.md +++ b/docs/api/math/ray/ray.md @@ -1,44 +1,60 @@ # Ray -3D 射线结构体，用于光线投射和拾取。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Ray.h` -## 结构体定义 +**描述**: 射线，用于 3D 拾取和光线追踪 -```cpp -struct Ray { - Vector3 origin; // 射线起点 - Vector3 direction; // 归一化方向 +## 概述 - Ray() = default; - Ray(const Vector3& origin, const Vector3& direction); +`Ray` 表示从原点出发沿特定方向延伸的无限射线。通过 `direction` 方向的归一化，确保射线方向向量为单位长度，支持精确的交点计算。广泛应用于光线追踪、碰撞拾取和视锥体裁剪等图形学场景。 - Vector3 GetPoint(float t) const; - bool Intersects(const Sphere& sphere, float& t) const; - bool Intersects(const Box& box, float& t) const; - bool Intersects(const Plane& plane, float& t) const; -}; -``` +**注意**：构造时 `direction` 会被自动归一化。 -## 构造函数 +## 结构体成员 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `origin` | `Vector3` | 射线起点 | +| `direction` | `Vector3` | 射线方向（归一化） | + +## 公共方法 | 方法 | 描述 | |------|------| -| `Ray()` | 默认构造 | -| `Ray(origin, direction)` | 从起点和方向构造 | +| [`Ray()`](ray-constructor-default.md) | 默认构造函数 | +| [`Ray(origin, direction)`](ray-constructor.md) | 从起点和方向构造（direction 会被自动归一化） | +| [`GetPoint`](getpoint.md) | 获取射线上 t 距离处的点 | +| [`Intersects`](intersects-sphere.md) | 与球体相交检测 | +| [`Intersects`](intersects-box.md) | 与有向包围盒相交检测 | +| [`Intersects`](intersects-plane.md) | 与平面相交检测 | -## 实例方法 +## 使用示例 -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [GetPoint(t)](getpoint.md) | `Vector3` | 获取射线上 t 距离处的点 | -| [Intersects(sphere, t)](intersects-sphere.md) | `bool` | 与球体相交，输出距离 t | -| [Intersects(box, t)](intersects-box.md) | `bool` | 与 OBB 相交，输出距离 t | -| [Intersects(plane, t)](intersects-plane.md) | `bool` | 与平面相交，输出距离 t | +```cpp +#include +#include +#include + +using namespace XCEngine::Math; + +Ray ray(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.0f, 0.0f)); +Vector3 point = ray.GetPoint(5.0f); // point = (5, 0, 0) + +Sphere sphere(Vector3(10.0f, 0.0f, 0.0f), 1.0f); +float t; +if (ray.Intersects(sphere, t)) { + Vector3 hitPoint = ray.GetPoint(t); +} +``` ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Math 模块总览](../math.md) - Math 模块总览 +- [Vector3](../vector3/vector3.md) - 方向和点类型 +- [Sphere](../sphere/sphere.md) - 球体类型 +- [Box](../box/box.md) - 包围盒类型 +- [Plane](../plane/plane.md) - 平面类型 diff --git a/docs/api/math/rect/contains-float.md b/docs/api/math/rect/contains-float.md index f6e14885..74a5f3c8 100644 --- a/docs/api/math/rect/contains-float.md +++ b/docs/api/math/rect/contains-float.md @@ -10,7 +10,7 @@ bool Contains(float px, float py) const - `px` - 点的 x 坐标 - `py` - 点的 y 坐标 -**返回：** `bool` - 点在矩形内（包含边界）返回 true +**返回：** `bool` - 点在矩形内（左上边界包含，右下边界不含）返回 true **复杂度：** O(1) diff --git a/docs/api/math/rect/contains-vector2.md b/docs/api/math/rect/contains-vector2.md index 69367899..cb17ba19 100644 --- a/docs/api/math/rect/contains-vector2.md +++ b/docs/api/math/rect/contains-vector2.md @@ -9,7 +9,7 @@ bool Contains(const Vector2& point) const **参数：** - `point` - 要检测的二维点 -**返回：** `bool` - 点在矩形内（包含边界）返回 true +**返回：** `bool` - 点在矩形内（左上边界包含，右下边界不含）返回 true **复杂度：** O(1) diff --git a/docs/api/math/rect/contains.md b/docs/api/math/rect/contains.md new file mode 100644 index 00000000..a49f722e --- /dev/null +++ b/docs/api/math/rect/contains.md @@ -0,0 +1,50 @@ +# Rect::Contains + +判断点是否在矩形内部。 + +```cpp +bool Contains(float px, float py) const; +bool Contains(const Vector2& point) const; +``` + +矩形使用左上位坐标系，内部定义为：x >= left && x < right && y >= top && y < bottom。即左边界和上边界在内部，右边界和下边界在外部。 + +**参数：** +- `px` - 点的 x 坐标 +- `py` - 点的 y 坐标 +- `point` - 要判断的点（Vector2 类型） + +**返回：** 点在矩形内部返回 true，否则返回 false + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + Rect rect(10.0f, 20.0f, 100.0f, 50.0f); + + if (rect.Contains(50.0f, 30.0f)) { + std::cout << "Point (50, 30) is inside\n"; + } + + Vector2 point(150.0f, 100.0f); + if (!rect.Contains(point)) { + std::cout << "Point (150, 100) is outside\n"; + } + + return 0; +} +``` + +## 相关文档 + +- [`Rect::Intersects`](intersects.md) - 判断是否相交 +- [Rect 总览](rect.md) \ No newline at end of file diff --git a/docs/api/math/rect/rect.md b/docs/api/math/rect/rect.md index 055eacec..0c0f9806 100644 --- a/docs/api/math/rect/rect.md +++ b/docs/api/math/rect/rect.md @@ -1,17 +1,81 @@ -# Rect / RectInt / Viewport +# Rect -2D 矩形和视口结构体。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Rect.h` -## 目录 +**描述**: 二维矩形，用于表示平面上的矩形区域 -- [Rect](rect.md) - 浮点矩形 -- [RectInt](rectint.md) - 整数矩形 -- [Viewport](viewport.md) - 渲染视口 +## 概述 + +Rect 结构体表示一个二维矩形，由位置 `(x, y)` 和尺寸 `(width, height)` 组成。矩形使用左上位坐标系，x 向右增加，y 向下增加。 + +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `x` | `float` | 矩形左上角 X 坐标 | `0.0f` | +| `y` | `float` | 矩形左上角 Y 坐标 | `0.0f` | +| `width` | `float` | 矩形宽度 | `0.0f` | +| `height` | `float` | 矩形高度 | `0.0f` | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`GetLeft`](getleft.md) | 获取矩形左边界 | +| [`GetRight`](getright.md) | 获取矩形右边界 | +| [`GetTop`](gettop.md) | 获取矩形上边界 | +| [`GetBottom`](getbottom.md) | 获取矩形下边界 | +| [`GetPosition`](getposition.md) | 获取矩形位置 | +| [`GetSize`](getsize.md) | 获取矩形尺寸 | +| [`GetCenter`](getcenter.md) | 获取矩形中心点 | +| [`Contains`](contains.md) | 判断点是否在矩形内 | +| [`Intersects`](intersects.md) | 判断是否与另一矩形相交 | +| [`Intersect`](intersect.md) | 计算两矩形交集（静态方法） | +| [`Union`](union.md) | 计算两矩形并集（静态方法） | +| [`Set`](set.md) | 设置矩形所有属性 | +| [`SetPosition`](setposition.md) | 设置矩形位置 | + +## 使用示例 + +```cpp +#include "XCEngine/Math/Rect.h" +#include "XCEngine/Math/Vector2.h" +#include + +using namespace XCEngine::Math; + +int main() { + Rect rect(10.0f, 20.0f, 100.0f, 50.0f); + + std::cout << "Position: (" << rect.x << ", " << rect.y << ")\n"; + std::cout << "Size: " << rect.width << " x " << rect.height << "\n"; + std::cout << "Left: " << rect.GetLeft() << ", Right: " << rect.GetRight() << "\n"; + std::cout << "Top: " << rect.GetTop() << ", Bottom: " << rect.GetBottom() << "\n"; + std::cout << "Center: (" << rect.GetCenter().x << ", " << rect.GetCenter().y << ")\n"; + + Vector2 point(50.0f, 30.0f); + if (rect.Contains(point)) { + std::cout << "Point is inside rect\n"; + } + + Rect other(60.0f, 40.0f, 100.0f, 50.0f); + if (rect.Intersects(other)) { + std::cout << "Rects intersect\n"; + } + + Rect intersection = Rect::Intersect(rect, other); + std::cout << "Intersection: " << intersection.width << " x " << intersection.height << "\n"; + + return 0; +} +``` ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [`RectInt`](rectint.md) - 整数矩形 +- [`Viewport`](viewport.md) - 视口 +- [`Vector2`](../vector2/vector2.md) - 二维向量 \ No newline at end of file diff --git a/docs/api/math/rect/setposition.md b/docs/api/math/rect/setposition.md new file mode 100644 index 00000000..73253cf4 --- /dev/null +++ b/docs/api/math/rect/setposition.md @@ -0,0 +1,47 @@ +# Rect::SetPosition + +设置矩形位置。 + +```cpp +void SetPosition(float newX, float newY); +void SetPosition(const Vector2& position); +``` + +**参数：** +- `newX` - 新的 x 坐标 +- `newY` - 新的 y 坐标 +- `position` - 新的位置（Vector2 类型） + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include "XCEngine/Math/Vector2.h" +#include + +using namespace XCEngine::Math; + +int main() { + Rect rect(0.0f, 0.0f, 100.0f, 50.0f); + + rect.SetPosition(10.0f, 20.0f); + std::cout << "Position: (" << rect.x << ", " << rect.y << ")\n"; + + rect.SetPosition(Vector2(50.0f, 60.0f)); + std::cout << "Position: (" << rect.x << ", " << rect.y << ")\n"; + + return 0; +} +``` + +## 相关文档 + +- [`Rect::Set`](set.md) - 设置所有属性 +- [`Rect::GetPosition`](getposition.md) - 获取位置 +- [Rect 总览](rect.md) \ No newline at end of file diff --git a/docs/api/math/rect/viewport.md b/docs/api/math/rect/viewport.md index b3a45e0c..523654ce 100644 --- a/docs/api/math/rect/viewport.md +++ b/docs/api/math/rect/viewport.md @@ -40,6 +40,6 @@ struct Viewport { ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Rect 模块总览 +- [Math 模块总览](../math.md) - 返回 Math 模块总览 - [Rect](rect-overview.md) - 浮点矩形 - [RectInt](rectint.md) - 整数矩形 diff --git a/docs/api/math/rectint/contains.md b/docs/api/math/rectint/contains.md new file mode 100644 index 00000000..0b49dbbe --- /dev/null +++ b/docs/api/math/rectint/contains.md @@ -0,0 +1,47 @@ +# RectInt::Contains + +```cpp +bool Contains(int32_t px, int32_t py) const; +``` + +判断整数坐标点是否在矩形内部。 + +矩形使用左上位坐标系，内部定义为：x >= left && x < right && y >= top && y < bottom。即左边界和上边界在内部，右边界和下边界在外部。 + +**参数：** +- `px` - 点的 x 坐标 +- `py` - 点的 y 坐标 + +**返回：** 点在矩形内部返回 true，否则返回 false + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(0, 0, 1920, 1080); + + if (rect.Contains(960, 540)) { + std::cout << "Point (960, 540) is inside\n"; + } + + if (!rect.Contains(2000, 1000)) { + std::cout << "Point (2000, 1000) is outside\n"; + } + + return 0; +} +``` + +## 相关文档 + +- [`RectInt::Intersects`](intersects.md) - 判断是否相交 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/getbottom.md b/docs/api/math/rectint/getbottom.md new file mode 100644 index 00000000..abc1eeab --- /dev/null +++ b/docs/api/math/rectint/getbottom.md @@ -0,0 +1,36 @@ +# RectInt::GetBottom + +```cpp +int32_t GetBottom() const; +``` + +获取矩形下边界 y 坐标。 + +**返回：** 矩形下边界 y 坐标（等于 y + height） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(10, 20, 100, 50); + int32_t bottom = rect.GetBottom(); + std::cout << "Bottom: " << bottom << "\n"; + return 0; +} +``` + +## 相关文档 + +- [`RectInt::GetLeft`](getleft.md) - 获取左边界 +- [`RectInt::GetRight`](getright.md) - 获取右边界 +- [`RectInt::GetTop`](gettop.md) - 获取上边界 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/getcenter.md b/docs/api/math/rectint/getcenter.md new file mode 100644 index 00000000..d3b650de --- /dev/null +++ b/docs/api/math/rectint/getcenter.md @@ -0,0 +1,35 @@ +# RectInt::GetCenter + +```cpp +Vector2 GetCenter() const; +``` + +获取矩形中心点坐标。 + +**返回：** 表示矩形中心点的 Vector2（转换为浮点） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(10, 20, 100, 50); + Vector2 center = rect.GetCenter(); + std::cout << "Center: (" << center.x << ", " << center.y << ")\n"; + return 0; +} +``` + +## 相关文档 + +- [`RectInt::GetPosition`](getposition.md) - 获取位置 +- [`RectInt::GetSize`](getsize.md) - 获取尺寸 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/getleft.md b/docs/api/math/rectint/getleft.md new file mode 100644 index 00000000..6e2a5350 --- /dev/null +++ b/docs/api/math/rectint/getleft.md @@ -0,0 +1,36 @@ +# RectInt::GetLeft + +```cpp +int32_t GetLeft() const; +``` + +获取矩形左边界 x 坐标。 + +**返回：** 矩形左边界 x 坐标（等于 x 成员变量） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(10, 20, 100, 50); + int32_t left = rect.GetLeft(); + std::cout << "Left: " << left << "\n"; + return 0; +} +``` + +## 相关文档 + +- [`RectInt::GetRight`](getright.md) - 获取右边界 +- [`RectInt::GetTop`](gettop.md) - 获取上边界 +- [`RectInt::GetBottom`](getbottom.md) - 获取下边界 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/getposition.md b/docs/api/math/rectint/getposition.md new file mode 100644 index 00000000..9a901844 --- /dev/null +++ b/docs/api/math/rectint/getposition.md @@ -0,0 +1,35 @@ +# RectInt::GetPosition + +```cpp +Vector2 GetPosition() const; +``` + +获取矩形位置（x, y 坐标）。 + +**返回：** 表示矩形位置的 Vector2（转换为浮点） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(10, 20, 100, 50); + Vector2 pos = rect.GetPosition(); + std::cout << "Position: (" << pos.x << ", " << pos.y << ")\n"; + return 0; +} +``` + +## 相关文档 + +- [`RectInt::GetSize`](getsize.md) - 获取尺寸 +- [`RectInt::GetCenter`](getcenter.md) - 获取中心点 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/getright.md b/docs/api/math/rectint/getright.md new file mode 100644 index 00000000..1b71436f --- /dev/null +++ b/docs/api/math/rectint/getright.md @@ -0,0 +1,36 @@ +# RectInt::GetRight + +```cpp +int32_t GetRight() const; +``` + +获取矩形右边界 x 坐标。 + +**返回：** 矩形右边界 x 坐标（等于 x + width） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(10, 20, 100, 50); + int32_t right = rect.GetRight(); + std::cout << "Right: " << right << "\n"; + return 0; +} +``` + +## 相关文档 + +- [`RectInt::GetLeft`](getleft.md) - 获取左边界 +- [`RectInt::GetTop`](gettop.md) - 获取上边界 +- [`RectInt::GetBottom`](getbottom.md) - 获取下边界 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/getsize.md b/docs/api/math/rectint/getsize.md new file mode 100644 index 00000000..c1a1327f --- /dev/null +++ b/docs/api/math/rectint/getsize.md @@ -0,0 +1,35 @@ +# RectInt::GetSize + +```cpp +Vector2 GetSize() const; +``` + +获取矩形尺寸（width, height）。 + +**返回：** 表示矩形尺寸的 Vector2（转换为浮点） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(10, 20, 100, 50); + Vector2 size = rect.GetSize(); + std::cout << "Size: (" << size.x << ", " << size.y << ")\n"; + return 0; +} +``` + +## 相关文档 + +- [`RectInt::GetPosition`](getposition.md) - 获取位置 +- [`RectInt::GetCenter`](getcenter.md) - 获取中心点 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/gettop.md b/docs/api/math/rectint/gettop.md new file mode 100644 index 00000000..e0b85812 --- /dev/null +++ b/docs/api/math/rectint/gettop.md @@ -0,0 +1,36 @@ +# RectInt::GetTop + +```cpp +int32_t GetTop() const; +``` + +获取矩形上边界 y 坐标。 + +**返回：** 矩形上边界 y 坐标（等于 y 成员变量） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(10, 20, 100, 50); + int32_t top = rect.GetTop(); + std::cout << "Top: " << top << "\n"; + return 0; +} +``` + +## 相关文档 + +- [`RectInt::GetLeft`](getleft.md) - 获取左边界 +- [`RectInt::GetRight`](getright.md) - 获取右边界 +- [`RectInt::GetBottom`](getbottom.md) - 获取下边界 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/intersects.md b/docs/api/math/rectint/intersects.md new file mode 100644 index 00000000..de4eb70d --- /dev/null +++ b/docs/api/math/rectint/intersects.md @@ -0,0 +1,48 @@ +# RectInt::Intersects + +```cpp +bool Intersects(const RectInt& other) const; +``` + +判断此矩形是否与另一矩形相交。 + +使用 AABB（轴对齐包围盒）碰撞检测算法。如果两个矩形在 x 轴和 y 轴上都有重叠，则返回 true。 + +**参数：** +- `other` - 另一个矩形 + +**返回：** 两矩形相交返回 true，否则返回 false + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rectA(0, 0, 100, 100); + RectInt rectB(50, 50, 100, 100); + + if (rectA.Intersects(rectB)) { + std::cout << "Rects intersect\n"; + } + + RectInt rectC(200, 200, 50, 50); + if (!rectA.Intersects(rectC)) { + std::cout << "Rects do not intersect\n"; + } + + return 0; +} +``` + +## 相关文档 + +- [`RectInt::Contains`](contains.md) - 判断点是否在矩形内 +- [RectInt 总览](rectint.md) \ No newline at end of file diff --git a/docs/api/math/rectint/rectint.md b/docs/api/math/rectint/rectint.md new file mode 100644 index 00000000..4dbfe6aa --- /dev/null +++ b/docs/api/math/rectint/rectint.md @@ -0,0 +1,63 @@ +# RectInt + +**命名空间**: `XCEngine::Math` + +**类型**: `struct` + +**头文件**: `XCEngine/Math/Rect.h` + +**描述**: 二维整数矩形，用于表示像素级 2D 区域 + +## 概述 + +RectInt 结构体表示一个二维整数矩形，由整数位置 `(x, y)` 和尺寸 `(width, height)` 组成。与 Rect 不同，它使用 `int32_t` 类型，适合像素级操作和坐标计算。 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`GetLeft`](getleft.md) | 获取矩形左边界 | +| [`GetRight`](getright.md) | 获取矩形右边界 | +| [`GetTop`](gettop.md) | 获取矩形上边界 | +| [`GetBottom`](getbottom.md) | 获取矩形下边界 | +| [`GetPosition`](getposition.md) | 获取矩形位置 | +| [`GetSize`](getsize.md) | 获取矩形尺寸 | +| [`GetCenter`](getcenter.md) | 获取矩形中心点 | +| [`Contains`](contains.md) | 判断点是否在矩形内 | +| [`Intersects`](intersects.md) | 判断是否与另一矩形相交 | + +## 使用示例 + +```cpp +#include "XCEngine/Math/Rect.h" +#include "XCEngine/Math/Vector2.h" +#include + +using namespace XCEngine::Math; + +int main() { + RectInt rect(10, 20, 100, 50); + + std::cout << "Position: (" << rect.x << ", " << rect.y << ")\n"; + std::cout << "Size: " << rect.width << " x " << rect.height << "\n"; + std::cout << "Left: " << rect.GetLeft() << ", Right: " << rect.GetRight() << "\n"; + std::cout << "Top: " << rect.GetTop() << ", Bottom: " << rect.GetBottom() << "\n"; + + if (rect.Contains(50, 30)) { + std::cout << "Point (50, 30) is inside rect\n"; + } + + RectInt other(60, 40, 100, 50); + if (rect.Intersects(other)) { + std::cout << "Rects intersect\n"; + } + + return 0; +} +``` + +## 相关文档 + +- [`Rect`](../rect/rect.md) - 浮点矩形 +- [`Viewport`](../rect/viewport.md) - 视口 +- [`Vector2`](../vector2/vector2.md) - 二维向量 \ No newline at end of file diff --git a/docs/api/math/sphere/contains.md b/docs/api/math/sphere/contains.md index 6e69e32e..50a98680 100644 --- a/docs/api/math/sphere/contains.md +++ b/docs/api/math/sphere/contains.md @@ -4,17 +4,37 @@ bool Contains(const Vector3& point) const ``` -检测点是否在球体内（包括表面）。 +检测点是否在球体内（包括球体表面）。使用平方距离比较避免开平方运算。 **参数：** - `point` - 要检测的点 -**返回：** `bool` - true 表示点在球体内 +**返回：** `bool` - true 表示点在球体内（包括表面） + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (sphere.Contains(point)) { /* point inside */ } +#include +#include + +using namespace XCEngine::Math; + +Sphere sphere(Vector3(0.0f, 0.0f, 0.0f), 1.0f); + +Vector3 inside(0.5f, 0.0f, 0.0f); +if (sphere.Contains(inside)) { +} + +Vector3 outside(2.0f, 0.0f, 0.0f); +if (!sphere.Contains(outside)) { +} ``` + +## 相关文档 + +- [Sphere](sphere.md) - 返回类总览 +- [Intersects](intersects.md) - 球体相交检测 diff --git a/docs/api/math/sphere/intersects.md b/docs/api/math/sphere/intersects.md index d3d5ad57..5f255a12 100644 --- a/docs/api/math/sphere/intersects.md +++ b/docs/api/math/sphere/intersects.md @@ -4,17 +4,33 @@ bool Intersects(const Sphere& other) const ``` -检测两个球体是否相交。 +检测两个球体是否相交。相切（外切或内切）也视为相交。使用平方距离比较避免开平方运算。 **参数：** - `other` - 另一个球体 -**返回：** `bool` - true 表示相交 +**返回：** `bool` - true 表示相交（包括相切） + +**线程安全：** ✅ **复杂度：** O(1) **示例：** ```cpp -if (sphere.Intersects(other)) { /* collision */ } +#include +#include + +using namespace XCEngine::Math; + +Sphere sphere1(Vector3(0.0f, 0.0f, 0.0f), 1.0f); +Sphere sphere2(Vector3(1.5f, 0.0f, 0.0f), 1.0f); + +if (sphere1.Intersects(sphere2)) { +} ``` + +## 相关文档 + +- [Sphere](sphere.md) - 返回类总览 +- [Contains](contains.md) - 点包含检测 diff --git a/docs/api/math/sphere/sphere.md b/docs/api/math/sphere/sphere.md index b0bd94c1..3761dc2b 100644 --- a/docs/api/math/sphere/sphere.md +++ b/docs/api/math/sphere/sphere.md @@ -1,32 +1,54 @@ # Sphere -3D 球体结构体。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Sphere.h` -## 结构体定义 +**描述**: 球体，用于碰撞检测和范围查询 + +## 概述 + +`Sphere` 是三维空间中的球体结构体，包含一个中心点 `center` 和半径 `radius`。主要用于碰撞检测和范围查询等几何计算场景。 + +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `center` | `Vector3` | 球体中心点 | `Vector3::Zero()` | +| `radius` | `float` | 球体半径 | `0.0f` | + +## 公共方法 + +| 方法 | 描述 | 线程安全 | 复杂度 | +|------|------|----------|--------| +| [`Sphere()`](sphere_default_constructor.md) | 默认构造，零初始化 | ✅ | O(1) | +| [`Sphere(const Vector3&, float)`](sphere_constructor.md) | 从中心和半径构造球体 | ✅ | O(1) | +| [`Contains`](contains.md) | 检测点是否在球体内 | ✅ | O(1) | +| [`Intersects`](intersects.md) | 检测两个球体是否相交 | ✅ | O(1) | + +## 使用示例 ```cpp -struct Sphere { - Vector3 center = Vector3::Zero(); - float radius = 0.0f; -}; +#include +#include + +using namespace XCEngine::Math; + +Sphere sphere(Vector3(0.0f, 0.0f, 0.0f), 1.0f); + +Vector3 point(0.5f, 0.5f, 0.0f); +if (sphere.Contains(point)) { + // point is inside the sphere +} + +Sphere other(Vector3(1.5f, 0.0f, 0.0f), 1.0f); +if (sphere.Intersects(other)) { + // spheres intersect +} ``` -## 构造函数 - -- `Sphere()` - 默认构造 -- `Sphere(const Vector3& center, float radius)` - 从中心和半径构造 - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Contains(point)](contains.md) | `bool` | 点是否在球体内 | -| [Intersects(other)](intersects.md) | `bool` | 与另一个球体相交 | - ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Math 模块总览](../math.md) - Math 模块总览 diff --git a/docs/api/math/sphere/sphere_constructor.md b/docs/api/math/sphere/sphere_constructor.md new file mode 100644 index 00000000..7e3302e9 --- /dev/null +++ b/docs/api/math/sphere/sphere_constructor.md @@ -0,0 +1,32 @@ +# Sphere::Sphere + +```cpp +Sphere(const Vector3& center, float radius) +``` + +构造一个指定中心和半径的球体。 + +**参数：** +- `center` - 球体中心点 +- `radius` - 球体半径 + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +Sphere sphere(Vector3(1.0f, 2.0f, 3.0f), 5.0f); +``` + +## 相关文档 + +- [Sphere](sphere.md) - 返回类总览 diff --git a/docs/api/math/sphere/sphere_default_constructor.md b/docs/api/math/sphere/sphere_default_constructor.md new file mode 100644 index 00000000..1a442afb --- /dev/null +++ b/docs/api/math/sphere/sphere_default_constructor.md @@ -0,0 +1,28 @@ +# Sphere::Sphere + +```cpp +Sphere() +``` + +默认构造函数，使用零初始化 center 为原点，radius 为 0。 + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +using namespace XCEngine::Math; + +Sphere sphere; +``` + +## 相关文档 + +- [Sphere](sphere.md) - 返回类总览 diff --git a/docs/api/math/transform/inverse-transform-direction.md b/docs/api/math/transform/inverse-transform-direction.md new file mode 100644 index 00000000..d29bd8f6 --- /dev/null +++ b/docs/api/math/transform/inverse-transform-direction.md @@ -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) - 正向变换方向 diff --git a/docs/api/math/transform/inverse-transform-point.md b/docs/api/math/transform/inverse-transform-point.md new file mode 100644 index 00000000..0b25cf70 --- /dev/null +++ b/docs/api/math/transform/inverse-transform-point.md @@ -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) - 正向变换点 diff --git a/docs/api/math/transform/inverse.md b/docs/api/math/transform/inverse.md index 8b4de547..1a03da5a 100644 --- a/docs/api/math/transform/inverse.md +++ b/docs/api/math/transform/inverse.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) - 返回类总览 diff --git a/docs/api/math/transform/inversetransformdirection.md b/docs/api/math/transform/inversetransformdirection.md deleted file mode 100644 index 38968c1c..00000000 --- a/docs/api/math/transform/inversetransformdirection.md +++ /dev/null @@ -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); -``` diff --git a/docs/api/math/transform/inversetransformpoint.md b/docs/api/math/transform/inversetransformpoint.md deleted file mode 100644 index 733b1738..00000000 --- a/docs/api/math/transform/inversetransformpoint.md +++ /dev/null @@ -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); -``` diff --git a/docs/api/math/transform/operator-star.md b/docs/api/math/transform/operator-star.md new file mode 100644 index 00000000..28a935be --- /dev/null +++ b/docs/api/math/transform/operator-star.md @@ -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) - 返回类总览 diff --git a/docs/api/math/transform/to-matrix.md b/docs/api/math/transform/to-matrix.md new file mode 100644 index 00000000..95ca6ea6 --- /dev/null +++ b/docs/api/math/transform/to-matrix.md @@ -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) - 返回类总览 diff --git a/docs/api/math/transform/tomatrix.md b/docs/api/math/transform/tomatrix.md deleted file mode 100644 index cfa9edde..00000000 --- a/docs/api/math/transform/tomatrix.md +++ /dev/null @@ -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(); -``` diff --git a/docs/api/math/transform/transform-direction.md b/docs/api/math/transform/transform-direction.md new file mode 100644 index 00000000..fba8495e --- /dev/null +++ b/docs/api/math/transform/transform-direction.md @@ -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) - 变换点 diff --git a/docs/api/math/transform/transform-point.md b/docs/api/math/transform/transform-point.md new file mode 100644 index 00000000..a0e32fc9 --- /dev/null +++ b/docs/api/math/transform/transform-point.md @@ -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) - 变换方向 diff --git a/docs/api/math/transform/transform.md b/docs/api/math/transform/transform.md index ab3f9ff6..63546ebd 100644 --- a/docs/api/math/transform/transform.md +++ b/docs/api/math/transform/transform.md @@ -1,39 +1,71 @@ # Transform -3D 变换结构体，包含位置、旋转和缩放，用于层次化变换。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `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 矩阵 diff --git a/docs/api/math/transform/transformdirection.md b/docs/api/math/transform/transformdirection.md deleted file mode 100644 index e371d00c..00000000 --- a/docs/api/math/transform/transformdirection.md +++ /dev/null @@ -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); -``` diff --git a/docs/api/math/transform/transformpoint.md b/docs/api/math/transform/transformpoint.md deleted file mode 100644 index 46d9ec10..00000000 --- a/docs/api/math/transform/transformpoint.md +++ /dev/null @@ -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); -``` diff --git a/docs/api/math/vector2/cross.md b/docs/api/math/vector2/cross.md index 779916fb..f1e8aa9d 100644 --- a/docs/api/math/vector2/cross.md +++ b/docs/api/math/vector2/cross.md @@ -4,7 +4,7 @@ static float Cross(const Vector2& a, const Vector2& b) ``` -计算两个 2D 向量的叉积（返回标量）。结果为正值表示 b 在 a 的逆时针方向。 +计算两个 2D 向量的叉积（返回标量）。结果为正值表示 b 在 a 的逆时针方向，负值表示 b 在 a 的顺时针方向。 **参数：** - `a` - 第一个向量 @@ -12,6 +12,10 @@ static float Cross(const Vector2& a, const Vector2& b) **返回：** `float` - 叉积结果 a.x * b.y - a.y * b.x +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -21,3 +25,8 @@ Vector2 a(1.0f, 0.0f); Vector2 b(0.0f, 1.0f); float cross = Vector2::Cross(a, b); // 1.0f (逆时针) ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 +- [Dot](Dot.md) - 点积运算 diff --git a/docs/api/math/vector2/dot.md b/docs/api/math/vector2/dot.md index d2159f50..b128ddc2 100644 --- a/docs/api/math/vector2/dot.md +++ b/docs/api/math/vector2/dot.md @@ -4,7 +4,7 @@ static float Dot(const Vector2& a, const Vector2& b) ``` -计算两个 2D 向量的点积。 +计算两个 2D 向量的点积。点积结果可用于判断两个向量的方向关系：正值表示夹角小于 90°，零表示垂直，负值表示夹角大于 90°。 **参数：** - `a` - 第一个向量 @@ -12,6 +12,10 @@ static float Dot(const Vector2& a, const Vector2& b) **返回：** `float` - 点积结果 a.x * b.x + a.y * b.y +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -21,3 +25,8 @@ Vector2 a(1.0f, 0.0f); Vector2 b(0.0f, 1.0f); float dot = Vector2::Dot(a, b); // 0.0f ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 +- [Cross](Cross.md) - 叉积运算 diff --git a/docs/api/math/vector2/down.md b/docs/api/math/vector2/down.md index 3481b338..517874cb 100644 --- a/docs/api/math/vector2/down.md +++ b/docs/api/math/vector2/down.md @@ -8,6 +8,10 @@ static Vector2 Down() **返回：** `Vector2` - 值为 (0, -1) 的向量 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -15,3 +19,7 @@ static Vector2 Down() ```cpp Vector2 down = Vector2::Down(); ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 diff --git a/docs/api/math/vector2/left.md b/docs/api/math/vector2/left.md index 692d318b..13c3cd53 100644 --- a/docs/api/math/vector2/left.md +++ b/docs/api/math/vector2/left.md @@ -8,6 +8,10 @@ static Vector2 Left() **返回：** `Vector2` - 值为 (-1, 0) 的向量 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -15,3 +19,7 @@ static Vector2 Left() ```cpp Vector2 left = Vector2::Left(); ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 diff --git a/docs/api/math/vector2/lerp.md b/docs/api/math/vector2/lerp.md index 08c66512..752df0e0 100644 --- a/docs/api/math/vector2/lerp.md +++ b/docs/api/math/vector2/lerp.md @@ -4,7 +4,7 @@ static Vector2 Lerp(const Vector2& a, const Vector2& b, float t) ``` -在线性插值两个向量之间。参数 t 会在 [0, 1] 范围内被限制。 +在两个向量之间进行线性插值。参数 t 会在 [0, 1] 范围内被限制，确保插值结果在两端向量之间。 **参数：** - `a` - 起始向量 @@ -13,6 +13,10 @@ static Vector2 Lerp(const Vector2& a, const Vector2& b, float t) **返回：** `Vector2` - 插值结果 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -22,3 +26,8 @@ Vector2 start(0.0f, 0.0f); Vector2 end(10.0f, 10.0f); Vector2 mid = Vector2::Lerp(start, end, 0.5f); // (5.0f, 5.0f) ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 +- [MoveTowards](movetowards.md) - 朝目标移动 diff --git a/docs/api/math/vector2/magnitude.md b/docs/api/math/vector2/magnitude.md index 227d3d31..bed3de63 100644 --- a/docs/api/math/vector2/magnitude.md +++ b/docs/api/math/vector2/magnitude.md @@ -14,6 +14,10 @@ float Magnitude() const **返回：** `float` - 向量长度 sqrt(x * x + y * y) +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -23,3 +27,9 @@ Vector2 v(3.0f, 4.0f); float len = v.Magnitude(); // 5.0f float len2 = Vector2::Magnitude(v); // 5.0f ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 +- [SqrMagnitude](sqrmagnitude.md) - 长度平方（更快） +- [Normalize](normalize.md) - 归一化向量 diff --git a/docs/api/math/vector2/movetowards.md b/docs/api/math/vector2/movetowards.md index db0f47a6..f126b139 100644 --- a/docs/api/math/vector2/movetowards.md +++ b/docs/api/math/vector2/movetowards.md @@ -4,7 +4,7 @@ static Vector2 MoveTowards(const Vector2& current, const Vector2& target, float maxDistance) ``` -将当前向量朝目标向量移动指定距离。如果距离已小于 maxDistance，则直接返回目标。 +将当前向量朝目标向量移动指定距离。如果当前向量与目标向量的距离已小于 maxDistance，则直接返回目标向量。 **参数：** - `current` - 当前向量 @@ -13,6 +13,10 @@ static Vector2 MoveTowards(const Vector2& current, const Vector2& target, float **返回：** `Vector2` - 移动后的位置 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -22,3 +26,8 @@ Vector2 current(0.0f, 0.0f); Vector2 target(10.0f, 0.0f); Vector2 moved = Vector2::MoveTowards(current, target, 3.0f); // (3.0f, 0.0f) ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 +- [Lerp](lerp.md) - 线性插值 diff --git a/docs/api/math/vector2/normalize.md b/docs/api/math/vector2/normalize.md index 3df54f1b..6c6d6fd6 100644 --- a/docs/api/math/vector2/normalize.md +++ b/docs/api/math/vector2/normalize.md @@ -4,13 +4,17 @@ static Vector2 Normalize(const Vector2& v) ``` -将向量归一化为单位长度。如果向量长度接近零，返回零向量。 +将向量归一化为单位长度。如果向量长度接近零（小于 EPSILON），返回零向量以避免除零错误。 **参数：** - `v` - 要归一化的向量 **返回：** `Vector2` - 归一化后的单位向量 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -18,3 +22,9 @@ static Vector2 Normalize(const Vector2& v) ```cpp Vector2 dir = Vector2::Normalize(Vector2(3.0f, 4.0f)); // (0.6f, 0.8f) ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 +- [Magnitude](Magnitude.md) - 计算向量长度 +- [Normalized](normalized.md) - 实例方法归一化 diff --git a/docs/api/math/vector2/normalized.md b/docs/api/math/vector2/normalized.md index 1e62dac1..e46c96a5 100644 --- a/docs/api/math/vector2/normalized.md +++ b/docs/api/math/vector2/normalized.md @@ -4,10 +4,14 @@ Vector2 Normalized() const ``` -返回当前向量的归一化副本（单位长度）。不修改原向量。 +返回当前向量的归一化副本（单位长度）。不修改原向量。如果向量长度接近零（小于 EPSILON），返回零向量。 **返回：** `Vector2` - 归一化后的向量副本 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -16,3 +20,9 @@ Vector2 Normalized() const Vector2 v(3.0f, 4.0f); Vector2 unit = v.Normalized(); // (0.6f, 0.8f), v 保持不变 ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 +- [Normalize](normalize.md) - 静态方法归一化 +- [Magnitude](magnitude.md) - 计算向量长度 diff --git a/docs/api/math/vector2/one.md b/docs/api/math/vector2/one.md index bbce99f6..54044069 100644 --- a/docs/api/math/vector2/one.md +++ b/docs/api/math/vector2/one.md @@ -8,6 +8,10 @@ static Vector2 One() **返回：** `Vector2` - 值为 (1, 1) 的向量 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -15,3 +19,7 @@ static Vector2 One() ```cpp Vector2 unit = Vector2::One(); ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 diff --git a/docs/api/math/vector2/right.md b/docs/api/math/vector2/right.md index 89a8561b..d967a637 100644 --- a/docs/api/math/vector2/right.md +++ b/docs/api/math/vector2/right.md @@ -8,6 +8,10 @@ static Vector2 Right() **返回：** `Vector2` - 值为 (1, 0) 的向量 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -15,3 +19,7 @@ static Vector2 Right() ```cpp Vector2 right = Vector2::Right(); ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 diff --git a/docs/api/math/vector2/sqrmagnitude.md b/docs/api/math/vector2/sqrmagnitude.md index 15183a20..b2b860b6 100644 --- a/docs/api/math/vector2/sqrmagnitude.md +++ b/docs/api/math/vector2/sqrmagnitude.md @@ -5,7 +5,7 @@ static float SqrMagnitude(const Vector2& v) float SqrMagnitude() const ``` -计算向量长度的平方。比 Magnitude 更快，避免了开方运算。 +计算向量长度的平方。比 Magnitude 更快，避免了开方运算。在比较相对长度或进行性能敏感的计算时优先使用。 **静态版本参数：** - `v` - 要计算长度的向量 @@ -14,6 +14,10 @@ float SqrMagnitude() const **返回：** `float` - 向量长度平方 x * x + y * y +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -23,3 +27,8 @@ Vector2 v(3.0f, 4.0f); float sqlen = v.SqrMagnitude(); // 25.0f float sqlen2 = Vector2::SqrMagnitude(v); // 25.0f ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 +- [Magnitude](magnitude.md) - 向量长度 diff --git a/docs/api/math/vector2/up.md b/docs/api/math/vector2/up.md index bf7c6975..9bbbd5df 100644 --- a/docs/api/math/vector2/up.md +++ b/docs/api/math/vector2/up.md @@ -8,6 +8,10 @@ static Vector2 Up() **返回：** `Vector2` - 值为 (0, 1) 的向量 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -15,3 +19,7 @@ static Vector2 Up() ```cpp Vector2 up = Vector2::Up(); ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 diff --git a/docs/api/math/vector2/vector2.md b/docs/api/math/vector2/vector2.md index 95a904e9..33599687 100644 --- a/docs/api/math/vector2/vector2.md +++ b/docs/api/math/vector2/vector2.md @@ -1,56 +1,73 @@ # Vector2 -2D 向量结构体，用于表示 2D 空间中的点、方向或颜色。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Vector2.h` -## 结构体定义 +**描述**: 二维向量，支持 2D 游戏开发和图形计算 -```cpp -struct Vector2 { - float x = 0.0f; - float y = 0.0f; -}; -``` +## 概述 -## 静态工厂方法 +Vector2 是 XCEngine 中的二维向量结构体，用于表示 2D 空间中的点、方向或颜色。提供完整的向量运算支持，包括加、减、乘、除等算术运算，以及点积、叉积、归一化、插值等数学运算。广泛应用于游戏开发中的位置表示、方向控制、碰撞检测和颜色计算等场景。 -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Zero()](zero.md) | `Vector2` | 返回 (0, 0) | -| [One()](one.md) | `Vector2` | 返回 (1, 1) | -| [Up()](up.md) | `Vector2` | 返回 (0, 1)，上方向 | -| [Down()](down.md) | `Vector2` | 返回 (0, -1)，下方向 | -| [Right()](right.md) | `Vector2` | 返回 (1, 0)，右方向 | -| [Left()](left.md) | `Vector2` | 返回 (-1, 0)，左方向 | +## 结构体成员 -## 静态数学方法 +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `x` | `float` | X 分量 | `0.0f` | +| `y` | `float` | Y 分量 | `0.0f` | -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Dot(a, b)](dot.md) | `float` | 点积 | -| [Cross(a, b)](cross.md) | `float` | 2D 叉积（返回标量） | -| [Normalize(v)](normalize.md) | `Vector2` | 归一化向量 | -| [Magnitude(v)](magnitude.md) | `float` | 向量长度 | -| [SqrMagnitude(v)](sqrmagnitude.md) | `float` | 长度平方（更快） | -| [Lerp(a, b, t)](lerp.md) | `Vector2` | 线性插值 | -| [MoveTowards(current, target, maxDistance)](movetowards.md) | `Vector2` | 朝目标移动 | +## 公共方法 -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Magnitude()](magnitude.md) | `float` | 获取向量长度 | -| [SqrMagnitude()](sqrmagnitude.md) | `float` | 获取长度平方 | -| [Normalized()](normalized.md) | `Vector2` | 获取归一化副本 | +| 方法 | 描述 | +|------|------| +| [`Zero`](Zero.md) | 返回 (0, 0) 零向量 | +| [`One`](One.md) | 返回 (1, 1) 单位向量 | +| [`Up`](Up.md) | 返回 (0, 1) 上方向 | +| [`Down`](Down.md) | 返回 (0, -1) 下方向 | +| [`Right`](Right.md) | 返回 (1, 0) 右方向 | +| [`Left`](Left.md) | 返回 (-1, 0) 左方向 | +| [`Dot`](Dot.md) | 计算两个向量的点积 | +| [`Cross`](Cross.md) | 计算两个向量的叉积（返回标量） | +| [`Normalize`](Normalize.md) | 归一化向量为单位长度 | +| [`Magnitude`](Magnitude.md) | 计算向量长度 | +| [`SqrMagnitude`](SqrMagnitude.md) | 计算向量长度平方 | +| [`Lerp`](Lerp.md) | 线性插值 | +| [`MoveTowards`](MoveTowards.md) | 朝目标移动 | +| [`Magnitude`](Magnitude.md) | 实例方法，计算当前向量长度 | +| [`SqrMagnitude`](SqrMagnitude.md) | 实例方法，计算当前向量长度平方 | +| [`Normalized`](Normalized.md) | 实例方法，返回归一化副本 | ## 运算符 -- 算术: `+`, `-`, `*` (scalar), `/` (scalar) -- 复合赋值: `+=`, `-=`, `*=`, `/=` -- 比较: `==`, `!=` +| 运算符 | 描述 | +|--------|------| +| `+`, `-` | 向量加减运算 | +| `*`, `/` | 向量与标量乘除运算 | +| `+=`, `-=`, `*=`, `/=` | 复合赋值运算 | +| `==`, `!=` | 相等性比较（基于 EPSILON 浮点比较） | + +## 使用示例 + +```cpp +#include "XCEngine/Math/Vector2.h" + +using namespace XCEngine::Math; + +Vector2 position(5.0f, 3.0f); +Vector2 velocity(1.0f, 0.5f); + +float speed = velocity.Magnitude(); +Vector2 normalizedVel = velocity.Normalized(); + +Vector2 newPos = position + velocity * speed; + +float dotProduct = Vector2::Dot(position, normalizedVel); + +Vector2 interpolated = Vector2::Lerp(position, Vector2(10.0f, 10.0f), 0.5f); +``` ## 相关文档 diff --git a/docs/api/math/vector2/zero.md b/docs/api/math/vector2/zero.md index 72c11cda..f0b7a72d 100644 --- a/docs/api/math/vector2/zero.md +++ b/docs/api/math/vector2/zero.md @@ -8,6 +8,10 @@ static Vector2 Zero() **返回：** `Vector2` - 值为 (0, 0) 的向量 +**线程安全：** ✅ + +**异常：** （无） + **复杂度：** O(1) **示例：** @@ -15,3 +19,7 @@ static Vector2 Zero() ```cpp Vector2 origin = Vector2::Zero(); ``` + +## 相关文档 + +- [Vector2](vector2.md) - 返回类总览 diff --git a/docs/api/math/vector3/angle.md b/docs/api/math/vector3/angle.md index b6cc2f2c..07c89a97 100644 --- a/docs/api/math/vector3/angle.md +++ b/docs/api/math/vector3/angle.md @@ -12,6 +12,8 @@ static float Angle(const Vector3& from, const Vector3& to) **返回：** `float` - 两向量之间的夹角（0-180度） +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -21,3 +23,7 @@ Vector3 a(1.0f, 0.0f, 0.0f); Vector3 b(0.0f, 1.0f, 0.0f); float angle = Vector3::Angle(a, b); // 90.0f ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/back.md b/docs/api/math/vector3/back.md index f630c311..e0ed8228 100644 --- a/docs/api/math/vector3/back.md +++ b/docs/api/math/vector3/back.md @@ -6,8 +6,12 @@ static Vector3 Back() 返回后方向向量 (0, 0, -1)。 +**参数：** 无 + **返回：** `Vector3` - 值为 (0, 0, -1) 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +19,8 @@ static Vector3 Back() ```cpp Vector3 back = Vector3::Back(); ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Forward`](forward.md) - 前向向量 diff --git a/docs/api/math/vector3/cross.md b/docs/api/math/vector3/cross.md index b7802671..d764c080 100644 --- a/docs/api/math/vector3/cross.md +++ b/docs/api/math/vector3/cross.md @@ -12,6 +12,8 @@ static Vector3 Cross(const Vector3& a, const Vector3& b) **返回：** `Vector3` - 叉积结果，垂直于 a 和 b 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -21,3 +23,7 @@ Vector3 right(1.0f, 0.0f, 0.0f); Vector3 up(0.0f, 1.0f, 0.0f); Vector3 forward = Vector3::Cross(right, up); // (0, 0, 1) ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/dot.md b/docs/api/math/vector3/dot.md index 91e0d8b3..8e26e68b 100644 --- a/docs/api/math/vector3/dot.md +++ b/docs/api/math/vector3/dot.md @@ -12,6 +12,8 @@ static float Dot(const Vector3& a, const Vector3& b) **返回：** `float` - 点积结果 a.x * b.x + a.y * b.y + a.z * b.z +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -21,3 +23,7 @@ Vector3 a(1.0f, 0.0f, 0.0f); Vector3 b(0.0f, 1.0f, 0.0f); float dot = Vector3::Dot(a, b); // 0.0f ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/down.md b/docs/api/math/vector3/down.md index 7b39dba4..adb63ba4 100644 --- a/docs/api/math/vector3/down.md +++ b/docs/api/math/vector3/down.md @@ -6,8 +6,12 @@ static Vector3 Down() 返回下方向向量 (0, -1, 0)。 +**参数：** 无 + **返回：** `Vector3` - 值为 (0, -1, 0) 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +19,8 @@ static Vector3 Down() ```cpp Vector3 down = Vector3::Down(); ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Up`](up.md) - 上向量 diff --git a/docs/api/math/vector3/forward.md b/docs/api/math/vector3/forward.md index ef19872b..030e6017 100644 --- a/docs/api/math/vector3/forward.md +++ b/docs/api/math/vector3/forward.md @@ -6,8 +6,12 @@ static Vector3 Forward() 返回前方向向量 (0, 0, 1)。 +**参数：** 无 + **返回：** `Vector3` - 值为 (0, 0, 1) 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +19,9 @@ static Vector3 Forward() ```cpp Vector3 forward = Vector3::Forward(); ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Back`](back.md) - 后向向量 +- [`Up`](up.md) - 上向量 diff --git a/docs/api/math/vector3/left.md b/docs/api/math/vector3/left.md index b2f1173a..923e8d68 100644 --- a/docs/api/math/vector3/left.md +++ b/docs/api/math/vector3/left.md @@ -6,8 +6,12 @@ static Vector3 Left() 返回左方向向量 (-1, 0, 0)。 +**参数：** 无 + **返回：** `Vector3` - 值为 (-1, 0, 0) 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +19,8 @@ static Vector3 Left() ```cpp Vector3 left = Vector3::Left(); ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Right`](right.md) - 右向量 diff --git a/docs/api/math/vector3/lerp.md b/docs/api/math/vector3/lerp.md index dd59840e..8e1217ac 100644 --- a/docs/api/math/vector3/lerp.md +++ b/docs/api/math/vector3/lerp.md @@ -13,6 +13,8 @@ static Vector3 Lerp(const Vector3& a, const Vector3& b, float t) **返回：** `Vector3` - 插值结果 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -22,3 +24,7 @@ Vector3 start(0.0f, 0.0f, 0.0f); Vector3 end(10.0f, 10.0f, 10.0f); Vector3 mid = Vector3::Lerp(start, end, 0.5f); // (5.0f, 5.0f, 5.0f) ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/magnitude.md b/docs/api/math/vector3/magnitude.md index c5c3e3fa..e74347ef 100644 --- a/docs/api/math/vector3/magnitude.md +++ b/docs/api/math/vector3/magnitude.md @@ -14,6 +14,8 @@ float Magnitude() const **返回：** `float` - 向量长度 sqrt(x * x + y * y + z * z) +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -23,3 +25,8 @@ Vector3 v(1.0f, 2.0f, 2.0f); float len = v.Magnitude(); // 3.0f float len2 = Vector3::Magnitude(v); // 3.0f ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`SqrMagnitude`](sqrmagnitude.md) - 计算长度的平方 diff --git a/docs/api/math/vector3/movetowards.md b/docs/api/math/vector3/movetowards.md index e1d3992d..ee900cf5 100644 --- a/docs/api/math/vector3/movetowards.md +++ b/docs/api/math/vector3/movetowards.md @@ -13,6 +13,8 @@ static Vector3 MoveTowards(const Vector3& current, const Vector3& target, float **返回：** `Vector3` - 移动后的位置 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -22,3 +24,7 @@ Vector3 current(0.0f, 0.0f, 0.0f); Vector3 target(10.0f, 0.0f, 0.0f); Vector3 moved = Vector3::MoveTowards(current, target, 3.0f); // (3.0f, 0, 0) ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/normalize.md b/docs/api/math/vector3/normalize.md index b35d4365..00a2bc9f 100644 --- a/docs/api/math/vector3/normalize.md +++ b/docs/api/math/vector3/normalize.md @@ -11,6 +11,8 @@ static Vector3 Normalize(const Vector3& v) **返回：** `Vector3` - 归一化后的单位向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -18,3 +20,8 @@ static Vector3 Normalize(const Vector3& v) ```cpp Vector3 dir = Vector3::Normalize(Vector3(3.0f, 4.0f, 0.0f)); // (0.6f, 0.8f, 0) ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Normalized`](normalized.md) - 实例方法版本 diff --git a/docs/api/math/vector3/normalized.md b/docs/api/math/vector3/normalized.md index 57f499d8..55995d55 100644 --- a/docs/api/math/vector3/normalized.md +++ b/docs/api/math/vector3/normalized.md @@ -8,6 +8,8 @@ Vector3 Normalized() const **返回：** `Vector3` - 归一化后的向量副本 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -16,3 +18,8 @@ Vector3 Normalized() const Vector3 v(3.0f, 4.0f, 0.0f); Vector3 unit = v.Normalized(); // (0.6f, 0.8f, 0), v 保持不变 ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Normalize`](normalize.md) - 静态方法版本 diff --git a/docs/api/math/vector3/one.md b/docs/api/math/vector3/one.md index 650c3d21..c41c053e 100644 --- a/docs/api/math/vector3/one.md +++ b/docs/api/math/vector3/one.md @@ -4,10 +4,14 @@ static Vector3 One() ``` -返回单位向量 (1, 1, 1)。 +返回分量为 (1, 1, 1) 的向量。 + +**参数：** 无 **返回：** `Vector3` - 值为 (1, 1, 1) 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +19,7 @@ static Vector3 One() ```cpp Vector3 unit = Vector3::One(); ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/operator_add.md b/docs/api/math/vector3/operator_add.md new file mode 100644 index 00000000..6dbae2e5 --- /dev/null +++ b/docs/api/math/vector3/operator_add.md @@ -0,0 +1,30 @@ +# Vector3::operator+ + +```cpp +Vector3 operator+(const Vector3& other) const +``` + +向量加法，将两个向量的对应分量相加。 + +**参数：** +- `other` - 要加的向量 + +**返回：** `Vector3` - 相加结果 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 a(1.0f, 2.0f, 3.0f); +Vector3 b(4.0f, 5.0f, 6.0f); +Vector3 c = a + b; // (5.0f, 7.0f, 9.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator-`](operator_sub.md) - 减法运算 +- [`operator+=`](operator_add_assign.md) - 加法赋值 diff --git a/docs/api/math/vector3/operator_add_assign.md b/docs/api/math/vector3/operator_add_assign.md new file mode 100644 index 00000000..1cc707fa --- /dev/null +++ b/docs/api/math/vector3/operator_add_assign.md @@ -0,0 +1,29 @@ +# Vector3::operator+= + +```cpp +Vector3& operator+=(const Vector3& other) +``` + +向量加法赋值，将 `other` 的分量加到当前向量。 + +**参数：** +- `other` - 要加的向量 + +**返回：** `Vector3&` - 引用到修改后的当前向量 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(1.0f, 2.0f, 3.0f); +v += Vector3(4.0f, 5.0f, 6.0f); // v = (5.0f, 7.0f, 9.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator+`](operator_add.md) - 加法运算 +- [`operator-=`](operator_sub_assign.md) - 减法赋值 diff --git a/docs/api/math/vector3/operator_div.md b/docs/api/math/vector3/operator_div.md new file mode 100644 index 00000000..3843ace3 --- /dev/null +++ b/docs/api/math/vector3/operator_div.md @@ -0,0 +1,40 @@ +# Vector3::operator/ + +```cpp +Vector3 operator/(float scalar) const +Vector3 operator/(const Vector3& other) const +``` + +向量除法。支持向量与标量相除，以及向量分量对应相除。 + +**参数：** +- `scalar` - 标量值（用于第一个重载） +- `other` - 向量（用于第二个重载，分量相除） + +**返回：** `Vector3` - 除法结果 + +**异常：** 第二个重载中，如果 `other` 的任一分量为零，结果为无穷大 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(6.0f, 8.0f, 10.0f); + +// 标量除法 +Vector3 scaled = v / 2.0f; // (3.0f, 4.0f, 5.0f) + +// 分量相除 +Vector3 a(6.0f, 8.0f, 10.0f); +Vector3 b(2.0f, 2.0f, 2.0f); +Vector3 componentwise = a / b; // (3.0f, 4.0f, 5.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator*`](operator_mul.md) - 乘法运算 +- [`operator/=`](operator_div_assign.md) - 除法赋值 diff --git a/docs/api/math/vector3/operator_div_assign.md b/docs/api/math/vector3/operator_div_assign.md new file mode 100644 index 00000000..673547d9 --- /dev/null +++ b/docs/api/math/vector3/operator_div_assign.md @@ -0,0 +1,31 @@ +# Vector3::operator/= + +```cpp +Vector3& operator/=(float scalar) +``` + +向量标量除法赋值，将当前向量的每个分量除以标量值。 + +**参数：** +- `scalar` - 标量值（不能为零） + +**返回：** `Vector3&` - 引用到修改后的当前向量 + +**异常：** 如果 `scalar` 为零，结果为无穷大 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(6.0f, 8.0f, 10.0f); +v /= 2.0f; // v = (3.0f, 4.0f, 5.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator/`](operator_div.md) - 除法运算 +- [`operator*=`](operator_mul_assign.md) - 乘法赋值 diff --git a/docs/api/math/vector3/operator_eq.md b/docs/api/math/vector3/operator_eq.md new file mode 100644 index 00000000..2fe28dab --- /dev/null +++ b/docs/api/math/vector3/operator_eq.md @@ -0,0 +1,32 @@ +# Vector3::operator== + +```cpp +bool operator==(const Vector3& other) const +``` + +判断两个向量是否相等。使用 EPSILON 进行浮点数比较。 + +**参数：** +- `other` - 要比较的向量 + +**返回：** `bool` - 如果两个向量相等返回 true，否则返回 false + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 a(1.0f, 2.0f, 3.0f); +Vector3 b(1.0f, 2.0f, 3.0f); +Vector3 c(1.0f, 2.0f, 3.00001f); + +bool equal1 = (a == b); // true +bool equal2 = (a == c); // true（因为差异在 EPSILON 内） +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator!=`](operator_neq.md) - 不等比较 diff --git a/docs/api/math/vector3/operator_index.md b/docs/api/math/vector3/operator_index.md new file mode 100644 index 00000000..62a72c03 --- /dev/null +++ b/docs/api/math/vector3/operator_index.md @@ -0,0 +1,35 @@ +# Vector3::operator[] + +```cpp +float operator[](int index) const +float& operator[](int index) +``` + +通过索引访问向量的分量。0 = x, 1 = y, 2 = z。 + +**参数：** +- `index` - 分量索引（0、1 或 2） + +**返回：** `float` 或 `float&` - 对应分量的值（const 版本返回值，non-const 版本返回引用） + +**异常：** 如果 index 超出范围（< 0 或 > 2），行为未定义 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(1.0f, 2.0f, 3.0f); + +float x = v[0]; // 1.0f +float y = v[1]; // 2.0f +float z = v[2]; // 3.0f + +v[0] = 10.0f; // v = (10.0f, 2.0f, 3.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/operator_mul.md b/docs/api/math/vector3/operator_mul.md new file mode 100644 index 00000000..1889609c --- /dev/null +++ b/docs/api/math/vector3/operator_mul.md @@ -0,0 +1,39 @@ +# Vector3::operator* + +```cpp +Vector3 operator*(float scalar) const +Vector3 operator*(const Vector3& other) const +``` + +向量乘法。支持向量与标量相乘，以及向量分量对应相乘。 + +**参数：** +- `scalar` - 标量值（用于第一个重载） +- `other` - 向量（用于第二个重载，分量相乘） + +**返回：** `Vector3` - 乘法结果 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(1.0f, 2.0f, 3.0f); + +// 标量乘法 +Vector3 scaled = v * 2.0f; // (2.0f, 4.0f, 6.0f) + +// 分量相乘 +Vector3 a(1.0f, 2.0f, 3.0f); +Vector3 b(2.0f, 3.0f, 4.0f); +Vector3 componentwise = a * b; // (2.0f, 6.0f, 12.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator/`](operator_div.md) - 除法运算 +- [`operator*=`](operator_mul_assign.md) - 乘法赋值 +- [Quaternion * Vector3](quaternion-multiply.md) - 四元数旋转向量 diff --git a/docs/api/math/vector3/operator_mul_assign.md b/docs/api/math/vector3/operator_mul_assign.md new file mode 100644 index 00000000..c5fc625a --- /dev/null +++ b/docs/api/math/vector3/operator_mul_assign.md @@ -0,0 +1,29 @@ +# Vector3::operator*= + +```cpp +Vector3& operator*=(float scalar) +``` + +向量标量乘法赋值，将当前向量的每个分量乘以标量值。 + +**参数：** +- `scalar` - 标量值 + +**返回：** `Vector3&` - 引用到修改后的当前向量 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(1.0f, 2.0f, 3.0f); +v *= 2.0f; // v = (2.0f, 4.0f, 6.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator*`](operator_mul.md) - 乘法运算 +- [`operator/=`](operator_div_assign.md) - 除法赋值 diff --git a/docs/api/math/vector3/operator_neq.md b/docs/api/math/vector3/operator_neq.md new file mode 100644 index 00000000..04731685 --- /dev/null +++ b/docs/api/math/vector3/operator_neq.md @@ -0,0 +1,30 @@ +# Vector3::operator!= + +```cpp +bool operator!=(const Vector3& other) const +``` + +判断两个向量是否不相等。使用 EPSILON 进行浮点数比较。 + +**参数：** +- `other` - 要比较的向量 + +**返回：** `bool` - 如果两个向量不相等返回 true，否则返回 false + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 a(1.0f, 2.0f, 3.0f); +Vector3 b(4.0f, 5.0f, 6.0f); + +bool notEqual = (a != b); // true +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator==`](operator_eq.md) - 相等比较 diff --git a/docs/api/math/vector3/operator_sub.md b/docs/api/math/vector3/operator_sub.md new file mode 100644 index 00000000..f5614ea3 --- /dev/null +++ b/docs/api/math/vector3/operator_sub.md @@ -0,0 +1,30 @@ +# Vector3::operator- + +```cpp +Vector3 operator-(const Vector3& other) const +``` + +向量减法，将两个向量的对应分量相减。 + +**参数：** +- `other` - 要减的向量 + +**返回：** `Vector3` - 相减结果 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 a(5.0f, 7.0f, 9.0f); +Vector3 b(1.0f, 2.0f, 3.0f); +Vector3 c = a - b; // (4.0f, 5.0f, 6.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator+`](operator_add.md) - 加法运算 +- [`operator-=`](operator_sub_assign.md) - 减法赋值 diff --git a/docs/api/math/vector3/operator_sub_assign.md b/docs/api/math/vector3/operator_sub_assign.md new file mode 100644 index 00000000..21513b6f --- /dev/null +++ b/docs/api/math/vector3/operator_sub_assign.md @@ -0,0 +1,29 @@ +# Vector3::operator-= + +```cpp +Vector3& operator-=(const Vector3& other) +``` + +向量减法赋值，从当前向量减去 `other` 的分量。 + +**参数：** +- `other` - 要减的向量 + +**返回：** `Vector3&` - 引用到修改后的当前向量 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(5.0f, 7.0f, 9.0f); +v -= Vector3(1.0f, 2.0f, 3.0f); // v = (4.0f, 5.0f, 6.0f) +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`operator-`](operator_sub.md) - 减法运算 +- [`operator+=`](operator_add_assign.md) - 加法赋值 diff --git a/docs/api/math/vector3/project.md b/docs/api/math/vector3/project.md index dcff56cb..62aca087 100644 --- a/docs/api/math/vector3/project.md +++ b/docs/api/math/vector3/project.md @@ -12,6 +12,8 @@ static Vector3 Project(const Vector3& vector, const Vector3& onNormal) **返回：** `Vector3` - 投影结果。如果法线长度为 0，返回零向量。 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -21,3 +23,8 @@ Vector3 v(1.0f, 1.0f, 0.0f); Vector3 normal(1.0f, 0.0f, 0.0f); Vector3 projected = Vector3::Project(v, normal); // (1, 0, 0) ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`ProjectOnPlane`](projectonplane.md) - 投影到平面上 diff --git a/docs/api/math/vector3/projectonplane.md b/docs/api/math/vector3/projectonplane.md index 84747f04..bc30190f 100644 --- a/docs/api/math/vector3/projectonplane.md +++ b/docs/api/math/vector3/projectonplane.md @@ -12,6 +12,8 @@ static Vector3 ProjectOnPlane(const Vector3& vector, const Vector3& planeNormal) **返回：** `Vector3` - 平面上的投影向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -21,3 +23,8 @@ Vector3 v(1.0f, 1.0f, 1.0f); Vector3 normal(0.0f, 1.0f, 0.0f); // XZ 平面 Vector3 projected = Vector3::ProjectOnPlane(v, normal); // (1, 0, 1) ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Project`](project.md) - 投影到法线上 diff --git a/docs/api/math/vector3/quaternion-multiply.md b/docs/api/math/vector3/quaternion-multiply.md index d21f0da7..eb39b923 100644 --- a/docs/api/math/vector3/quaternion-multiply.md +++ b/docs/api/math/vector3/quaternion-multiply.md @@ -12,6 +12,8 @@ Vector3 operator*(const Quaternion& q, const Vector3& v) **返回：** `Vector3` - 旋转后的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -21,3 +23,7 @@ Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); Vector3 forward = Vector3::Forward(); Vector3 rotated = rot * forward; // 绕 Y 轴旋转 90 度 ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/reflect.md b/docs/api/math/vector3/reflect.md index 570be5f4..5b238c25 100644 --- a/docs/api/math/vector3/reflect.md +++ b/docs/api/math/vector3/reflect.md @@ -12,6 +12,8 @@ static Vector3 Reflect(const Vector3& inDirection, const Vector3& inNormal) **返回：** `Vector3` - 反射方向 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -21,3 +23,7 @@ Vector3 incoming(1.0f, -1.0f, 0.0f); Vector3 normal(0.0f, 1.0f, 0.0f); Vector3 reflected = Vector3::Reflect(incoming, normal); // (1, 1, 0) ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/right.md b/docs/api/math/vector3/right.md index 7fe121b5..39391084 100644 --- a/docs/api/math/vector3/right.md +++ b/docs/api/math/vector3/right.md @@ -6,8 +6,12 @@ static Vector3 Right() 返回右方向向量 (1, 0, 0)。 +**参数：** 无 + **返回：** `Vector3` - 值为 (1, 0, 0) 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +19,8 @@ static Vector3 Right() ```cpp Vector3 right = Vector3::Right(); ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Left`](left.md) - 左向量 diff --git a/docs/api/math/vector3/sqrmagnitude.md b/docs/api/math/vector3/sqrmagnitude.md index 94e42d61..7c8ef29f 100644 --- a/docs/api/math/vector3/sqrmagnitude.md +++ b/docs/api/math/vector3/sqrmagnitude.md @@ -14,6 +14,8 @@ float SqrMagnitude() const **返回：** `float` - 向量长度平方 x * x + y * y + z * z +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -23,3 +25,8 @@ Vector3 v(1.0f, 2.0f, 2.0f); float sqlen = v.SqrMagnitude(); // 9.0f float sqlen2 = Vector3::SqrMagnitude(v); // 9.0f ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Magnitude`](magnitude.md) - 计算向量长度 diff --git a/docs/api/math/vector3/up.md b/docs/api/math/vector3/up.md index 2ae2335a..b5fef878 100644 --- a/docs/api/math/vector3/up.md +++ b/docs/api/math/vector3/up.md @@ -6,8 +6,12 @@ static Vector3 Up() 返回上方向向量 (0, 1, 0)。 +**参数：** 无 + **返回：** `Vector3` - 值为 (0, 1, 0) 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +19,8 @@ static Vector3 Up() ```cpp Vector3 up = Vector3::Up(); ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 +- [`Down`](down.md) - 下向量 diff --git a/docs/api/math/vector3/vector3-constructor.md b/docs/api/math/vector3/vector3-constructor.md new file mode 100644 index 00000000..c2c426a9 --- /dev/null +++ b/docs/api/math/vector3/vector3-constructor.md @@ -0,0 +1,39 @@ +# Vector3::Vector3 + +```cpp +Vector3() = default; +constexpr Vector3(float x, float y, float z); +``` + +构造一个三维向量。 + +**参数：** +- `x` - X 分量，默认为 0.0f +- `y` - Y 分量，默认为 0.0f +- `z` - Z 分量，默认为 0.0f + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Vector3.h" + +using namespace XCEngine::Math; + +int main() { + Vector3 a; + Vector3 b(1.0f, 2.0f, 3.0f); + Vector3 c(4.5f, 5.5f, 6.5f); + + return 0; +} +``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector3/vector3.md b/docs/api/math/vector3/vector3.md index 541a62b2..efa489e5 100644 --- a/docs/api/math/vector3/vector3.md +++ b/docs/api/math/vector3/vector3.md @@ -1,69 +1,87 @@ # Vector3 -3D 向量结构体，用于表示 3D 空间中的点、方向、颜色或法线。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Vector3.h` -## 结构体定义 +**描述**: 三维向量，用于 3D 图形和游戏开发中的位置、方向和缩放计算 -```cpp -struct Vector3 { - float x = 0.0f; - float y = 0.0f; - float z = 0.0f; -}; -``` +## 概述 -## 静态工厂方法 +Vector3 是 XCEngine 中用于表示三维向量的核心类型，支持常见的向量运算。它广泛用于 3D 图形编程中的位置、方向、速度、缩放等计算场景。 -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Zero()](zero.md) | `Vector3` | 返回 (0, 0, 0) | -| [One()](one.md) | `Vector3` | 返回 (1, 1, 1) | -| [Forward()](forward.md) | `Vector3` | 返回 (0, 0, 1)，前方向（Z+） | -| [Back()](back.md) | `Vector3` | 返回 (0, 0, -1)，后方向 | -| [Up()](up.md) | `Vector3` | 返回 (0, 1, 0)，上方向 | -| [Down()](down.md) | `Vector3` | 返回 (0, -1, 0)，下方向 | -| [Right()](right.md) | `Vector3` | 返回 (1, 0, 0)，右方向 | -| [Left()](left.md) | `Vector3` | 返回 (-1, 0, 0)，左方向 | +## 结构体成员 -## 静态数学方法 +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `x` | `float` | X 分量 | `0.0f` | +| `y` | `float` | Y 分量 | `0.0f` | +| `z` | `float` | Z 分量 | `0.0f` | -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Dot(a, b)](dot.md) | `float` | 点积 | -| [Cross(a, b)](cross.md) | `Vector3` | 叉积（垂直于 a 和 b） | -| [Normalize(v)](normalize.md) | `Vector3` | 归一化向量 | -| [Magnitude(v)](magnitude.md) | `float` | 向量长度 | -| [SqrMagnitude(v)](sqrmagnitude.md) | `float` | 长度平方 | -| [Lerp(a, b, t)](lerp.md) | `Vector3` | 线性插值 | -| [MoveTowards(current, target, maxDistance)](movetowards.md) | `Vector3` | 朝目标移动 | -| [Project(vector, onNormal)](project.md) | `Vector3` | 投影到法线上 | -| [ProjectOnPlane(vector, planeNormal)](projectonplane.md) | `Vector3` | 投影到平面上 | -| [Angle(from, to)](angle.md) | `float` | 两向量夹角（度） | -| [Reflect(inDirection, inNormal)](reflect.md) | `Vector3` | 反射 | +## 公共方法 -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Magnitude()](magnitude.md) | `float` | 获取向量长度 | -| [SqrMagnitude()](sqrmagnitude.md) | `float` | 获取长度平方 | -| [Normalized()](normalized.md) | `Vector3` | 获取归一化副本 | +| 方法 | 描述 | +|------|------| +| [`Zero`](zero.md) | 返回零向量 (0, 0, 0) | +| [`One`](one.md) | 返回单位向量 (1, 1, 1) | +| [`Forward`](forward.md) | 返回前向向量 (0, 0, 1) | +| [`Back`](back.md) | 返回后向向量 (0, 0, -1) | +| [`Up`](up.md) | 返回上向量 (0, 1, 0) | +| [`Down`](down.md) | 返回下向量 (0, -1, 0) | +| [`Right`](right.md) | 返回右向量 (1, 0, 0) | +| [`Left`](left.md) | 返回左向量 (-1, 0, 0) | +| [`Dot`](dot.md) | 计算点积 | +| [`Cross`](cross.md) | 计算叉积 | +| [`Normalize`](normalize.md) | 返回归一化向量 | +| [`Magnitude`](magnitude.md) | 计算向量长度 | +| [`SqrMagnitude`](sqrmagnitude.md) | 计算向量长度的平方 | +| [`Lerp`](lerp.md) | 线性插值 | +| [`MoveTowards`](movetowards.md) | 移向目标点 | +| [`Project`](project.md) | 投影到法向量上 | +| [`ProjectOnPlane`](projectonplane.md) | 投影到平面上 | +| [`Angle`](angle.md) | 计算两个向量之间的夹角 | +| [`Reflect`](reflect.md) | 反射向量 | +| [`Normalized`](normalized.md) | 返回归一化副本（实例方法） | ## 运算符 -- 算术: `+`, `-`, `*` (scalar/memberwise), `/` (scalar/memberwise) -- 复合赋值: `+=`, `-=`, `*=`, `/=` -- 下标: `operator[]` (0=x, 1=y, 2=z) -- 比较: `==`, `!=` +| 运算符 | 描述 | +|--------|------| +| [`+`](operator_add.md), [`-`](operator_sub.md) | 向量加减 | +| [`*`](operator_mul.md), [`/`](operator_div.md) | 向量与标量或分量相乘/相除 | +| [`*=`](operator_mul_assign.md), [`/=`](operator_div_assign.md) | 复合赋值运算符 | +| [`[]`](./operator_index.md) | 下标访问 x, y, z 分量 | +| [`==`](operator_eq.md), [`!=`](operator_neq.md) | 相等性比较 | +| [`* (Quaternion)`](quaternion-multiply.md) | 用四元数旋转向量 | -## 与 Quaternion 的乘法 +## 使用示例 -[Vector3 * Quaternion](quaternion-multiply.md) - 用四元数旋转向量 +```cpp +#include "XCEngine/Math/Vector3.h" +#include + +using namespace XCEngine::Math; + +int main() { + Vector3 position(1.0f, 2.0f, 3.0f); + Vector3 direction = Vector3::Forward(); + + float dot = Vector3::Dot(position, direction); + Vector3 cross = Vector3::Cross(position, direction); + Vector3 normalized = position.Normalized(); + + std::cout << "Position: (" << position.x << ", " << position.y << ", " << position.z << ")\n"; + std::cout << "Dot product: " << dot << "\n"; + std::cout << "Normalized: (" << normalized.x << ", " << normalized.y << ", " << normalized.z << ")\n"; + + return 0; +} +``` ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Math 模块总览](../math.md) - Math 模块总览 +- [Vector2](../vector2/vector2.md) - 二维向量 +- [Vector4](../vector4/vector4.md) - 四维向量 diff --git a/docs/api/math/vector3/zero.md b/docs/api/math/vector3/zero.md index 24770129..ee86b54e 100644 --- a/docs/api/math/vector3/zero.md +++ b/docs/api/math/vector3/zero.md @@ -6,8 +6,12 @@ static Vector3 Zero() 返回零向量 (0, 0, 0)。 +**参数：** 无 + **返回：** `Vector3` - 值为 (0, 0, 0) 的向量 +**线程安全：** ✅ + **复杂度：** O(1) **示例：** @@ -15,3 +19,7 @@ static Vector3 Zero() ```cpp Vector3 origin = Vector3::Zero(); ``` + +## 相关文档 + +- [Vector3 类总览](vector3.md) - 返回类总览 diff --git a/docs/api/math/vector4/constructor.md b/docs/api/math/vector4/constructor.md new file mode 100644 index 00000000..45d4fbe0 --- /dev/null +++ b/docs/api/math/vector4/constructor.md @@ -0,0 +1,25 @@ +# Vector4::Vector4 + +使用四个分量构造四维向量。 + +```cpp +constexpr Vector4(float x, float y, float z, float w) +``` + +**参数：** +- `x` - X 分量 +- `y` - Y 分量 +- `z` - Z 分量 +- `w` - W 分量（通常用于齐次坐标） + +**返回：** 新创建的 Vector4 实例 + +**示例：** + +```cpp +Vector4 v(1.0f, 2.0f, 3.0f, 4.0f); +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 diff --git a/docs/api/math/vector4/constructor_default.md b/docs/api/math/vector4/constructor_default.md new file mode 100644 index 00000000..0ab7b73b --- /dev/null +++ b/docs/api/math/vector4/constructor_default.md @@ -0,0 +1,20 @@ +# Vector4::Vector4 + +```cpp +Vector4() = default; +``` + +默认构造函数，创建零向量 (0, 0, 0, 0)。 + +**返回：** 新创建的 Vector4 实例 + +**示例：** + +```cpp +Vector4 v; // (0, 0, 0, 0) +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 +- [Zero](zero.md) - 返回零向量 diff --git a/docs/api/math/vector4/constructor_vector3.md b/docs/api/math/vector4/constructor_vector3.md new file mode 100644 index 00000000..37cd34d4 --- /dev/null +++ b/docs/api/math/vector4/constructor_vector3.md @@ -0,0 +1,25 @@ +# Vector4::Vector4 (from Vector3) + +```cpp +explicit Vector4(const Vector3& v, float w = 0.0f) +``` + +从 Vector3 构造四维向量，w 分量默认为 0.0f。 + +**参数：** +- `v` - 源 Vector3 向量 +- `w` - W 分量（默认值为 `0.0f`） + +**返回：** 新创建的 Vector4 实例 + +**示例：** + +```cpp +Vector3 v3(1.0f, 2.0f, 3.0f); +Vector4 v4a(v3); +Vector4 v4b(v3, 1.0f); +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 diff --git a/docs/api/math/vector4/dot.md b/docs/api/math/vector4/dot.md index 0e848f6c..d5e41d41 100644 --- a/docs/api/math/vector4/dot.md +++ b/docs/api/math/vector4/dot.md @@ -1,11 +1,11 @@ # Vector4::Dot +计算两个 4D 向量的点积。 + ```cpp static float Dot(const Vector4& a, const Vector4& b) ``` -计算两个 4D 向量的点积。 - **参数：** - `a` - 第一个向量 - `b` - 第二个向量 @@ -21,3 +21,7 @@ Vector4 a(1.0f, 2.0f, 3.0f, 4.0f); Vector4 b(4.0f, 3.0f, 2.0f, 1.0f); float dot = Vector4::Dot(a, b); // 20.0f ``` + +## 相关文档 + +- [Vector4 总览](vector4.md) diff --git a/docs/api/math/vector4/one.md b/docs/api/math/vector4/one.md index bbc06be3..4217b000 100644 --- a/docs/api/math/vector4/one.md +++ b/docs/api/math/vector4/one.md @@ -1,11 +1,11 @@ # Vector4::One +返回单位向量 (1, 1, 1, 1)。 + ```cpp static Vector4 One() ``` -返回单位向量 (1, 1, 1, 1)。 - **返回：** `Vector4` - 值为 (1, 1, 1, 1) 的向量 **复杂度：** O(1) @@ -15,3 +15,7 @@ static Vector4 One() ```cpp Vector4 unit = Vector4::One(); ``` + +## 相关文档 + +- [Vector4 总览](vector4.md) diff --git a/docs/api/math/vector4/operator-add.md b/docs/api/math/vector4/operator-add.md new file mode 100644 index 00000000..cef75b8d --- /dev/null +++ b/docs/api/math/vector4/operator-add.md @@ -0,0 +1,24 @@ +# Vector4::operator+ + +```cpp +Vector4 operator+(const Vector4& other) const +``` + +向量加法。 + +**参数：** +- `other` - 要相加的向量 + +**返回：** `Vector4` - 相加结果向量 + +**示例：** + +```cpp +Vector4 a(1.0f, 2.0f, 3.0f, 4.0f); +Vector4 b(5.0f, 6.0f, 7.0f, 8.0f); +Vector4 c = a + b; // (6, 8, 10, 12) +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 diff --git a/docs/api/math/vector4/operator-brackets.md b/docs/api/math/vector4/operator-brackets.md new file mode 100644 index 00000000..0db6df94 --- /dev/null +++ b/docs/api/math/vector4/operator-brackets.md @@ -0,0 +1,28 @@ +# Vector4::operator[] + +```cpp +float operator[](int index) const +float& operator[](int index) +``` + +通过下标访问向量分量。 + +**参数：** +- `index` - 分量索引 (0=x, 1=y, 2=z, 3=w) + +**返回：** `float` 或 `float&` - 对应分量的值（常量版本返回值，左值版本返回引用） + +**注意事项：** 未进行边界检查。index 应在 [0, 3] 范围内。 + +**示例：** + +```cpp +Vector4 v(1.0f, 2.0f, 3.0f, 4.0f); +float x = v[0]; // 1.0f +float w = v[3]; // 4.0f +v[1] = 5.0f; // v 变为 (1, 5, 3, 4) +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 diff --git a/docs/api/math/vector4/operator-eq.md b/docs/api/math/vector4/operator-eq.md new file mode 100644 index 00000000..67b7ea71 --- /dev/null +++ b/docs/api/math/vector4/operator-eq.md @@ -0,0 +1,25 @@ +# Vector4::operator== + +```cpp +bool operator==(const Vector4& other) const +``` + +判断两个向量是否相等。 + +**参数：** +- `other` - 要比较的向量 + +**返回：** `bool` - 如果所有分量差的绝对值都小于 EPSILON 则返回 true，否则返回 false + +**示例：** + +```cpp +Vector4 a(1.0f, 2.0f, 3.0f, 4.0f); +Vector4 b(1.0f, 2.0f, 3.0f, 4.0f); +bool eq = (a == b); // true +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 +- [operator!=](operator-ne.md) - 不等比较 diff --git a/docs/api/math/vector4/operator-mul.md b/docs/api/math/vector4/operator-mul.md new file mode 100644 index 00000000..f5ea0a72 --- /dev/null +++ b/docs/api/math/vector4/operator-mul.md @@ -0,0 +1,23 @@ +# Vector4::operator* + +```cpp +Vector4 operator*(float scalar) const +``` + +向量与标量乘法。 + +**参数：** +- `scalar` - 标量值 + +**返回：** `Vector4` - 缩放后的向量 + +**示例：** + +```cpp +Vector4 v(1.0f, 2.0f, 3.0f, 4.0f); +Vector4 scaled = v * 2.0f; // (2, 4, 6, 8) +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 diff --git a/docs/api/math/vector4/operator-ne.md b/docs/api/math/vector4/operator-ne.md new file mode 100644 index 00000000..6ccbef21 --- /dev/null +++ b/docs/api/math/vector4/operator-ne.md @@ -0,0 +1,24 @@ +# Vector4::operator!= + +```cpp +bool operator!=(const Vector4& other) const +``` + +判断两个向量是否不相等。 + +**参数：** +- `other` - 要比较的向量 + +**返回：** `bool` - 如果任何分量差的绝对值大于等于 EPSILON 则返回 true，否则返回 false + +**示例：** + +```cpp +Vector4 a(1.0f, 2.0f, 3.0f, 4.0f); +Vector4 b(5.0f, 6.0f, 7.0f, 8.0f); +bool ne = (a != b); // true +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 diff --git a/docs/api/math/vector4/operator-sub.md b/docs/api/math/vector4/operator-sub.md new file mode 100644 index 00000000..cb1b9c5e --- /dev/null +++ b/docs/api/math/vector4/operator-sub.md @@ -0,0 +1,24 @@ +# Vector4::operator- + +```cpp +Vector4 operator-(const Vector4& other) const +``` + +向量减法。 + +**参数：** +- `other` - 要相减的向量 + +**返回：** `Vector4` - 相减结果向量 + +**示例：** + +```cpp +Vector4 a(5.0f, 6.0f, 7.0f, 8.0f); +Vector4 b(1.0f, 2.0f, 3.0f, 4.0f); +Vector4 c = a - b; // (4, 4, 4, 4) +``` + +## 相关文档 + +- [Vector4 总览](vector4.md) - 返回类总览 diff --git a/docs/api/math/vector4/project.md b/docs/api/math/vector4/project.md index 17b1420e..8bae0932 100644 --- a/docs/api/math/vector4/project.md +++ b/docs/api/math/vector4/project.md @@ -1,11 +1,11 @@ # Vector4::Project +将向量投影到法线向量上。 + ```cpp static Vector4 Project(const Vector4& vector, const Vector4& onNormal) ``` -将向量投影到法线向量上。 - **参数：** - `vector` - 要投影的向量 - `onNormal` - 投影到的法线向量 @@ -21,3 +21,7 @@ Vector4 v(1.0f, 1.0f, 1.0f, 1.0f); Vector4 normal(1.0f, 0.0f, 0.0f, 0.0f); Vector4 projected = Vector4::Project(v, normal); // (1, 0, 0, 0) ``` + +## 相关文档 + +- [Vector4 总览](vector4.md) diff --git a/docs/api/math/vector4/tovector3.md b/docs/api/math/vector4/tovector3.md index 852cc56c..753ab049 100644 --- a/docs/api/math/vector4/tovector3.md +++ b/docs/api/math/vector4/tovector3.md @@ -1,11 +1,11 @@ # Vector4::ToVector3 +将 Vector4 转换为 Vector3，丢弃 w 分量。 + ```cpp Vector3 ToVector3() const ``` -将 Vector4 转换为 Vector3，丢弃 w 分量。 - **返回：** `Vector3` - 转换后的 Vector3 (x, y, z) **复杂度：** O(1) @@ -16,3 +16,8 @@ Vector3 ToVector3() const Vector4 pos4(1.0f, 2.0f, 3.0f, 1.0f); Vector3 pos3 = pos4.ToVector3(); // (1, 2, 3) ``` + +## 相关文档 + +- [Vector4 总览](vector4.md) +- [Vector3 总览](../vector3/vector3.md) diff --git a/docs/api/math/vector4/vector4.md b/docs/api/math/vector4/vector4.md index fa8dbf94..ef22fab7 100644 --- a/docs/api/math/vector4/vector4.md +++ b/docs/api/math/vector4/vector4.md @@ -1,53 +1,71 @@ # Vector4 -4D 向量结构体，用于表示齐次坐标、颜色 (RGBA) 或 SIMD 操作。 +**命名空间**: `XCEngine::Math` -**头文件：** `#include ` +**类型**: `struct` -**命名空间：** `XCEngine::Math` +**头文件**: `XCEngine/Math/Vector4.h` -## 结构体定义 +**描述**: 四维向量，用于齐次坐标变换和四元数相关计算 + +## 概述 + +Vector4 是四维向量结构体，常用于： +- 齐次坐标变换（x, y, z, w） +- RGBA 颜色表示 +- SIMD 矢量操作 +- 四元数分量存储 + +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `x` | `float` | X 分量 | `0.0f` | +| `y` | `float` | Y 分量 | `0.0f` | +| `z` | `float` | Z 分量 | `0.0f` | +| `w` | `float` | W 分量（齐次坐标） | `0.0f` | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Vector4()`](constructor_default.md) | 默认构造函数，创建零向量 | +| [`Vector4(x, y, z, w)`](constructor.md) | 从四个分量构造向量 | +| [`Vector4(Vector3, w)`](constructor_vector3.md) | 从 Vector3 构造（w 默认 0） | +| [`Zero`](zero.md) | 返回零向量 (0, 0, 0, 0) | +| [`One`](one.md) | 返回单位向量 (1, 1, 1, 1) | +| [`Dot`](dot.md) | 计算两个向量的点积 | +| [`Project`](project.md) | 将向量投影到法线向量上 | +| [`ToVector3`](tovector3.md) | 转换为 Vector3 | +| [`operator[]`](./operator-brackets.md) | 下标访问分量 | +| [`operator+`](operator-add.md) | 向量加法 | +| [`operator-`](operator-sub.md) | 向量减法 | +| [`operator*`](operator-mul.md) | 向量数乘 | +| [`operator==`](operator-eq.md) | 相等比较 | +| [`operator!=`](operator-ne.md) | 不等比较 | + +## 使用示例 ```cpp -struct Vector4 { - float x = 0.0f; - float y = 0.0f; - float z = 0.0f; - float w = 0.0f; -}; +#include +#include +#include + +int main() { + Vector4 a(1.0f, 2.0f, 3.0f, 4.0f); + Vector4 b(4.0f, 3.0f, 2.0f, 1.0f); + + Vector4 sum = a + b; + Vector4 scaled = a * 2.0f; + float dot = Vector4::Dot(a, b); + + Vector4 projected = Vector4::Project(a, Vector4(1.0f, 0.0f, 0.0f, 0.0f)); + Vector3 v3 = a.ToVector3(); + + return 0; +} ``` -## 构造函数 - -- `Vector4(float x, float y, float z, float w)` - 从四个分量构造 -- `explicit Vector4(const Vector3& v, float w = 0.0f)` - 从 Vector3 构造 - -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Zero()](zero.md) | `Vector4` | 返回 (0, 0, 0, 0) | -| [One()](one.md) | `Vector4` | 返回 (1, 1, 1, 1) | - -## 静态数学方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [Dot(a, b)](dot.md) | `float` | 4D 点积 | -| [Project(vector, onNormal)](project.md) | `Vector4` | 投影 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| [ToVector3()](tovector3.md) | `Vector3` | 转换到 Vector3（丢弃 w） | - -## 运算符 - -- 算术: `+`, `-`, `*` (scalar) -- 下标: `operator[]` (0=x, 1=y, 2=z, 3=w) -- 比较: `==`, `!=` - ## 相关文档 -- [Math 模块总览](../math.md) - 返回 Math 模块总览 +- [Math 模块总览](../math.md) - Math 模块总览 diff --git a/docs/api/math/vector4/zero.md b/docs/api/math/vector4/zero.md index 89a11c13..406c6f78 100644 --- a/docs/api/math/vector4/zero.md +++ b/docs/api/math/vector4/zero.md @@ -1,11 +1,11 @@ # Vector4::Zero +返回零向量 (0, 0, 0, 0)。 + ```cpp static Vector4 Zero() ``` -返回零向量 (0, 0, 0, 0)。 - **返回：** `Vector4` - 值为 (0, 0, 0, 0) 的向量 **复杂度：** O(1) @@ -15,3 +15,8 @@ static Vector4 Zero() ```cpp Vector4 origin = Vector4::Zero(); ``` + +## 相关文档 + +- [Vector4 总览](vector4.md) + diff --git a/docs/api/math/viewport/getaspectratio.md b/docs/api/math/viewport/getaspectratio.md new file mode 100644 index 00000000..a3706706 --- /dev/null +++ b/docs/api/math/viewport/getaspectratio.md @@ -0,0 +1,34 @@ +# Viewport::GetAspectRatio + +```cpp +float GetAspectRatio() const; +``` + +获取视口宽高比。 + +**返回：** 宽高比 (width / height)，如果 height 为 0 则返回 0.0f + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + Viewport viewport(0.0f, 0.0f, 1920.0f, 1080.0f); + float aspect = viewport.GetAspectRatio(); + std::cout << "Aspect Ratio: " << aspect << "\n"; + return 0; +} +``` + +## 相关文档 + +- [`Viewport::GetRect`](getrect.md) - 转换为 Rect +- [Viewport 总览](viewport.md) \ No newline at end of file diff --git a/docs/api/math/viewport/getrect.md b/docs/api/math/viewport/getrect.md new file mode 100644 index 00000000..ebc95e4d --- /dev/null +++ b/docs/api/math/viewport/getrect.md @@ -0,0 +1,34 @@ +# Viewport::GetRect + +```cpp +Rect GetRect() const; +``` + +将视口转换为 Rect。 + +**返回：** 对应的 Rect（x, y, width, height），不包含深度范围 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + Viewport viewport(0.0f, 0.0f, 1920.0f, 1080.0f, 0.0f, 1.0f); + Rect rect = viewport.GetRect(); + std::cout << "Rect: (" << rect.x << ", " << rect.y << ", " << rect.width << ", " << rect.height << ")\n"; + return 0; +} +``` + +## 相关文档 + +- [`Viewport::GetAspectRatio`](getaspectratio.md) - 获取宽高比 +- [Viewport 总览](viewport.md) \ No newline at end of file diff --git a/docs/api/math/viewport/viewport.md b/docs/api/math/viewport/viewport.md new file mode 100644 index 00000000..3b0821fa --- /dev/null +++ b/docs/api/math/viewport/viewport.md @@ -0,0 +1,49 @@ +# Viewport + +**命名空间**: `XCEngine::Math` + +**类型**: `struct` + +**头文件**: `XCEngine/Math/Viewport.h` + +**描述**: 视口，用于渲染目标区域和坐标映射 + +## 概述 + +Viewport 结构体表示一个渲染视口，除了位置和尺寸外，还包含深度范围 `(minDepth, maxDepth)`。主要用于屏幕到归一化设备坐标（NDC）的映射，以及渲染目标区域的定义。 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`GetAspectRatio`](getaspectratio.md) | 获取视口宽高比 | +| [`GetRect`](getrect.md) | 转换为 Rect | + +## 使用示例 + +```cpp +#include "XCEngine/Math/Rect.h" +#include + +using namespace XCEngine::Math; + +int main() { + Viewport viewport(0.0f, 0.0f, 1920.0f, 1080.0f, 0.0f, 1.0f); + + std::cout << "Position: (" << viewport.x << ", " << viewport.y << ")\n"; + std::cout << "Size: " << viewport.width << " x " << viewport.height << "\n"; + std::cout << "Depth: " << viewport.minDepth << " to " << viewport.maxDepth << "\n"; + std::cout << "Aspect Ratio: " << viewport.GetAspectRatio() << "\n"; + + Rect rect = viewport.GetRect(); + std::cout << "As Rect: (" << rect.x << ", " << rect.y << ", " << rect.width << ", " << rect.height << ")\n"; + + return 0; +} +``` + +## 相关文档 + +- [`Rect`](../rect/rect.md) - 浮点矩形 +- [`RectInt`](../rect/rectint.md) - 整数矩形 +- [`Vector2`](../vector2/vector2.md) - 二维向量 \ No newline at end of file