docs: 重构 API 文档结构并修正源码准确性

- 重组文档目录结构: 每个模块的概述页移动到模块子目录
- 重命名 index.md 为 main.md
- 修正所有模块文档中的错误:
  - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式
  - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节
  - core: 修复 types 链接错误
  - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI
  - memory: 修复头文件路径, malloc vs operator new, 新增方法文档
  - resources: 修复 Shader/Texture 链接错误
  - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接
- 验证: fix_links.py 确认 0 个断裂引用

docs/api/math/aabb/aabb.md

@@ -0,0 +1,43 @@
+# AABB / OBB
+
+轴对齐包围盒 (AABB) 和有向包围盒 (OBB)。
+
+**头文件：** `#include <XCEngine/Math/AABB.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## AABB
+
+`AABB` 在 Math 库中通过 `Bounds` 类型实现，参见 [./bounds/bounds.md](../bounds/bounds.md)。
+
+## OBB - 有向包围盒
+
+OBB 是可以任意方向旋转的包围盒。
+
+```cpp
+struct OBB {
+    Vector3 center;
+    Vector3 extents;
+    Matrix4 transform;
+};
+```
+
+### 构造函数
+
+- `OBB()` - 默认构造
+- `OBB(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
+
+### 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetAxis(index)](obb-getaxis.md) | `Vector3` | 获取局部轴 |
+| [GetMin()](obb-getmin.md) | `Vector3` | 局部空间最小点 |
+| [GetMax()](obb-getmax.md) | `Vector3` | 局部空间最大点 |
+| [Contains(point)](obb-contains.md) | `bool` | 点是否在 OBB 内 |
+| [Intersects(OBB)](obb-intersects-obb.md) | `bool` | 与另一个 OBB 相交 |
+| [Intersects(Sphere)](obb-intersects-sphere.md) | `bool` | 与球体相交 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/aabb/obb-contains.md

@@ -0,0 +1,20 @@
+# OBB::Contains
+
+```cpp
+bool Contains(const Vector3& point) const
+```
+
+检测点是否在 OBB 内。
+
+**参数：**
+- `point` - 要检测的点
+
+**返回：** `bool` - true 表示点在 OBB 内
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (obb.Contains(point)) { /* inside */ }
+```

docs/api/math/aabb/obb-getaxis.md

@@ -0,0 +1,20 @@
+# OBB::GetAxis
+
+```cpp
+Vector3 GetAxis(int index) const
+```
+
+获取 OBB 的局部轴。
+
+**参数：**
+- `index` - 轴索引 (0=X, 1=Y, 2=Z)
+
+**返回：** `Vector3` - 对应的局部轴
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 xAxis = obb.GetAxis(0);
+```

docs/api/math/aabb/obb-getmax.md

@@ -0,0 +1,17 @@
+# OBB::GetMax
+
+```cpp
+Vector3 GetMax() const
+```
+
+获取局部空间最大点。
+
+**返回：** `Vector3` - center + extents
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 max = obb.GetMax();
+```

docs/api/math/aabb/obb-getmin.md

@@ -0,0 +1,17 @@
+# OBB::GetMin
+
+```cpp
+Vector3 GetMin() const
+```
+
+获取局部空间最小点。
+
+**返回：** `Vector3` - center - extents
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 min = obb.GetMin();
+```

docs/api/math/aabb/obb-intersects-obb.md

@@ -0,0 +1,25 @@
+# OBB::Intersects(OBB)
+
+```cpp
+bool Intersects(const OBB& other) const;
+```
+
+判断两个 OBB 是否相交（SAT 分离轴定理）。
+
+**返回：** 两包围盒是否相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+OBB a(centerA, extentsA);
+OBB b(centerB, extentsB);
+if (a.Intersects(b)) {
+    // 两包围盒相交
+}
+```
+
+## 相关文档
+
+- [AABB 总览](aabb.md) - 返回 AABB 概览

docs/api/math/aabb/obb-intersects-sphere.md

@@ -0,0 +1,28 @@
+# OBB::Intersects(Sphere)
+
+```cpp
+bool Intersects(const Sphere& sphere) const;
+```
+
+判断 OBB 与球体是否相交。
+
+**参数：**
+- `sphere` - 球体
+
+**返回：** OBB 与球体是否相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+OBB obb(center, extents);
+Sphere s(sphereCenter, radius);
+if (obb.Intersects(s)) {
+    // OBB 与球体相交
+}
+```
+
+## 相关文档
+
+- [AABB 总览](aabb.md) - 返回 AABB 概览

docs/api/math/bounds/bounds.md

@@ -0,0 +1,40 @@
+# Bounds
+
+轴对齐包围盒 (AABB)，中心-范围表示。
+
+**头文件：** `#include <XCEngine/Math/Bounds.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Bounds {
+    Vector3 center = Vector3::Zero();
+    Vector3 extents = Vector3::Zero();
+};
+```
+
+## 构造函数
+
+- `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 模块总览

docs/api/math/bounds/contains.md

@@ -0,0 +1,20 @@
+# Bounds::Contains
+
+```cpp
+bool Contains(const Vector3& point) const
+```
+
+检测点是否在包围盒内。
+
+**参数：**
+- `point` - 要检测的点
+
+**返回：** `bool` - true 表示点在盒内
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (bounds.Contains(point)) { /* inside */ }
+```

docs/api/math/bounds/encapsulate-bounds.md

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

docs/api/math/bounds/encapsulate.md

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

docs/api/math/bounds/expand.md

@@ -0,0 +1,19 @@
+# Bounds::Expand
+
+```cpp
+void Expand(float amount)
+void Expand(const Vector3& amount)
+```
+
+扩展包围盒。
+
+**参数：**
+- `amount` - 扩展量（各方向或统一）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+bounds.Expand(1.0f);
+```

docs/api/math/bounds/getclosestpoint.md

@@ -0,0 +1,20 @@
+# Bounds::GetClosestPoint
+
+```cpp
+Vector3 GetClosestPoint(const Vector3& point) const
+```
+
+获取包围盒上最接近给定点的点。
+
+**参数：**
+- `point` - 参考点
+
+**返回：** `Vector3` - 盒上最接近的点
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 closest = bounds.GetClosestPoint(point);
+```

docs/api/math/bounds/getmax.md

@@ -0,0 +1,17 @@
+# Bounds::GetMax
+
+```cpp
+Vector3 GetMax() const
+```
+
+获取包围盒的最大点。
+
+**返回：** `Vector3` - center + extents
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 max = bounds.GetMax();
+```

docs/api/math/bounds/getmin.md

@@ -0,0 +1,17 @@
+# Bounds::GetMin
+
+```cpp
+Vector3 GetMin() const
+```
+
+获取包围盒的最小点。
+
+**返回：** `Vector3` - center - extents
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 min = bounds.GetMin();
+```

docs/api/math/bounds/getvolume.md

@@ -0,0 +1,17 @@
+# Bounds::GetVolume
+
+```cpp
+float GetVolume() const
+```
+
+计算包围盒的体积。
+
+**返回：** `float` - 体积
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+float vol = bounds.GetVolume();
+```

docs/api/math/bounds/intersects.md

@@ -0,0 +1,20 @@
+# Bounds::Intersects
+
+```cpp
+bool Intersects(const Bounds& other) const
+```
+
+检测两个 Bounds 是否相交。
+
+**参数：**
+- `other` - 另一个 Bounds
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (bounds.Intersects(other)) { /* collision */ }
+```

docs/api/math/bounds/setminmax.md

@@ -0,0 +1,19 @@
+# Bounds::SetMinMax
+
+```cpp
+void SetMinMax(const Vector3& min, const Vector3& max)
+```
+
+从最小/最大点设置包围盒。
+
+**参数：**
+- `min` - 最小点
+- `max` - 最大点
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+bounds.SetMinMax(minPoint, maxPoint);
+```

docs/api/math/box/box.md

@@ -0,0 +1,37 @@
+# Box
+
+带变换的有向包围盒 (OBB) 结构体。
+
+**头文件：** `#include <XCEngine/Math/Box.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Box {
+    Vector3 center = Vector3::Zero();
+    Vector3 extents = Vector3::Zero();
+    Matrix4x4 transform = Matrix4x4::Identity();
+};
+```
+
+## 构造函数
+
+- `Box()` - 默认构造
+- `Box(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetMin()](getmin.md) | `Vector3` | 局部空间最小点 |
+| [GetMax()](getmax.md) | `Vector3` | 局部空间最大点 |
+| [Contains(point)](contains.md) | `bool` | 点是否在盒内 |
+| [Intersects(Sphere)](intersects.md) | `bool` | 与球体相交 |
+| [Intersects(Box)](intersects-box.md) | `bool` | 与另一个 OBB 相交 |
+| [Intersects(Ray, t)](intersects-ray.md) | `bool` | 与射线相交 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/box/contains.md

@@ -0,0 +1,20 @@
+# Box::Contains
+
+```cpp
+bool Contains(const Vector3& point) const
+```
+
+检测点是否在盒内。
+
+**参数：**
+- `point` - 要检测的点
+
+**返回：** `bool` - true 表示点在盒内
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (box.Contains(point)) { /* inside */ }
+```

docs/api/math/box/getmax.md

@@ -0,0 +1,17 @@
+# Box::GetMax
+
+```cpp
+Vector3 GetMax() const
+```
+
+获取局部空间最大点。
+
+**返回：** `Vector3` - (+extents)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 max = box.GetMax();
+```

docs/api/math/box/getmin.md

