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/rect/contains-float.md

@@ -0,0 +1,24 @@
+# Rect::Contains (float)
+
+```cpp
+bool Contains(float px, float py) const
+```
+
+检测浮点坐标点是否在矩形内。
+
+**参数：**
+- `px` - 点的 x 坐标
+- `py` - 点的 y 坐标
+
+**返回：** `bool` - 点在矩形内（包含边界）返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect screenRect(0.0f, 0.0f, 1920.0f, 1080.0f);
+if (screenRect.Contains(mouseX, mouseY)) {
+    // 鼠标在屏幕矩形内
+}
+```

docs/api/math/rect/contains-vector2.md

@@ -0,0 +1,24 @@
+# Rect::Contains (Vector2)
+
+```cpp
+bool Contains(const Vector2& point) const
+```
+
+检测 Vector2 点是否在矩形内。
+
+**参数：**
+- `point` - 要检测的二维点
+
+**返回：** `bool` - 点在矩形内（包含边界）返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(0.0f, 0.0f, 100.0f, 100.0f);
+Vector2 point(50.0f, 50.0f);
+if (rect.Contains(point)) {
+    // 点在矩形内
+}
+```

docs/api/math/rect/getbottom.md

@@ -0,0 +1,18 @@
+# Rect::GetBottom
+
+```cpp
+float GetBottom() const
+```
+
+获取矩形下边界。
+
+**返回：** `float` - 下边界坐标 (y + height)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(10.0f, 20.0f, 100.0f, 50.0f);
+float bottom = rect.GetBottom();  // 70.0f
+```

docs/api/math/rect/getcenter.md

@@ -0,0 +1,18 @@
+# Rect::GetCenter
+
+```cpp
+Vector2 GetCenter() const
+```
+
+获取矩形中心点。
+
+**返回：** `Vector2` - 中心点坐标
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(10.0f, 20.0f, 100.0f, 50.0f);
+Vector2 center = rect.GetCenter();  // (60.0f, 45.0f)
+```

docs/api/math/rect/getleft.md

@@ -0,0 +1,18 @@
+# Rect::GetLeft
+
+```cpp
+float GetLeft() const
+```
+
+获取矩形左边界。
+
+**返回：** `float` - 左边界坐标 (x)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(10.0f, 20.0f, 100.0f, 50.0f);
+float left = rect.GetLeft();  // 10.0f
+```

docs/api/math/rect/getposition.md

@@ -0,0 +1,18 @@
+# Rect::GetPosition
+
+```cpp
+Vector2 GetPosition() const
+```
+
+获取矩形左上角位置。
+
+**返回：** `Vector2` - 位置向量 (x, y)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(10.0f, 20.0f, 100.0f, 50.0f);
+Vector2 pos = rect.GetPosition();  // (10.0f, 20.0f)
+```

docs/api/math/rect/getright.md

@@ -0,0 +1,18 @@
+# Rect::GetRight
+
+```cpp
+float GetRight() const
+```
+
+获取矩形右边界。
+
+**返回：** `float` - 右边界坐标 (x + width)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(10.0f, 20.0f, 100.0f, 50.0f);
+float right = rect.GetRight();  // 110.0f
+```

docs/api/math/rect/getsize.md

@@ -0,0 +1,18 @@
+# Rect::GetSize
+
+```cpp
+Vector2 GetSize() const
+```
+
+获取矩形尺寸。
+
+**返回：** `Vector2` - 尺寸向量 (width, height)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(10.0f, 20.0f, 100.0f, 50.0f);
+Vector2 size = rect.GetSize();  // (100.0f, 50.0f)
+```

docs/api/math/rect/gettop.md

@@ -0,0 +1,18 @@
+# Rect::GetTop
+
+```cpp
+float GetTop() const
+```
+
+获取矩形上边界。
+
+**返回：** `float` - 上边界坐标 (y)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(10.0f, 20.0f, 100.0f, 50.0f);
+float top = rect.GetTop();  // 20.0f
+```

docs/api/math/rect/intersect.md

@@ -0,0 +1,23 @@
+# Rect::Intersect
+
+```cpp
+static Rect Intersect(const Rect& a, const Rect& b)
+```
+
+计算两矩形的交集区域。
+
+**参数：**
+- `a` - 第一个矩形
+- `b` - 第二个矩形
+
+**返回：** `Rect` - 两矩形的交集，若无交集则返回零尺寸矩形
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rectA(0.0f, 0.0f, 100.0f, 100.0f);
+Rect rectB(50.0f, 50.0f, 100.0f, 100.0f);
+Rect overlap = Rect::Intersect(rectA, rectB);  // (50, 50, 50, 50)
+```

