《OGRE 3D 渲染引擎原理与架构》6.2 Archive 与资源定位

Archive 是资源文件的统一抽象:文件系统、ZIP、网络都在同一接口后面。ArchiveManager::load 先按 filename 查缓存,未命中再按 archiveType 查工厂创建,类型不匹配的工厂抛 ERR_ITEM_NOT_FOUND。open 返回 DataStreamPtr,流的生命周期由流自己控制。lab 用 C++ 复现缓存命中、按类型创建与未注册工厂抛异常。

6.2 Archive 与资源定位

资源要加载,先得知道去哪找文件。OGRE 把「文件从哪来」抽象成 Archive——一个统一接口,背后可以是文件系统目录、ZIP 包、甚至网络位置。6.1 讲的是资源对象怎么活,这一节讲资源文件怎么定位。

本章与站内既有内容的分工

helio 卷二资产管线讲的是编辑器导入与依赖解析;本系列 6.2 聚焦引擎侧「归档」这一层的抽象与缓存。Archive 与 3.1 的插件系统强相关——文件系统/ ZIP 归档是插件注册的,后面再讲。

Archive:统一文件来源

OgreArchive.h 的 Archive 是纯抽象的文件来源。它持有名字与类型,把「这个归档存了哪些文件、怎么打开」留给子类:

// OgreMain/include/OgreArchive.h:Archive 类(v14.6.3 源码摘录,已删减)
    class _OgreExport Archive : public ArchiveAlloc
    {
    protected:
        /// Archive name
        String mName; 
        /// Archive type code
        String mType;
        /// Read-only flag
        bool mReadOnly;
    public:
        /// Get the name of this archive
        const String& getName(void) const { return mName; }
        /// Returns whether this archive is case sensitive in the way it matches files
        virtual bool isCaseSensitive(void) const = 0;
        /// Loads the archive. This initializes all the internal data of the class.
        virtual void load() = 0;
        /// Unloads the archive.
        virtual void unload() = 0;
        /** Open a stream on a given file. 
        @note
            There is no equivalent 'close' method; the returned stream
            controls the lifecycle of this file operation.
        @param filename The fully qualified name of the file
        */
        virtual DataStreamPtr open(const String& filename, bool readOnly = true) const = 0;
        ...
    };

关键接口就四个:isCaseSensitive(文件系统在 macOS/Windows 大小写不敏感,ZIP 敏感——这直接影响文件匹配语义)、load/unload(初始化归档内部索引,比如 ZIP 的目录表)、open(打开单个文件返回流)。open 返回 DataStreamPtr 而没有 close 方法——流的生命周期由返回的流自己控制,智能指针自动释放。子类实现各不同:FileSystemArchive 用目录遍历,ZipArchive 解压 ZIP 目录,网络归档则走 URL。

ArchiveManager:缓存 + 工厂

ArchiveManager(单例)管两件事:按 filename 缓存已打开的归档,按 archiveType 找工厂创建新归档。它的 load 是这条链:

// OgreMain/src/OgreArchiveManager.cpp:ArchiveManager::load(v14.6.3 源码摘录,已删减)
    Archive* ArchiveManager::load( const String& filename, const String& archiveType, bool readOnly)
    {
        ArchiveMap::iterator i = mArchives.find(filename);
        Archive* pArch = 0;

        if (i == mArchives.end())
        {
            // Search factories
            ArchiveFactoryMap::iterator it = mArchFactories.find(archiveType);
            if (it == mArchFactories.end())
            {
                // Factory not found
                OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND,
                            "Cannot find an ArchiveFactory for type '" + archiveType + "'");
            }

            pArch = it->second->createInstance(filename, readOnly);
            pArch->load();
            mArchives[filename] = pArch;
        }
        else
        {
            ...
        }
    }