@@ -0,0 +1,17 @@
+# Box::GetMin
+
+```cpp
+Vector3 GetMin() const
+```
+
+获取局部空间最小点。
+
+**返回：** `Vector3` - (-extents)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 min = box.GetMin();
+```

docs/api/math/box/intersects-box.md

@@ -0,0 +1,20 @@
+# Box::Intersects (Box)
+
+```cpp
+bool Intersects(const Box& other) const
+```
+
+检测两个 OBB 是否相交（使用 SAT 算法）。
+
+**参数：**
+- `other` - 另一个 OBB
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (box.Intersects(otherBox)) { /* collision */ }
+```

docs/api/math/box/intersects-ray.md

@@ -0,0 +1,24 @@
+# Box::Intersects (Ray)
+
+```cpp
+bool Intersects(const Ray& ray, float& t) const
+```
+
+检测盒是否与射线相交。
+
+**参数：**
+- `ray` - 射线
+- `t` - 输出交点距离
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+float t;
+if (box.Intersects(ray, t)) {
+    Vector3 hit = ray.GetPoint(t);
+}
+```

docs/api/math/box/intersects.md

@@ -0,0 +1,20 @@
+# Box::Intersects
+
+```cpp
+bool Intersects(const Sphere& sphere) const
+```
+
+检测盒是否与球体相交。
+
+**参数：**
+- `sphere` - 球体
+
+**返回：** `bool` - true 表示相交
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (box.Intersects(sphere)) { /* collision */ }
+```

docs/api/math/color/black.md

@@ -0,0 +1,11 @@
+# Color::Black
+
+```cpp
+static Color Black()
+```
+
+返回黑色 (0, 0, 0, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Black();`

docs/api/math/color/blue.md

@@ -0,0 +1,11 @@
+# Color::Blue
+
+```cpp
+static Color Blue()
+```
+
+返回蓝色 (0, 0, 1, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Blue();`

docs/api/math/color/clear.md

@@ -0,0 +1,11 @@
+# Color::Clear
+
+```cpp
+static Color Clear()
+```
+
+返回透明黑色 (0, 0, 0, 0)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Clear();`

docs/api/math/color/color.md

@@ -0,0 +1,59 @@
+# Color
+
+颜色结构体，支持 RGBA 浮点分量。
+
+**头文件：** `#include <XCEngine/Math/Color.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Color {
+    float r = 1.0f;
+    float g = 1.0f;
+    float b = 1.0f;
+    float a = 1.0f;
+};
+```
+
+## 静态工厂方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [White()](white.md) | `Color` | (1, 1, 1, 1) |
+| [Black()](black.md) | `Color` | (0, 0, 0, 1) |
+| [Red()](red.md) | `Color` | (1, 0, 0, 1) |
+| [Green()](green.md) | `Color` | (0, 1, 0, 1) |
+| [Blue()](blue.md) | `Color` | (0, 0, 1, 1) |
+| [Yellow()](yellow.md) | `Color` | (1, 1, 0, 1) |
+| [Cyan()](cyan.md) | `Color` | (0, 1, 1, 1) |
+| [Magenta()](magenta.md) | `Color` | (1, 0, 1, 1) |
+| [Clear()](clear.md) | `Color` | (0, 0, 0, 0)，透明黑 |
+
+## 静态方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Lerp(a, b, t)](lerp.md) | `Color` | 颜色线性插值 |
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [ToRGBA()](torgba.md) | `uint32_t` | 转换为 32-bit RGBA (0xRRGGBBAA) |
+| [ToVector3()](tovector3.md) | `Vector3` | 转换为 RGB (丢弃 alpha) |
+| [ToVector4()](tovector4.md) | `Vector4` | 转换为 RGBA |
+
+## 运算符
+
+| 运算符 | 描述 |
+|--------|------|
+| `operator+(Color, Color)` | 颜色相加 |
+| `operator-(Color, Color)` | 颜色相减 |
+| `operator*(Color, float)` | 颜色乘以标量 |
+| `operator/(Color, float)` | 颜色除以标量 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/color/cyan.md

@@ -0,0 +1,11 @@
+# Color::Cyan
+
+```cpp
+static Color Cyan()
+```
+
+返回青色 (0, 1, 1, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Cyan();`

docs/api/math/color/green.md

