6.3 ResourceGroupManager 与资源组
单个资源由 ResourceManager 管,但资源通常按组批量管理:进关卡要一口气加载一整个世界的资源,退关卡要整组卸载。资源组(ResourceGroup)就是「按用途分桶」的机制,ResourceGroupManager 是它的总管。
本章与站内既有内容的分工
helio 卷二的资产目录管的是编辑器资产的组织;本系列 6.3 管引擎运行时的资源分组生命周期——组的状态机、批量加载卸载。两者概念相关但层次不同。
三个内置组
OgreResourceGroupManager.cpp 定义了三个常驻组:
// OgreMain/src/OgreResourceGroupManager.cpp:内置组名(v14.6.3 源码摘录,已删减)
const char* const RGN_DEFAULT = "General";
const char* const RGN_INTERNAL = "OgreInternal";
const char* const RGN_AUTODETECT = "OgreAutodetect";
General:默认组,addResourceLocation不带组名就进这里,构造时自动创建;OgreInternal:引擎内部资源(如内置材质脚本),不让应用脚本污染;OgreAutodetect:特殊组——资源自己不写死归属,加载时按名字自动探测它属于哪个组(6.1 的changeGroupOwnership就是干这个)。
组的生命周期:五态状态机
每个组的生命周期用 ResourceGroup::Status 枚举描述:
// OgreMain/include/OgreResourceGroupManager.h:ResourceGroup::Status(v14.6.3 源码摘录,已删减)
struct ResourceGroup
{
enum Status
{
UNINITIALSED = 0,
INITIALISING = 1,
INITIALISED = 2,
LOADING = 3,
LOADED = 4
};
/// General mutex for dealing with group content
OGRE_AUTO_MUTEX;
/// Group name
String name;
/// Group status
Status groupStatus;
/// List of possible locations to search
状态流转是线性的:UNINITIALSED → INITIALISING → INITIALISED → LOADING → LOADED。注意「初始化」和「加载」是两步:初始化只创建已声明资源(对象就位但数据没读),加载才真正读数据。这么拆是为了让「进场景前把对象都建好」和「按需读数据」分开控制。
initialiseResourceGroup:解析脚本 + 创建声明资源
初始化一个组会做两件事:解析组内的资源脚本(.material、.overlay 等),再创建所有 declareResource 声明过的资源:
// OgreMain/src/OgreResourceGroupManager.cpp:initialiseResourceGroup(v14.6.3 源码摘录,已删减)
void ResourceGroupManager::initialiseResourceGroup(const String& name)
{
LogManager::getSingleton().logMessage("Initialising resource group " + name);
ResourceGroup* grp = getResourceGroup(name, true);
OGRE_LOCK_MUTEX(grp->OGRE_AUTO_MUTEX_NAME); // lock group mutex;
if (grp->groupStatus == ResourceGroup::UNINITIALSED)
{
// in the process of initialising
grp->groupStatus = ResourceGroup::INITIALISING;
// Set current group
parseResourceGroupScripts(grp);
mCurrentGroup = grp;
LogManager::getSingleton().logMessage("Creating resources for group " + name);
createDeclaredResources(grp);
grp->groupStatus = ResourceGroup::INITIALISED;
LogManager::getSingleton().logMessage("All done");
// Reset current group
mCurrentGroup = 0;
}
}
parseResourceGroupScripts 把组归档里的 .material 等脚本喂给 ScriptCompilerManager(卷四讲脚本解析);createDeclaredResources 遍历声明表逐个创建。整段在组级互斥锁里,且状态机保证了「已经初始化过的组不会重复初始化」。
把东西放进组:addResourceLocation 与 declareResource
两个配套接口把资源挂进组。addResourceLocation 把归档位置记入组:
// OgreMain/include/OgreResourceGroupManager.h:addResourceLocation(v14.6.3 源码摘录,已删减)
void addResourceLocation(const String& name, const String& locType,
const String& resGroup = DEFAULT_RESOURCE_GROUP_NAME, bool recursive = false, bool readOnly = true);
declareResource 声明一个资源归属某个组,注明类型(预置类型含 Font、GpuProgram、Material、Mesh、Skeleton、Texture 等,插件可加):
// OgreMain/include/OgreResourceGroupManager.h:declareResource(v14.6.3 教学示意,参照上游同名实现,已删减)
void declareResource(const String& name, const String& resourceType,
const String& groupName, ...);
loadResourceGroup:逐个加载,幂等
真正加载整组时,loadResourceGroup 遍历 loadResourceOrderMap 里的每个资源调 res->load()。关键注释值得引用——已加载的资源会被 load 跳过(6.1 的幂等性在这里派上用场):
// OgreMain/src/OgreResourceGroupManager.cpp:loadResourceGroup 片段(v14.6.3 源码摘录,已删减)
// If loading one of these resources cascade-loads another resource,
// the list will get longer! But these should be loaded immediately
// Call load regardless, already loaded resources will be skipped
res->load();
res->load() 的幂等意味着:脚本里显式依赖的资源(级联加载进来的)不会重复读;进度事件 fireResourceLoadStarted/Ended 无论如何都发,保证进度条计数与预估一致。
资源组、文件与资源对象
flowchart LR
A["ArchiveFactory"] -->|"创建"| B["Archive"]
C["ResourceGroupManager"] -->|"按组登记位置"| B
C -->|"初始化组时枚举脚本"| D["ScriptLoader"]
C -->|"按资源类型分派声明"| E["ResourceManager"]
D -->|"解析并创建"| E
E -->|"按名称和组登记"| F["Resource"]
F -.->|"需要内容时请求文件流"| C
B -->|"提供"| G["DataStream"]
G -->|"读取或反序列化"| F
一个资源组怎样找到实际文件
原生样例把 plane.material 放进文件系统位置,然后初始化 BookDepth。这个动作解析脚本,并把材质定义登记到 MaterialManager。此时材质对象已经能按名称和组查到,isLoaded() 仍为 false。文件索引、资源对象登记和加载状态是三份独立的数据。文件名能解析到位置,也可能要等第一次请求时才创建相应资源对象。
addResourceLocation 枚举归档并建立名字索引。样例先解析材质,再导出引用该材质的网格,导出后重新登记文件位置,保证新文件参与查找。普通项目可以先准备资产,再一次登记。诊断时依次检查组、归档位置、文件索引、资源登记和加载状态,这能定位“材质名存在但纹理尚未加载”和“网格文件不在组中”两类问题。 资源组源码
· 文件查找
sequenceDiagram
participant H as 宿主
participant G as ResourceGroupManager
participant A as FileSystem Archive
participant M as MaterialManager
participant R as Mesh
H->>G: addResourceLocation
G->>A: 打开位置并枚举文件,建立索引
H->>G: initialiseResourceGroup
G->>M: 解析脚本并登记材质定义
Note over G,M: 材质定义可查,加载状态仍独立
H->>R: 请求加载网格
R->>G: openResource 按名称与组查找
alt 找到文件
G->>A: 打开数据流
A-->>R: 返回流,准备网格数据
else 最终未找到
G-->>R: 报告文件找不到
end
源码定位
OgreMain/include/OgreResourceGroupManager.h:ResourceGroup::Status五态、addResourceLocation/declareResource/initialiseResourceGroup/loadResourceGroupOgreMain/src/OgreResourceGroupManager.cpp:内置组名(RGN_DEFAULT等)、initialiseResourceGroup/loadResourceGroup实现
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现默认组、位置挂组、声明资源、组状态机与批量加载幂等。它与 src/06-3-resource-group.cpp 逐字节一致:
// file: src/06-3-resource-group.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/06-3-resource-group.cpp -o bin/06-3-resource-group && ./bin/06-3-resource-group
//
// 复现 OgreResourceGroupManager 的资源组生命周期:
// 默认 "General" 组;createResourceGroup/addResourceLocation/declareResource;
// initialiseResourceGroup 的 UNINITIALSED→INITIALISED 状态机;load 逐个且幂等。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <map>
#include <string>
#include <vector>
namespace ogre_repro {
const std::string RGN_DEFAULT = "General";
// 对应 ResourceGroupManager::ResourceGroup(内嵌结构)
struct ResourceGroup {
enum Status { UNINITIALSED = 0, INITIALISING = 1, INITIALISED = 2,
LOADING = 3, LOADED = 4 };
std::string name;
Status groupStatus = UNINITIALSED;
std::vector<std::string> locations;
std::vector<std::string> declared; // 已声明资源名
std::vector<int> created; // initialise 时创建的资源
std::vector<int> loaded; // load 时加载的资源
};
// 对应 ResourceGroupManager:组表 + 生命周期方法
class ResourceGroupManager {
public:
std::map<std::string, ResourceGroup*> mResourceGroupMap;
ResourceGroupManager() {
createResourceGroup(RGN_DEFAULT); // "General" 组默认存在(OGRE 真实行为)
}
ResourceGroup* createResourceGroup(const std::string& name) {
auto it = mResourceGroupMap.find(name);
if (it != mResourceGroupMap.end()) return it->second; // 已存在复用
ResourceGroup* g = new ResourceGroup;
g->name = name;
mResourceGroupMap[name] = g;
return g;
}
ResourceGroup* getResourceGroup(const std::string& name) {
auto it = mResourceGroupMap.find(name);
return it == mResourceGroupMap.end() ? nullptr : it->second;
}
// 对应 addResourceLocation:把归档位置记入指定组
void addResourceLocation(const std::string& location,
const std::string& resGroup) {
ResourceGroup* g = getResourceGroup(resGroup);
if (!g) g = createResourceGroup(resGroup);
g->locations.push_back(location);
}
// 对应 declareResource:声明资源归属该组
void declareResource(const std::string& name, const std::string& resGroup) {
ResourceGroup* g = getResourceGroup(resGroup);
if (!g) g = createResourceGroup(resGroup);
g->declared.push_back(name);
}
// 对应 initialiseResourceGroup:UNINITIALSED → INITIALISED,创建已声明资源
void initialiseResourceGroup(const std::string& name) {
ResourceGroup* g = getResourceGroup(name);
if (!g) return;
if (g->groupStatus == ResourceGroup::UNINITIALSED) {
g->groupStatus = ResourceGroup::INITIALISING;
for (size_t i = 0; i < g->declared.size(); ++i) g->created.push_back(1);
g->groupStatus = ResourceGroup::INITIALISED;
}
}
// 对应 loadResourceGroup:逐个 load,幂等(已加载跳过)
void loadResourceGroup(const std::string& name) {
ResourceGroup* g = getResourceGroup(name);
if (!g) return;
g->groupStatus = ResourceGroup::LOADING;
for (size_t i = 0; i < g->created.size(); ++i) {
bool alreadyLoaded = static_cast<size_t>(i) < g->loaded.size();
if (!alreadyLoaded) g->loaded.push_back(1); // res->load()(幂等)
}
g->groupStatus = ResourceGroup::LOADED;
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
ResourceGroupManager mgr;
// 默认 "General" 组已存在(对应 RGN_DEFAULT)
CHECK(mgr.getResourceGroup("General") != nullptr);
CHECK(mgr.getResourceGroup("General")->groupStatus ==
ResourceGroup::UNINITIALSED);
// addResourceLocation:位置记入指定组
mgr.addResourceLocation("media/models", "General");
mgr.addResourceLocation("media/materials", "General");
CHECK_EQ(mgr.getResourceGroup("General")->locations.size(), 2u);
// 新组 + 声明资源
ResourceGroup* ui = mgr.createResourceGroup("UI");
CHECK(ui != nullptr);
mgr.addResourceLocation("media/ui", "UI");
mgr.declareResource("menu.font", "UI");
mgr.declareResource("statusbar.material", "UI");
CHECK_EQ(ui->declared.size(), 2u);
// initialise:UNINITIALSED → INITIALISED,创建声明资源
mgr.initialiseResourceGroup("UI");
CHECK(ui->groupStatus == ResourceGroup::INITIALISED);
CHECK_EQ(ui->created.size(), 2u);
// 幂等:重复 initialise 不重复创建
mgr.initialiseResourceGroup("UI");
CHECK_EQ(ui->created.size(), 2u);
// load:逐个加载
mgr.loadResourceGroup("UI");
CHECK(ui->groupStatus == ResourceGroup::LOADED);
CHECK_EQ(ui->loaded.size(), 2u);
// 幂等:重复 load 不重复加载
mgr.loadResourceGroup("UI");
CHECK_EQ(ui->loaded.size(), 2u);
// 未初始化组直接 load:无声明资源可加载
ResourceGroup* empty = mgr.createResourceGroup("Empty");
mgr.loadResourceGroup("Empty");
CHECK(empty->groupStatus == ResourceGroup::LOADED);
CHECK_EQ(empty->loaded.size(), 0u);
return lab::report("06-3 资源系统:ResourceGroup 与资源组");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过,断言 13/13 通过。
小结
- 三个内置组:
General(默认)、OgreInternal(引擎内部)、OgreAutodetect(自动探测归属)。 - 组生命周期五态:UNINITIALSED → INITIALISING → INITIALISED → LOADING → LOADED。
- initialise 解析脚本并创建声明资源;load 逐个
res->load()且幂等。 addResourceLocation把归档挂组,declareResource声明资源归属。- 级联加载进列表的资源靠 load 幂等跳过重复读。
阅读导航:上一节:6.2 Archive 与资源定位 · 下一节:7.1 Mesh 与 SubMesh 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。