顺序是:先查缓存(按 filename)→ 未命中查工厂表(按 archiveType)→ 没工厂抛 ERR_ITEM_NOT_FOUND → 有工厂就 createInstance → load → 入缓存。两个值得注意的真实语义:

  1. 缓存键只有 filename:同一个 filename 再次 load,无论传什么 archiveType 都命中缓存返回同一个归档——缓存优先于类型校验。这保证了资源组反复 addResourceLocation 同一路径时不重复建归档。
  2. 工厂表按 archiveType:"FileSystem"、"Zip" 等类型名由插件注册(Root::loadPlugin 时 ArchiveManager::addArchiveFactory)。类型名就是定位工厂的键。

资源定位的上层入口

ResourceGroupManager::addResourceLocation(location, archiveType) 最终调 ArchiveManager::load 拿到归档,记入该资源组的归档列表。此后加载该组资源时,按顺序逐个归档 find 文件名,命中即 open。所以一条资源文件的定位链是:

addResourceLocation("media/models", "FileSystem")
  → ArchiveManager::load("media/models", "FileSystem")   // 缓存/工厂
  → ResourceGroupManager 记录归档
加载 "tree.mesh" → 组内归档逐个 find → 命中 open → DataStream

源码定位

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现 Archive 抽象、按类型创建、缓存复用与未注册工厂抛异常。它与 src/06-2-archive-location.cpp 逐字节一致:

// file: src/06-2-archive-location.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/06-2-archive-location.cpp -o bin/06-2-archive-location && ./bin/06-2-archive-location
//
// 复现 OgreArchive 抽象与 OgreArchiveManager::load 的缓存/工厂链条:
//   先查缓存 → 未命中按 archiveType 查工厂 → createInstance → load → 入缓存。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <map>
#include <stdexcept>
#include <string>
#include <vector>

namespace ogre_repro {

// 对应 DataStreamPtr:模拟打开的文件内容
struct DataStream {
  std::string content;
};

// 对应 OgreArchive:名字/类型/只读 + 纯虚 open/exists
class Archive {
 public:
  std::string mName;
  std::string mType;
  bool mReadOnly;
  int loadCalls = 0;

  Archive(const std::string& name, const std::string& type, bool ro)
      : mName(name), mType(type), mReadOnly(ro) {}
  virtual ~Archive() = default;

  const std::string& getName() const { return mName; }
  bool isReadOnly() const { return mReadOnly; }

  virtual DataStream* open(const std::string& filename) const = 0;
  virtual bool exists(const std::string& filename) const = 0;
};

// 对应 FileSystemArchive:以内存 map 模拟目录里的文件
class FileSystemArchive : public Archive {
 public:
  std::map<std::string, std::string> files;

  FileSystemArchive(const std::string& name, bool ro)
      : Archive(name, "FileSystem", ro) {}
  DataStream* open(const std::string& filename) const override {
    auto it = files.find(filename);
    if (it == files.end()) return nullptr;
    return new DataStream{it->second};
  }
  bool exists(const std::string& filename) const override {
    return files.find(filename) != files.end();
  }
};

// 对应 ZipArchive:同样以 map 模拟,但按压缩包语义加载
class ZipArchive : public Archive {
 public:
  std::map<std::string, std::string> files;

  ZipArchive(const std::string& name, bool ro)
      : Archive(name, "Zip", ro) {}
  DataStream* open(const std::string& filename) const override {
    auto it = files.find(filename);
    if (it == files.end()) return nullptr;
    return new DataStream{it->second};
  }
  bool exists(const std::string& filename) const override {
    return files.find(filename) != files.end();
  }
};

// 对应 ArchiveFactory:getTypeName/createInstance
class ArchiveFactory {
 public:
  virtual ~ArchiveFactory() = default;
  virtual const std::string& getTypeName() const = 0;
  virtual Archive* createInstance(const std::string& name, bool readOnly) = 0;
};

class FileSystemArchiveFactory : public ArchiveFactory {
 public:
  const std::string& getTypeName() const override {
    static const std::string t = "FileSystem";
    return t;
  }
  Archive* createInstance(const std::string& name, bool ro) override {
    return new FileSystemArchive(name, ro);
  }
};

class ZipArchiveFactory : public ArchiveFactory {
 public:
  const std::string& getTypeName() const override {
    static const std::string t = "Zip";
    return t;
  }
  Archive* createInstance(const std::string& name, bool ro) override {
    return new ZipArchive(name, ro);
  }
};

// 对应 ArchiveManager:工厂表 + 按类型创建 + 缓存复用
class ArchiveManager {
 public:
  std::map<std::string, ArchiveFactory*> mArchFactories;
  std::map<std::string, Archive*> mArchives;