@@ -0,0 +1,11 @@
+# Color::Green
+
+```cpp
+static Color Green()
+```
+
+返回绿色 (0, 1, 0, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Green();`

docs/api/math/color/lerp.md

@@ -0,0 +1,22 @@
+# Color::Lerp
+
+```cpp
+static Color Lerp(const Color& a, const Color& b, float t)
+```
+
+在两个颜色之间进行线性插值。
+
+**参数：**
+- `a` - 起始颜色
+- `b` - 结束颜色
+- `t` - 插值因子 (0-1)
+
+**返回：** `Color` - 插值结果
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color lerped = Color::Lerp(Color::Red(), Color::Blue(), 0.5f);
+```

docs/api/math/color/magenta.md

@@ -0,0 +1,11 @@
+# Color::Magenta
+
+```cpp
+static Color Magenta()
+```
+
+返回品红色 (1, 0, 1, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Magenta();`

docs/api/math/color/red.md

@@ -0,0 +1,11 @@
+# Color::Red
+
+```cpp
+static Color Red()
+```
+
+返回红色 (1, 0, 0, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Red();`

docs/api/math/color/torgba.md

@@ -0,0 +1,18 @@
+# Color::ToRGBA
+
+```cpp
+uint32_t ToRGBA() const
+```
+
+将颜色转换为 32-bit RGBA 整数格式。
+
+**返回：** `uint32_t` - RGBA 值 (0xRRGGBBAA)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c(1.0f, 0.0f, 0.0f, 1.0f);
+uint32_t rgba = c.ToRGBA();
+```

docs/api/math/color/tovector3.md

@@ -0,0 +1,17 @@
+# Color::ToVector3
+
+```cpp
+Vector3 ToVector3() const
+```
+
+将颜色转换为 Vector3（丢弃 alpha）。
+
+**返回：** `Vector3` - RGB 值
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 rgb = Color::Red().ToVector3();
+```

docs/api/math/color/tovector4.md

@@ -0,0 +1,17 @@
+# Color::ToVector4
+
+```cpp
+Vector4 ToVector4() const
+```
+
+将颜色转换为 Vector4。
+
+**返回：** `Vector4` - RGBA 值
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector4 rgba = Color::Red().ToVector4();
+```

docs/api/math/color/white.md

@@ -0,0 +1,11 @@
+# Color::White
+
+```cpp
+static Color White()
+```
+
+返回白色 (1, 1, 1, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::White();`

docs/api/math/color/yellow.md

@@ -0,0 +1,11 @@
+# Color::Yellow
+
+```cpp
+static Color Yellow()
+```
+
+返回黄色 (1, 1, 0, 1)。
+
+**返回：** `Color`
+
+**示例：** `Color c = Color::Yellow();`

docs/api/math/frustum/contains-bounds.md

@@ -0,0 +1,25 @@
+# Frustum::Contains (bounds)
+
+```cpp
+bool Contains(const Bounds& bounds) const
+```
+
+检测轴对齐包围盒是否完全在视锥体内。
+
+**参数：**
+- `bounds` - 要检测的轴对齐包围盒
+
+**返回：** `bool` - Bounds 完全在视锥内返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+Bounds objectBounds = object.GetWorldBounds();
+if (frustum.Contains(objectBounds)) {
+    // 包围盒完全在视锥内，需要渲染
+    Render(object);
+}
+```

docs/api/math/frustum/contains-point.md

@@ -0,0 +1,24 @@
+# Frustum::Contains (point)
+
+```cpp
+bool Contains(const Vector3& point) const
+```
+
+检测点是否在视锥体内。
+
+**参数：**
+- `point` - 要检测的世界空间点
+
+**返回：** `bool` - 点在视锥内返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+Vector3 point = object.GetPosition();
+if (frustum.Contains(point)) {
+    // 点在视锥内
+}
+```

docs/api/math/frustum/contains-sphere.md

@@ -0,0 +1,24 @@
+# Frustum::Contains (sphere)
+
+```cpp
+bool Contains(const Sphere& sphere) const
+```
+
+检测球体是否完全在视锥体内。
+
+**参数：**
+- `sphere` - 要检测的球体
+
+**返回：** `bool` - 球体完全在视锥内返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+Sphere collider = object.GetBoundingSphere();
+if (frustum.Contains(collider)) {
+    // 球体完全在视锥内
+}
+```

docs/api/math/frustum/frustum.md

@@ -0,0 +1,45 @@
+# Frustum
+
+视锥体，用于视锥剔除。
+
+**头文件：** `#include <XCEngine/Math/Frustum.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 类定义
+
+```cpp
+class Frustum {
+public:
+    Plane planes[6];
+
+    enum class PlaneIndex {
+        Left = 0,
+        Right = 1,
+        Bottom = 2,
+        Top = 3,
+        Near = 4,
+        Far = 5
+    };
+
+    bool Contains(const Vector3& point) const;
+    bool Contains(const Sphere& sphere) const;
+    bool Contains(const Bounds& bounds) const;
+    bool Intersects(const Bounds& bounds) const;
+    bool Intersects(const Sphere& sphere) const;
+};
+```
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Contains(point)](contains-point.md) | `bool` | 点是否在视锥内 |
+| [Contains(sphere)](contains-sphere.md) | `bool` | 球体是否完全在视锥内 |
+| [Contains(bounds)](contains-bounds.md) | `bool` | Bounds 是否完全在视锥内 |
+| [Intersects(bounds)](intersects-bounds.md) | `bool` | Bounds 是否与视锥相交 |
+| [Intersects(sphere)](intersects-sphere.md) | `bool` | 球体是否与视锥相交 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/frustum/intersects-bounds.md

@@ -0,0 +1,26 @@
+# Frustum::Intersects (bounds)
+
+```cpp
+bool Intersects(const Bounds& bounds) const
+```
+
+检测轴对齐包围盒是否与视锥体相交。
+
+**参数：**
+- `bounds` - 要检测的轴对齐包围盒
+
+**返回：** `bool` - 与视锥相交返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+for (const auto& object : sceneObjects) {
+    if (frustum.Intersects(object.bounds)) {
+        // 物体与视锥相交，需要渲染
+        Render(object);
+    }
+}
+```

docs/api/math/frustum/intersects-sphere.md

@@ -0,0 +1,25 @@
+# Frustum::Intersects (sphere)
+
+```cpp
+bool Intersects(const Sphere& sphere) const
+```
+
+检测球体是否与视锥体相交。
+
+**参数：**
+- `sphere` - 要检测的球体
+
+**返回：** `bool` - 与视锥相交返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Frustum frustum = camera.CalculateFrustum();
+Sphere collider = object.GetBoundingSphere();
+if (frustum.Intersects(collider)) {
+    // 球体与视锥相交
+    Render(object);
+}
+```

docs/api/math/h/deg-to-rad.md

@@ -0,0 +1,20 @@
+# Math::DEG_TO_RAD
+
+```cpp
+constexpr float DEG_TO_RAD = Math::PI / 180.0f;
+```
+
+`DEG_TO_RAD` 是角度转弧度的转换系数。1 度等于 `PI / 180` 弧度，约等于 0.01745329251994329577。使用该常量将角度值乘以 `DEG_TO_RAD` 即可得到对应的弧度值。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float angleDegrees = 90.0f;
+float angleRadians = angleDegrees * Math::DEG_TO_RAD;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/degrees.md

@@ -0,0 +1,20 @@
+# Math::Degrees
+
+```cpp
+float Degrees(float radians);
+```
+
+`Degrees` 函数将弧度值转换为角度值。转换公式为：`角度 = 弧度 * (180 / PI)`。该函数是 `Radians` 函数的逆函数，常用于将三角函数的返回值或物理引擎中的弧度值转换为人机界面友好的角度值。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float radians = Math::HALF_PI;
+float degrees = Math::Degrees(radians);
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/epsilon.md

@@ -0,0 +1,23 @@
+# Math::EPSILON
+
+```cpp
+constexpr float EPSILON = 1e-6f;
+```
+
+`EPSILON` 是一个非常小的浮点数常量，值为 0.000001。该常量主要用于浮点数比较，由于浮点数精度问题，直接使用 `==` 比较浮点数可能产生错误结果，此时应使用 `EPSILON` 进行容差比较。例如判断两个浮点数是否相等，可以检查它们的差的绝对值是否小于 `EPSILON`。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float a = 0.1f + 0.2f;
+float b = 0.3f;
+if (Math::Abs(a - b) < Math::EPSILON) {
+    // a 和 b 可以视为相等
+}
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/float-max.md

@@ -0,0 +1,19 @@
+# Math::FLOAT_MAX
+
+```cpp
+constexpr float FLOAT_MAX = 3.402823466e+38f;
+```
+
+`FLOAT_MAX` 是 IEEE 754 单精度浮点数能表示的最大正有限值，约为 3.402823466e+38。该常量常用于初始化变量为最大值、在搜索算法中作为上界、或在需要表示"无穷大"但又不想引入 `INFINITY` 的场景中使用。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float maxDistance = Math::FLOAT_MAX;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/h.md

@@ -0,0 +1,54 @@
+# Math
+
+**命名空间**: `XCEngine::Math`
+
+**类型**: `header`
+
+**描述**: 数学库常量和辅助函数头文件。
+
+## 概述
+
+`Math.h` 提供了图形引擎常用的数学常量和辅助函数，包括圆周率、角度转换、浮点精度等基础常量，以及角度弧度转换等常用函数。
+
+## 常量
+
+| 常量 | 值 | 描述 |
+|------|-----|------|
+| [PI](pi.md) | 3.14159265358979323846f | 圆周率 |
+| [TWO_PI](two-pi.md) | 6.28318530717958647692f | 2π |
+| [HALF_PI](half-pi.md) | 1.57079632679489661923f | π/2 |
+| [DEG_TO_RAD](deg-to-rad.md) | PI / 180.0f | 度到弧度 |
+| [RAD_TO_DEG](rad-to-deg.md) | 180.0f / PI | 弧度到度 |
+| [EPSILON](epsilon.md) | 1e-6f | 浮点精度 |
+| [FLOAT_MAX](float-max.md) | 3.402823466e+38f | 浮点最大值 |
+
+## 辅助函数
+
+| 函数 | 描述 |
+|------|------|
+| [Radians](radians.md) | 度转弧度 |
+| [Degrees](degrees.md) | 弧度转度 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+using namespace XCEngine::Math;
+
+// 使用常量
+float angle = 90.0f * DEG_TO_RAD;  // 90度转弧度
+
+// 使用函数
+float rad = Radians(180.0f);        // 180度 -> π 弧度
+float deg = Degrees(Math::PI);      // π 弧度 -> 180度
+
+// 比较浮点数
+if (fabsf(a - b) < EPSILON) {
+    // 认为 a 和 b 相等
+}
+```
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/h/half-pi.md

@@ -0,0 +1,19 @@
+# Math::HALF_PI
+
+```cpp
+constexpr float HALF_PI = 1.57079632679489661923f;
+```
+
+`HALF_PI` 是圆周率除以 2，即 90 度对应的弧度值，约为 1.57079632679489661923。该常量常用于角度与弧度的转换、四分之一圆周计算等场景。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float ninetyDegreesRadians = Math::HALF_PI;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/pi.md

@@ -0,0 +1,22 @@
+# Math::PI
+
+```cpp
+constexpr float PI = 3.14159265358979323846f;
+```
+
+圆周率常量，精确到 float 能表示的最高精度。
+
+**用途：** 用于三角函数计算、弧度角度转换、圆形/弧度相关计算。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float circumference = 2.0f * Math::PI * radius;
+float area = Math::PI * radius * radius;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/rad-to-deg.md

@@ -0,0 +1,20 @@
+# Math::RAD_TO_DEG
+
+```cpp
+constexpr float RAD_TO_DEG = 180.0f / Math::PI;
+```
+
+`RAD_TO_DEG` 是弧度转角度的转换系数。1 弧度等于 `180 / PI` 度，约等于 57.29577951308232087685。使用该常量将弧度值乘以 `RAD_TO_DEG` 即可得到对应的角度值。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float radians = Math::HALF_PI;
+float degrees = radians * Math::RAD_TO_DEG;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/radians.md

@@ -0,0 +1,20 @@
+# Math::Radians
+
+```cpp
+float Radians(float degrees);
+```
+
+`Radians` 函数将角度值转换为弧度值。转换公式为：`弧度 = 角度 * (PI / 180)`。该函数是 `Degrees` 函数的逆函数，常用于将 UI 输入的角度值或游戏中的角度值转换为三角函数所需的弧度值。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float degrees = 90.0f;
+float radians = Math::Radians(degrees);
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/h/two-pi.md

@@ -0,0 +1,19 @@
+# Math::TWO_PI
+
+```cpp
+constexpr float TWO_PI = 6.28318530717958647692f;
+```
+
+`TWO_PI` 是圆周率的两倍，即完整的圆周长对应的弧度值，约为 6.28318530717958647692。该常量常用于需要完整圆周旋转的场景，例如角度归一化、三角函数周期计算、圆形运动等。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Math.h>
+
+float fullCircleRadians = Math::TWO_PI;
+```
+
+## 相关文档
+
+- [Math 总览](h.md) - 返回 Math 概览

docs/api/math/math-aabb.md

@@ -1,67 +0,0 @@
-# AABB / OBB
-
-轴对齐包围盒 (AABB) 和有向包围盒 (OBB)。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/AABB.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## AABB - 轴对齐包围盒
-
-`AABB` 在 Math 库中通过 `Bounds` 类型实现，参见 [math-bounds.md](math-bounds.md)。
-
-## OBB - 有向包围盒
-
-OBB 是可以任意方向旋转的包围盒。
-
-```cpp
-struct OBB {
-    Vector3 center;
-    Vector3 extents;     // 半长
-    Matrix4 transform;    // 变换矩阵
-};
-```
-
-### 构造函数
-
-- `OBB()` - 默认构造
-- `OBB(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
-
-### 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `GetAxis(index)` | `Vector3` | 获取局部轴 (0=X, 1=Y, 2=Z) |
-| `GetMin()` | `Vector3` | 局部空间最小点 |
-| `GetMax()` | `Vector3` | 局部空间最大点 |
-| `Contains(point)` | `bool` | 点是否在 OBB 内 |
-| `Intersects(OBB)` | `bool` | 与另一个 OBB 相交 (SAT) |
-| `Intersects(Sphere)` | `bool` | 与球体相交 |
-
-## 备注
-
-- AABB 与轴对齐，检测简单但可能不够紧凑
-- OBB 可旋转，检测使用分离轴定理 (SAT)
-- OBB 适合动态旋转的物体
-
-## 使用示例
-
-```cpp
-// OBB
-OBB obb;
-obb.center = Vector3(0.0f);
-obb.extents = Vector3(1.0f);
-obb.transform = Matrix4::TRS(pos, rot, scale);
-
-Vector3 localAxis = obb.GetAxis(0);
-
-if (obb.Contains(point)) { ... }
-if (obb.Intersects(otherOBB)) { ... }
-if (obb.Intersects(sphere)) { ... }
-```

docs/api/math/math-bounds.md

@@ -1,61 +0,0 @@
-# Bounds
-
-轴对齐包围盒 (AABB)，中心-范围表示。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Bounds.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Bounds {
-    Vector3 center = Vector3::Zero();
-    Vector3 extents = Vector3::Zero();  // 半长，不是最大点
-};
-```
-
-## 构造函数
-
-- `Bounds()` - 默认构造
-- `Bounds(const Vector3& center, const Vector3& size)` - 从中心和大小构造
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `GetMin()` | `Vector3` | 最小点: `center - extents` |
-| `GetMax()` | `Vector3` | 最大点: `center + extents` |
-| `SetMinMax(min, max)` | `void` | 从最小/最大点设置 |
-| `Contains(point)` | `bool` | 点是否在盒内 |
-| `Intersects(other)` | `bool` | 与另一个 Bounds 相交 |
-| `Encapsulate(point)` | `void` | 扩展包含点 |
-| `Encapsulate(bounds)` | `void` | 扩展包含另一个 Bounds |
-| `Expand(amount)` | `void` | 各方向扩展 amount |
-| `Expand(amount)` | `void` | 按 Vector3 扩展 |
-| `GetClosestPoint(point)` | `Vector3` | 盒上最接近给定点的点 |
-| `GetVolume()` | `float` | 体积 |
-
-## 使用示例
-
-```cpp
-Bounds bounds(center, extents);
-
-// 包含点
-if (bounds.Contains(point)) { ... }
-
-// 扩展包围盒
-bounds.Encapsulate(newPoint);
-
-// 相交检测
-if (bounds.Intersects(other)) { ... }
-
-// 设置
-bounds.SetMinMax(minPoint, maxPoint);
-```

docs/api/math/math-box.md

@@ -1,63 +0,0 @@
-# Box
-
-带变换的有向包围盒 (OBB) 结构体。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Box.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Box {
-    Vector3 center = Vector3::Zero();
-    Vector3 extents = Vector3::Zero();      // 半长
-    Matrix4x4 transform = Matrix4x4::Identity();
-};
-```
-
-OBB 由中心点、半长向量和变换矩阵定义。
-
-## 构造函数
-
-- `Box()` - 默认构造
-- `Box(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `GetMin()` | `Vector3` | 局部空间最小点 (-extents) |
-| `GetMax()` | `Vector3` | 局部空间最大点 (+extents) |
-| `Contains(point)` | `bool` | 点是否在盒内（变换到局部空间检测） |
-| `Intersects(Sphere)` | `bool` | 与球体相交 |
-| `Intersects(Box)` | `bool` | 与另一个 OBB 相交（SAT 算法） |
-| `Intersects(Ray, t)` | `bool` | 与射线相交，输出距离 t |
-
-## 使用示例
-
-```cpp
-Box box(Vector3(0.0f), Vector3(1.0f));  // 2x2x2 盒子
-box.transform = Matrix4::TRS(position, rotation, scale);
-
-// 点检测
-if (box.Contains(testPoint)) { ... }
-
-// 球体相交
-if (box.Intersects(sphere)) { ... }
-
-// OBB 相交
-if (box.Intersects(otherBox)) { ... }
-
-// 射线相交
-float t;
-if (box.Intersects(ray, t)) {
-    Vector3 hit = ray.GetPoint(t);
-}
-```

docs/api/math/math-color.md

@@ -1,72 +0,0 @@
-# Color
-
-颜色结构体，支持 RGBA 浮点分量。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Color.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Color {
-    float r = 1.0f;
-    float g = 1.0f;
-    float b = 1.0f;
-    float a = 1.0f;
-};
-```
-
-分量范围: 0.0f ~ 1.0f
-
-## 静态工厂方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `White()` | `Color` | (1, 1, 1, 1) |
-| `Black()` | `Color` | (0, 0, 0, 1) |
-| `Red()` | `Color` | (1, 0, 0, 1) |
-| `Green()` | `Color` | (0, 1, 0, 1) |
-| `Blue()` | `Color` | (0, 0, 1, 1) |
-| `Yellow()` | `Color` | (1, 1, 0, 1) |
-| `Cyan()` | `Color` | (0, 1, 1, 1) |
-| `Magenta()` | `Color` | (1, 0, 1, 1) |
-| `Clear()` | `Color` | (0, 0, 0, 0)，透明黑 |
-
-## 静态方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Lerp(a, b, t)` | `Color` | 颜色线性插值 |
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `ToRGBA()` | `uint32_t` | 转换为 32-bit RGBA (0xAABBGGRR) |
-| `ToVector3()` | `Vector3` | 转换为 RGB (丢弃 alpha) |
-| `ToVector4()` | `Vector4` | 转换为 RGBA |
-
-## 运算符
-
-| 运算符 | 描述 |
-|--------|------|
-| `operator+(Color, Color)` | 颜色相加 |
-| `operator-(Color, Color)` | 颜色相减 |
-| `operator*(Color, float)` | 颜色乘以标量 |
-| `operator/(Color, float)` | 颜色除以标量 |
-
-## 使用示例
-
-```cpp
-Color red = Color::Red();
-Color lerped = Color::Lerp(red, Color::Blue(), 0.5f);
-uint32_t rgba = lerped.ToRGBA();
-Vector4 v4 = lerped.ToVector4();
-```

docs/api/math/math-frustum.md

@@ -1,61 +0,0 @@
-# Frustum
-
-视锥体，用于视锥剔除。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Frustum.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-class Frustum {
-public:
-    Plane planes[6];  // 6 个裁剪平面
-
-    enum class PlaneIndex {
-        Left = 0,
-        Right = 1,
-        Bottom = 2,
-        Top = 3,
-        Near = 4,
-        Far = 5
-    };
-};
-```
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Contains(point)` | `bool` | 点是否在视锥内 |
-| `Contains(Sphere)` | `bool` | 球体是否在视锥内 |
-| `Contains(Bounds)` | `bool` | Bounds 是否在视锥内 |
-| `Intersects(Bounds)` | `bool` | Bounds 是否与视锥相交 |
-| `Intersects(Sphere)` | `bool` | 球体是否与视锥相交 |
-
-## 使用示例
-
-```cpp
-Frustum frustum;
-// 需要从相机矩阵构建视锥平面
-
-// 视锥剔除
-for (const auto& object : objects) {
-    if (frustum.Contains(object.bounds)) {
-        // 物体在视锥内，渲染
-        Render(object);
-    }
-}
-
-// 或使用相交检测
-if (frustum.Intersects(bounds)) {
-    Render(object);
-}
-```

docs/api/math/math-h.md

@@ -1,51 +0,0 @@
-# Math - 数学常量
-
-数学库全局常量和辅助函数。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Math.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 数学常量
-
-| 常量 | 值 | 描述 |
-|------|-----|------|
-| `PI` | 3.14159265358979323846f | 圆周率 |
-| `TWO_PI` | 6.28318530717958647692f | 2π |
-| `HALF_PI` | 1.57079632679489661923f | π/2 |
-| `DEG_TO_RAD` | PI / 180.0f | 度转弧度 |
-| `RAD_TO_DEG` | 180.0f / PI | 弧度转度 |
-| `EPSILON` | 1e-6f | 浮点比较容差 |
-| `FLOAT_MAX` | 3.402823466e+38f | float 最大值 |
-
-## 辅助函数
-
-| 函数 | 返回值 | 描述 |
-|------|--------|------|
-| `Radians(degrees)` | `float` | 度转弧度 |
-| `Degrees(radians)` | `float` | 弧度转度 |
-
-## 使用示例
-
-```cpp
-using namespace XCEngine::Math;
-
-float radians = 90.0f * DEG_TO_RAD;    // 90度 -> 弧度
-float degrees = PI * RAD_TO_DEG;        // 弧度 -> 度
-float rad2 = Radians(45.0f);           // 使用函数
-
-// 浮点比较
-if (std::abs(a - b) < EPSILON) {
-    // a 和 b 相等
-}
-
-// 三角函数（来自 <cmath>）
-float sinVal = std::sin(angle);
-float cosVal = std::cos(angle);
-```

docs/api/math/math-matrix3.md

@@ -1,69 +0,0 @@
-# Matrix3 / Matrix3x3
-
-3x3 矩阵结构体，用于表示 3D 旋转和缩放变换。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Matrix3.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 类型别名
-
-```cpp
-using Matrix3 = Matrix3x3;
-```
-
-## 存储方式
-
-行优先存储 (row-major)：
-```
-m[row][col]
-m[0][0] m[0][1] m[0][2]
-m[1][0] m[1][1] m[1][2]
-m[2][0] m[2][1] m[2][2]
-```
-
-## 构造函数
-
-- 默认构造函数初始化为零矩阵
-
-## 静态工厂方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Identity()` | `Matrix3` | 单位矩阵 |
-| `Zero()` | `Matrix3` | 零矩阵 |
-| `RotationX(float radians)` | `Matrix3` | X 轴旋转矩阵 |
-| `RotationY(float radians)` | `Matrix3` | Y 轴旋转矩阵 |
-| `RotationZ(float radians)` | `Matrix3` | Z 轴旋转矩阵 |
-| `Scale(const Vector3& scale)` | `Matrix3` | 缩放矩阵 |
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Transpose()` | `Matrix3` | 转置矩阵 |
-| `Inverse()` | `Matrix3` | 逆矩阵 |
-| `Determinant()` | `float` | 行列式 |
-
-## 运算符
-
-| 运算符 | 描述 |
-|--------|------|
-| `operator*(Matrix3, Matrix3)` | 矩阵乘法 |
-| `operator*(Matrix3, Vector3)` | 矩阵-向量乘法 |
-
-## 使用示例
-
-```cpp
-Matrix3 rotX = Matrix3::RotationX(Math::HALF_PI);
-Matrix3 rotY = Matrix3::RotationY(0.0f);
-Matrix3 scale = Matrix3::Scale(Vector3(2.0f, 2.0f, 2.0f));
-Matrix3 combined = rotX * scale;
-Vector3 transformed = combined * Vector3(1.0f, 0.0f, 0.0f);
-```

docs/api/math/math-matrix4.md

@@ -1,101 +0,0 @@
-# Matrix4 / Matrix4x4
-
-4x4 矩阵结构体，用于表示完整的 3D 变换（平移、旋转、缩放）、视图和投影变换。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Matrix4.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 类型别名
-
-```cpp
-using Matrix4 = Matrix4x4;
-```
-
-## 存储方式
-
-行优先存储 (row-major)：
-```
-m[0][0] m[0][1] m[0][2] m[0][3]
-m[1][0] m[1][1] m[1][2] m[1][3]
-m[2][0] m[2][1] m[2][2] m[2][3]
-m[3][0] m[3][1] m[3][2] m[3][3]
-```
-
-## 静态工厂方法
-
-### 基础变换
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Identity()` | `Matrix4` | 单位矩阵 |
-| `Zero()` | `Matrix4` | 零矩阵 |
-| `Translation(const Vector3& v)` | `Matrix4` | 平移矩阵 |
-| `Scale(const Vector3& v)` | `Matrix4` | 缩放矩阵 |
-| `Rotation(const Quaternion& q)` | `Matrix4` | 旋转矩阵（四元数） |
-| `TRS(translation, rotation, scale)` | `Matrix4` | 完整变换 |
-
-### 旋转
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `RotationX(float radians)` | `Matrix4` | X 轴旋转 |
-| `RotationY(float radians)` | `Matrix4` | Y 轴旋转 |
-| `RotationZ(float radians)` | `Matrix4` | Z 轴旋转 |
-
-### 相机变换
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `LookAt(eye, target, up)` | `Matrix4` | 视图矩阵 |
-| `Perspective(fov, aspect, near, far)` | `Matrix4` | 透视投影 |
-| `Orthographic(left, right, bottom, top, near, far)` | `Matrix4` | 正交投影 |
-
-## 实例方法
-
-### 乘法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `operator*(Matrix4, Matrix4)` | `Matrix4` | 矩阵乘法 |
-| `operator*(Matrix4, Vector4)` | `Vector4` | 矩阵-向量乘法 |
-| `MultiplyPoint(v)` | `Vector3` | 点变换（带平移） |
-| `MultiplyVector(v)` | `Vector3` | 方向变换（不带平移） |
-
-### 分解
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Transpose()` | `Matrix4` | 转置矩阵 |
-| `Inverse()` | `Matrix4` | 逆矩阵 |
-| `Determinant()` | `float` | 行列式 |
-| `GetTranslation()` | `Vector3` | 获取平移分量 |
-| `GetRotation()` | `Quaternion` | 获取旋转分量 |
-| `GetScale()` | `Vector3` | 获取缩放分量 |
-| `Decompose(translation, rotation, scale)` | `void` | 分解所有分量 |
-
-## 使用示例
-
-```cpp
-// MVP 矩阵
-Matrix4 model = Matrix4::TRS(position, rotation, scale);
-Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up());
-Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f);
-Matrix4 mvp = proj * view * model;
-
-// 变换点
-Vector3 worldPos = model.MultiplyPoint(localPos);
-Vector3 worldDir = model.MultiplyVector(localDir);
-
-// 分解矩阵
-Vector3 translation;
-Quaternion rotation;
-Vector3 scale;
-model.Decompose(translation, rotation, scale);
-```

docs/api/math/math-plane.md

@@ -1,66 +0,0 @@
-# Plane
-
-3D 平面结构体，由法线和距离表示。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Plane.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Plane {
-    Vector3 normal = Vector3::Up();  // 单位法线
-    float distance = 0.0f;           // 原点到平面的有符号距离
-};
-```
-
-平面方程: `dot(normal, X) + distance = 0`
-
-## 构造函数
-
-- `Plane()` - 默认构造 (y=0 平面)
-- `Plane(const Vector3& normal, float distance)` - 从法线和距离构造
-
-## 静态工厂方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `FromPoints(a, b, c)` | `Plane` | 从三个不共线点创建 |
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `GetDistanceToPoint(point)` | `float` | 点到平面的有符号距离 |
-| `GetClosestPoint(point)` | `Vector3` | 平面上最接近给定点的点 |
-| `GetSide(point)` | `bool` | 点在平面的哪一侧 (true=正面) |
-| `Intersects(Sphere)` | `bool` | 与球体相交 |
-
-## 使用示例
-
-```cpp
-// 创建平面
-Plane floor;
-floor.normal = Vector3::Up();
-floor.distance = 0.0f;  // y=0 平面
-
-// 或者从三点创建
-Plane plane = Plane::FromPoints(p0, p1, p2);
-
-// 检测点在哪侧
-bool above = floor.GetSide(point);
-float signedDist = floor.GetDistanceToPoint(point);
-
-// 投影点到平面
-Vector3 closest = floor.GetClosestPoint(point);
-
-// 平面相交检测
-if (plane.Intersects(sphere)) { ... }
-```

