docs: update resources API docs

docs/api/resources/resource-dependency-graph/add-dependency.md

@@ -0,0 +1,36 @@
+# AddDependency
+
+添加资源之间的依赖关系。
+
+## 方法签名
+
+```cpp
+void AddDependency(ResourceGUID owner, ResourceGUID dependency);
+```
+
+## 详细描述
+
+在两个已存在的节点之间建立依赖关系。`owner` 节点依赖于 `dependency` 节点，即 `dependency` 会被 `owner` 使用。该方法会同时更新两个节点的关联数组：
+- 将 `dependency` 添加到 `owner` 的 `dependencies` 列表
+- 将 `owner` 添加到 `dependency` 的 `dependents` 列表
+
+如果任一节点不存在或依赖关系已存在，则不做任何操作。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `owner` | `ResourceGUID` | 依赖方（被依赖项的使用者）的全局唯一标识符 |
+| `dependency` | `ResourceGUID` | 被依赖项（owner 所依赖的资源）的全局唯一标识符 |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+graph.AddNode("material"_guid, ResourceType::Material);
+graph.AddNode("texture"_guid, ResourceType::Texture);
+graph.AddDependency("material"_guid, "texture"_guid);  // material 依赖 texture
+```

docs/api/resources/resource-dependency-graph/add-node.md

@@ -0,0 +1,32 @@
+# AddNode
+
+添加资源节点到依赖图中。
+
+## 方法签名
+
+```cpp
+void AddNode(ResourceGUID guid, ResourceType type);
+```
+
+## 详细描述
+
+将指定资源添加为依赖图中的新节点。如果节点已存在，则不做任何操作。该方法会创建一个带有空依赖关系和被依赖关系列表的新节点，初始引用计数为 0。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 要添加的资源的全局唯一标识符 |
+| `type` | `ResourceType` | 资源类型 |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+ResourceDependencyGraph graph;
+graph.AddNode("texture_albedo"_guid, ResourceType::Texture);
+graph.AddNode("material_standard"_guid, ResourceType::Material);
+```

docs/api/resources/resource-dependency-graph/clear.md

@@ -0,0 +1,30 @@
+# Clear
+
+清空整个依赖图。
+
+## 方法签名
+
+```cpp
+void Clear();
+```
+
+## 详细描述
+
+移除所有节点并清空内部数据结构。调用此方法后，依赖图将处于空状态，所有之前添加的节点和依赖关系都将被销毁。
+
+## 参数
+
+无
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+graph.AddNode("A"_guid, ResourceType::Texture);
+graph.AddNode("B"_guid, ResourceType::Material);
+graph.Clear();
+// 现在依赖图为空
+```

docs/api/resources/resource-dependency-graph/decrement-ref-count.md

@@ -0,0 +1,32 @@
+# DecrementRefCount
+
+减少资源的引用计数。
+
+## 方法签名
+
+```cpp
+void DecrementRefCount(ResourceGUID guid);
+```
+
+## 详细描述
+
+原子地减少指定资源的引用计数。引用计数不会减少到 0 以下。如果节点不存在或引用计数已为 0，则不做任何操作。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 目标资源的全局唯一标识符 |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+graph.IncrementRefCount("texture"_guid);
+graph.IncrementRefCount("texture"_guid);
+graph.DecrementRefCount("texture"_guid);  // refCount 现在为 1
+graph.DecrementRefCount("texture"_guid);  // refCount 现在为 0
+```

docs/api/resources/resource-dependency-graph/get-all-dependencies.md

@@ -0,0 +1,41 @@
+# GetAllDependencies
+
+获取资源的完整依赖链（递归）。
+
+## 方法签名
+
+```cpp
+Containers::Array<ResourceGUID> GetAllDependencies(ResourceGUID guid) const;
+```
+
+## 详细描述
+
+使用深度优先搜索递归获取指定资源的所有传递依赖项，返回完整的依赖链。返回结果不包括 `guid` 自身，且每个资源 GUID 只出现一次（即使有多个路径依赖该资源）。
+
+搜索算法使用栈实现 DFS，遍历所有依赖项及其子依赖项。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 要查询的资源的全局唯一标识符 |
+
+## 返回值
+
+`Containers::Array<ResourceGUID>` - 完整依赖链的 GUID 数组
+
+## 示例
+
+```cpp
+// 假设依赖关系: A -> B -> C -> D
+graph.AddNode("A"_guid, ResourceType::Material);
+graph.AddNode("B"_guid, ResourceType::Texture);
+graph.AddNode("C"_guid, ResourceType::Image);
+graph.AddNode("D"_guid, ResourceType::File);
+graph.AddDependency("A"_guid, "B"_guid);
+graph.AddDependency("B"_guid, "C"_guid);
+graph.AddDependency("C"_guid, "D"_guid);
+
+auto allDeps = graph.GetAllDependencies("A"_guid);
+// allDeps 包含 ["B", "C", "D"]（顺序可能因实现而异）
+```

