100 lines
3.1 KiB
Markdown
100 lines
3.1 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` | 请求唯一标识符 |
|
||
|
||
## 公共方法
|
||
|
||
### 生命周期
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `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) - 资源加载器接口
|