docs/api/math/math-quaternion.md

@@ -1,86 +0,0 @@
-# Quaternion
-
-四元数结构体，用于表示 3D 旋转，避免欧拉角的万向锁问题。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Quaternion.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Quaternion {
-    float x = 0.0f;
-    float y = 0.0f;
-    float z = 0.0f;
-    float w = 1.0f;  // w 是标量分量
-};
-```
-
-四元数格式: `(x, y, z, w)` = `(vec, w)`
-
-## 静态工厂方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Identity()` | `Quaternion` | 返回 (0, 0, 0, 1)，恒等旋转 |
-| `FromAxisAngle(axis, radians)` | `Quaternion` | 从轴角创建 |
-| `FromEulerAngles(pitch, yaw, roll)` | `Quaternion` | 从欧拉角创建（弧度） |
-| `FromEulerAngles(euler)` | `Quaternion` | 从 Vector3 欧拉角创建 |
-| `FromRotationMatrix(matrix)` | `Quaternion` | 从旋转矩阵创建 |
-| `Slerp(a, b, t)` | `Quaternion` | 球面线性插值 |
-| `LookRotation(forward, up)` | `Quaternion` | 看向方向 |
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `ToEulerAngles()` | `Vector3` | 转换为欧拉角（弧度） |
-| `ToMatrix4x4()` | `Matrix4` | 转换为 4x4 旋转矩阵 |
-| `Inverse()` | `Quaternion` | 共轭/逆四元数 |
-| `Dot(other)` | `float` | 点积 |
-| `Magnitude()` | `float` | 模长 |
-| `Normalized()` | `Quaternion` | 归一化 |
-| `Normalize(q)` | `Quaternion` | 归一化（静态） |
-
-## 运算符
-
-| 运算符 | 描述 |
-|--------|------|
-| `operator*(Quaternion, Quaternion)` | 组合旋转 |
-
-## 与 Vector3 的乘法
-
-```cpp
-Vector3 operator*(const Quaternion& q, const Vector3& v);
-```
-用四元数旋转向量。
-
-## 使用示例
-
-```cpp
-// 创建旋转
-Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f);
-
-// 组合旋转
-Quaternion combined = rot1 * rot2;
-
-// 球面插值
-Quaternion lerped = Quaternion::Slerp(rot1, rot2, 0.5f);
-
-// 旋转向量
-Vector3 rotated = rot * Vector3::Forward();
-
-// 转换
-Vector3 euler = rot.ToEulerAngles();
-Matrix4 mat = rot.ToMatrix4x4();
-
-// 看向目标
-Quaternion lookAt = Quaternion::LookRotation(target - position);
-```

