《OGRE 3D 渲染引擎原理与架构》6.3 ResourceGroupManager 与资源组

资源组把资源按用途分桶:默认组 General、内部组 OgreInternal、自动探测组 OgreAutodetect。每组的生命周期是五态状态机,initialiseResourceGroup 解析脚本并创建声明资源,loadResourceGroup 逐个加载且幂等。addResourceLocation 把归档挂到组,declareResource 声明资源归属。lab 用 C++ 复现组状态机与批量加载幂等。

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

运行资产到首帧样例 。

源码定位

上游引用固定到 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 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图