10.2 序列化器实现
10.1 讲了 .mesh 的字节布局。这一节看 Serializer 基类怎么决定端序,以及 MeshSerializer 怎么注册和分发多个格式版本——这是 OGRE 能读十几年旧文件的关键。
本章与站内既有内容的分工
10.1 讲了 chunk 字节布局,这里补上「写侧端序判定」和「版本注册表」这层机制。format 版本兼容是资源系统的真实需求(旧版 DCC 导出的 mesh 仍要能读),本节讲 OGRE 的实现方式。
determineEndianness:写侧按请求端序判定
Serializer 有两个 determineEndianness 重载。读侧版本在 10.1 讲过(按 magic 判定);写侧版本按请求端序与平台端序的差异设置 mFlipEndian:
// OgreMain/src/OgreSerializer.cpp:Serializer::determineEndianness(Endian)(v14.6.3 源码摘录,已删减)
void Serializer::determineEndianness(Endian requestedEndian)
{
switch(requestedEndian)
{
case ENDIAN_NATIVE:
mFlipEndian = false;
break;
case ENDIAN_BIG:
#if OGRE_ENDIAN == OGRE_ENDIAN_BIG
mFlipEndian = false;
#else
mFlipEndian = true;
#endif
break;
case ENDIAN_LITTLE:
#if OGRE_ENDIAN == OGRE_ENDIAN_BIG
mFlipEndian = true;
#else
mFlipEndian = false;
#endif
break;
}
}
机制表(OGRE_ENDIAN 是编译期宏):
| 请求端序 | 平台大端 | 平台小端 |
|---|---|---|
| ENDIAN_NATIVE | 不翻转 | 不翻转 |
| ENDIAN_BIG | 不翻转 | 翻转 |
| ENDIAN_LITTLE | 翻转 | 不翻转 |
mFlipEndian 为真时,后续 writeShorts/writeInts/writeFloats 在写出前逐元素翻转字节(10.1 的 flipBytes)。所以写端序由调用者显式指定(exportMesh(..., Endian endianMode)),默认 ENDIAN_NATIVE。
版本注册表:逆序、最新在前
MeshSerializer 的构造函数把各格式版本注册进 mVersionData:
// OgreMain/src/OgreMeshSerializer.cpp:MeshSerializer 构造函数(v14.6.3 源码摘录,已删减)
MeshSerializer::MeshSerializer()
:mListener(0)
{
// Init implementations
// String identifiers have not always been 100% unified with OGRE version
// Note MUST be added in reverse order so latest is first in the list
// This one is a little ugly, 1.10 is used for version 1.1 legacy meshes.
// So bump up to 1.100
mVersionData.push_back(OGRE_NEW MeshVersionData(
MESH_VERSION_1_10, "[MeshSerializer_v1.100]",
OGRE_NEW MeshSerializerImpl()));
mVersionData.push_back(OGRE_NEW MeshVersionData(
MESH_VERSION_1_8, "[MeshSerializer_v1.8]",
OGRE_NEW MeshSerializerImpl_v1_8()));
if(!mSupportLegacyFormats)
return;
// ... 后续 v1.41 / v1.40 / v1.30 / v1.20 / v1.10 仅当支持 legacy 时注册
}
三个要点:
- 逆序注册:注释明说「MUST be added in reverse order so latest is first」——
mVersionData[0]恒为最新格式; - 版本串不跟 OGRE 版本号严格对齐:注释说「String identifiers have not always been 100% unified」——
MESH_VERSION_1_10这个枚举其实对应v1.100版本串,因为 1.1 的旧 mesh 需要更高版本号区分; - legacy 默认关闭:
mSupportLegacyFormats(enablePre1_8Formats控制)为假时只注册 v1.100 和 v1.8,MESH_VERSION_LEGACY以下的旧实现(含安全漏洞)不加载。
exportMesh / importMesh:分发到具体实现
exportMesh 按 MeshVersion 选实现;LEGACY 禁止写入:
// OgreMain/src/OgreMeshSerializer.cpp:MeshSerializer::exportMesh(v14.6.3 源码摘录,已删减)
if (version == MESH_VERSION_LEGACY)
OGRE_EXCEPT(Exception::ERR_INVALIDPARAMS,
"You may not supply a legacy version number (pre v1.0) for writing meshes.",
"MeshSerializer::exportMesh");
MeshSerializerImpl* impl = 0;
if (version == MESH_VERSION_LATEST)
impl = mVersionData[0]->impl.get();
else
{
for (auto & i : mVersionData)
{
if (version == i->version)
{
impl = i->impl.get();
break;
}
}
}
...
impl->exportMesh(pMesh, stream, endianMode);
importMesh 先读版本串,再按版本串匹配实现(而不是按枚举):
// OgreMain/src/OgreMeshSerializer.cpp:MeshSerializer::importMesh(v14.6.3 源码摘录,已删减)
String ver = readString(stream);
// Jump back to start
stream->seek(0);
// Find the implementation to use
MeshSerializerImpl* impl = 0;
for (auto & i : mVersionData)
{
if (i->versionString == ver)
{
impl = i->impl.get();
break;
}
}
选择实现后,MeshSerializerImpl 的 exportMesh/importMesh 才真正写/读各种 chunk(M_GEOMETRY、M_SUBMESH……)。这样一个 MeshSerializer 外观类把多个内部实现按版本挡在后面:写按枚举选,读按字符串匹配。
源码定位
OgreMain/src/OgreSerializer.cpp:determineEndianness(Endian requestedEndian)(ENDIAN_NATIVE/BIG/LITTLE分支)OgreMain/src/OgreMeshSerializer.cpp:MeshSerializer构造函数(逆序注册)、exportMesh(版本选择 + LEGACY 禁止)、importMesh(版本串匹配)OgreMain/include/OgreMeshSerializer.h:MeshVersion枚举、MeshSerializerListener
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现写侧端序判定与版本注册分发。它与 src/10-2-serializer-impl.cpp 逐字节一致:
// file: src/10-2-serializer-impl.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/10-2-serializer-impl.cpp -o bin/10-2-serializer-impl && ./bin/10-2-serializer-impl
//
// 复现 Serializer::determineEndianness(写侧) 与 MeshSerializer 版本注册/分发:
// 写端序由「请求端序 vs 平台端序」决定是否翻转;
// 版本表逆序注册、最新在前;exportMesh 按 MeshVersion 选实现,LEGACY 禁止写;
// importMesh 按版本串匹配实现,匹配不到抛错。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <string>
#include <vector>
namespace ogre_repro {
// 对应 Serializer::Endian
enum Endian { ENDIAN_NATIVE, ENDIAN_BIG, ENDIAN_LITTLE };
// 对应 Serializer::determineEndianness(Endian requested):
// 平台是小端(本机),请求 BIG 才需要翻转,LITTLE/NATIVE 不翻转
bool determineWriteEndian(Endian requested, bool platformLittle) {
if (requested == ENDIAN_NATIVE) return false;
if (platformLittle) return requested == ENDIAN_BIG;
return requested == ENDIAN_LITTLE;
}
// 对应 MeshVersion
enum MeshVersion {
MESH_VERSION_LATEST,
MESH_VERSION_1_10,
MESH_VERSION_1_8,
MESH_VERSION_LEGACY
};
// 对应 MeshSerializer.cpp 的版本表条目
struct MeshVersionData {
MeshVersion version;
std::string versionString;
std::string implName;
};
struct InvalidLegacyWrite {}; // LEGACY 只读不可写
struct VersionNotFound {};
// 对应 MeshSerializer:注册 + 导出/导入的实现选择
class MeshSerializer {
public:
std::vector<MeshVersionData> mVersionData;
MeshSerializer() {
// 逆序注册,最新在前(对应真实构造函数注释 "MUST be added in reverse order")
mVersionData.push_back({MESH_VERSION_1_10, "[MeshSerializer_v1.100]", "v1_100"});
mVersionData.push_back({MESH_VERSION_1_8, "[MeshSerializer_v1.8]", "v1_8"});
// legacy 格式默认关闭,不注册
}
// 对应 exportMesh:按版本选实现;LEGACY 禁止写入
std::string selectExportImpl(MeshVersion version) const {
if (version == MESH_VERSION_LEGACY)
throw InvalidLegacyWrite();
if (version == MESH_VERSION_LATEST)
return mVersionData[0].implName; // 最新 = 列表第一项
for (const auto& d : mVersionData)
if (d.version == version) return d.implName;
throw VersionNotFound();
}
// 对应 importMesh:读版本串后按版本串匹配实现
std::string selectImportImpl(const std::string& ver) const {
for (const auto& d : mVersionData)
if (d.versionString == ver) return d.implName;
throw VersionNotFound();
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// ---- 写端序判定(平台 = 小端)----
CHECK(!determineWriteEndian(ENDIAN_NATIVE, true));
CHECK(!determineWriteEndian(ENDIAN_LITTLE, true));
CHECK(determineWriteEndian(ENDIAN_BIG, true));
// 平台 = 大端时反之
CHECK(determineWriteEndian(ENDIAN_LITTLE, false));
CHECK(!determineWriteEndian(ENDIAN_BIG, false));
// ---- 版本注册表:逆序注册、最新在前 ----
MeshSerializer ser;
CHECK(ser.mVersionData.size() == 2);
CHECK(ser.mVersionData[0].versionString == "[MeshSerializer_v1.100]");
CHECK(ser.mVersionData[0].version == MESH_VERSION_1_10);
CHECK(ser.mVersionData[1].versionString == "[MeshSerializer_v1.8]");
// ---- exportMesh:版本选择 ----
CHECK(ser.selectExportImpl(MESH_VERSION_LATEST) == "v1_100");
CHECK(ser.selectExportImpl(MESH_VERSION_1_10) == "v1_100");
CHECK(ser.selectExportImpl(MESH_VERSION_1_8) == "v1_8");
// LEGACY 禁止写入
bool threw = false;
try {
ser.selectExportImpl(MESH_VERSION_LEGACY);
} catch (const InvalidLegacyWrite&) {
threw = true;
}
CHECK(threw);
// ---- importMesh:按版本串匹配 ----
CHECK(ser.selectImportImpl("[MeshSerializer_v1.100]") == "v1_100");
CHECK(ser.selectImportImpl("[MeshSerializer_v1.8]") == "v1_8");
// 未知版本串 → 抛错(对应旧文件无法读取)
threw = false;
try {
ser.selectImportImpl("[MeshSerializer_v0.9]");
} catch (const VersionNotFound&) {
threw = true;
}
CHECK(threw);
return lab::report("10-2 资源序列化:序列化器实现");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 16/16 通过。
小结
- 写侧
determineEndianness(Endian):按请求端序对比平台端序决定mFlipEndian(ENDIAN_NATIVE恒不翻转)。 - 版本表逆序注册、最新在前;
MESH_VERSION_LATEST恒选mVersionData[0]。 LEGACY禁止写入;legacy 格式默认不加载(enablePre1_8Formats控制)。- 写按枚举选实现,读按版本串匹配实现——一个外观类挡多个内部实现。
阅读导航:上一节:10.1 二进制 chunk 格式 · 下一节:10.3 反序列化与加载流程 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。