docs/api/math/math-ray.md

@@ -1,58 +0,0 @@
-# Ray
-
-3D 射线结构体，用于光线投射和拾取。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Ray.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Ray {
-    Vector3 origin;      // 射线起点
-    Vector3 direction;   // 归一化方向
-};
-```
-
-## 构造函数
-
-- `Ray()` - 默认构造
-- `Ray(const Vector3& origin, const Vector3& direction)` - 从点和方向构造
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `GetPoint(t)` | `Vector3` | 获取射线上 t 距离处的点: `origin + direction * t` |
-
-## 相交检测
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Intersects(Sphere, t)` | `bool` | 与球体相交，输出距离 t |
-| `Intersects(Box, t)` | `bool` | 与 AABB 相交，输出距离 t |
-| `Intersects(Plane, t)` | `bool` | 与平面相交，输出距离 t |
-
-## 使用示例
-
-```cpp
-Ray ray(cameraPosition, rayDirection);
-
-// 与球体相交
-float t;
-if (ray.Intersects(sphere, t)) {
-    Vector3 hitPoint = ray.GetPoint(t);
-}
-
-// 与平面相交
-if (ray.Intersects(plane, t)) {
-    Vector3 hitPoint = ray.GetPoint(t);
-}
-```

docs/api/math/math-rect.md

