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 → 入缓存。两个值得注意的真实语义:
- 缓存键只有 filename:同一个 filename 再次 load,无论传什么 archiveType 都命中缓存返回同一个归档——缓存优先于类型校验。这保证了资源组反复 addResourceLocation 同一路径时不重复建归档。
- 工厂表按 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
源码定位
OgreMain/include/OgreArchive.h:Archive(mName/mType/mReadOnly、isCaseSensitive/load/unload/open)OgreMain/include/OgreArchiveManager.h:ArchiveManager::load声明与归档/工厂表OgreMain/src/OgreArchiveManager.cpp:load的缓存/工厂链条实现OgreMain/include/OgreResourceGroupManager.h:addResourceLocation
上游引用固定到 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 与资源组 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。