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 个断裂引用
2026-03-19 00:22:30 +08:00
parent d0e16962c8
commit dc850d7739
1012 changed files with 26673 additions and 9222 deletions
--- a/docs/api/resources/mesh/addsection.md
+++ b/docs/api/resources/mesh/addsection.md
@@ -0,0 +1,30 @@
+# Mesh::AddSection
+
+```cpp
+void AddSection(const MeshSection& section)
+```
+
+添加网格分段（Submesh）。一个 Mesh 可以包含多个分段，每个分段对应一组索引和不同的材质。
+
+**参数：**
+- `section` - 网格分段描述结构体
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+MeshSection section;
+section.baseVertex = 0;
+section.vertexCount = 1000;
+section.startIndex = 0;
+section.indexCount = 3000;
+section.materialID = 0;
+mesh->AddSection(section);
+```
+
+## 相关文档
+
+- [Mesh 总览](mesh.md) - 返回类总览
--- a/docs/api/resources/mesh/mesh.md
+++ b/docs/api/resources/mesh/mesh.md
@@ -0,0 +1,149 @@
+# Mesh
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 网格资源类，管理 3D 模型的顶点数据、索引数据和网格分段信息。
+
+## 概述
+
+`Mesh` 是 XCEngine 中的网格资源类，继承自 `IResource`。它管理网格的顶点数据（位置、法线、UV、切线、颜色、骨骼权重等）、索引数据和网格分段（submesh）。
+
+## 头文件
+
+```cpp
+#include <XCEngine/Resources/Mesh.h>
+```
+
+## 枚举类型
+
+### VertexAttribute
+
+顶点属性标志枚举（可组合）。
+
+| 值 | 描述 |
+|----|------|
+| `Position` | 位置坐标 |
+| `Normal` | 法线 |
+| `Tangent` | 切线 |
+| `Color` | 顶点颜色 |
+| `UV0` | 第一组纹理坐标 |
+| `UV1` | 第二组纹理坐标 |
+| `UV2` | 第三组纹理坐标 |
+| `UV3` | 第四组纹理坐标 |
+| `BoneWeights` | 骨骼权重 |
+| `BoneIndices` | 骨骼索引 |
+
+## MeshSection 结构体
+
+网格分段（Submesh）描述。
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `baseVertex` | `Core::uint32` | 基础顶点索引 |
+| `vertexCount` | `Core::uint32` | 顶点数量 |
+| `startIndex` | `Core::uint32` | 起始索引 |
+| `indexCount` | `Core::uint32` | 索引数量 |
+| `materialID` | `Core::uint32` | 对应材质 ID |
+
+## 公共方法
+
+### 基础属性
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceType GetType() const` | 返回 `ResourceType::Mesh` |
+| `const Containers::String& GetName() const` | 获取网格名称 |
+| `const Containers::String& GetPath() const` | 获取网格路径 |
+| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
+| `bool IsValid() const` | 检查网格是否有效 |
+| `size_t GetMemorySize() const` | 获取内存大小 |
+| `void Release()` | 释放网格引用 |
+
+### 顶点数据
+
+| 方法 | 描述 |
+|------|------|
+| `void SetVertexData(const void* data, size_t size, Core::uint32 vertexCount, Core::uint32 vertexStride, VertexAttribute attributes)` | 设置顶点数据 |
+| `const void* GetVertexData() const` | 获取顶点数据指针 |
+| `size_t GetVertexDataSize() const` | 获取顶点数据大小 |
+| `Core::uint32 GetVertexCount() const` | 获取顶点数量 |
+| `Core::uint32 GetVertexStride() const` | 获取顶点结构体大小（字节） |
+| `VertexAttribute GetVertexAttributes() const` | 获取顶点属性标志 |
+
+### 索引数据
+
+| 方法 | 描述 |
+|------|------|
+| `void SetIndexData(const void* data, size_t size, Core::uint32 indexCount, bool use32Bit)` | 设置索引数据 |
+| `const void* GetIndexData() const` | 获取索引数据指针 |
+| `size_t GetIndexDataSize() const` | 获取索引数据大小 |
+| `Core::uint32 GetIndexCount() const` | 获取索引数量 |
+| `bool IsUse32BitIndex() const` | 是否使用 32 位索引 |
+
+### 网格分段
+
+| 方法 | 描述 |
+|------|------|
+| `void AddSection(const MeshSection& section)` | 添加网格分段 |
+| `const Containers::Array<MeshSection>& GetSections() const` | 获取所有分段 |
+
+## 使用示例
+
+```cpp
+// 加载网格
+ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
+
+// 手动设置顶点数据
+struct Vertex {
+    float position[3];
+    float normal[3];
+    float uv[2];
+};
+
+Containers::Array<Vertex> vertices;
+vertices.Resize(vertexCount);
+// ... 填充顶点数据 ...
+
+mesh->SetVertexData(
+    vertices.Data(),
+    vertices.Size() * sizeof(Vertex),
+    vertexCount,
+    sizeof(Vertex),
+    VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0
+);
+
+// 设置索引数据
+Containers::Array<uint32_t> indices;
+indices.Resize(indexCount);
+// ... 填充索引数据 ...
+
+mesh->SetIndexData(
+    indices.Data(),
+    indices.Size() * sizeof(uint32_t),
+    indexCount,
+    true  // 32 位索引
+);
+
+// 添加分段（一个网格可能有多个材质）
+MeshSection section;
+section.baseVertex = 0;
+section.vertexCount = vertexCount;
+section.startIndex = 0;
+section.indexCount = indexCount;
+section.materialID = 0;
+mesh->AddSection(section);
+
+// 访问数据
+uint32_t vCount = mesh->GetVertexCount();
+uint32_t iCount = mesh->GetIndexCount();
+auto sections = mesh->GetSections();
+```
+
+## 相关文档
+
+- [IResource](../iresource/iresource.md) - 资源基类
+- [Material](../material/material.md) - 材质资源
+- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [Resources 总览](../resources.md) - 返回模块总览
--- a/docs/api/resources/mesh/setindexdata.md
+++ b/docs/api/resources/mesh/setindexdata.md
@@ -0,0 +1,30 @@
+# Mesh::SetIndexData
+
+```cpp
+void SetIndexData(const void* data, size_t size, Core::uint32 indexCount, bool use32Bit)
+```
+
+设置网格索引数据。复制索引缓冲数据到内部存储。
+
+**参数：**
+- `data` - 索引数据指针
+- `size` - 数据大小（字节）
+- `indexCount` - 索引数量
+- `use32Bit` - 是否使用 32 位索引（否则使用 16 位）
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为索引数据大小
+
+**示例：**
+
+```cpp
+Containers::Array<uint32_t> indices;
+// ... 填充索引数据 ...
+mesh->SetIndexData(indices.Data(), indices.Size() * sizeof(uint32_t),
+    indices.Size(), true);
+```
+
+## 相关文档
+
+- [Mesh 总览](mesh.md) - 返回类总览
--- a/docs/api/resources/mesh/setvertexdata.md
+++ b/docs/api/resources/mesh/setvertexdata.md
@@ -0,0 +1,37 @@
+# Mesh::SetVertexData
+
+```cpp
+void SetVertexData(const void* data, size_t size, Core::uint32 vertexCount,
+                   Core::uint32 vertexStride, VertexAttribute attributes)
+```
+
+设置网格顶点数据。复制顶点缓冲数据到内部存储。
+
+**参数：**
+- `data` - 顶点数据指针
+- `size` - 数据大小（字节）
+- `vertexCount` - 顶点数量
+- `vertexStride` - 单个顶点结构体大小（字节）
+- `attributes` - 顶点属性标志组合
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为顶点数据大小
+
+**示例：**
+
+```cpp
+struct Vertex {
+    float position[3];
+    float normal[3];
+    float uv[2];
+};
+
+mesh->SetVertexData(vertices.Data(), vertices.Size() * sizeof(Vertex),
+    vertexCount, sizeof(Vertex),
+    VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0);
+```
+
+## 相关文档
+
+- [Mesh 总览](mesh.md) - 返回类总览