@@ -1,137 +0,0 @@
-# Rect / RectInt / Viewport
-
-2D 矩形和视口结构体。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Rect.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
----
-
-## Rect - 浮点矩形
-
-```cpp
-struct Rect {
-    float x = 0.0f;      // 左边界
-    float y = 0.0f;      // 上边界
-    float width = 0.0f;
-    float height = 0.0f;
-};
-```
-
-### 构造
-
-- `Rect(float x, float y, float w, float h)`
-
-### 边界访问
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `GetLeft()` | `float` | x |
-| `GetRight()` | `float` | x + width |
-| `GetTop()` | `float` | y |
-| `GetBottom()` | `float` | y + height |
-| `GetPosition()` | `Vector2` | (x, y) |
-| `GetSize()` | `Vector2` | (width, height) |
-| `GetCenter()` | `Vector2` | 中心点 |
-
-### 检测方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Contains(px, py)` | `bool` | 点是否在矩形内 |
-| `Contains(point)` | `bool` | Vector2 点检测 |
-| `Intersects(other)` | `bool` | 与另一矩形相交 |
-
-### 静态方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Intersect(a, b)` | `Rect` | 两矩形交集 |
-| `Union(a, b)` | `Rect` | 两矩形并集 |
-
-### 设置方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Set(x, y, w, h)` | `void` | 设置所有值 |
-| `SetPosition(x, y)` | `void` | 设置位置 |
-| `SetPosition(Vector2)` | `void` | 设置位置 |
-
----
-
-## RectInt - 整数矩形
-
-```cpp
-struct RectInt {
-    int32_t x = 0;
-    int32_t y = 0;
-    int32_t width = 0;
-    int32_t height = 0;
-};
-```
-
-与 Rect 类似，但使用 int32_t 类型。
-
-### 边界访问
-
-`GetLeft/Right/Top/Bottom/GetPosition/GetSize/GetCenter` - 返回 int32_t 或 Vector2。
-
-### 检测
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Contains(px, py)` | `bool` | 整数点检测 |
-| `Intersects(other)` | `bool` | 相交检测 |
-
----
-
-## Viewport - 视口
-
-用于渲染视口和屏幕映射。
-
-```cpp
-struct Viewport {
-    float x = 0.0f;
-    float y = 0.0f;
-    float width = 0.0f;
-    float height = 0.0f;
-    float minDepth = 0.0f;
-    float maxDepth = 1.0f;
-};
-```
-
-### 构造
-
-- `Viewport(float x, float y, float w, float h)`
-- `Viewport(float x, float y, float w, float h, float minD, float maxD)`
-
-### 方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `GetAspectRatio()` | `float` | 宽高比 (width/height) |
-| `GetRect()` | `Rect` | 转换为 Rect |
-
----
-
-## 使用示例
-
-```cpp
-// Rect
-Rect screenRect(0.0f, 0.0f, 1920.0f, 1080.0f);
-if (screenRect.Contains(mouseX, mouseY)) { ... }
-
-// 矩形相交
-Rect overlap = Rect::Intersect(rectA, rectB);
-
-// Viewport
-Viewport viewport(0, 0, 1920, 1080);
-float aspect = viewport.GetAspectRatio();  // 16:9 = 1.78
-```

docs/api/math/math-sphere.md

@@ -1,47 +0,0 @@
-# Sphere
-
-3D 球体结构体。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Sphere.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Sphere {
-    Vector3 center = Vector3::Zero();
-    float radius = 0.0f;
-};
-```
-
-## 构造函数
-
-- `Sphere()` - 默认构造
-- `Sphere(const Vector3& center, float radius)` - 从中心和半径构造
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Contains(point)` | `bool` | 点是否在球体内（包括表面） |
-| `Intersects(other)` | `bool` | 与另一个球体是否相交 |
-
-## 使用示例
-
-```cpp
-Sphere sphere(Vector3(0.0f, 0.0f, 0.0f), 1.0f);
-
-// 检测点
-if (sphere.Contains(Vector3(0.5f, 0.0f, 0.0f))) { ... }
-
-// 检测球体相交
-Sphere other(Vector3(1.0f, 0.0f, 0.0f), 1.0f);
-if (sphere.Intersects(other)) { ... }
-```

docs/api/math/math-transform.md

@@ -1,67 +0,0 @@
-# Transform
-
-3D 变换结构体，包含位置、旋转和缩放，用于层次化变换。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Transform.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## Space 枚举
-
-```cpp
-enum class Space { Self, World };
-```
-
-## 结构体定义
-
-```cpp
-struct Transform {
-    Vector3 position = Vector3::Zero();
-    Quaternion rotation = Quaternion::Identity();
-    Vector3 scale = Vector3::One();
-};
-```
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `ToMatrix()` | `Matrix4` | 转换为 4x4 变换矩阵 |
-| `Inverse()` | `Transform` | 逆变换 |
-| `operator*(Transform, Transform)` | `Transform` | 组合变换 |
-
-### 空间变换
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `TransformPoint(point)` | `Vector3` | 变换点（带平移） |
-| `TransformDirection(direction)` | `Vector3` | 变换方向（不带平移） |
-| `InverseTransformPoint(point)` | `Vector3` | 逆变换点 |
-| `InverseTransformDirection(direction)` | `Vector3` | 逆变换方向 |
-
-## 使用示例
-
-```cpp
-Transform world;
-world.position = Vector3(10.0f, 0.0f, 0.0f);
-world.rotation = Quaternion::Identity();
-world.scale = Vector3::One();
-
-Matrix4 matrix = world.ToMatrix();
-
-// 组合父子变换
-Transform parent, child;
-parent.position = Vector3(5.0f, 0.0f, 0.0f);
-child.position = Vector3(2.0f, 0.0f, 0.0f);
-Transform worldTransform = parent * child;
-
-// 变换点
-Vector3 localPos(1.0f, 0.0f, 0.0f);
-Vector3 worldPos = world.TransformPoint(localPos);
-```

docs/api/math/math-vector2.md

@@ -1,68 +0,0 @@
-# Vector2
-
-2D 向量结构体，用于表示 2D 空间中的点、方向或颜色。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Vector2.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Vector2 {
-    float x = 0.0f;
-    float y = 0.0f;
-};
-```
-
-## 静态工厂方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Zero()` | `Vector2` | 返回 (0, 0) |
-| `One()` | `Vector2` | 返回 (1, 1) |
-| `Up()` | `Vector2` | 返回 (0, 1)，上方向 |
-| `Down()` | `Vector2` | 返回 (0, -1)，下方向 |
-| `Right()` | `Vector2` | 返回 (1, 0)，右方向 |
-| `Left()` | `Vector2` | 返回 (-1, 0)，左方向 |
-
-## 静态数学方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Dot(a, b)` | `float` | 点积 |
-| `Cross(a, b)` | `float` | 2D 叉积（返回标量） |
-| `Normalize(v)` | `Vector2` | 归一化向量 |
-| `Magnitude(v)` | `float` | 向量长度 |
-| `SqrMagnitude(v)` | `float` | 长度平方（更快） |
-| `Lerp(a, b, t)` | `Vector2` | 线性插值 |
-| `MoveTowards(current, target, maxDistance)` | `Vector2` | 朝目标移动 |
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Magnitude()` | `float` | 获取向量长度 |
-| `SqrMagnitude()` | `float` | 获取长度平方 |
-| `Normalized()` | `Vector2` | 获取归一化副本 |
-
-## 运算符
-
-- 算术: `+`, `-`, `*` (scalar), `/` (scalar)
-- 复合赋值: `+=`, `-=`, `*=`, `/=`
-- 比较: `==`, `!=`
-
-## 使用示例
-
-```cpp
-Vector2 pos(5.0f, 3.0f);
-Vector2 dir = Vector2::Normalize(pos);
-float len = pos.Magnitude();
-Vector2 lerped = Vector2::Lerp(pos, Vector2::Zero(), 0.5f);
-```

docs/api/math/math-vector3.md

@@ -1,84 +0,0 @@
-# Vector3
-
-3D 向量结构体，用于表示 3D 空间中的点、方向、颜色或法线。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Math/Vector3.h>
-```
-
-## 命名空间
-
-`XCEngine::Math`
-
-## 结构体定义
-
-```cpp
-struct Vector3 {
-    float x = 0.0f;
-    float y = 0.0f;
-    float z = 0.0f;
-};
-```
-
-## 静态工厂方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Zero()` | `Vector3` | 返回 (0, 0, 0) |
-| `One()` | `Vector3` | 返回 (1, 1, 1) |
-| `Forward()` | `Vector3` | 返回 (0, 0, 1)，前方向（Z+） |
-| `Back()` | `Vector3` | 返回 (0, 0, -1)，后方向 |
-| `Up()` | `Vector3` | 返回 (0, 1, 0)，上方向 |
-| `Down()` | `Vector3` | 返回 (0, -1, 0)，下方向 |
-| `Right()` | `Vector3` | 返回 (1, 0, 0)，右方向 |
-| `Left()` | `Vector3` | 返回 (-1, 0, 0)，左方向 |
-
-## 静态数学方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Dot(a, b)` | `float` | 点积 |
-| `Cross(a, b)` | `Vector3` | 叉积（垂直于 a 和 b） |
-| `Normalize(v)` | `Vector3` | 归一化向量 |
-| `Magnitude(v)` | `float` | 向量长度 |
-| `SqrMagnitude(v)` | `float` | 长度平方 |
-| `Lerp(a, b, t)` | `Vector3` | 线性插值 |
-| `MoveTowards(current, target, maxDistance)` | `Vector3` | 朝目标移动 |
-| `Project(vector, onNormal)` | `Vector3` | 投影到法线上 |
-| `ProjectOnPlane(vector, planeNormal)` | `Vector3` | 投影到平面上 |
-| `Angle(from, to)` | `float` | 两向量夹角（度） |
-| `Reflect(inDirection, inNormal)` | `Vector3` | 反射 |
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| `Magnitude()` | `float` | 获取向量长度 |
-| `SqrMagnitude()` | `float` | 获取长度平方 |
-| `Normalized()` | `Vector3` | 获取归一化副本 |
-
-## 运算符
-
-- 算术: `+`, `-`, `*` (scalar/memberwise), `/` (scalar/memberwise)
-- 复合赋值: `+=`, `-=`, `*=`, `/=`
-- 下标: `operator[]` (0=x, 1=y, 2=z)
-- 比较: `==`, `!=`
-
-## 与 Quaternion 的乘法
-
-```cpp
-Vector3 operator*(const Quaternion& q, const Vector3& v);
-```
-用四元数旋转向量。
-
-## 使用示例
-
-```cpp
-Vector3 pos(1.0f, 2.0f, 3.0f);
-Vector3 dir = Vector3::Normalize(pos);
-float len = pos.Magnitude();
-Vector3 reflected = Vector3::Reflect(dir, Vector3::Up());
-float angle = Vector3::Angle(Vector3::Forward(), dir);
-```