docs/api/resources/resource-dependency-graph/get-dependencies.md

@@ -0,0 +1,38 @@
+# GetDependencies
+
+获取资源的直接依赖项列表。
+
+## 方法签名
+
+```cpp
+Containers::Array<ResourceGUID> GetDependencies(ResourceGUID guid) const;
+```
+
+## 详细描述
+
+返回指定资源直接依赖的所有资源 GUID 数组。这些是 `guid` 节点在 `dependencies` 数组中存储的资源，仅包含一层依赖关系，不包括传递依赖。
+
+如果指定节点不存在，返回空数组。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 要查询的资源的全局唯一标识符 |
+
+## 返回值
+
+`Containers::Array<ResourceGUID>` - 直接依赖项的 GUID 数组
+
+## 示例
+
+```cpp
+graph.AddNode("material"_guid, ResourceType::Material);
+graph.AddNode("texture1"_guid, ResourceType::Texture);
+graph.AddNode("texture2"_guid, ResourceType::Texture);
+graph.AddDependency("material"_guid, "texture1"_guid);
+graph.AddDependency("material"_guid, "texture2"_guid);
+
+auto deps = graph.GetDependencies("material"_guid);
+// deps 包含 ["texture1", "texture2"]
+```

docs/api/resources/resource-dependency-graph/get-dependents.md

@@ -0,0 +1,38 @@
+# GetDependents
+
+获取资源的直接被依赖项列表。
+
+## 方法签名
+
+```cpp
+Containers::Array<ResourceGUID> GetDependents(ResourceGUID guid) const;
+```
+
+## 详细描述
+
+返回直接依赖指定资源的所有资源 GUID 数组。这些是 `guid` 节点在 `dependents` 数组中存储的资源，仅包含一层被依赖关系，不包括传递被依赖项。
+
+如果指定节点不存在，返回空数组。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 要查询的资源的全局唯一标识符 |
+
+## 返回值
+
+`Containers::Array<ResourceGUID>` - 直接被依赖项的 GUID 数组
+
+## 示例
+
+```cpp
+graph.AddNode("texture"_guid, ResourceType::Texture);
+graph.AddNode("material1"_guid, ResourceType::Material);
+graph.AddNode("material2"_guid, ResourceType::Material);
+graph.AddDependency("material1"_guid, "texture"_guid);
+graph.AddDependency("material2"_guid, "texture"_guid);
+
+auto deps = graph.GetDependents("texture"_guid);
+// deps 包含 ["material1", "material2"]
+```

docs/api/resources/resource-dependency-graph/get-ref-count.md

@@ -0,0 +1,31 @@
+# GetRefCount
+
+获取资源的引用计数。
+
+## 方法签名
+
+```cpp
+Core::uint32 GetRefCount(ResourceGUID guid) const;
+```
+
+## 详细描述
+
+返回指定资源的当前引用计数。如果节点不存在，返回 0。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 目标资源的全局唯一标识符 |
+
+## 返回值
+
+`Core::uint32` - 当前引用计数，如果节点不存在则返回 0
+
+## 示例
+
+```cpp
+graph.IncrementRefCount("texture"_guid);
+graph.IncrementRefCount("texture"_guid);
+uint32 count = graph.GetRefCount("texture"_guid);  // 返回 2
+```

docs/api/resources/resource-dependency-graph/has-circular-dependency.md

@@ -0,0 +1,36 @@
+# HasCircularDependency
+
+检测资源是否存在循环依赖。
+
+## 方法签名
+
+```cpp
+bool HasCircularDependency(ResourceGUID guid, Containers::Array<ResourceGUID>& outCycle) const;
+```
+
+## 详细描述
+
+检测从指定资源出发是否存在循环依赖关系。算法使用深度优先搜索遍历依赖图，如果发现在同一条路径上访问同一个节点两次，则说明存在循环依赖。
+
+当检测到循环时，`outCycle` 参数将被填充为从起点到循环点的路径（包含循环点）。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 起始资源的全局唯一标识符 |
+| `outCycle` | `Containers::Array<ResourceGUID>&` | 输出参数，接收检测到的循环路径 |
+
+## 返回值
+
+`bool` - 如果存在循环依赖返回 `true`，否则返回 `false`
+
+## 示例
+
+```cpp
+// 假设存在循环: A -> B -> C -> A
+Containers::Array<ResourceGUID> cycle;
+if (graph.HasCircularDependency("A"_guid, cycle)) {
+    // cycle 包含类似 ["A", "B", "C", "A"] 的路径
+}
+```

