docs: update math API docs
This commit is contained in:
@@ -1,44 +1,65 @@
|
||||
# Box
|
||||
|
||||
带变换的包围盒结构体（支持 OBB 语义，取决于方法）。
|
||||
**命名空间**: `XCEngine::Math`
|
||||
|
||||
**头文件：** `#include <XCEngine/Math/Box.h>`
|
||||
**类型**: `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 <XCEngine/Math/Box.h>
|
||||
#include <XCEngine/Math/Vector3.h>
|
||||
#include <XCEngine/Math/Sphere.h>
|
||||
|
||||
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 模块总览
|
||||
|
||||
42
docs/api/math/box/constructor.md
Normal file
42
docs/api/math/box/constructor.md
Normal file
@@ -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 <XCEngine/Math/Box.h>
|
||||
#include <XCEngine/Math/Vector3.h>
|
||||
|
||||
using namespace XCEngine::Math;
|
||||
|
||||
Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 2.0f, 1.5f));
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Box 类总览](box.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 <XCEngine/Math/Box.h>
|
||||
#include <XCEngine/Math/Vector3.h>
|
||||
|
||||
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) - 返回类总览
|
||||
|
||||
@@ -4,14 +4,29 @@
|
||||
Vector3 GetMax() const
|
||||
```
|
||||
|
||||
获取局部空间最大点。
|
||||
获取盒体在局部空间中的最大点（角点）。
|
||||
|
||||
**返回：** `Vector3` - (+extents)
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `Vector3` - 盒体最大点，即 `center + extents`
|
||||
|
||||
**线程安全：** ✅
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Box.h>
|
||||
#include <XCEngine/Math/Vector3.h>
|
||||
|
||||
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) - 获取最小点
|
||||
|
||||
@@ -4,14 +4,29 @@
|
||||
Vector3 GetMin() const
|
||||
```
|
||||
|
||||
获取局部空间最小点。
|
||||
获取盒体在局部空间中的最小点（角点）。
|
||||
|
||||
**返回：** `Vector3` - (-extents)
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `Vector3` - 盒体最小点，即 `center - extents`
|
||||
|
||||
**线程安全：** ✅
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Math/Box.h>
|
||||
#include <XCEngine/Math/Vector3.h>
|
||||
|
||||
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) - 获取最大点
|
||||
|
||||
@@ -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 <XCEngine/Math/Box.h>
|
||||
|
||||
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) - 返回类总览
|
||||
|
||||
@@ -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 <XCEngine/Math/Box.h>
|
||||
#include <XCEngine/Math/Ray.h>
|
||||
|
||||
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) - 射线相交检测
|
||||
|
||||
@@ -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 <XCEngine/Math/Box.h>
|
||||
#include <XCEngine/Math/Sphere.h>
|
||||
|
||||
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) - 返回类总览
|
||||
|
||||
Reference in New Issue
Block a user