docs/api/math/math.md

@@ -16,37 +16,37 @@ Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四
 
 | 组件 | 文件 | 描述 |
 |------|------|------|
-| [Vector2](./math-vector2.md) | `Vector2.h` | 二维向量 |
-| [Vector3](./math-vector3.md) | `Vector3.h` | 三维向量 |
-| [Vector4](./math-vector4.md) | `Vector4.h` | 四维向量 |
+| [Vector2](vector2/vector2.md) | `Vector2.h` | 二维向量 |
+| [Vector3](vector3/vector3.md) | `Vector3.h` | 三维向量 |
+| [Vector4](vector4/vector4.md) | `Vector4.h` | 四维向量 |
 
 ### 矩阵类型
 
 | 组件 | 文件 | 描述 |
 |------|------|------|
-| [Matrix3](./math-matrix3.md) | `Matrix3.h` | 3x3 矩阵 |
-| [Matrix4](./math-matrix4.md) | `Matrix4.h` | 4x4 矩阵 |
+| [Matrix3](matrix3/matrix3.md) | `Matrix3.h` | 3x3 矩阵 |
+| [Matrix4](matrix4/matrix4.md) | `Matrix4.h` | 4x4 矩阵 |
 
 ### 旋转/变换
 
 | 组件 | 文件 | 描述 |
 |------|------|------|
-| [Quaternion](./math-quaternion.md) | `Quaternion.h` | 四元数 |
-| [Transform](./math-transform.md) | `Transform.h` | 变换组件 |
+| [Quaternion](quaternion/quaternion.md) | `Quaternion.h` | 四元数 |
+| [Transform](transform/transform.md) | `Transform.h` | 变换组件 |
 
 ### 几何类型
 
 | 组件 | 文件 | 描述 |
 |------|------|------|
-| [Color](./math-color.md) | `Color.h` | 颜色 |
-| [Ray](./math-ray.md) | `Ray.h` | 射线 |
-| [Plane](./math-plane.md) | `Plane.h` | 平面 |
-| [Sphere](./math-sphere.md) | `Sphere.h` | 球体 |
-| [Box](./math-box.md) | `Box.h` | 盒子 |
-| [Bounds](./math-bounds.md) | `Bounds.h` | 包围盒 |
-| [AABB](./math-aabb.md) | `AABB.h` | 轴对齐包围盒 |
-| [Frustum](./math-frustum.md) | `Frustum.h` | 视锥体 |
-| [Rect](./math-rect.md) | `Rect.h` | 二维矩形 |
+| [Color](color/color.md) | `Color.h` | 颜色 |
+| [Ray](ray/ray.md) | `Ray.h` | 射线 |
+| [Plane](plane/plane.md) | `Plane.h` | 平面 |
+| [Sphere](sphere/sphere.md) | `Sphere.h` | 球体 |
+| [Box](box/box.md) | `Box.h` | 盒子 |
+| [Bounds](bounds/bounds.md) | `Bounds.h` | 包围盒 |
+| [AABB](aabb/aabb.md) | `AABB.h` | 轴对齐包围盒 |
+| [Frustum](frustum/frustum.md) | `Frustum.h` | 视锥体 |
+| [Rect](rect/rect.md) | `Rect.h` | 二维矩形 |
 
 ## 常量定义
 
@@ -60,7 +60,7 @@ Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四
 | `EPSILON` | 1e-6f | 浮点精度 |
 | `FLOAT_MAX` | 3.402823466e+38f | 浮点最大值 |
 
-详细文档: [Math.h - 常量和辅助函数](./math-h.md)
+详细文档: [Math.h - 常量和辅助函数](h/h.md)
 
 ## 辅助函数
 
@@ -93,7 +93,7 @@ Matrix4 projection = Matrix4::Perspective(fov, aspect, near, far);
 Matrix4 mvp = projection * view * model;
 
 // 四元数运算
-Quaternion q1 = Quaternion::FromEuler(0, 90, 0);
+Quaternion q1 = Quaternion::FromEulerAngles(0, 90 * DEG_TO_RAD, 0);
 Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(45.0f));
 Quaternion combined = q1 * q2;
 Vector3 rotated = q2 * Vector3::Forward();

docs/api/math/matrix3/determinant.md

@@ -0,0 +1,18 @@
+# Matrix3::Determinant
+
+```cpp
+float Determinant() const
+```
+
+计算矩阵的行列式。
+
+**返回：** `float` - 行列式值
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 mat = ...;
+float det = mat.Determinant();
+```

docs/api/math/matrix3/identity.md

@@ -0,0 +1,17 @@
+# Matrix3::Identity
+
+```cpp
+static Matrix3 Identity()
+```
+
+返回 3x3 单位矩阵。
+
+**返回：** `Matrix3` - 单位矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 identity = Matrix3::Identity();
+```

docs/api/math/matrix3/inverse.md

@@ -0,0 +1,18 @@
+# Matrix3::Inverse
+
+```cpp
+Matrix3 Inverse() const
+```
+
+返回矩阵的逆矩阵。
+
+**返回：** `Matrix3` - 逆矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 mat = ...;
+Matrix3 inv = mat.Inverse();
+```

docs/api/math/matrix3/matrix3.md

@@ -0,0 +1,57 @@
+# Matrix3 / Matrix3x3
+
+3x3 矩阵结构体，用于表示 3D 旋转和缩放变换。
+
+**头文件：** `#include <XCEngine/Math/Matrix3.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 类型别名
+
+```cpp
+using Matrix3 = Matrix3x3;
+```
+
+## 存储方式
+
+行优先存储 (row-major)：
+```
+m[row][col]
+m[0][0] m[0][1] m[0][2]
+m[1][0] m[1][1] m[1][2]
+m[2][0] m[2][1] m[2][2]
+```
+
+## 构造函数
+
+- 默认构造函数初始化为零矩阵
+
+## 静态工厂方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Identity()](identity.md) | `Matrix3` | 单位矩阵 |
+| [Zero()](zero.md) | `Matrix3` | 零矩阵 |
+| [RotationX(radians)](rotationx.md) | `Matrix3` | X 轴旋转矩阵 |
+| [RotationY(radians)](rotationy.md) | `Matrix3` | Y 轴旋转矩阵 |
+| [RotationZ(radians)](rotationz.md) | `Matrix3` | Z 轴旋转矩阵 |
+| [Scale(scale)](scale.md) | `Matrix3` | 缩放矩阵 |
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Transpose()](transpose.md) | `Matrix3` | 转置矩阵 |
+| [Inverse()](inverse.md) | `Matrix3` | 逆矩阵 |
+| [Determinant()](determinant.md) | `float` | 行列式 |
+
+## 运算符
+
+| 运算符 | 描述 |
+|--------|------|
+| `operator*(Matrix3, Matrix3)` | 矩阵乘法 |
+| `operator*(Matrix3, Vector3)` | 矩阵-向量乘法 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/matrix3/rotationx.md

@@ -0,0 +1,20 @@
+# Matrix3::RotationX
+
+```cpp
+static Matrix3 RotationX(float radians)
+```
+
+创建绕 X 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotX = Matrix3::RotationX(Math::HALF_PI);
+```

docs/api/math/matrix3/rotationy.md

@@ -0,0 +1,20 @@
+# Matrix3::RotationY
+
+```cpp
+static Matrix3 RotationY(float radians)
+```
+
+创建绕 Y 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotY = Matrix3::RotationY(Math::HALF_PI);
+```

docs/api/math/matrix3/rotationz.md

@@ -0,0 +1,20 @@
+# Matrix3::RotationZ
+
+```cpp
+static Matrix3 RotationZ(float radians)
+```
+
+创建绕 Z 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotZ = Matrix3::RotationZ(Math::HALF_PI);
+```

docs/api/math/matrix3/scale.md

@@ -0,0 +1,20 @@
+# Matrix3::Scale
+
+```cpp
+static Matrix3 Scale(const Vector3& scale)
+```
+
+创建缩放矩阵。
+
+**参数：**
+- `scale` - 各轴缩放因子
+
+**返回：** `Matrix3` - 缩放矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 scale = Matrix3::Scale(Vector3(2.0f, 2.0f, 2.0f));
+```

docs/api/math/matrix3/transpose.md

@@ -0,0 +1,18 @@
+# Matrix3::Transpose
+
+```cpp
+Matrix3 Transpose() const
+```
+
+返回矩阵的转置。
+
+**返回：** `Matrix3` - 转置矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 mat = ...;
+Matrix3 transposed = mat.Transpose();
+```

docs/api/math/matrix3/zero.md

@@ -0,0 +1,17 @@
+# Matrix3::Zero
+
+```cpp
+static Matrix3 Zero()
+```
+
+返回零矩阵。
+
+**返回：** `Matrix3` - 零矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 zero = Matrix3::Zero();
+```

docs/api/math/matrix4/decompose.md

