3.2 自定义存档
3.1 讲的是「资源怎么加载」,但资源的数据从哪来?OGRE 的答案是 Archive——一个对「文件容器」的抽象。它可能是磁盘文件夹,可能是 ZIP 压缩包,甚至可能是一个远程网络位置。第 3.2 节就看这个抽象层的接口长什么样、怎么把它接到引擎上。
本章与站内既有内容的分工
第 3.1 节讲 Resource/ResourceManager 两件套,面向资源内容的加载;本节往下沉一层,讲 Archive/ArchiveFactory/ArchiveManager 三件套,面向「文件从哪个容器取」。卷一讲到 ResourceGroupManager 时提过存档是它的下层依赖;这里把接口逐个展开,并和第 3.3 节的编解码器(文件字节流 → 图像数据)衔接——存档负责「拿到字节流」,编解码器负责「把字节流变成可用的资源」。
Archive:文件容器的抽象
Archive 的类文档第一句就点破本质——「archive is a generic term for a container of files」,容器可能是磁盘文件夹、压缩包、甚至远程位置。每次在容器里找到一个文件,OGRE 用一个 FileInfo 结构描述它:
// OgreMain/include/OgreArchive.h:FileInfo(v14.6.3 源码摘录,已删减)
struct FileInfo {
/// The archive in which the file has been found (for info when performing
/// multi-Archive searches, note you should still open through ResourceGroupManager)
const Archive* archive;
/// The file's fully qualified name
String filename;
/// Path name; separated by '/' and ending with '/'
String path;
/// Base filename
String basename;
/// Compressed size
size_t compressedSize;
/// Uncompressed size
size_t uncompressedSize;
};
FileInfo 携带六项信息:来源存档指针、全限定文件名、路径(以 / 结尾)、基文件名、压缩/解压大小。注意 filename 是「全限定名」,basename 只是最后一段——listFileInfo 的调用方经常需要区分这两者(比如按扩展名过滤时要看 basename)。
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:
/// 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.
@warning
Do not call this function directly, it is meant to be used
only by the ArchiveManager class.
*/
virtual void load() = 0;
/** Unloads the archive.
@warning
Do not call this function directly, it is meant to be used
only by the ArchiveManager class.
*/
virtual void unload() = 0;
/** Open a stream on a given file.
...
@param filename The fully qualified name of the file
@param readOnly Whether to open the file in read-only mode or not (note,
if the archive is read-only then this cannot be set to false)
@return A shared pointer to a DataStream which can be used to
read / write the file. If the file is not present, returns a null
shared pointer.
*/
virtual DataStreamPtr open(const String& filename, bool readOnly = true) const = 0;
virtual StringVectorPtr list(bool recursive = true, bool dirs = false) const = 0;
virtual FileInfoListPtr listFileInfo(bool recursive = true, bool dirs = false) const = 0;
virtual StringVectorPtr find(const String& pattern, bool recursive = true,
bool dirs = false) const = 0;
/** Find out if the named file exists (note: fully qualified filename required) */
virtual bool exists(const String& filename) const = 0;
/** Retrieve the modification time of a given file */
virtual time_t getModifiedTime(const String& filename) const = 0;
};
Archive 要回答的问题清单可以归纳成四组:
| 能力 | 方法 | 语义 |
|---|---|---|
| 打开 | open(filename) | 返回指向文件内容的 DataStream,可读可写;文件不存在返回空指针 |
| 枚举 | list / listFileInfo | 列出全部文件名 / 文件名+元数据,recursive 控制是否递归子路径 |
| 查询 | find(pattern) | 按通配模式查找,* 是通配符 |
| 判定 | exists / getModifiedTime / isCaseSensitive | 文件是否存在、修改时间、大小写敏感度 |
两个设计细节值得注意。第一,load()/unload() 的注释都带 @warning:不要直接调用,只由 ArchiveManager 调用——存档的生命周期归管理器管,应用层绕开它访问存档会破坏引用计数。第二,open 的返回是 DataStreamPtr,文件的读取语义全部封装在数据流里,调用方不关心底层是内存、磁盘还是网络。
ArchiveFactory:一对一的创建器
抽象接口不能直接 new——每个存档类型(FileSystem、Zip、Memory…)都需要一个具体子类。谁负责创建具体子类?ArchiveFactory:
// OgreMain/include/OgreArchiveFactory.h:ArchiveFactory(v14.6.3 源码摘录,已删减)
class _OgreExport ArchiveFactory : public FactoryObj< Archive >, public ArchiveAlloc
{
public:
virtual ~ArchiveFactory() {}
/** Creates a new object.
@param name Name of the object to create
@param readOnly whether the Archive is read only
@return
An object created by the factory. The type of the object depends on
the factory.
*/
virtual Archive* createInstance(const String& name, bool readOnly) OGRE_NODISCARD = 0;
Archive* createInstance(const String& name) override OGRE_NODISCARD { return createInstance(name, true); }
};
ArchiveFactory 继承 FactoryObj<Archive>,只有一个纯虚方法 createInstance。它既是「创建器」又是「类型标签」:一个工厂对应一种存档类型(用 getType() 标识),ArchiveManager 靠这个类型字符串找到正确的工厂。插件模式在这里最典型——Zip 插件注册一个 ZipArchiveFactory,FileSystem 插件注册一个 FileSystemArchiveFactory,各自只负责造自己的子类。
ArchiveManager:注册与分发
工厂要生效,必须先注册到 ArchiveManager:
// OgreMain/include/OgreArchiveManager.h:load / addArchiveFactory(v14.6.3 源码摘录,已删减)
Archive* load( const String& filename, const String& archiveType, bool readOnly);
/** Unloads an archive.
You must ensure that this archive is not being used before removing it.
*/
void unload(Archive* arch);
/** Unloads an archive by name.
You must ensure that this archive is not being used before removing it.
*/
void unload(const String& filename);
/** Get an iterator over the Archives in this Manager. */
ArchiveMapIterator getArchiveIterator(void);
/** Adds a new ArchiveFactory to the list of available factories.
Plugin developers who add new archive codecs need to call
this after defining their ArchiveFactory subclass and
Archive subclasses for their archive type.
*/
void addArchiveFactory(ArchiveFactory* factory);
addArchiveFactory 的注释直接对插件开发者说话:定义了新的 ArchiveFactory 子类和对应的 Archive 子类后,必须调用这个方法把它挂进工厂列表。load(filename, archiveType) 则做完整分发——按 archiveType 字符串找到工厂,调 createInstance 造出 Archive,登记进 mArchives map,之后对同一存档的查询都走这个 map。unload 则按指针或按名移除,注释提醒调用方保证存档没在被使用。
源码定位
OgreMain/include/OgreArchive.h:FileInfo(50-64)、Archive类(85-220)、open(144)、list(170)、listFileInfo(180)、find(194)、exists(198)、getModifiedTime(201)OgreMain/include/OgreArchiveFactory.h:ArchiveFactory(59-73)、createInstance(70-72)OgreMain/include/OgreArchiveManager.h:load(81)、unload(87/92)、addArchiveFactory(103)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现存档三件套:内存版 Archive(覆盖 exists/list/listFileInfo/find)、ArchiveFactory::createInstance、ArchiveManager::load/addArchiveFactory 的注册分发。它与 src/ogre-ext-03-2-custom-archive.cpp 逐字节一致:
// file: src/ogre-ext-03-2-custom-archive.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-03-2-custom-archive.cpp -o bin/ogre-ext-03-2-custom-archive && ./bin/ogre-ext-03-2-custom-archive
//
// 复现自定义存档机制(对应 OgreMain/include/OgreArchive.h 50-64 的 FileInfo、
// 85-220 的 Archive 纯虚接口,OgreArchiveFactory.h 59-73 的 ArchiveFactory::
// createInstance,OgreArchiveManager.h 81-103 的 load/addArchiveFactory):
// 内存版 Archive 提供只读文件清单与通配查询;Factory 按类型字符串创建实例;
// Manager 以 map 保存已加载存档并按类型分发。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <map>
#include <string>
#include <vector>
namespace ogre_repro {
// 对应 OgreArchive.h 50-64 的 FileInfo:简化版保留文件名/基名/大小
struct FileInfo {
std::string filename;
std::string basename;
std::size_t uncompressedSize;
};
// 对应 OgreArchive.h 85-:内存版 Archive,覆盖纯虚接口
class Archive {
public:
Archive(const std::string& name, const std::string& archType)
: mName(name), mType(archType), mReadOnly(true) {}
virtual ~Archive() {}
const std::string& getName() const { return mName; }
const std::string& getType() const { return mType; }
virtual bool exists(const std::string& filename) const = 0;
virtual std::vector<std::string> list(bool recursive = true) const = 0;
virtual std::vector<FileInfo> listFileInfo(bool recursive = true) const = 0;
virtual std::vector<std::string> find(const std::string& pattern) const = 0;
protected:
std::string mName;
std::string mType;
bool mReadOnly; // 只读存档:create/remove 会失败(此处不展开)
};
// 对应 FileSystem/Zip 插件:把文件清单存在 map 里
class MemoryArchive : public Archive {
public:
MemoryArchive(const std::string& name, const std::string& archType)
: Archive(name, archType) {}
void addFile(const std::string& filename, std::size_t size) {
mFiles.emplace(filename, size);
}
bool exists(const std::string& filename) const override {
return mFiles.count(filename) != 0;
}
std::vector<std::string> list(bool recursive = true) const override {
(void)recursive;
std::vector<std::string> out;
for (const auto& f : mFiles) out.push_back(f.first);
return out;
}
std::vector<FileInfo> listFileInfo(bool recursive = true) const override {
(void)recursive;
std::vector<FileInfo> out;
for (const auto& f : mFiles) {
FileInfo fi;
fi.filename = f.first;
fi.uncompressedSize = f.second;
std::size_t slash = f.first.rfind('/');
fi.basename = slash == std::string::npos ? f.first : f.first.substr(slash + 1);
out.push_back(fi);
}
return out;
}
// 简化通配:'*' 开头的 pattern 按后缀匹配,其余按子串匹配
std::vector<std::string> find(const std::string& pattern) const override {
std::vector<std::string> out;
for (const auto& f : mFiles) {
if (pattern.empty()) continue;
if (pattern[0] == '*') {
std::size_t suffixLen = pattern.size() - 1;
if (f.first.size() >= suffixLen &&
f.first.compare(f.first.size() - suffixLen, suffixLen, pattern, 1) == 0)
out.push_back(f.first);
} else if (f.first.find(pattern) != std::string::npos) {
out.push_back(f.first);
}
}
return out;
}
std::map<std::string, std::size_t> mFiles;
};
// 对应 OgreArchiveFactory.h 59-73:工厂接口与内存存档工厂
class ArchiveFactory {
public:
virtual ~ArchiveFactory() {}
virtual Archive* createInstance(const std::string& name) = 0;
};
class MemoryArchiveFactory : public ArchiveFactory {
public:
Archive* createInstance(const std::string& name) override {
return new MemoryArchive(name, "Memory");
}
};
// 对应 OgreArchiveManager.h:注册工厂、按类型加载、按名卸载
class ArchiveManager {
public:
void addArchiveFactory(ArchiveFactory* factory) {
mFactories.emplace("Memory", factory);
}
Archive* load(const std::string& filename, const std::string& archiveType) {
auto it = mFactories.find(archiveType);
if (it == mFactories.end()) return nullptr; // 找不到工厂
Archive* arch = it->second->createInstance(filename);
mArchives.emplace(filename, arch);
return arch;
}
void unload(const std::string& filename) { mArchives.erase(filename); }
Archive* get(const std::string& filename) {
auto it = mArchives.find(filename);
return it == mArchives.end() ? nullptr : it->second;
}
std::map<std::string, ArchiveFactory*> mFactories;
std::map<std::string, Archive*> mArchives;
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
MemoryArchiveFactory factory;
ArchiveManager mgr;
mgr.addArchiveFactory(&factory);
// 初始没有任何已加载存档
CHECK_EQ(mgr.mArchives.size(), size_t(0));
// load:经工厂创建实例并登记(对应 ArchiveManager::load)
Archive* arch = mgr.load("trees.bin", "Memory");
CHECK(arch != nullptr);
CHECK_EQ(arch->getType(), "Memory");
CHECK_EQ(mgr.mArchives.size(), size_t(1));
// 未知类型:找不到工厂,load 失败
Archive* bad = mgr.load("bad.bin", "Zip");
CHECK(bad == nullptr);
// 往内存存档填充三个文件
MemoryArchive* mem = static_cast<MemoryArchive*>(arch);
mem->addFile("forest/oak.mesh", 1024);
mem->addFile("forest/rock.mesh", 512);
mem->addFile("readme.txt", 64);
// exists 精确匹配
CHECK(mem->exists("forest/oak.mesh"));
CHECK(!mem->exists("forest/absent.mesh"));
// list 返回全部文件名
std::vector<std::string> names = mem->list();
CHECK_EQ(names.size(), size_t(3));
// find("*.mesh") 匹配两个 mesh 文件
std::vector<std::string> meshes = mem->find("*.mesh");
CHECK_EQ(meshes.size(), size_t(2));
// find("readme") 子串匹配
std::vector<std::string> docs = mem->find("readme");
CHECK_EQ(docs.size(), size_t(1));
CHECK(docs[0] == "readme.txt");
// listFileInfo 产出 basename 与大小(map 按文件名排序)
std::vector<FileInfo> infos = mem->listFileInfo();
CHECK_EQ(infos.size(), size_t(3));
CHECK_EQ(infos[0].uncompressedSize, size_t(1024));
CHECK(infos[0].basename == "oak.mesh");
// unload 后 get 返回 null
mgr.unload("trees.bin");
CHECK(mgr.get("trees.bin") == nullptr);
CHECK_EQ(mgr.mArchives.size(), size_t(0));
return lab::report("3.2 自定义存档");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 16/16 通过。
小结
Archive是文件容器的抽象:open/list/listFileInfo/find/exists/getModifiedTime六个纯虚方法定义能力。FileInfo携带来源、全限定名、路径、基名、压缩/解压大小六项元数据。load()/unload()只由ArchiveManager调用,应用层应走ResourceGroupManager的更高层入口。ArchiveFactory::createInstance是一对一的创建器,一个工厂对应一种存档类型。ArchiveManager负责addArchiveFactory注册与load(archiveType)按类型分发。
阅读导航:上一节:3.1 自定义资源类型 · 下一节:3.3 编解码器 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。