refactor: reorganize docs into plan/ and add skills/

2026-03-18 17:49:22 +08:00
parent fc7c8f6797
commit 9bad996ecf
143 changed files with 13263 additions and 0 deletions
--- a/docs/api/resources/resources-asyncloader.md
+++ b/docs/api/resources/resources-asyncloader.md
@@ -0,0 +1,99 @@
+# AsyncLoader
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (singleton)
+
+**描述**: 异步资源加载器单例，负责多线程后台资源加载和完成回调调度。
+
+## 概述
+
+`AsyncLoader` 是 XCEngine 的后台异步加载系统。它使用独立工作线程从磁盘加载资源，并在加载完成后通过回调通知调用者。它维护待处理队列和完成队列，通过双缓冲机制实现无锁的线程安全操作。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static AsyncLoader& Get()` | 获取单例实例 |
+
+## LoadRequest 结构体
+
+异步加载请求结构体。
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `path` | `Containers::String` | 资源路径 |
+| `type` | `ResourceType` | 资源类型 |
+| `callback` | `std::function<void(LoadResult)>` | 加载完成回调函数 |
+| `settings` | `ImportSettings*` | 导入设置（可为 nullptr） |
+| `requestId` | `Core::uint64` | 请求唯一标识符 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize(Core::uint32 workerThreadCount = 2)` | 初始化异步加载器，创建工作线程 |
+| `void Shutdown()` | 关闭异步加载器，等待所有挂起任务完成 |
+
+### 提交请求
+
+| 方法 | 描述 |
+|------|------|
+| `void Submit(const Containers::String& path, ResourceType type, std::function<void(LoadResult)> callback)` | 提交异步加载请求 |
+| `void Submit(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function<void(LoadResult)> callback)` | 带设置的异步加载请求 |
+
+### 进度查询
+
+| 方法 | 描述 |
+|------|------|
+| `void Update()` | 更新函数，在主线程调用，处理完成的加载请求 |
+| `bool IsLoading() const` | 是否有正在加载的资源 |
+| `Core::uint32 GetPendingCount() const` | 获取待处理加载请求数量 |
+| `float GetProgress() const` | 获取整体加载进度（0.0f ~ 1.0f） |
+
+### 取消操作
+
+| 方法 | 描述 |
+|------|------|
+| `void CancelAll()` | 取消所有待处理的加载请求 |
+| `void Cancel(Core::uint64 requestId)` | 取消指定 ID 的加载请求 |
+
+## 使用示例
+
+```cpp
+// 初始化（使用 4 个工作线程）
+AsyncLoader::Get().Initialize(4);
+
+// 提交多个异步加载请求
+AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Texture> tex(result.resource);
+            printf("Texture loaded: %s\n", tex->GetPath().CStr());
+        }
+    });
+
+AsyncLoader::Get().Submit("models/player.fbx", ResourceType::Mesh,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Mesh> mesh(result.resource);
+            printf("Mesh loaded: %s\n", mesh->GetPath().CStr());
+        }
+    });
+
+// 在主循环中调用 Update 处理完成回调
+while (AsyncLoader::Get().IsLoading()) {
+    AsyncLoader::Get().Update();  // 在主线程分发回调
+    // 其他渲染逻辑...
+}
+
+// 关闭
+AsyncLoader::Get().Shutdown();
+```
+
+## 相关文档
+
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
+- [IResourceLoader](./resources-iloader.md) - 资源加载器接口
--- a/docs/api/resources/resources-audioclip.md
+++ b/docs/api/resources/resources-audioclip.md
@@ -0,0 +1,131 @@
+# AudioClip
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。
+
+## 概述
+
+`AudioClip` 是 XCEngine 中的音频资源类，继承自 `IResource`。它管理音频的原始样本数据、采样率、通道数、位深度、时长、格式类型和播放参数。
+
+## 头文件
+
+```cpp
+#include <XCEngine/Resources/AudioClip.h>
+```
+
+## 枚举类型
+
+### AudioFormat
+
+音频格式枚举。
+
+| 值 | 描述 |
+|----|------|
+| `Unknown` | 未知格式 |
+| `WAV` | WAV 格式 |
+| `OGG` | OGG Vorbis 格式 |
+| `MP3` | MP3 格式 |
+| `FLAC` | FLAC 无损格式 |
+
+### AudioType
+
+音频类型枚举。
+
+| 值 | 描述 |
+|----|------|
+| `SoundEffect` | 音效 |
+| `Music` | 音乐 |
+| `Voice` | 语音 |
+| `Ambient` | 环境音 |
+
+## 公共方法
+
+### 基础属性
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceType GetType() const` | 返回 `ResourceType::AudioClip` |
+| `const Containers::String& GetName() const` | 获取音频名称 |
+| `const Containers::String& GetPath() const` | 获取音频路径 |
+| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
+| `bool IsValid() const` | 检查音频是否有效 |
+| `size_t GetMemorySize() const` | 获取内存大小 |
+| `void Release()` | 释放音频引用 |
+
+### 音频数据
+
+| 方法 | 描述 |
+|------|------|
+| `void SetAudioData(const Containers::Array<Core::uint8>& data)` | 设置音频数据 |
+| `const Containers::Array<Core::uint8>& GetAudioData() const` | 获取音频数据指针 |
+
+### 音频参数
+
+| 方法 | 描述 |
+|------|------|
+| `void SetSampleRate(Core::uint32 rate)` | 设置采样率（Hz） |
+| `Core::uint32 GetSampleRate() const` | 获取采样率 |
+| `void SetChannels(Core::uint32 channels)` | 设置通道数（1=单声道, 2=立体声） |
+| `Core::uint32 GetChannels() const` | 获取通道数 |
+| `void SetBitsPerSample(Core::uint32 bits)` | 设置位深度（8/16/24/32） |
+| `Core::uint32 GetBitsPerSample() const` | 获取位深度 |
+| `void SetDuration(float seconds)` | 设置时长（秒） |
+| `float GetDuration() const` | 获取时长（秒） |
+
+### 格式与类型
+
+| 方法 | 描述 |
+|------|------|
+| `void SetAudioFormat(AudioFormat format)` | 设置音频格式 |
+| `AudioFormat GetAudioFormat() const` | 获取音频格式 |
+| `void SetAudioType(AudioType type)` | 设置音频类型 |
+| `AudioType GetAudioType() const` | 获取音频类型 |
+
+### 3D 和循环
+
+| 方法 | 描述 |
+|------|------|
+| `void SetIs3D(bool is3D)` | 设置是否为 3D 音频 |
+| `bool Is3D() const` | 检查是否为 3D 音频 |
+| `void SetLoop(bool loop)` | 设置是否循环播放 |
+| `bool IsLoop() const` | 检查是否循环播放 |
+
+### RHI 资源
+
+| 方法 | 描述 |
+|------|------|
+| `class IRHIAudioBuffer* GetRHIResource() const` | 获取 RHI 音频缓冲区 |
+| `void SetRHIResource(class IRHIAudioBuffer* resource)` | 设置 RHI 音频缓冲区 |
+
+## 使用示例
+
+```cpp
+// 加载音频
+ResourceHandle<AudioClip> sfx = ResourceManager::Get().Load<AudioClip>("sounds/explosion.wav");
+ResourceHandle<AudioClip> music = ResourceManager::Get().Load<AudioClip>("music/background.ogg");
+
+// 设置参数
+sfx->SetAudioType(AudioType::SoundEffect);
+sfx->SetSampleRate(44100);
+sfx->SetChannels(2);
+sfx->SetBitsPerSample(16);
+sfx->SetDuration(1.5f);
+sfx->SetLoop(false);
+
+// 3D 音频
+sfx->SetIs3D(false);
+music->SetIs3D(false);
+
+// 获取信息
+uint32_t sampleRate = sfx->GetSampleRate();
+float duration = sfx->GetDuration();
+bool loop = sfx->IsLoop();
+```
+
+## 相关文档
+
+- [IResource](./resources-iresource.md) - 资源基类
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
--- a/docs/api/resources/resources-dependencygraph.md
+++ b/docs/api/resources/resources-dependencygraph.md
@@ -0,0 +1,110 @@
+# ResourceDependencyGraph
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 资源依赖图管理器，负责跟踪资源之间的依赖关系、引用计数和拓扑排序。
+
+## 概述
+
+`ResourceDependencyGraph` 维护了所有资源之间的依赖关系图。它支持添加/移除依赖节点、查询依赖关系、循环依赖检测、拓扑排序（用于正确的加载/卸载顺序）等功能。
+
+## 公共方法
+
+### 节点管理
+
+| 方法 | 描述 |
+|------|------|
+| `void AddNode(ResourceGUID guid, ResourceType type)` | 添加依赖节点 |
+| `void RemoveNode(ResourceGUID guid)` | 移除依赖节点 |
+| `bool HasNode(ResourceGUID guid) const` | 检查节点是否存在 |
+
+### 依赖关系
+
+| 方法 | 描述 |
+|------|------|
+| `void AddDependency(ResourceGUID owner, ResourceGUID dependency)` | 添加依赖关系（A 依赖 B） |
+| `void RemoveDependency(ResourceGUID owner, ResourceGUID dependency)` | 移除依赖关系 |
+| `Containers::Array<ResourceGUID> GetDependencies(ResourceGUID guid) const` | 获取指定资源的直接依赖列表 |
+| `Containers::Array<ResourceGUID> GetDependents(ResourceGUID guid) const` | 获取依赖指定资源的所有资源列表 |
+| `Containers::Array<ResourceGUID> GetAllDependencies(ResourceGUID guid) const` | 获取所有递归依赖（包括传递依赖） |
+
+### 引用计数
+
+| 方法 | 描述 |
+|------|------|
+| `void IncrementRefCount(ResourceGUID guid)` | 增加引用计数 |
+| `void DecrementRefCount(ResourceGUID guid)` | 减少引用计数 |
+| `Core::uint32 GetRefCount(ResourceGUID guid) const` | 获取引用计数 |
+
+### 循环检测
+
+| 方法 | 描述 |
+|------|------|
+| `bool HasCircularDependency(ResourceGUID guid, Containers::Array<ResourceGUID>& outCycle) const` | 检测是否存在循环依赖 |
+
+### 排序与卸载
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::Array<ResourceGUID> TopologicalSort() const` | 拓扑排序（按依赖顺序） |
+| `bool Unload(ResourceGUID guid)` | 安全卸载（考虑依赖关系） |
+
+### 清理
+
+| 方法 | 描述 |
+|------|------|
+| `void Clear()` | 清空所有节点和依赖关系 |
+
+## DependencyNode 结构体
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 资源全局唯一标识符 |
+| `type` | `ResourceType` | 资源类型 |
+| `dependencies` | `Containers::Array<ResourceGUID>` | 此资源依赖的其他资源 |
+| `dependents` | `Containers::Array<ResourceGUID>` | 依赖此资源的其他资源 |
+| `refCount` | `Core::uint32` | 引用计数 |
+
+## 使用示例
+
+```cpp
+ResourceDependencyGraph graph;
+
+// 添加节点
+graph.AddNode(textureGuid, ResourceType::Texture);
+graph.AddNode(materialGuid, ResourceType::Material);
+graph.AddNode(shaderGuid, ResourceType::Shader);
+
+// 设置依赖关系：Material 依赖 Texture 和 Shader
+graph.AddDependency(materialGuid, textureGuid);
+graph.AddDependency(materialGuid, shaderGuid);
+
+// 查询依赖
+auto deps = graph.GetDependencies(materialGuid);
+// deps 包含 textureGuid 和 shaderGuid
+
+// 查询被依赖者
+auto dependents = graph.GetDependents(textureGuid);
+// dependents 包含 materialGuid
+
+// 拓扑排序（正确的加载顺序）
+auto loadOrder = graph.TopologicalSort();
+// loadOrder 保证依赖在目标之前加载
+
+// 循环依赖检测
+Containers::Array<ResourceGUID> cycle;
+if (graph.HasCircularDependency(guid, cycle)) {
+    printf("Circular dependency detected!");
+}
+
+// 引用计数
+graph.IncrementRefCount(guid);
+graph.DecrementRefCount(guid);
+```
+
+## 相关文档
+
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
+- [ResourceHandle](./resources-resourcehandle.md) - 资源句柄
--- a/docs/api/resources/resources-filesystem.md
+++ b/docs/api/resources/resources-filesystem.md
@@ -0,0 +1,118 @@
+# ResourceFileSystem
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 资源文件系统，负责资源文件的查找、读取和虚拟文件系统（支持目录和归档包）管理。
+
+## 概述
+
+`ResourceFileSystem` 实现了虚拟资源文件系统，支持从多个目录和归档包（如 `.zip`、`.pak`）中查找和读取资源。它通过 `IArchive` 接口支持不同的归档格式，并提供资源信息缓存。
+
+## IArchive 接口
+
+抽象归档接口，用于封装单个归档包或目录的读取操作。
+
+### 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `virtual bool Open(const Containers::String& path)` | 打开归档 |
+| `virtual void Close()` | 关闭归档 |
+| `virtual bool Read(fileName, buffer, size, offset)` | 从归档中读取文件 |
+| `virtual size_t GetSize(fileName)` | 获取文件大小 |
+| `virtual bool Exists(fileName)` | 检查文件是否存在 |
+| `virtual void Enumerate(pattern, outFiles)` | 枚举匹配的文件 |
+| `virtual bool IsValid() const` | 是否有效 |
+
+## ResourceInfo 结构体
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `path` | `Containers::String` | 资源相对路径 |
+| `size` | `size_t` | 文件大小（字节） |
+| `modifiedTime` | `Core::uint64` | 修改时间戳 |
+| `inArchive` | `bool` | 是否在归档包中 |
+| `archivePath` | `Containers::String` | 所属归档路径 |
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static ResourceFileSystem& Get()` | 获取单例实例 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize(const Containers::String& rootPath)` | 初始化，设置资源根目录 |
+| `void Shutdown()` | 关闭，释放所有归档 |
+
+### 归档和目录管理
+
+| 方法 | 描述 |
+|------|------|
+| `bool AddArchive(const Containers::String& archivePath)` | 添加归档包（优先查找） |
+| `bool AddDirectory(const Containers::String& directoryPath)` | 添加资源目录 |
+| `void RemoveArchive(const Containers::String& archivePath)` | 移除归档包 |
+
+### 资源查找
+
+| 方法 | 描述 |
+|------|------|
+| `bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath)` | 查找资源的绝对路径 |
+| `bool Exists(const Containers::String& relativePath)` | 检查资源是否存在 |
+| `Containers::Array<Core::uint8> ReadResource(const Containers::String& relativePath)` | 读取资源文件内容（字节数组） |
+
+### 资源信息
+
+| 方法 | 描述 |
+|------|------|
+| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo)` | 获取资源信息 |
+| `void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources)` | 枚举匹配的资源 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Resources/ResourceFileSystem.h>
+
+// 初始化资源文件系统
+ResourceFileSystem::Get().Initialize("resources/");
+
+// 添加归档包（优先于目录）
+ResourceFileSystem::Get().AddArchive("data/resources.pak");
+
+// 添加额外资源目录
+ResourceFileSystem::Get().AddDirectory("user_content/");
+
+// 检查资源是否存在
+if (ResourceFileSystem::Get().Exists("textures/player.png")) {
+    // 读取资源
+    auto data = ResourceFileSystem::Get().ReadResource("textures/player.png");
+    // 使用数据...
+}
+
+// 获取资源信息
+ResourceInfo info;
+if (ResourceFileSystem::Get().GetResourceInfo("shaders/default.vert", info)) {
+    printf("Size: %zu, InArchive: %s\n", info.size, info.inArchive ? "yes" : "no");
+}
+
+// 枚举资源
+Containers::Array<ResourceInfo> textures;
+ResourceFileSystem::Get().EnumerateResources("textures/*.png", textures);
+for (const auto& tex : textures) {
+    printf("Found: %s\n", tex.path.CStr());
+}
+
+// 关闭
+ResourceFileSystem::Get().Shutdown();
+```
+
+## 相关文档
+
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
+- [IResourceLoader](./resources-iloader.md) - 资源加载器
--- a/docs/api/resources/resources-iloader.md
+++ b/docs/api/resources/resources-iloader.md
@@ -0,0 +1,112 @@
+# IResourceLoader
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (abstract)
+
+**描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。
+
+## 概述
+
+`IResourceLoader` 是资源加载系统的核心抽象接口。它定义了同步和异步加载资源的方法，以及资源类型的查询和依赖信息的获取。`ResourceManager` 通过注册加载器来支持不同类型资源的加载。
+
+## 公共方法
+
+### 资源信息
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceType GetResourceType() const` | 获取此加载器支持的资源类型 |
+| `const Containers::String& GetResourceTypeName() const` | 获取资源类型的字符串名称 |
+| `size_t GetResourceSize(const Containers::String& path) const` | 获取资源文件大小 |
+
+### 同步加载
+
+| 方法 | 描述 |
+|------|------|
+| `LoadResult Load(const Containers::String& path, ImportSettings* settings)` | 同步加载资源 |
+| `bool Save(const Containers::String& path, IResource* resource)` | 保存资源到文件 |
+
+### 异步加载
+
+| 方法 | 描述 |
+|------|------|
+| `LoadResult LoadAsync(const Containers::String& path, ImportSettings* settings)` | 异步加载资源（内部使用） |
+
+### 依赖管理
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::Array<Containers::String> GetDependencies(const Containers::String& path) const` | 获取资源依赖的文件路径列表 |
+
+### 资源操作
+
+| 方法 | 描述 |
+|------|------|
+| `bool Reload(IResource* resource, const Containers::String& path)` | 重新加载资源 |
+| `void Unload(IResource* resource)` | 卸载资源 |
+
+### 文件系统
+
+| 方法 | 描述 |
+|------|------|
+| `bool Exists(const Containers::String& path) const` | 检查资源文件是否存在 |
+| `Containers::String ResolvePath(const Containers::String& relativePath) const` | 解析资源路径 |
+
+## LoadResult 结构体
+
+加载操作的返回值结构体。
+
+```cpp
+struct LoadResult {
+    IResource* resource = nullptr;           // 加载的资源对象
+    bool success = false;                     // 是否成功
+    Containers::String errorMessage;         // 错误信息
+    size_t memorySize = 0;                   // 资源内存大小
+    Containers::Array<Containers::String> dependencies;  // 依赖列表
+};
+```
+
+### 布尔转换
+
+| 转换 | 描述 |
+|------|------|
+| `explicit operator bool() const` | `success == true` 时返回 true |
+
+## 使用示例
+
+```cpp
+class TextureLoader : public IResourceLoader {
+public:
+    ResourceType GetResourceType() const override {
+        return ResourceType::Texture;
+    }
+    
+    const Containers::String& GetResourceTypeName() const override {
+        static Containers::String name = "Texture";
+        return name;
+    }
+    
+    LoadResult Load(const Containers::String& path, 
+                    ImportSettings* settings) override {
+        LoadResult result;
+        // 实现加载逻辑...
+        result.success = true;
+        result.resource = new Texture();
+        return result;
+    }
+    
+    Containers::Array<Containers::String> 
+    GetDependencies(const Containers::String& path) const override {
+        return {};  // 纹理通常无依赖
+    }
+};
+
+// 注册加载器
+ResourceManager::Get().RegisterLoader(new TextureLoader());
+```
+
+## 相关文档
+
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
+- [AsyncLoader](./resources-asyncloader.md) - 异步加载器
--- a/docs/api/resources/resources-importsettings.md
+++ b/docs/api/resources/resources-importsettings.md
@@ -0,0 +1,164 @@
+# ImportSettings
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (abstract)
+
+**描述**: 资源导入设置抽象基类，定义资源导入时的配置选项接口。
+
+## 概述
+
+`ImportSettings` 是所有资源导入设置的抽象基类。它提供了克隆和 JSON 序列化接口，允许不同资源类型定义各自的导入选项。引擎内置了两个具体实现：`TextureImportSettings` 和 `MeshImportSettings`。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `virtual Core::UniqueRef<ImportSettings> Clone() const = 0` | 克隆一份设置 |
+| `virtual bool LoadFromJSON(const Containers::String& json)` | 从 JSON 加载设置 |
+| `virtual Containers::String SaveToJSON() const` | 保存为 JSON 字符串 |
+
+---
+
+## TextureImportSettings
+
+纹理导入设置，继承自 `ImportSettings`。
+
+**头文件**: `XCEngine/Resources/TextureImportSettings.h`
+
+### 枚举类型
+
+#### MipmapFilter
+
+| 值 | 描述 |
+|----|------|
+| `Box` | Box 滤波器 |
+| `Kaiser` | Kaiser 滤波器 |
+
+#### CompressionQuality
+
+| 值 | 描述 |
+|----|------|
+| `Low` | 低质量 |
+| `Medium` | 中等质量 |
+| `High` | 高质量 |
+| `Ultra` | 超高质量 |
+
+### 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `void SetTextureType(TextureType type)` | 设置纹理类型 |
+| `TextureType GetTextureType() const` | 获取纹理类型 |
+| `void SetTargetFormat(TextureFormat format)` | 设置目标格式 |
+| `TextureFormat GetTargetFormat() const` | 获取目标格式 |
+| `void SetGenerateMipmaps(bool generate)` | 设置是否生成 Mipmap |
+| `bool GetGenerateMipmaps() const` | 获取是否生成 Mipmap |
+| `void SetMipmapFilter(MipmapFilter filter)` | 设置 Mipmap 滤波器 |
+| `MipmapFilter GetMipmapFilter() const` | 获取 Mipmap 滤波器 |
+| `void SetMaxAnisotropy(Core::uint32 anisotropy)` | 设置最大各向异性级别 |
+| `Core::uint32 GetMaxAnisotropy() const` | 获取最大各向异性级别 |
+| `void SetSRGB(bool srgb)` | 设置是否 sRGB |
+| `bool GetSRGB() const` | 获取 sRGB 设置 |
+| `void SetFlipVertical(bool flip)` | 设置是否垂直翻转 |
+| `bool GetFlipVertical() const` | 获取垂直翻转设置 |
+| `void SetFlipHorizontal(bool flip)` | 设置是否水平翻转 |
+| `bool GetFlipHorizontal() const` | 获取水平翻转设置 |
+| `void SetBorderColor(const Math::Vector3& color)` | 设置边框颜色 |
+| `const Math::Vector3& GetBorderColor() const` | 获取边框颜色 |
+| `void SetCompressionQuality(CompressionQuality quality)` | 设置压缩质量 |
+| `CompressionQuality GetCompressionQuality() const` | 获取压缩质量 |
+| `void SetUseHardwareCompression(bool use)` | 设置是否使用硬件压缩 |
+| `bool GetUseHardwareCompression() const` | 获取硬件压缩设置 |
+| `void SetMaxSize(Core::uint32 size)` | 设置最大纹理尺寸 |
+| `Core::uint32 GetMaxSize() const` | 获取最大纹理尺寸 |
+| `void SetGenerateNormalMap(bool generate)` | 设置是否生成法线贴图 |
+| `bool GetGenerateNormalMap() const` | 获取法线贴图生成设置 |
+| `void SetNormalMapStrength(float strength)` | 设置法线贴图强度 |
+| `float GetNormalMapStrength() const` | 获取法线贴图强度 |
+
+---
+
+## MeshImportSettings
+
+网格导入设置，继承自 `ImportSettings`。
+
+**头文件**: `XCEngine/Resources/MeshImportSettings.h`
+
+### MeshImportFlags
+
+| 值 | 描述 |
+|----|------|
+| `None` | 无特殊标志 |
+| `FlipUVs` | 翻转 UV 坐标 |
+| `FlipWindingOrder` | 翻转绕序 |
+| `GenerateNormals` | 生成法线 |
+| `GenerateTangents` | 生成切线 |
+| `OptimizeMesh` | 优化网格 |
+| `ImportSkinning` | 导入骨骼蒙皮 |
+| `ImportAnimations` | 导入动画 |
+| `ImportMaterials` | 导入材质 |
+| `ImportCameras` | 导入相机 |
+| `ImportLights` | 导入灯光 |
+
+支持位运算组合（`operator|`、`operator&`、`operator~`）。
+
+### 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `void SetImportFlags(MeshImportFlags flags)` | 设置导入标志 |
+| `MeshImportFlags GetImportFlags() const` | 获取导入标志 |
+| `void AddImportFlag(MeshImportFlags flag)` | 添加单个导入标志 |
+| `void RemoveImportFlag(MeshImportFlags flag)` | 移除单个导入标志 |
+| `bool HasImportFlag(MeshImportFlags flag) const` | 检查是否包含某标志 |
+| `void SetScale(float scale)` | 设置缩放 |
+| `float GetScale() const` | 获取缩放 |
+| `void SetOffset(const Math::Vector3& offset)` | 设置偏移 |
+| `const Math::Vector3& GetOffset() const` | 获取偏移 |
+| `void SetAxisConversion(bool convert)` | 设置轴转换 |
+| `bool GetAxisConversion() const` | 获取轴转换设置 |
+| `void SetMergeMeshes(bool merge)` | 设置是否合并网格 |
+| `bool GetMergeMeshes() const` | 获取合并网格设置 |
+| `void SetOptimizeThreshold(float threshold)` | 设置优化阈值 |
+| `float GetOptimizeThreshold() const` | 获取优化阈值 |
+| `void SetImportScale(float scale)` | 设置导入缩放 |
+| `float GetImportScale() const` | 获取导入缩放 |
+| `void SetThreshold(float threshold)` | 设置阈值 |
+| `float GetThreshold() const` | 获取阈值 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Resources/TextureImportSettings.h>
+#include <XCEngine/Resources/MeshImportSettings.h>
+
+// 纹理导入设置
+TextureImportSettings texSettings;
+texSettings.SetTextureType(RHI::TextureType::Texture2D);
+texSettings.SetGenerateMipmaps(true);
+texSettings.SetSRGB(true);
+texSettings.SetCompressionQuality(CompressionQuality::High);
+texSettings.SetMaxAnisotropy(16);
+
+// 加载设置
+texSettings.LoadFromJSON(R"({"sRGB":true,"maxAnisotropy":8})");
+
+// 保存设置
+Containers::String json = texSettings.SaveToJSON();
+
+// 网格导入设置
+MeshImportSettings meshSettings;
+meshSettings.SetImportFlags(MeshImportFlags::FlipUVs | MeshImportFlags::GenerateNormals);
+meshSettings.SetScale(1.0f);
+meshSettings.SetAxisConversion(true);
+
+// 使用设置加载资源
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png", &texSettings);
+ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("model.fbx", &meshSettings);
+```
+
+## 相关文档
+
+- [IResourceLoader](./resources-iloader.md) - 资源加载器
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
--- a/docs/api/resources/resources-iresource.md
+++ b/docs/api/resources/resources-iresource.md
@@ -0,0 +1,79 @@
+# IResource
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (abstract)
+
+**描述**: 资源基类接口，所有具体资源类型（Texture、Mesh、Material 等）都必须继承自此类。
+
+## 概述
+
+`IResource` 是 XCEngine 资源管理系统的核心抽象基类。它定义了所有资源共有的基本属性和行为，包括资源类型、名称、路径、GUID、内存大小和有效性状态。
+
+## 公共方法
+
+### 基础属性
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceType GetType() const` | 获取资源类型 |
+| `const Containers::String& GetName() const` | 获取资源名称 |
+| `const Containers::String& GetPath() const` | 获取资源路径 |
+| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
+| `bool IsValid() const` | 检查资源是否有效 |
+| `size_t GetMemorySize() const` | 获取资源占用的内存大小（字节） |
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Release()` | 释放资源引用 |
+
+### 构造参数
+
+```cpp
+struct ConstructParams {
+    Containers::String name;      // 资源名称
+    Containers::String path;       // 资源路径
+    ResourceGUID guid;             // 全局唯一标识符
+    size_t memorySize = 0;         // 内存大小
+};
+```
+
+### 初始化方法
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize(const ConstructParams& params)` | 使用构造参数初始化资源 |
+| `void SetInvalid()` | 将资源标记为无效 |
+
+## 公共成员
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `m_name` | `Containers::String` | 资源名称 |
+| `m_path` | `Containers::String` | 资源路径 |
+| `m_guid` | `ResourceGUID` | 全局唯一标识符 |
+| `m_isValid` | `bool` | 资源是否有效 |
+| `m_memorySize` | `size_t` | 内存占用大小 |
+
+## 使用示例
+
+```cpp
+class MyResource : public IResource {
+public:
+    ResourceType GetType() const override { return ResourceType::Custom; }
+    const Containers::String& GetName() const override { return m_name; }
+    const Containers::String& GetPath() const override { return m_path; }
+    ResourceGUID GetGUID() const override { return m_guid; }
+    bool IsValid() const override { return m_isValid; }
+    size_t GetMemorySize() const override { return m_memorySize; }
+    void Release() override { /* 释放逻辑 */ }
+};
+```
+
+## 相关文档
+
+- [ResourceHandle](./resources-resourcehandle.md) - 资源句柄
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
+- [ResourceTypes](./resources-resourcetypes.md) - 资源类型定义
--- a/docs/api/resources/resources-material.md
+++ b/docs/api/resources/resources-material.md
@@ -0,0 +1,146 @@
+# Material
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 材质资源类，管理渲染所需的着色器和属性参数。
+
+## 概述
+
+`Material` 是 XCEngine 中的材质资源类，继承自 `IResource`。它管理材质关联的着色器和各种属性参数（浮点数、向量、纹理等），并支持将属性数据打包到常量缓冲区。
+
+## 头文件
+
+```cpp
+#include <XCEngine/Resources/Material.h>
+```
+
+## 枚举类型
+
+### MaterialPropertyType
+
+材质属性类型枚举。
+
+| 值 | 描述 |
+|----|------|
+| `Float` | 单精度浮点数 |
+| `Float2` | 二维浮点向量 |
+| `Float3` | 三维浮点向量 |
+| `Float4` | 四维浮点向量 |
+| `Int` | 整数 |
+| `Int2` | 二维整数向量 |
+| `Int3` | 三维整数向量 |
+| `Int4` | 四维整数向量 |
+| `Bool` | 布尔值 |
+| `Texture` | 纹理资源 |
+| `Cubemap` | 立方体贴图资源 |
+
+## 结构体
+
+### MaterialProperty
+
+材质属性结构体。
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `name` | `Containers::String` | 属性名称 |
+| `type` | `MaterialPropertyType` | 属性类型 |
+| `value` | `union` | 属性值（float/int/bool） |
+| `refCount` | `Core::uint32` | 引用计数 |
+
+## 公共方法
+
+### 基础属性
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceType GetType() const` | 返回 `ResourceType::Material` |
+| `const Containers::String& GetName() const` | 获取材质名称 |
+| `const Containers::String& GetPath() const` | 获取材质路径 |
+| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
+| `bool IsValid() const` | 检查材质是否有效 |
+| `size_t GetMemorySize() const` | 获取内存大小 |
+| `void Release()` | 释放材质引用 |
+
+### 着色器管理
+
+| 方法 | 描述 |
+|------|------|
+| `void SetShader(const ResourceHandle<Shader>& shader)` | 设置材质着色器 |
+| `Shader* GetShader() const` | 获取材质着色器 |
+
+### 属性设置
+
+| 方法 | 描述 |
+|------|------|
+| `void SetFloat(const Containers::String& name, float value)` | 设置浮点属性 |
+| `void SetFloat2(const Containers::String& name, const Math::Vector2& value)` | 设置 Vector2 属性 |
+| `void SetFloat3(const Containers::String& name, const Math::Vector3& value)` | 设置 Vector3 属性 |
+| `void SetFloat4(const Containers::String& name, const Math::Vector4& value)` | 设置 Vector4 属性 |
+| `void SetInt(const Containers::String& name, Core::int32 value)` | 设置整数属性 |
+| `void SetBool(const Containers::String& name, bool value)` | 设置布尔属性 |
+| `void SetTexture(const Containers::String& name, const ResourceHandle<Texture>& texture)` | 设置纹理属性 |
+
+### 属性获取
+
+| 方法 | 描述 |
+|------|------|
+| `float GetFloat(const Containers::String& name) const` | 获取浮点属性 |
+| `Math::Vector2 GetFloat2(const Containers::String& name) const` | 获取 Vector2 属性 |
+| `Math::Vector3 GetFloat3(const Containers::String& name) const` | 获取 Vector3 属性 |
+| `Math::Vector4 GetFloat4(const Containers::String& name) const` | 获取 Vector4 属性 |
+| `Core::int32 GetInt(const Containers::String& name) const` | 获取整数属性 |
+| `bool GetBool(const Containers::String& name) const` | 获取布尔属性 |
+| `ResourceHandle<Texture> GetTexture(const Containers::String& name) const` | 获取纹理属性 |
+
+### 常量缓冲区
+
+| 方法 | 描述 |
+|------|------|
+| `const Containers::Array<Core::uint8>& GetConstantBufferData() const` | 获取常量缓冲区数据 |
+| `void UpdateConstantBuffer()` | 更新常量缓冲区数据 |
+
+### 属性管理
+
+| 方法 | 描述 |
+|------|------|
+| `bool HasProperty(const Containers::String& name) const` | 检查属性是否存在 |
+| `void RemoveProperty(const Containers::String& name)` | 移除属性 |
+| `void ClearAllProperties()` | 清空所有属性 |
+
+## 使用示例
+
+```cpp
+// 加载材质
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
+
+// 设置着色器
+mat->SetShader(shaderHandle);
+
+// 设置各种属性
+mat->SetFloat("roughness", 0.5f);
+mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f));
+mat->SetTexture("albedoMap", albedoTex);
+mat->SetTexture("normalMap", normalTex);
+mat->SetInt("normalScale", 1);
+
+// 获取属性
+float roughness = mat->GetFloat("roughness");
+Math::Vector3 albedo = mat->GetFloat3("albedo");
+
+// 检查属性
+if (mat->HasProperty("metallic")) {
+    float metallic = mat->GetFloat("metallic");
+}
+
+// 更新常量缓冲区
+mat->UpdateConstantBuffer();
+auto cbData = mat->GetConstantBufferData();
+```
+
+## 相关文档
+
+- [IResource](./resources-iresource.md) - 资源基类
+- [Shader](./resources-shader.md) - 着色器资源
+- [Texture](./resources-texture.md) - 纹理资源
--- a/docs/api/resources/resources-mesh.md
+++ b/docs/api/resources/resources-mesh.md
@@ -0,0 +1,148 @@
+# 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](./resources-iresource.md) - 资源基类
+- [Material](./resources-material.md) - 材质资源
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
--- a/docs/api/resources/resources-overview.md
+++ b/docs/api/resources/resources-overview.md
@@ -0,0 +1,82 @@
+# Resources 模块概览
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `module`
+
+**描述**: XCEngine 的资源管理系统，提供资源的异步加载、缓存和依赖管理。
+
+## 概述
+
+Resources 模块提供了一套完整的资源管理解决方案，支持同步和异步加载、资源缓存、依赖图管理等功能。
+
+## 模块内容
+
+### 核心组件
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [IResource](./resources-iresource.md) | `IResource.h` | 资源基类 |
+| [ResourceHandle](./resources-resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 |
+| [IResourceLoader](./resources-iloader.md) | `IResourceLoader.h` | 资源加载器接口 |
+| [ResourceManager](./resources-resourcemanager.md) | `ResourceManager.h` | 资源管理器 |
+| [ResourceCache](./resources-resourcecache.md) | `ResourceCache.h` | 资源缓存 |
+| [AsyncLoader](./resources-asyncloader.md) | `AsyncLoader.h` | 异步加载器 |
+| [ResourceDependencyGraph](./resources-dependencygraph.md) | `ResourceDependencyGraph.h` | 依赖图 |
+| [ResourceTypes](./resources-resourcetypes.md) | `ResourceTypes.h` | 资源类型定义 |
+
+### 具体资源类型
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Texture](./resources-texture.md) | `Texture.h` | 纹理资源 |
+| [Mesh](./resources-mesh.md) | `Mesh.h` | 网格资源 |
+| [Material](./resources-material.md) | `Material.h` | 材质资源 |
+| [Shader](./resources-shader.md) | `Shader.h` | 着色器资源 |
+| [AudioClip](./resources-audioclip.md) | `AudioClip.h` | 音频资源 |
+
+## 资源类型
+
+| 类型 | 描述 |
+|------|------|
+| `Texture` | 纹理资源 |
+| `Mesh` | 网格/模型资源 |
+| `Material` | 材质资源 |
+| `Shader` | 着色器资源 |
+| `AudioClip` | 音频资源 |
+| `Binary` | 二进制数据 |
+| `AnimationClip` | 动画片段 |
+| `Skeleton` | 骨骼 |
+| `Font` | 字体 |
+| `ParticleSystem` | 粒子系统 |
+| `Scene` | 场景 |
+| `Prefab` | 预制体 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Resources/ResourceManager.h>
+
+// 初始化资源管理器
+ResourceManager::Get().Initialize();
+ResourceManager::Get().SetResourceRoot("resources/");
+
+// 同步加载资源
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
+
+// 异步加载
+ResourceManager::Get().LoadAsync<Texture>("textures/terrain.png", 
+    [](ResourceHandle<Texture> tex) {
+        // 加载完成回调
+    });
+
+// 释放资源
+tex.Reset();
+mesh.Reset();
+```
+
+## 相关文档
+
+- [RHI 模块](../rhi/rhi-overview.md) - GPU 资源创建
--- a/docs/api/resources/resources-resourcecache.md
+++ b/docs/api/resources/resources-resourcecache.md
@@ -0,0 +1,98 @@
+# ResourceCache
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 资源缓存管理类，使用 LRU（最近最少使用）策略管理内存压力下的资源驱逐。
+
+## 概述
+
+`ResourceCache` 实现了资源的内存缓存管理。它跟踪每个资源的访问时间和访问次数，在内存压力下自动驱逐最近最少使用的资源，确保内存使用不超过预算。
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceCache()` | 默认构造函数 |
+| `~ResourceCache()` | 析构函数 |
+
+### 缓存操作
+
+| 方法 | 描述 |
+|------|------|
+| `void Add(ResourceGUID guid, IResource* resource)` | 添加资源到缓存 |
+| `void Remove(ResourceGUID guid)` | 从缓存中移除资源 |
+| `IResource* Find(ResourceGUID guid) const` | 查找资源 |
+| `void Touch(ResourceGUID guid)` | 更新资源的访问时间（LRU） |
+
+### 内存管理
+
+| 方法 | 描述 |
+|------|------|
+| `size_t GetSize() const` | 获取缓存中资源数量 |
+| `size_t GetMemoryUsage() const` | 获取缓存内存使用量（字节） |
+| `void SetMemoryBudget(size_t bytes)` | 设置内存预算 |
+| `size_t GetMemoryBudget() const` | 获取内存预算 |
+| `void OnMemoryPressure(size_t requiredBytes)` | 内存压力回调，驱逐资源以释放空间 |
+| `void OnZeroRefCount(ResourceGUID guid)` | 当引用计数为零时的回调 |
+
+### 缓存控制
+
+| 方法 | 描述 |
+|------|------|
+| `void Flush()` | 清空缓存，释放所有资源 |
+| `void Clear()` | 清空缓存但不释放资源 |
+
+### LRU 信息
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::Array<ResourceGUID> GetLRUList(size_t count) const` | 获取最近最少使用的 GUID 列表 |
+
+## CacheEntry 结构体
+
+缓存条目结构体。
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `resource` | `IResource*` | 资源指针 |
+| `guid` | `ResourceGUID` | 全局唯一标识符 |
+| `memorySize` | `size_t` | 内存大小 |
+| `lastAccessTime` | `Core::uint64` | 上次访问时间戳 |
+| `accessCount` | `Core::uint32` | 访问次数 |
+
+### 静态方法
+
+| 方法 | 描述 |
+|------|------|
+| `static Core::uint64 GetCurrentTick()` | 获取当前时间戳 |
+
+## 使用示例
+
+```cpp
+ResourceCache cache;
+cache.SetMemoryBudget(512 * 1024 * 1024);  // 512MB 预算
+
+// 添加资源
+cache.Add(guid, resource);
+
+// 访问资源（更新 LRU）
+cache.Touch(guid);
+
+// 查找资源
+IResource* res = cache.Find(guid);
+
+// 内存压力时自动驱逐
+cache.OnMemoryPressure(100 * 1024 * 1024);  // 需要 100MB
+
+// 获取最少使用的资源
+auto lruList = cache.GetLRUList(10);
+```
+
+## 相关文档
+
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
+- [IResource](./resources-iresource.md) - 资源基类
--- a/docs/api/resources/resources-resourcehandle.md
+++ b/docs/api/resources/resources-resourcehandle.md
@@ -0,0 +1,100 @@
+# ResourceHandle
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (template)
+
+**描述**: 模板资源句柄类，提供资源的引用计数式安全访问，自动管理资源的加载和释放。
+
+## 概述
+
+`ResourceHandle<T>` 是一个模板句柄类，用于安全地持有对资源的引用。它通过 `ResourceManager` 自动管理引用计数：当句柄被创建时引用计数增加，当句柄被销毁或调用 `Reset()` 时引用计数减少。这确保了资源在其仍被使用时不会被卸载。
+
+## 模板参数
+
+| 参数 | 约束 | 描述 |
+|------|------|------|
+| `T` | 必须派生自 `IResource` | 资源类型 |
+
+## 公共方法
+
+### 构造/析构
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceHandle() = default` | 默认构造空句柄 |
+| `explicit ResourceHandle(T* resource)` | 从裸指针构造（自动增加引用） |
+| `ResourceHandle(const ResourceHandle& other)` | 拷贝构造（自动增加引用） |
+| `ResourceHandle(ResourceHandle&& other) noexcept` | 移动构造 |
+| `~ResourceHandle()` | 析构函数（自动调用 Reset） |
+
+### 赋值
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceHandle& operator=(const ResourceHandle& other)` | 拷贝赋值（自动管理引用） |
+| `ResourceHandle& operator=(ResourceHandle&& other) noexcept` | 移动赋值 |
+
+### 资源访问
+
+| 方法 | 描述 |
+|------|------|
+| `T* Get() const` | 获取裸指针 |
+| `T* operator->() const` | 通过指针访问资源成员 |
+| `T& operator*() const` | 解引用获取资源引用 |
+
+### 状态查询
+
+| 方法 | 描述 |
+|------|------|
+| `bool IsValid() const` | 检查句柄是否持有有效资源 |
+| `explicit operator bool() const` | 隐式布尔转换 |
+
+### GUID 和类型
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceGUID GetGUID() const` | 获取资源的全局唯一标识符 |
+| `ResourceType GetResourceType() const` | 获取资源类型 |
+
+### 资源释放
+
+| 方法 | 描述 |
+|------|------|
+| `void Reset()` | 释放当前资源引用 |
+| `void Swap(ResourceHandle& other)` | 交换两个句柄的内容 |
+
+## 比较运算
+
+| 运算符 | 描述 |
+|------|------|
+| `operator==(ResourceHandle, ResourceHandle)` | 比较 GUID 是否相等 |
+| `operator!=(ResourceHandle, ResourceHandle)` | 比较 GUID 是否不等 |
+
+## 使用示例
+
+```cpp
+// 加载资源（引用计数 +1）
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+
+// 检查有效性
+if (tex.IsValid()) {
+    // 安全访问资源
+    uint32_t width = tex->GetWidth();
+}
+
+// 拷贝句柄（引用计数 +1）
+ResourceHandle<Texture> tex2 = tex;
+
+// 移动句柄
+ResourceHandle<Texture> tex3 = std::move(tex2);
+
+// 句柄离开作用域时自动释放（引用计数 -1）
+tex.Reset();  // 手动释放
+```
+
+## 相关文档
+
+- [IResource](./resources-iresource.md) - 资源基类
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
+- [ResourceCache](./resources-resourcecache.md) - 资源缓存
--- a/docs/api/resources/resources-resourcemanager.md
+++ b/docs/api/resources/resources-resourcemanager.md
@@ -0,0 +1,166 @@
+# ResourceManager
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (singleton)
+
+**描述**: 资源管理器单例，负责资源的加载、缓存、引用计数管理和异步加载调度。
+
+## 概述
+
+`ResourceManager` 是 XCEngine 资源管理系统的核心单例类。它提供统一的资源加载接口、自动缓存管理、引用计数跟踪和异步加载支持。所有资源访问都应通过 `ResourceManager` 进行。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static ResourceManager& Get()` | 获取单例实例 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize()` | 初始化资源管理器 |
+| `void Shutdown()` | 关闭资源管理器，卸载所有资源 |
+
+### 资源根目录
+
+| 方法 | 描述 |
+|------|------|
+| `void SetResourceRoot(const Containers::String& rootPath)` | 设置资源根目录 |
+| `const Containers::String& GetResourceRoot() const` | 获取资源根目录 |
+
+### 同步加载
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceHandle<T> Load(const Containers::String& path, ImportSettings* settings = nullptr)` | 同步加载资源（模板方法） |
+
+### 异步加载
+
+| 方法 | 描述 |
+|------|------|
+| `void LoadAsync(const Containers::String& path, ResourceType type, std::function<void(LoadResult)> callback)` | 异步加载资源 |
+| `void LoadAsync(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function<void(LoadResult)> callback)` | 带设置的异步加载 |
+
+### 批量加载
+
+| 方法 | 描述 |
+|------|------|
+| `void LoadGroup(const Containers::Array<Containers::String>& paths, std::function<void(ResourceHandle<T>)> callback)` | 批量异步加载同类资源 |
+
+### 卸载管理
+
+| 方法 | 描述 |
+|------|------|
+| `void Unload(const Containers::String& path)` | 按路径卸载资源 |
+| `void Unload(ResourceGUID guid)` | 按 GUID 卸载资源 |
+| `void UnloadUnused()` | 卸载所有无引用的资源 |
+| `void UnloadAll()` | 卸载所有资源 |
+
+### 引用计数
+
+| 方法 | 描述 |
+|------|------|
+| `void AddRef(ResourceGUID guid)` | 增加引用计数（内部使用） |
+| `void Release(ResourceGUID guid)` | 减少引用计数（内部使用） |
+| `Core::uint32 GetRefCount(ResourceGUID guid) const` | 获取引用计数 |
+
+### 查找
+
+| 方法 | 描述 |
+|------|------|
+| `IResource* Find(const Containers::String& path)` | 按路径查找资源 |
+| `IResource* Find(ResourceGUID guid)` | 按 GUID 查找资源 |
+| `bool Exists(const Containers::String& path) const` | 检查资源是否存在 |
+| `bool Exists(ResourceGUID guid) const` | 检查 GUID 对应资源是否存在 |
+
+### 加载器管理
+
+| 方法 | 描述 |
+|------|------|
+| `void RegisterLoader(IResourceLoader* loader)` | 注册资源加载器 |
+| `void UnregisterLoader(ResourceType type)` | 注销加载器 |
+| `IResourceLoader* GetLoader(ResourceType type) const` | 获取指定类型的加载器 |
+
+### 内存管理
+
+| 方法 | 描述 |
+|------|------|
+| `void SetMemoryBudget(size_t bytes)` | 设置内存预算 |
+| `size_t GetMemoryUsage() const` | 获取当前内存使用量 |
+| `size_t GetMemoryBudget() const` | 获取内存预算 |
+| `void FlushCache()` | 清空缓存 |
+
+### 路径解析
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::String ResolvePath(const Containers::String& relativePath) const` | 将相对路径解析为绝对路径 |
+
+### 资源信息
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::Array<Containers::String> GetResourcePaths() const` | 获取所有已加载资源的路径列表 |
+| `void UnloadGroup(const Containers::Array<ResourceGUID>& guids)` | 按 GUID 批量卸载 |
+
+## 私有方法（内部使用）
+
+| 方法 | 描述 |
+|------|------|
+| `IResource* FindInCache(ResourceGUID guid)` | 在缓存中查找资源 |
+| `void AddToCache(ResourceGUID guid, IResource* resource)` | 添加到缓存 |
+| `IResourceLoader* FindLoader(ResourceType type)` | 查找加载器 |
+| `void ReloadResource(ResourceGUID guid)` | 重新加载资源 |
+
+## 使用示例
+
+```cpp
+// 初始化
+ResourceManager::Get().Initialize();
+ResourceManager::Get().SetResourceRoot("resources/");
+
+// 注册加载器
+ResourceManager::Get().RegisterLoader(new TextureLoader());
+ResourceManager::Get().RegisterLoader(new MeshLoader());
+ResourceManager::Get().RegisterLoader(new MaterialLoader());
+
+// 同步加载
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
+
+// 异步加载
+ResourceManager::Get().LoadAsync<Texture>("textures/terrain.png",
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Texture> tex(result.resource);
+            // 使用纹理...
+        }
+    });
+
+// 批量加载
+Containers::Array<Containers::String> paths = {"a.png", "b.png", "c.png"};
+ResourceManager::Get().LoadGroup<Texture>(paths,
+    [](ResourceHandle<Texture> tex) {
+        if (tex.IsValid()) {
+            // 处理加载完成的纹理...
+        }
+    });
+
+// 设置内存预算
+ResourceManager::Get().SetMemoryBudget(1024 * 1024 * 1024);  // 1GB
+
+// 卸载
+ResourceManager::Get().UnloadUnused();
+ResourceManager::Get().Shutdown();
+```
+
+## 相关文档
+
+- [IResource](./resources-iresource.md) - 资源基类
+- [ResourceHandle](./resources-resourcehandle.md) - 资源句柄
+- [ResourceCache](./resources-resourcecache.md) - 资源缓存
+- [AsyncLoader](./resources-asyncloader.md) - 异步加载器
--- a/docs/api/resources/resources-resourcetypes.md
+++ b/docs/api/resources/resources-resourcetypes.md
@@ -0,0 +1,101 @@
+# ResourceTypes
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `enums` / `structs`
+
+**描述**: 资源模块中使用的所有类型定义，包括资源类型枚举、GUID 结构体等。
+
+## 概述
+
+本文档汇总了 Resources 模块中的所有类型定义，包括资源类型枚举、GUID 结构体等基础类型。
+
+---
+
+## ResourceType
+
+资源类型枚举。
+
+| 值 | 描述 |
+|----|------|
+| `Unknown` | 未知类型 |
+| `Texture` | 纹理资源 |
+| `Mesh` | 网格/模型资源 |
+| `Material` | 材质资源 |
+| `Shader` | 着色器资源 |
+| `AudioClip` | 音频资源 |
+| `Binary` | 二进制数据 |
+| `AnimationClip` | 动画片段 |
+| `Skeleton` | 骨骼 |
+| `Font` | 字体 |
+| `ParticleSystem` | 粒子系统 |
+| `Scene` | 场景 |
+| `Prefab` | 预制体 |
+
+---
+
+## ResourceGUID
+
+全局唯一标识符结构体，用于唯一标识每个资源。
+
+```cpp
+struct ResourceGUID {
+    uint64_t value = 0;
+};
+```
+
+### 构造方法
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceGUID()` | 默认构造（值为 0） |
+| `explicit ResourceGUID(uint64_t value)` | 从整数值构造 |
+
+### 比较运算
+
+| 运算符 | 描述 |
+|------|------|
+| `operator==(ResourceGUID, ResourceGUID)` | 判断相等 |
+| `operator!=(ResourceGUID, ResourceGUID)` | 判断不等 |
+
+### 哈希支持
+
+`ResourceGUID` 可作为 HashMap 的键使用。
+
+### 静态方法
+
+| 方法 | 描述 |
+|------|------|
+| `static ResourceGUID Generate(const Containers::String& path)` | 从资源路径生成唯一 GUID |
+
+---
+
+## 辅助函数
+
+| 函数 | 描述 |
+|------|------|
+| `const char* GetResourceTypeName(ResourceType type)` | 获取资源类型的字符串名称 |
+
+---
+
+## 使用示例
+
+```cpp
+// 使用 ResourceGUID
+ResourceGUID texGuid = ResourceGUID::Generate("textures/player.png");
+ResourceGUID meshGuid = ResourceGUID::Generate("models/player.fbx");
+
+// GUID 比较
+if (texGuid == meshGuid) {
+    // 相同资源
+}
+
+// 在 HashMap 中使用
+Containers::HashMap<ResourceGUID, IResource*> cache;
+cache[texGuid] = texture;
+```
+
+## 相关文档
+
+- [IResource](./resources-iresource.md) - 资源基类
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
--- a/docs/api/resources/resources-shader.md
+++ b/docs/api/resources/resources-shader.md
@@ -0,0 +1,149 @@
+# Shader
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 着色器资源类，管理着色器源码、编译后的二进制和 uniform/attribute 信息。
+
+## 概述
+
+`Shader` 是 XCEngine 中的着色器资源类，继承自 `IResource`。它管理着色器源码、编译后的二进制数据、着色器类型、语言类型、uniform 列表和 attribute 列表，并持有对应的 RHI 着色器资源指针。
+
+## 头文件
+
+```cpp
+#include <XCEngine/Resources/Shader.h>
+```
+
+## 枚举类型
+
+### ShaderType
+
+着色器类型枚举。
+
+| 值 | 描述 |
+|----|------|
+| `Vertex` | 顶点着色器 |
+| `Fragment` | 片元着色器 |
+| `Geometry` | 几何着色器 |
+| `Compute` | 计算着色器 |
+| `Hull` | Hull 着色器（曲面细分控制） |
+| `Domain` | Domain 着色器（曲面细分评估） |
+
+### ShaderLanguage
+
+着色器语言枚举。
+
+| 值 | 描述 |
+|----|------|
+| `GLSL` | OpenGL Shading Language |
+| `HLSL` | High-Level Shading Language |
+| `SPIRV` | SPIR-V 二进制格式 |
+
+## 结构体
+
+### ShaderUniform
+
+Uniform 变量描述。
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `name` | `Containers::String` | Uniform 名称 |
+| `location` | `Core::uint32` | 位置/绑定点 |
+| `size` | `Core::uint32` | 大小（字节） |
+| `type` | `Core::uint32` | 类型标识 |
+
+### ShaderAttribute
+
+顶点属性描述。
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `name` | `Containers::String` | 属性名称 |
+| `location` | `Core::uint32` | 位置索引 |
+| `size` | `Core::uint32` | 大小（字节） |
+| `type` | `Core::uint32` | 类型标识 |
+
+## 公共方法
+
+### 基础属性
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceType GetType() const` | 返回 `ResourceType::Shader` |
+| `const Containers::String& GetName() const` | 获取着色器名称 |
+| `const Containers::String& GetPath() const` | 获取着色器路径 |
+| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
+| `bool IsValid() const` | 检查着色器是否有效 |
+| `size_t GetMemorySize() const` | 获取内存大小 |
+| `void Release()` | 释放着色器引用 |
+
+### 类型与语言
+
+| 方法 | 描述 |
+|------|------|
+| `void SetShaderType(ShaderType type)` | 设置着色器类型 |
+| `ShaderType GetShaderType() const` | 获取着色器类型 |
+| `void SetShaderLanguage(ShaderLanguage lang)` | 设置着色器语言 |
+| `ShaderLanguage GetShaderLanguage() const` | 获取着色器语言 |
+
+### 源码与编译
+
+| 方法 | 描述 |
+|------|------|
+| `void SetSourceCode(const Containers::String& source)` | 设置源码 |
+| `const Containers::String& GetSourceCode() const` | 获取源码 |
+| `void SetCompiledBinary(const Containers::Array<Core::uint8>& binary)` | 设置编译后二进制 |
+| `const Containers::Array<Core::uint8>& GetCompiledBinary() const` | 获取编译后二进制 |
+
+### Uniform 和 Attribute
+
+| 方法 | 描述 |
+|------|------|
+| `void AddUniform(const ShaderUniform& uniform)` | 添加 Uniform 描述 |
+| `const Containers::Array<ShaderUniform>& GetUniforms() const` | 获取 Uniform 列表 |
+| `void AddAttribute(const ShaderAttribute& attribute)` | 添加 Attribute 描述 |
+| `const Containers::Array<ShaderAttribute>& GetAttributes() const` | 获取 Attribute 列表 |
+
+### RHI 资源
+
+| 方法 | 描述 |
+|------|------|
+| `class IRHIShader* GetRHIResource() const` | 获取 RHI 着色器资源 |
+| `void SetRHIResource(class IRHIShader* resource)` | 设置 RHI 着色器资源 |
+
+## 使用示例
+
+```cpp
+// 加载着色器
+ResourceHandle<Shader> vs = ResourceManager::Get().Load<Shader>("shaders/vertex.glsl");
+ResourceHandle<Shader> fs = ResourceManager::Get().Load<Shader>("shaders/fragment.glsl");
+
+// 设置类型
+vs->SetShaderType(ShaderType::Vertex);
+fs->SetShaderType(ShaderType::Fragment);
+
+// 设置语言
+vs->SetShaderLanguage(ShaderLanguage::GLSL);
+
+// 设置编译后二进制
+vs->SetCompiledBinary(compiledSpirv);
+
+// 添加 Uniform
+ShaderUniform uniform;
+uniform.name = "modelMatrix";
+uniform.location = 0;
+uniform.size = sizeof(float) * 16;
+uniform.type = 0;
+vs->AddUniform(uniform);
+
+// 访问 RHI 资源
+RHIShader* rhiShader = vs->GetRHIResource();
+```
+
+## 相关文档
+
+- [IResource](./resources-iresource.md) - 资源基类
+- [RHIShader](../rhi/rhi-shader.md) - RHI 着色器接口
+- [Material](./resources-material.md) - 材质资源
--- a/docs/api/resources/resources-texture.md
+++ b/docs/api/resources/resources-texture.md
@@ -0,0 +1,152 @@
+# 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](./resources-iresource.md) - 资源基类
+- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
+- [RHITexture](../rhi/rhi-texture.md) - RHI 纹理接口