docs/api/math/rect/intersects.md

@@ -0,0 +1,24 @@
+# Rect::Intersects
+
+```cpp
+bool Intersects(const Rect& other) const
+```
+
+检测两矩形是否相交。
+
+**参数：**
+- `other` - 另一个矩形
+
+**返回：** `bool` - 两矩形相交返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rectA(0.0f, 0.0f, 100.0f, 100.0f);
+Rect rectB(50.0f, 50.0f, 100.0f, 100.0f);
+if (rectA.Intersects(rectB)) {
+    // 两矩形相交
+}
+```

docs/api/math/rect/rect-overview.md

@@ -0,0 +1,69 @@
+# Rect
+
+浮点矩形结构体，用于 2D 区域表示。
+
+**头文件：** `#include <XCEngine/Math/Rect.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Rect {
+    float x = 0.0f;      // 左边界
+    float y = 0.0f;      // 上边界
+    float width = 0.0f;
+    float height = 0.0f;
+
+    Rect() = default;
+    Rect(float x, float y, float w, float h) : x(x), y(y), width(w), height(h) {}
+};
+```
+
+## 构造函数
+
+| 方法 | 描述 |
+|------|------|
+| `Rect()` | 默认构造，初始化为零 |
+| `Rect(x, y, w, h)` | 从坐标和尺寸构造 |
+
+## 边界访问
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetLeft()](getleft.md) | `float` | 左边界 (x) |
+| [GetRight()](getright.md) | `float` | 右边界 (x + width) |
+| [GetTop()](gettop.md) | `float` | 上边界 (y) |
+| [GetBottom()](getbottom.md) | `float` | 下边界 (y + height) |
+| [GetPosition()](getposition.md) | `Vector2` | 左上角位置 (x, y) |
+| [GetSize()](getsize.md) | `Vector2` | 尺寸 (width, height) |
+| [GetCenter()](getcenter.md) | `Vector2` | 中心点 |
+
+## 检测方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Contains(px, py)](contains-float.md) | `bool` | 浮点坐标点检测 |
+| [Contains(point)](contains-vector2.md) | `bool` | Vector2 点检测 |
+| [Intersects(other)](intersects.md) | `bool` | 与另一矩形相交 |
+
+## 静态方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Intersect(a, b)](intersect.md) | `Rect` | 两矩形交集 |
+| [Union(a, b)](union.md) | `Rect` | 两矩形并集 |
+
+## 设置方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Set(x, y, w, h)](set.md) | `void` | 设置所有值 |
+| [SetPosition(x, y)](setposition-float.md) | `void` | 设置位置 |
+| [SetPosition(position)](setposition-vector2.md) | `void` | 设置位置 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Rect 模块总览
+- [RectInt](rectint.md) - 整数矩形版本
+- [Viewport](viewport.md) - 渲染视口

docs/api/math/rect/rect.md

@@ -0,0 +1,17 @@
+# Rect / RectInt / Viewport
+
+2D 矩形和视口结构体。
+
+**头文件：** `#include <XCEngine/Math/Rect.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 目录
+
+- [Rect](rect.md) - 浮点矩形
+- [RectInt](rectint.md) - 整数矩形
+- [Viewport](viewport.md) - 渲染视口
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/rect/rectint-contains.md

@@ -0,0 +1,24 @@
+# RectInt::Contains
+
+```cpp
+bool Contains(int32_t px, int32_t py) const
+```
+
+检测整数坐标点是否在矩形内。
+
+**参数：**
+- `px` - 点的 x 坐标
+- `py` - 点的 y 坐标
+
+**返回：** `bool` - 点在矩形内（包含边界）返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rect(0, 0, 1920, 1080);
+if (rect.Contains(pixelX, pixelY)) {
+    // 像素在矩形内
+}
+```

docs/api/math/rect/rectint-getbottom.md

@@ -0,0 +1,18 @@
+# RectInt::GetBottom
+
+```cpp
+int32_t GetBottom() const
+```
+
+获取矩形下边界。
+
+**返回：** `int32_t` - 下边界坐标 (y + height)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rect(10, 20, 100, 50);
+int32_t bottom = rect.GetBottom();  // 70
+```

docs/api/math/rect/rectint-getcenter.md

