ssdfasd
dc850d7739
- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 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 个断裂引用
117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# 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` | 请求唯一标识符 |
|
||
|
||
### 构造方法
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `LoadRequest()` | 默认构造 |
|
||
| `LoadRequest(const Containers::String& p, ResourceType t, std::function<void(LoadResult)> cb, ImportSettings* s = nullptr)` | 从参数构造 |
|
||
| `LoadRequest(LoadRequest&& other) noexcept` | 移动构造 |
|
||
| `LoadRequest(const LoadRequest&) = default` | 拷贝构造 |
|
||
|
||
### 赋值
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `LoadRequest& operator=(LoadRequest&& other) noexcept` | 移动赋值 |
|
||
| `LoadRequest& operator=(const LoadRequest&) = default` | 拷贝赋值 |
|
||
|
||
## 公共方法
|
||
|
||
### 生命周期
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `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](../resourcemanager/resourcemanager.md) - 资源管理器
|
||
- [IResourceLoader](../iloader/iloader.md) - 资源加载器接口
|
||
- [Resources 总览](../resources.md) - 返回模块总览
|