docs/api/resources/resource-dependency-graph/has-node.md

@@ -0,0 +1,31 @@
+# HasNode
+
+检查节点是否存在。
+
+## 方法签名
+
+```cpp
+bool HasNode(ResourceGUID guid) const;
+```
+
+## 详细描述
+
+检查指定资源节点是否存在于依赖图中。这是在添加依赖关系前验证节点是否存在的常用方法。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 要检查的资源的全局唯一标识符 |
+
+## 返回值
+
+`bool` - 如果节点存在返回 `true`，否则返回 `false`
+
+## 示例
+
+```cpp
+graph.AddNode("texture"_guid, ResourceType::Texture);
+bool exists = graph.HasNode("texture"_guid);  // 返回 true
+bool notExists = graph.HasNode("unknown"_guid);  // 返回 false
+```

docs/api/resources/resource-dependency-graph/increment-ref-count.md

@@ -0,0 +1,32 @@
+# IncrementRefCount
+
+增加资源的引用计数。
+
+## 方法签名
+
+```cpp
+void IncrementRefCount(ResourceGUID guid);
+```
+
+## 详细描述
+
+原子地增加指定资源的引用计数。引用计数用于追踪资源被多少其他资源或系统引用。当引用计数大于 0 时，资源不能被卸载。
+
+如果节点不存在，则不做任何操作。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 目标资源的全局唯一标识符 |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+graph.IncrementRefCount("texture"_guid);
+graph.IncrementRefCount("texture"_guid);  // refCount 现在为 2
+```

docs/api/resources/resource-dependency-graph/index.md

@@ -0,0 +1,94 @@
+# ResourceDependencyGraph
+
+## 命名空间
+
+`XCEngine::Resources`
+
+## 类型
+
+类 (`class`)
+
+## 描述
+
+资源依赖图管理器，用于跟踪和管理资源之间的依赖关系。该类维护一个双向依赖图，支持添加/移除节点和依赖关系、查询依赖链、循环依赖检测、引用计数管理以及拓扑排序。
+
+## 概述
+
+`ResourceDependencyGraph` 提供了一套完整的资源依赖关系管理机制。每个资源被表示为一个节点，节点之间通过有向边建立依赖关系。类内部维护两个方向的关系：
+- **依赖项** (dependencies): 当前资源直接依赖的资源
+- **被依赖项** (dependents): 直接依赖当前资源的资源
+
+该图结构支持：
+- 双向依赖查询
+- 递归获取完整依赖链
+- 循环依赖检测
+- 引用计数追踪
+- 拓扑排序以确定资源加载/卸载顺序
+
+## 公共方法表格
+
+| 方法 | 描述 |
+|------|------|
+| `AddNode(ResourceGUID guid, ResourceType type)` | 添加资源节点到依赖图 |
+| `RemoveNode(ResourceGUID guid)` | 从依赖图中移除资源节点 |
+| `AddDependency(ResourceGUID owner, ResourceGUID dependency)` | 添加依赖关系 |
+| `RemoveDependency(ResourceGUID owner, ResourceGUID dependency)` | 移除依赖关系 |
+| `GetDependencies(ResourceGUID guid)` | 获取资源的直接依赖项 |
+| `GetDependents(ResourceGUID guid)` | 获取资源的直接被依赖项 |
+| `GetAllDependencies(ResourceGUID guid)` | 获取资源的完整依赖链（递归） |
+| `IncrementRefCount(ResourceGUID guid)` | 增加资源引用计数 |
+| `DecrementRefCount(ResourceGUID guid)` | 减少资源引用计数 |
+| `GetRefCount(ResourceGUID guid)` | 获取资源引用计数 |
+| `HasCircularDependency(ResourceGUID guid, Containers::Array<ResourceGUID>& outCycle)` | 检测是否存在循环依赖 |
+| `TopologicalSort()` | 对所有资源节点进行拓扑排序 |
+| `Unload(ResourceGUID guid)` | 检查资源是否可以卸载 |
+| `Clear()` | 清空整个依赖图 |
+| `HasNode(ResourceGUID guid)` | 检查节点是否存在 |
+
+## 使用示例
+
+```cpp
+#include "Resources/ResourceDependencyGraph.h"
+
+using namespace XCEngine;
+using namespace Resources;
+
+void Example() {
+    ResourceDependencyGraph graph;
+    
+    // 添加资源节点
+    graph.AddNode("texture_albedo"_guid, ResourceType::Texture);
+    graph.AddNode("material_standard"_guid, ResourceType::Material);
+    graph.AddNode("mesh_cube"_guid, ResourceType::Mesh);
+    
+    // 建立依赖关系
+    graph.AddDependency("material_standard"_guid, "texture_albedo"_guid);
+    graph.AddDependency("mesh_cube"_guid, "material_standard"_guid);
+    
+    // 查询依赖
+    auto deps = graph.GetDependencies("material_standard"_guid);    // 返回 ["texture_albedo"]
+    auto allDeps = graph.GetAllDependencies("mesh_cube"_guid);      // 返回 ["material_standard", "texture_albedo"]
+    
+    // 引用计数管理
+    graph.IncrementRefCount("texture_albedo"_guid);
+    graph.IncrementRefCount("texture_albedo"_guid);
+    uint32 count = graph.GetRefCount("texture_albedo"_guid);  // 返回 2
+    
+    // 检测循环依赖
+    Containers::Array<ResourceGUID> cycle;
+    if (graph.HasCircularDependency("mesh_cube"_guid, cycle)) {
+        // 处理循环依赖
+    }
+    
+    // 检查是否可以卸载
+    if (graph.Unload("texture_albedo"_guid)) {
+        // 可以卸载
+    }
+}
+```
+
+## 相关文档
+
+- [ResourceTypes](./resource-types.md)
+- [ResourceManager](../resource-manager/resource-manager.md)
+- [ResourcePool](./resource-pool.md)

docs/api/resources/resource-dependency-graph/remove-dependency.md

@@ -0,0 +1,34 @@
+# RemoveDependency
+
+移除资源之间的依赖关系。
+
+## 方法签名
+
+```cpp
+void RemoveDependency(ResourceGUID owner, ResourceGUID dependency);
+```
+
+## 详细描述
+
+移除两个节点之间的依赖关系。该方法会同时更新两个节点的关联数组：
+- 从 `owner` 的 `dependencies` 列表中移除 `dependency`
+- 从 `dependency` 的 `dependents` 列表中移除 `owner`
+
+如果任一节点不存在或依赖关系不存在，则不做任何操作。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `owner` | `ResourceGUID` | 依赖方的全局唯一标识符 |
+| `dependency` | `ResourceGUID` | 被依赖项的全局唯一标识符 |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+graph.RemoveDependency("material"_guid, "texture"_guid);
+```