@@ -0,0 +1,18 @@
+# RectInt::GetCenter
+
+```cpp
+Vector2 GetCenter() const
+```
+
+获取矩形中心点（转换为浮点）。
+
+**返回：** `Vector2` - 中心点坐标
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rect(10, 20, 100, 50);
+Vector2 center = rect.GetCenter();  // (60.0f, 45.0f)
+```

docs/api/math/rect/rectint-getleft.md

@@ -0,0 +1,18 @@
+# RectInt::GetLeft
+
+```cpp
+int32_t GetLeft() const
+```
+
+获取矩形左边界。
+
+**返回：** `int32_t` - 左边界坐标 (x)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rect(10, 20, 100, 50);
+int32_t left = rect.GetLeft();  // 10
+```

docs/api/math/rect/rectint-getposition.md

@@ -0,0 +1,18 @@
+# RectInt::GetPosition
+
+```cpp
+Vector2 GetPosition() const
+```
+
+获取矩形左上角位置（转换为浮点）。
+
+**返回：** `Vector2` - 位置向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rect(10, 20, 100, 50);
+Vector2 pos = rect.GetPosition();  // (10.0f, 20.0f)
+```

docs/api/math/rect/rectint-getright.md

@@ -0,0 +1,18 @@
+# RectInt::GetRight
+
+```cpp
+int32_t GetRight() const
+```
+
+获取矩形右边界。
+
+**返回：** `int32_t` - 右边界坐标 (x + width)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rect(10, 20, 100, 50);
+int32_t right = rect.GetRight();  // 110
+```

docs/api/math/rect/rectint-getsize.md

@@ -0,0 +1,18 @@
+# RectInt::GetSize
+
+```cpp
+Vector2 GetSize() const
+```
+
+获取矩形尺寸（转换为浮点）。
+
+**返回：** `Vector2` - 尺寸向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rect(10, 20, 100, 50);
+Vector2 size = rect.GetSize();  // (100.0f, 50.0f)
+```

docs/api/math/rect/rectint-gettop.md

@@ -0,0 +1,18 @@
+# RectInt::GetTop
+
+```cpp
+int32_t GetTop() const
+```
+
+获取矩形上边界。
+
+**返回：** `int32_t` - 上边界坐标 (y)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rect(10, 20, 100, 50);
+int32_t top = rect.GetTop();  // 20
+```

docs/api/math/rect/rectint-intersects.md

@@ -0,0 +1,24 @@
+# RectInt::Intersects
+
+```cpp
+bool Intersects(const RectInt& other) const
+```
+
+检测两整数矩形是否相交。
+
+**参数：**
+- `other` - 另一个整数矩形
+
+**返回：** `bool` - 两矩形相交返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+RectInt rectA(0, 0, 100, 100);
+RectInt rectB(50, 50, 100, 100);
+if (rectA.Intersects(rectB)) {
+    // 两矩形相交
+}
+```

docs/api/math/rect/rectint.md

@@ -0,0 +1,53 @@
+# RectInt
+
+整数矩形结构体，用于像素级 2D 区域表示。
+
+**头文件：** `#include <XCEngine/Math/Rect.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct RectInt {
+    int32_t x = 0;
+    int32_t y = 0;
+    int32_t width = 0;
+    int32_t height = 0;
+
+    RectInt() = default;
+    RectInt(int32_t x, int32_t y, int32_t w, int32_t h);
+};
+```
+
+## 构造函数
+
+| 方法 | 描述 |
+|------|------|
+| `RectInt()` | 默认构造 |
+| `RectInt(x, y, w, h)` | 从整数坐标和尺寸构造 |
+
+## 边界访问
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetLeft()](rectint-getleft.md) | `int32_t` | 左边界 |
+| [GetRight()](rectint-getright.md) | `int32_t` | 右边界 |
+| [GetTop()](rectint-gettop.md) | `int32_t` | 上边界 |
+| [GetBottom()](rectint-getbottom.md) | `int32_t` | 下边界 |
+| [GetPosition()](rectint-getposition.md) | `Vector2` | 位置（转换为浮点） |
+| [GetSize()](rectint-getsize.md) | `Vector2` | 尺寸（转换为浮点） |
+| [GetCenter()](rectint-getcenter.md) | `Vector2` | 中心点 |
+
+## 检测方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Contains(px, py)](rectint-contains.md) | `bool` | 整数坐标点检测 |
+| [Intersects(other)](rectint-intersects.md) | `bool` | 与另一矩形相交 |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Rect 模块总览
+- [Rect](rect-overview.md) - 浮点矩形版本
+- [Viewport](viewport.md) - 渲染视口

docs/api/math/rect/set.md

@@ -0,0 +1,24 @@
+# Rect::Set
+
+```cpp
+void Set(float newX, float newY, float newWidth, float newHeight)
+```
+
+设置矩形所有属性。
+
+**参数：**
+- `newX` - 新的左边界
+- `newY` - 新的上边界
+- `newWidth` - 新的宽度
+- `newHeight` - 新的高度
+
+**返回：** `void`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect;
+rect.Set(10.0f, 20.0f, 100.0f, 50.0f);
+```