@@ -0,0 +1,24 @@
+# Matrix4::Decompose
+
+```cpp
+void Decompose(Vector3& translation, Quaternion& rotation, Vector3& scale) const
+```
+
+将矩阵分解为平移、旋转和缩放分量。
+
+**参数：**
+- `translation` - 输出平移向量
+- `rotation` - 输出旋转四元数
+- `scale` - 输出缩放向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Vector3 translation;
+Quaternion rotation;
+Vector3 scale;
+m.Decompose(translation, rotation, scale);
+```

docs/api/math/matrix4/determinant.md

@@ -0,0 +1,18 @@
+# Matrix4::Determinant
+
+```cpp
+float Determinant() const
+```
+
+计算矩阵的行列式。
+
+**返回：** `float` - 行列式值
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+float det = m.Determinant();
+```

docs/api/math/matrix4/getrotation.md

@@ -0,0 +1,18 @@
+# Matrix4::GetRotation
+
+```cpp
+Quaternion GetRotation() const
+```
+
+从矩阵中提取旋转分量。
+
+**返回：** `Quaternion` - 旋转四元数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Quaternion rotation = m.GetRotation();
+```

docs/api/math/matrix4/getscale.md

@@ -0,0 +1,18 @@
+# Matrix4::GetScale
+
+```cpp
+Vector3 GetScale() const
+```
+
+从矩阵中提取缩放分量。
+
+**返回：** `Vector3` - 缩放向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Vector3 scale = m.GetScale();
+```

docs/api/math/matrix4/gettranslation.md

@@ -0,0 +1,18 @@
+# Matrix4::GetTranslation
+
+```cpp
+Vector3 GetTranslation() const
+```
+
+从矩阵中提取平移分量。
+
+**返回：** `Vector3` - 平移向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Vector3 translation = m.GetTranslation();
+```

docs/api/math/matrix4/identity.md

@@ -0,0 +1,17 @@
+# Matrix4::Identity
+
+```cpp
+static Matrix4 Identity()
+```
+
+返回 4x4 单位矩阵。
+
+**返回：** `Matrix4` - 单位矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 identity = Matrix4::Identity();
+```

docs/api/math/matrix4/inverse.md

@@ -0,0 +1,18 @@
+# Matrix4::Inverse
+
+```cpp
+Matrix4 Inverse() const
+```
+
+返回矩阵的逆矩阵。
+
+**返回：** `Matrix4` - 逆矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 m = ...;
+Matrix4 inv = m.Inverse();
+```

docs/api/math/matrix4/lookat.md

@@ -0,0 +1,22 @@
+# Matrix4::LookAt
+
+```cpp
+static Matrix4 LookAt(const Vector3& eye, const Vector3& target, const Vector3& up)
+```
+
+创建视图矩阵（观察矩阵）。
+
+**参数：**
+- `eye` - 相机位置
+- `target` - 观察目标点
+- `up` - 世界空间中的上方向
+
+**返回：** `Matrix4` - 视图矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up());
+```

docs/api/math/matrix4/matrix4.md

@@ -0,0 +1,79 @@
+# Matrix4 / Matrix4x4
+
+4x4 矩阵结构体，用于表示完整的 3D 变换（平移、旋转、缩放）、视图和投影变换。
+
+**头文件：** `#include <XCEngine/Math/Matrix4.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 类型别名
+
+```cpp
+using Matrix4 = Matrix4x4;
+```
+
+## 存储方式
+
+行优先存储 (row-major)：
+```
+m[0][0] m[0][1] m[0][2] m[0][3]
+m[1][0] m[1][1] m[1][2] m[1][3]
+m[2][0] m[2][1] m[2][2] m[2][3]
+m[3][0] m[3][1] m[3][2] m[3][3]
+```
+
+## 静态工厂方法
+
+### 基础变换
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Identity()](identity.md) | `Matrix4` | 单位矩阵 |
+| [Zero()](zero.md) | `Matrix4` | 零矩阵 |
+| [Translation(v)](translation.md) | `Matrix4` | 平移矩阵 |
+| [Scale(v)](scale.md) | `Matrix4` | 缩放矩阵 |
+| [Rotation(q)](rotation.md) | `Matrix4` | 旋转矩阵（四元数） |
+| [TRS(translation, rotation, scale)](trs.md) | `Matrix4` | 完整变换 |
+
+### 旋转
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [RotationX(radians)](rotationx.md) | `Matrix4` | X 轴旋转 |
+| [RotationY(radians)](rotationy.md) | `Matrix4` | Y 轴旋转 |
+| [RotationZ(radians)](rotationz.md) | `Matrix4` | Z 轴旋转 |
+
+### 相机变换
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [LookAt(eye, target, up)](lookat.md) | `Matrix4` | 视图矩阵 |
+| [Perspective(fov, aspect, near, far)](perspective.md) | `Matrix4` | 透视投影 |
+| [Orthographic(left, right, bottom, top, near, far)](orthographic.md) | `Matrix4` | 正交投影 |
+
+## 实例方法
+
+### 乘法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| `operator*(Matrix4, Matrix4)` | `Matrix4` | 矩阵乘法 |
+| `operator*(Matrix4, Vector4)` | `Vector4` | 矩阵-向量乘法 |
+| [MultiplyPoint(v)](multiplypoint.md) | `Vector3` | 点变换（带平移） |
+| [MultiplyVector(v)](multiplyvector.md) | `Vector3` | 方向变换（不带平移） |
+
+### 分解
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Transpose()](transpose.md) | `Matrix4` | 转置矩阵 |
+| [Inverse()](inverse.md) | `Matrix4` | 逆矩阵 |
+| [Determinant()](determinant.md) | `float` | 行列式 |
+| [GetTranslation()](gettranslation.md) | `Vector3` | 获取平移分量 |
+| [GetRotation()](getrotation.md) | `Quaternion` | 获取旋转分量 |
+| [GetScale()](getscale.md) | `Vector3` | 获取缩放分量 |
+| [Decompose(translation, rotation, scale)](decompose.md) | `void` | 分解所有分量 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/matrix4/multiplypoint.md

@@ -0,0 +1,21 @@
+# Matrix4::MultiplyPoint
+
+```cpp
+Vector3 MultiplyPoint(const Vector3& v) const
+```
+
+使用矩阵变换点（包含平移）。
+
+**参数：**
+- `v` - 要变换的点
+
+**返回：** `Vector3` - 变换后的点
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 model = Matrix4::TRS(pos, rot, scale);
+Vector3 worldPos = model.MultiplyPoint(localPos);
+```

docs/api/math/matrix4/multiplyvector.md

@@ -0,0 +1,21 @@
+# Matrix4::MultiplyVector
+
+```cpp
+Vector3 MultiplyVector(const Vector3& v) const
+```
+
+使用矩阵变换方向向量（不包含平移）。
+
+**参数：**
+- `v` - 要变换的方向向量
+
+**返回：** `Vector3` - 变换后的方向
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 model = Matrix4::TRS(pos, rot, scale);
+Vector3 worldDir = model.MultiplyVector(localDir);
+```

docs/api/math/matrix4/orthographic.md

@@ -0,0 +1,25 @@
+# Matrix4::Orthographic
+
+```cpp
+static Matrix4 Orthographic(float left, float right, float bottom, float top, float near, float far)
+```
+
+创建正交投影矩阵。
+
+**参数：**
+- `left` - 左裁剪面
+- `right` - 右裁剪面
+- `bottom` - 下裁剪面
+- `top` - 上裁剪面
+- `near` - 近裁剪面距离
+- `far` - 远裁剪面距离
+
+**返回：** `Matrix4` - 正交投影矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 ortho = Matrix4::Orthographic(-aspect, aspect, -1.0f, 1.0f, 0.1f, 100.0f);
+```

docs/api/math/matrix4/perspective.md

@@ -0,0 +1,23 @@
+# Matrix4::Perspective
+
+```cpp
+static Matrix4 Perspective(float fov, float aspect, float near, float far)
+```
+
+创建透视投影矩阵。
+
+**参数：**
+- `fov` - 垂直视野角度（弧度）
+- `aspect` - 宽高比
+- `near` - 近裁剪面距离
+- `far` - 远裁剪面距离
+
+**返回：** `Matrix4` - 透视投影矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f);
+```

docs/api/math/matrix4/rotation.md

@@ -0,0 +1,21 @@
+# Matrix4::Rotation
+
+```cpp
+static Matrix4 Rotation(const Quaternion& q)
+```
+
+从四元数创建旋转矩阵。
+
+**参数：**
+- `q` - 四元数
+
+**返回：** `Matrix4` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f);
+Matrix4 rotation = Matrix4::Rotation(rot);
+```

docs/api/math/matrix4/rotationx.md

@@ -0,0 +1,20 @@
+# Matrix4::RotationX
+
+```cpp
+static Matrix4 RotationX(float radians)
+```
+
+创建绕 X 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix4` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 rotX = Matrix4::RotationX(Math::HALF_PI);
+```

docs/api/math/matrix4/rotationy.md

@@ -0,0 +1,20 @@
+# Matrix4::RotationY
+
+```cpp
+static Matrix4 RotationY(float radians)
+```
+
+创建绕 Y 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix4` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 rotY = Matrix4::RotationY(Math::HALF_PI);
+```

docs/api/math/matrix4/rotationz.md

@@ -0,0 +1,20 @@
+# Matrix4::RotationZ
+
+```cpp
+static Matrix4 RotationZ(float radians)
+```
+
+创建绕 Z 轴旋转的矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix4` - 旋转矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 rotZ = Matrix4::RotationZ(Math::HALF_PI);
+```

docs/api/math/matrix4/scale.md

@@ -0,0 +1,20 @@
+# Matrix4::Scale
+
+```cpp
+static Matrix4 Scale(const Vector3& v)
+```
+
+创建缩放矩阵。
+
+**参数：**
+- `v` - 各轴缩放因子
+
+**返回：** `Matrix4` - 缩放矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix4 scale = Matrix4::Scale(Vector3(2.0f, 2.0f, 2.0f));
+```