  ~ArchiveManager() {
    for (auto& kv : mArchives) delete kv.second;
  }

  void addFactory(ArchiveFactory* f) { mArchFactories[f->getTypeName()] = f; }

  // 对应 ArchiveManager::load:先查缓存,未命中再查工厂创建
  Archive* load(const std::string& filename, const std::string& archiveType,
                bool readOnly) {
    auto it = mArchives.find(filename);
    if (it != mArchives.end()) return it->second;  // 缓存命中

    auto fit = mArchFactories.find(archiveType);
    if (fit == mArchFactories.end())
      throw std::runtime_error("Cannot find an ArchiveFactory for type '" +
                               archiveType + "'");
    Archive* arch = fit->second->createInstance(filename, readOnly);
    arch->loadCalls++;
    mArchives[filename] = arch;
    return arch;
  }
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  FileSystemArchiveFactory fsFactory;
  ZipArchiveFactory zipFactory;

  ArchiveManager mgr;
  mgr.addFactory(&fsFactory);
  mgr.addFactory(&zipFactory);

  // 按类型创建:类型名落到正确工厂
  Archive* fs = mgr.load("data", "FileSystem", true);
  CHECK(fs->mType == "FileSystem");
  CHECK(fs->isReadOnly());
  CHECK(fs->mName == "data");

  // 缓存键仅 filename:同 filename 跨 type 复用已有归档(OGRE 真实语义)
  Archive* sameData = mgr.load("data", "Zip", true);
  CHECK(sameData == fs);
  CHECK(sameData->mType == "FileSystem");

  // 不同 filename 按类型创建:Zip 工厂独立创建
  Archive* zip = mgr.load("data.zip", "Zip", true);
  CHECK(zip != fs);
  CHECK(zip->mType == "Zip");
  CHECK(zip->mName == "data.zip");

  // 填充文件并 open
  static_cast<FileSystemArchive*>(fs)->files["tree.mesh"] = "MESH_DATA";
  DataStream* stream = fs->open("tree.mesh");
  CHECK(stream != nullptr);
  CHECK(stream->content == "MESH_DATA");
  CHECK(fs->exists("tree.mesh"));
  CHECK(!fs->exists("nope.mesh"));
  delete stream;

  // 缓存复用:同名再 load 不重建
  Archive* fs2 = mgr.load("data", "FileSystem", true);
  CHECK(fs2 == fs);
  CHECK_EQ(mgr.mArchives.size(), 2u);

  // 未注册类型抛异常(对应 ERR_ITEM_NOT_FOUND);用未缓存的新文件名
  bool threw = false;
  try {
    mgr.load("new_archive", "UnknownType", true);
  } catch (const std::runtime_error&) {
    threw = true;
  }
  CHECK(threw);

  return lab::report("06-2 资源系统:Archive 与定位");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过,断言 15/15 通过。

小结

  • Archive 抽象「文件来源」,isCaseSensitive/load/open 三个接口,子类各自实现。
  • ArchiveManager::load 先按 filename 查缓存,未命中再按 archiveType 查工厂。
  • 缓存键只有 filename:同 filename 跨 type 复用,缓存优先于类型校验。
  • 工厂表按 archiveType 定位,未注册类型抛 ERR_ITEM_NOT_FOUND。
  • open 返回 DataStreamPtr,无 close 方法,流的生命周期由流自管。

阅读导航:上一节:6.1 ResourceManager 与资源生命周期 · 下一节:6.3 ResourceGroupManager 与资源组 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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