docs/api/resources/resource-dependency-graph/remove-node.md

@@ -0,0 +1,33 @@
+# RemoveNode
+
+从依赖图中移除资源节点。
+
+## 方法签名
+
+```cpp
+void RemoveNode(ResourceGUID guid);
+```
+
+## 详细描述
+
+从依赖图中移除指定节点。此操作不会自动移除与其他节点之间的依赖关系，这些关系需要在调用此方法前手动清除。该方法直接从内部哈希表中删除节点。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 要移除的资源的全局唯一标识符 |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+graph.RemoveNode("texture_albedo"_guid);
+```
+
+## 注意
+
+移除节点前，建议先使用 `RemoveDependency` 清除该节点的所有依赖关系，以保持依赖图的一致性。

docs/api/resources/resource-dependency-graph/topological-sort.md

@@ -0,0 +1,28 @@
+# TopologicalSort
+
+对所有资源节点进行拓扑排序。
+
+## 方法签名
+
+```cpp
+Containers::Array<ResourceGUID> TopologicalSort() const;
+```
+
+## 详细描述
+
+返回所有资源节点的一种拓扑排序顺序，确保每个资源的所有依赖项都出现在该资源之前。该方法可用于确定资源的加载顺序。
+
+## 参数
+
+无
+
+## 返回值
+
+`Containers::Array<ResourceGUID>` - 按拓扑顺序排列的资源 GUID 数组
+
+## 示例
+
+```cpp
+auto sorted = graph.TopologicalSort();
+// 返回资源加载顺序
+```

docs/api/resources/resource-dependency-graph/unload.md

@@ -0,0 +1,39 @@
+# Unload
+
+检查资源是否可以卸载。
+
+## 方法签名
+
+```cpp
+bool Unload(ResourceGUID guid);
+```
+
+## 详细描述
+
+检查指定资源是否满足卸载条件。资源可以卸载当且仅当满足以下条件：
+1. 节点存在于依赖图中
+2. 资源的引用计数为 0
+3. 所有直接依赖该资源的资源的引用计数也都为 0
+
+该方法是一个检查函数，不会实际执行卸载操作。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 目标资源的全局唯一标识符 |
+
+## 返回值
+
+`bool` - 如果可以卸载返回 `true`，否则返回 `false`
+
+## 示例
+
+```cpp
+graph.IncrementRefCount("texture"_guid);
+if (graph.Unload("texture"_guid)) {
+    // 不能卸载，因为引用计数 > 0
+} else {
+    // 检查失败
+}
+```