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

18
docs/api/math/ray/getpoint.md
View File

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

28
docs/api/math/ray/intersects-box.md
View File

@@ -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 <XCEngine/Math/Ray.h>
#include <XCEngine/Math/Box.h>
#include <XCEngine/Math/Vector3.h>
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) - 包围盒类型

26
docs/api/math/ray/intersects-plane.md
View File

@@ -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 <XCEngine/Math/Ray.h>
#include <XCEngine/Math/Plane.h>
#include <XCEngine/Math/Vector3.h>
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) - 平面类型

23
docs/api/math/ray/intersects-sphere.md
View File

@@ -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 <XCEngine/Math/Ray.h>
#include <XCEngine/Math/Sphere.h>
#include <XCEngine/Math/Vector3.h>
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) - 球体类型

27
docs/api/math/ray/ray-constructor-default.md Normal file
View File

@@ -0,0 +1,27 @@
# Ray::Ray (默认构造函数)
```cpp
Ray() = default
```
默认构造函数，使用默认方式构造射线。
**返回：** 无
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Math/Ray.h>
using namespace XCEngine::Math;
Ray ray; // 未初始化状态
```
## 相关文档
- [Ray 类总览](ray.md) - 返回类总览

33
docs/api/math/ray/ray-constructor.md Normal file
View File

@@ -0,0 +1,33 @@
# Ray::Ray (构造函数)
```cpp
Ray(const Vector3& origin, const Vector3& direction)
```
从起点和方向构造射线。
**参数：**
- `origin` - 射线起点
- `direction` - 射线方向（构造时会被归一化）
**返回：** 无
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Math/Ray.h>
#include <XCEngine/Math/Vector3.h>
using namespace XCEngine::Math;
Ray ray(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.0f, 0.0f));
// direction 已被归一化
```
## 相关文档
- [Ray 类总览](ray.md) - 返回类总览

70
docs/api/math/ray/ray.md
View File

@@ -1,44 +1,60 @@
# Ray
3D 射线结构体，用于光线投射和拾取。
**命名空间**: `XCEngine::Math`
**头文件：** `#include <XCEngine/Math/Ray.h>`
**类型**: `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 <XCEngine/Math/Ray.h>
#include <XCEngine/Math/Vector3.h>
#include <XCEngine/Math/Sphere.h>
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) - 平面类型