《OGRE 3D 渲染引擎原理与架构》10.2 序列化器实现

Serializer 的端序方法有两种:读侧由 magic 判定翻转,写侧按请求端序对比平台端序决定是否翻转。MeshSerializer 在构造时逆序注册各版本格式(最新在前),exportMesh 按 MeshVersion 选实现且禁止写 legacy,importMesh 按版本串匹配实现。lab 用 C++ 复现端序判定与版本注册分发。

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 时注册
    }

三个要点:

  1. 逆序注册:注释明说「MUST be added in reverse order so latest is first」——mVersionData[0] 恒为最新格式;
  2. 版本串不跟 OGRE 版本号严格对齐:注释说「String identifiers have not always been 100% unified」——MESH_VERSION_1_10 这个枚举其实对应 v1.100 版本串,因为 1.1 的旧 mesh 需要更高版本号区分;
  3. 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 外观类把多个内部实现按版本挡在后面:写按枚举选,读按字符串匹配。

源码定位

上游引用固定到 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 反序列化与加载流程 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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