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/texture/create.md
+++ b/docs/api/resources/texture/create.md
@@ -0,0 +1,39 @@
+# Texture::Create
+
+```cpp
+bool Create(Core::uint32 width, Core::uint32 height, Core::uint32 depth,
+            Core::uint32 mipLevels, TextureType type, TextureFormat format,
+            const void* data, size_t dataSize)
+```
+
+创建纹理资源。设置纹理的尺寸、格式和像素数据，并分配 GPU 资源。
+
+**参数：**
+- `width` - 纹理宽度（像素）
+- `height` - 纹理高度（像素）
+- `depth` - 纹理深度（3D 纹理设为 1）
+- `mipLevels` - Mipmap 级别数（0 表示自动生成所有级别）
+- `type` - 纹理类型
+- `format` - 纹理格式
+- `data` - 像素数据指针
+- `dataSize` - 像素数据大小
+
+**返回：** 创建成功返回 true
+
+**复杂度：** O(n)，n 为像素数量
+
+**示例：**
+
+```cpp
+Texture tex;
+bool ok = tex.Create(
+    1024, 1024, 1, 0,
+    TextureType::Texture2D,
+    TextureFormat::RGBA8_UNORM,
+    pixelData, pixelDataSize
+);
+```
+
+## 相关文档
+
+- [Texture 总览](texture.md) - 返回类总览
--- a/docs/api/resources/texture/generatemipmaps.md
+++ b/docs/api/resources/texture/generatemipmaps.md
@@ -0,0 +1,24 @@
+# Texture::GenerateMipmaps
+
+```cpp
+bool GenerateMipmaps()
+```
+
+生成纹理的 Mipmap 链。根据基础级别纹理自动生成所有下采样级别，用于纹理在缩小渲染时避免闪烁。
+
+**参数：** 无
+
+**返回：** 生成成功返回 true
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+tex.Create(1024, 1024, 1, 1, TextureType::Texture2D, TextureFormat::RGBA8_UNORM, data, size);
+tex.GenerateMipmaps();
+```
+
+## 相关文档
+
+- [Texture 总览](texture.md) - 返回类总览
--- a/docs/api/resources/texture/texture.md
+++ b/docs/api/resources/texture/texture.md
@@ -0,0 +1,153 @@
+# Texture
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 纹理资源类，管理 2D/3D 纹理和立方体贴图的像素数据。
+
+## 概述
+
+`Texture` 是 XCEngine 中的纹理资源类，继承自 `IResource`。它管理纹理的尺寸、格式、像素数据，并支持 mipmap 生成等功能。
+
+## 头文件
+
+```cpp
+#include <XCEngine/Resources/Texture.h>
+```
+
+## 枚举类型
+
+### TextureType
+
+纹理类型枚举。
+
+| 值 | 描述 |
+|----|------|
+| `Texture2D` | 2D 纹理 |
+| `Texture3D` | 3D 体积纹理 |
+| `TextureCube` | 立方体贴图 |
+| `Texture2DArray` | 2D 纹理数组 |
+| `TextureCubeArray` | 立方体贴图数组 |
+
+### TextureFormat
+
+纹理像素格式枚举。
+
+| 值 | 描述 |
+|----|------|
+| `Unknown` | 未知格式 |
+| `R8_UNORM` | 单通道 8 位归一化 |
+| `RG8_UNORM` | 双通道 8 位归一化 |
+| `RGBA8_UNORM` | 四通道 8 位归一化 |
+| `RGBA8_SRGB` | 四通道 8 位 sRGB |
+| `R16_FLOAT` | 单通道 16 位浮点 |
+| `RG16_FLOAT` | 双通道 16 位浮点 |
+| `RGBA16_FLOAT` | 四通道 16 位浮点 |
+| `R32_FLOAT` | 单通道 32 位浮点 |
+| `RG32_FLOAT` | 双通道 32 位浮点 |
+| `RGBA32_FLOAT` | 四通道 32 位浮点 |
+| `D16_UNORM` | 16 位深度 |
+| `D24_UNORM_S8_UINT` | 24 位深度 + 8 位模板 |
+| `D32_FLOAT` | 32 位深度 |
+| `D32_FLOAT_S8_X24_UINT` | 32 位深度 + 8+24 位模板 |
+| `BC1_UNORM` | BC1 压缩 (DXT1) |
+| `BC1_UNORM_SRGB` | BC1 sRGB |
+| `BC2_UNORM` | BC2 压缩 (DXT3) |
+| `BC2_UNORM_SRGB` | BC2 sRGB |
+| `BC3_UNORM` | BC3 压缩 (DXT5) |
+| `BC3_UNORM_SRGB` | BC3 sRGB |
+| `BC4_UNORM` | BC4 压缩 |
+| `BC5_UNORM` | BC5 压缩 |
+| `BC6H_UF16` | BC6H 压缩 |
+| `BC7_UNORM` | BC7 压缩 |
+| `BC7_UNORM_SRGB` | BC7 sRGB |
+
+### TextureUsage
+
+纹理用途标志枚举（可组合）。
+
+| 值 | 描述 |
+|----|------|
+| `None` | 无特殊用途 |
+| `ShaderResource` | 着色器资源 |
+| `RenderTarget` | 渲染目标 |
+| `DepthStencil` | 深度模板 |
+| `UnorderedAccess` | 无序访问 |
+| `TransferSrc` | 传输源 |
+| `TransferDst` | 传输目标 |
+
+## 公共方法
+
+### 基础属性
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceType GetType() const` | 返回 `ResourceType::Texture` |
+| `const Containers::String& GetName() const` | 获取纹理名称 |
+| `const Containers::String& GetPath() const` | 获取纹理路径 |
+| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
+| `bool IsValid() const` | 检查纹理是否有效 |
+| `size_t GetMemorySize() const` | 获取内存大小 |
+| `void Release()` | 释放纹理引用 |
+
+### 纹理属性
+
+| 方法 | 描述 |
+|------|------|
+| `Core::uint32 GetWidth() const` | 获取纹理宽度（像素） |
+| `Core::uint32 GetHeight() const` | 获取纹理高度（像素） |
+| `Core::uint32 GetDepth() const` | 获取纹理深度（3D 纹理） |
+| `Core::uint32 GetMipLevels() const` | 获取 Mipmap 级别数 |
+| `Core::uint32 GetArraySize() const` | 获取数组大小 |
+| `TextureType GetTextureType() const` | 获取纹理类型 |
+| `TextureFormat GetFormat() const` | 获取纹理格式 |
+| `TextureUsage GetUsage() const` | 获取纹理用途标志 |
+
+### 像素数据
+
+| 方法 | 描述 |
+|------|------|
+| `const void* GetPixelData() const` | 获取像素数据指针 |
+| `size_t GetPixelDataSize() const` | 获取像素数据大小 |
+
+### 创建与操作
+
+| 方法 | 描述 |
+|------|------|
+| `bool Create(Core::uint32 width, Core::uint32 height, Core::uint32 depth, Core::uint32 mipLevels, TextureType type, TextureFormat format, const void* data, size_t dataSize)` | 创建纹理 |
+| `bool GenerateMipmaps()` | 生成 Mipmap |
+
+## 使用示例
+
+```cpp
+// 加载纹理
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+
+// 手动创建纹理
+Texture tex;
+bool created = tex.Create(
+    1024,                          // 宽度
+    1024,                          // 高度
+    1,                             // 深度
+    0,                             // Mipmap 级别（0=全部）
+    TextureType::Texture2D,         // 类型
+    TextureFormat::RGBA8_UNORM,   // 格式
+    pixelData,                     // 像素数据
+    pixelDataSize                  // 数据大小
+);
+
+// 生成 Mipmap
+tex.GenerateMipmaps();
+
+// 访问纹理属性
+uint32_t w = tex.GetWidth();
+uint32_t h = tex.GetHeight();
+```
+
+## 相关文档
+
+- [IResource](../iresource/iresource.md) - 资源基类
+- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [RHITexture](../../rhi/texture/texture.md) - RHI 纹理接口
+- [Resources 总览](../resources.md) - 返回模块总览