docs: update resources API docs

2026-03-20 02:35:35 +08:00
parent fd792b7df1
commit ea756c0177
314 changed files with 9439 additions and 1360 deletions
--- a/docs/api/resources/mesh/mesh.md
+++ b/docs/api/resources/mesh/mesh.md
@@ -2,149 +2,120 @@

 **命名空间**: `XCEngine::Resources`

-**类型**: `class`
+**类型**: `class` (inherits from `IResource`)

-**描述**: 网格资源类，管理 3D 模型的顶点数据、索引数据和网格分段信息。
+**头文件**: `XCEngine/Resources/Mesh.h`
+
+**描述**: 网格资源类，用于存储和管理 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 |
+Mesh 类是 XCEngine 引擎中的核心资源类型之一，负责管理 3D 模型的网格数据。它存储顶点属性（位置、法线、切线、UV 坐标、骨骼权重等）、索引数据以及网格分段（MeshSection）信息。Mesh 资源通常由资源加载器从外部文件（如 .obj、.fbx 等格式）加载，或通过程序化方式生成。

 ## 公共方法

-### 基础属性
-
 | 方法 | 描述 |
 |------|------|
-| `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()` | 释放网格引用 |
+| [`Mesh`](constructor.md) | 构造函数 |
+| [`~Mesh`](destructor.md) | 析构函数 |
+| [`GetType`](get-type.md) | 获取资源类型 |
+| [`GetName`](get-name.md) | 获取资源名称 |
+| [`GetPath`](get-path.md) | 获取资源路径 |
+| [`GetGUID`](get-guid.md) | 获取资源全局唯一标识符 |
+| [`IsValid`](is-valid.md) | 检查资源是否有效 |
+| [`GetMemorySize`](get-memory-size.md) | 获取资源内存大小 |
+| [`Release`](release.md) | 释放资源 |
+| [`SetVertexData`](set-vertex-data.md) | 设置顶点数据 |
+| [`GetVertexData`](get-vertex-data.md) | 获取顶点数据指针 |
+| [`GetVertexDataSize`](get-vertex-data-size.md) | 获取顶点数据大小 |
+| [`GetVertexCount`](get-vertex-count.md) | 获取顶点数量 |
+| [`GetVertexStride`](get-vertex-stride.md) | 获取顶点步长 |
+| [`GetVertexAttributes`](get-vertex-attributes.md) | 获取顶点属性 |
+| [`SetIndexData`](set-index-data.md) | 设置索引数据 |
+| [`GetIndexData`](get-index-data.md) | 获取索引数据指针 |
+| [`GetIndexDataSize`](get-index-data-size.md) | 获取索引数据大小 |
+| [`GetIndexCount`](get-index-count.md) | 获取索引数量 |
+| [`IsUse32BitIndex`](is-use-32bit-index.md) | 是否使用 32 位索引 |
+| [`AddSection`](add-section.md) | 添加网格分段 |
+| [`GetSections`](get-sections.md) | 获取所有网格分段 |

-### 顶点数据
+## 相关类型

-| 方法 | 描述 |
-|------|------|
-| `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` | 获取顶点属性标志 |
+### VertexAttribute

-### 索引数据
+```cpp
+enum class VertexAttribute : Core::uint32 {
+    Position = 1 << 0,
+    Normal = 1 << 1,
+    Tangent = 1 << 2,
+    Color = 1 << 3,
+    UV0 = 1 << 4,
+    UV1 = 1 << 5,
+    UV2 = 1 << 6,
+    UV3 = 1 << 7,
+    BoneWeights = 1 << 8,
+    BoneIndices = 1 << 9
+};
+```

-| 方法 | 描述 |
-|------|------|
-| `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 位索引 |
+顶点属性枚举，用于指定网格包含哪些顶点数据通道。多个属性可以通过按位或组合使用。

-### 网格分段
+### MeshSection

-| 方法 | 描述 |
-|------|------|
-| `void AddSection(const MeshSection& section)` | 添加网格分段 |
-| `const Containers::Array<MeshSection>& GetSections() const` | 获取所有分段 |
+```cpp
+struct MeshSection {
+    Core::uint32 baseVertex;
+    Core::uint32 vertexCount;
+    Core::uint32 startIndex;
+    Core::uint32 indexCount;
+    Core::uint32 materialID;
+};
+```
+
+网格分段结构，描述网格中某个子网格的区域信息，包括顶点范围、索引范围和材质 ID。

 ## 使用示例

 ```cpp
-// 加载网格
-ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
+#include "XCEngine/Resources/Mesh.h"
+#include "XCEngine/Containers/Array.h"

-// 手动设置顶点数据
-struct Vertex {
-    float position[3];
-    float normal[3];
-    float uv[2];
-};
+using namespace XCEngine;
+using namespace Resources;

-Containers::Array<Vertex> vertices;
-vertices.Resize(vertexCount);
-// ... 填充顶点数据 ...
+void CreateQuadMesh(Mesh* outMesh) {
+    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
-);
+    Vertex vertices[4] = {
+        {{-0.5f, -0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {0.0f, 0.0f}},
+        {{ 0.5f, -0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {1.0f, 0.0f}},
+        {{ 0.5f,  0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {1.0f, 1.0f}},
+        {{-0.5f,  0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {0.0f, 1.0f}}
+    };

-// 设置索引数据
-Containers::Array<uint32_t> indices;
-indices.Resize(indexCount);
-// ... 填充索引数据 ...
+    uint32_t indices[6] = {0, 1, 2, 0, 2, 3};

-mesh->SetIndexData(
-    indices.Data(),
-    indices.Size() * sizeof(uint32_t),
-    indexCount,
-    true  // 32 位索引
-);
+    VertexAttribute attributes = VertexAttribute::Position | 
+                                 VertexAttribute::Normal | 
+                                 VertexAttribute::UV0;

-// 添加分段（一个网格可能有多个材质）
-MeshSection section;
-section.baseVertex = 0;
-section.vertexCount = vertexCount;
-section.startIndex = 0;
-section.indexCount = indexCount;
-section.materialID = 0;
-mesh->AddSection(section);
+    outMesh->SetVertexData(vertices, sizeof(vertices), 4, sizeof(Vertex), attributes);
+    outMesh->SetIndexData(indices, sizeof(indices), 6, false);

-// 访问数据
-uint32_t vCount = mesh->GetVertexCount();
-uint32_t iCount = mesh->GetIndexCount();
-auto sections = mesh->GetSections();
+    MeshSection section;
+    section.baseVertex = 0;
+    section.vertexCount = 4;
+    section.startIndex = 0;
+    section.indexCount = 6;
+    section.materialID = 0;
+    outMesh->AddSection(section);
+}
 ```

 ## 相关文档

 - [IResource](../iresource/iresource.md) - 资源基类
- [Material](../material/material.md) - 材质资源
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
- [Resources 总览](../resources.md) - 返回模块总览
- **实现说明**: `MeshLoader::Load()` 仅为示例实现，不解析 FBX/OBJ 等格式的实际网格数据