docs: update math API docs

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);
+```

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);
+```

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();
+```

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();
+```

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)) {
+}
+```

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)) {
+}
+```

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) - 球体