docs/api/math/rect/setposition-float.md

@@ -0,0 +1,22 @@
+# Rect::SetPosition (float)
+
+```cpp
+void SetPosition(float newX, float newY)
+```
+
+设置矩形位置（保持尺寸不变）。
+
+**参数：**
+- `newX` - 新的左边界
+- `newY` - 新的上边界
+
+**返回：** `void`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(0.0f, 0.0f, 100.0f, 50.0f);
+rect.SetPosition(50.0f, 30.0f);  // rect 现在为 (50, 30, 100, 50)
+```

docs/api/math/rect/setposition-vector2.md

@@ -0,0 +1,21 @@
+# Rect::SetPosition (Vector2)
+
+```cpp
+void SetPosition(const Vector2& position)
+```
+
+用 Vector2 设置矩形位置（保持尺寸不变）。
+
+**参数：**
+- `position` - 新的位置向量
+
+**返回：** `void`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rect(0.0f, 0.0f, 100.0f, 50.0f);
+rect.SetPosition(Vector2(50.0f, 30.0f));  // rect 现在为 (50, 30, 100, 50)
+```

docs/api/math/rect/union.md

@@ -0,0 +1,23 @@
+# Rect::Union
+
+```cpp
+static Rect Union(const Rect& a, const Rect& b)
+```
+
+计算包含两矩形的最小矩形。
+
+**参数：**
+- `a` - 第一个矩形
+- `b` - 第二个矩形
+
+**返回：** `Rect` - 包含两矩形的最小外接矩形
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Rect rectA(0.0f, 0.0f, 50.0f, 50.0f);
+Rect rectB(100.0f, 100.0f, 50.0f, 50.0f);
+Rect combined = Rect::Union(rectA, rectB);  // (0, 0, 150, 150)
+```

docs/api/math/rect/viewport-getaspectratio.md

@@ -0,0 +1,18 @@
+# Viewport::GetAspectRatio
+
+```cpp
+float GetAspectRatio() const
+```
+
+获取视口宽高比。
+
+**返回：** `float` - 宽高比 (width / height)，height 为 0 时返回 0.0f
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Viewport viewport(0, 0, 1920, 1080);
+float aspect = viewport.GetAspectRatio();  // 1.777... (16:9)
+```

docs/api/math/rect/viewport-getrect.md

@@ -0,0 +1,18 @@
+# Viewport::GetRect
+
+```cpp
+Rect GetRect() const
+```
+
+将视口转换为 Rect。
+
+**返回：** `Rect` - 对应的矩形 (x, y, width, height)，不包含深度范围
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Viewport viewport(0, 0, 1920, 1080, 0.0f, 1.0f);
+Rect rect = viewport.GetRect();  // (0, 0, 1920, 1080)
+```

docs/api/math/rect/viewport.md

@@ -0,0 +1,45 @@
+# Viewport
+
+渲染视口结构体，用于屏幕到归一化坐标的映射。
+
+**头文件：** `#include <XCEngine/Math/Rect.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```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() = default;
+    Viewport(float x, float y, float w, float h);
+    Viewport(float x, float y, float w, float h, float minD, float maxD);
+};
+```
+
+## 构造函数
+
+| 方法 | 描述 |
+|------|------|
+| `Viewport()` | 默认构造 |
+| `Viewport(x, y, w, h)` | 2D 视口 |
+| `Viewport(x, y, w, h, minD, maxD)` | 带深度范围的 3D 视口 |
+
+## 方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [GetAspectRatio()](viewport-getaspectratio.md) | `float` | 宽高比 (width / height) |
+| [GetRect()](viewport-getrect.md) | `Rect` | 转换为 Rect |
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Rect 模块总览
+- [Rect](rect-overview.md) - 浮点矩形
+- [RectInt](rectint.md) - 整数矩形