docs: update math API docs

2026-03-20 02:35:15 +08:00
parent e165dbea1c
commit c5b17239ca
243 changed files with 5307 additions and 1327 deletions
--- a/docs/api/math/plane/constructor-default.md
+++ 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 <XCEngine/Math/Plane.h>
+
+using namespace XCEngine::Math;
+
+void DefaultConstructorExample() {
+    Plane plane;
+}
+```
+
+## 相关文档
+
+- [Plane 类总览](plane.md) - 返回类总览
--- a/docs/api/math/plane/constructor.md
+++ 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 <XCEngine/Math/Plane.h>
+#include <XCEngine/Math/Vector3.h>
+
+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) - 返回类总览
--- 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 <XCEngine/Math/Plane.h>
+#include <XCEngine/Math/Vector3.h>
+
+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) - 返回类总览
--- 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 <XCEngine/Math/Plane.h>
+#include <XCEngine/Math/Vector3.h>
+
+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) - 计算有符号距离
--- 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 <XCEngine/Math/Plane.h>
+#include <XCEngine/Math/Vector3.h>
+#include <cstdio>
+
+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) - 判断点在哪一侧
--- 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 <XCEngine/Math/Plane.h>
+#include <XCEngine/Math/Vector3.h>
+
+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) - 计算有符号距离
--- 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 <XCEngine/Math/Plane.h>
+#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Math/Vector3.h>
+
+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) - 球体类
--- a/docs/api/math/plane/plane.md
+++ b/docs/api/math/plane/plane.md
@@ -1,40 +1,64 @@
 # Plane

-3D 平面结构体，由法线和距离表示。
+**命名空间**: `XCEngine::Math`

-**头文件：** `#include <XCEngine/Math/Plane.h>`
+**类型**: `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 <XCEngine/Math/Plane.h>
+#include <XCEngine/Math/Vector3.h>
+#include <XCEngine/Math/Sphere.h>
+
+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) - 三维向量