xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update math API docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-20 02:35:15 +08:00
parent e165dbea1c
commit c5b17239ca
243 changed files with 5307 additions and 1327 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/api/math/bounds/bounds.constructors.md Normal file
View File

@@ -0,0 +1,38 @@
# Bounds::Bounds
```cpp
Bounds()
Bounds(const Vector3& center, const Vector3& size)
```
构造一个 Bounds 对象。默认构造函数创建中心为原点、范围为零的包围盒。
**参数：**
- `center` - 包围盒的中心点
- `size` - 包围盒的完整尺寸（非 extents，构造时会自动除以 2）
**返回：** 无
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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) - 获取最大点

80
docs/api/math/bounds/bounds.md
View File

@@ -1,40 +1,64 @@
# Bounds
轴对齐包围盒 (AABB)，中心-范围表示。
**命名空间**: `XCEngine::Math`
**头文件：** `#include <XCEngine/Math/Bounds.h>`
**类型**: `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 <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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 模块总览

24
docs/api/math/bounds/contains.md
View File

@@ -4,17 +4,35 @@
bool Contains(const Vector3& point) const
```
检测点是否在包围盒内。
检测给定点是否在包围盒内部。边界上的点被视为在盒内。
**参数：**
- `point` - 要检测的点
**返回：** `bool` - true 表示点在盒内
**返回：** `bool` - true 表示点在盒内（包括边界）
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
if (bounds.Contains(point)) { /* inside */ }
#include <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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 是否相交

18
docs/api/math/bounds/encapsulate-bounds.md
View File

@@ -1,18 +0,0 @@
# Bounds::Encapsulate (Bounds)
```cpp
void Encapsulate(const Bounds& bounds)
```
扩展包围盒以包含另一个 Bounds。
**参数：**
- `bounds` - 要包含的 Bounds
**复杂度：** O(1)
**示例：**
```cpp
bounds.Encapsulate(otherBounds);
```

25
docs/api/math/bounds/encapsulate.md
View File

@@ -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 <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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) - 均匀扩展包围盒

23
docs/api/math/bounds/expand.md
View File

@@ -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 <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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

22
docs/api/math/bounds/getclosestpoint.md
View File

@@ -4,17 +4,35 @@
Vector3 GetClosestPoint(const Vector3& point) const
```
获取包围盒上最接近给定点的点。
获取包围盒上最接近给定点的点。如果点在盒内，则返回该点本身；如果在盒外，则返回该点在盒面上的投影点。
**参数：**
- `point` - 参考点
**返回：** `Vector3` - 盒上最接近的点
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
Vector3 closest = bounds.GetClosestPoint(point);
#include <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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) - 检测点是否在盒内

18
docs/api/math/bounds/getmax.md
View File

@@ -4,14 +4,28 @@
Vector3 GetMax() const
```
获取包围盒的最大点。
获取包围盒的最大点（最大 corner）。
**返回：** `Vector3` - center + extents
**返回：** `Vector3` - 包围盒最大点，等于 `center + extents`
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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) - 获取最小点

18
docs/api/math/bounds/getmin.md
View File

@@ -4,14 +4,28 @@
Vector3 GetMin() const
```
获取包围盒的最小点。
获取包围盒的最小点（最小 corner）。
**返回：** `Vector3` - center - extents
**返回：** `Vector3` - 包围盒最小点，等于 `center - extents`
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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) - 获取最大点

17
docs/api/math/bounds/getvolume.md
View File

@@ -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 <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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) - 返回类总览

22
docs/api/math/bounds/intersects.md
View File

@@ -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 <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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) - 检测点是否在盒内

25
docs/api/math/bounds/setminmax.md
View File

@@ -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 <XCEngine/Math/Bounds.h>
#include <XCEngine/Math/Vector3.h>
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) - 获取最大点