《OGRE 3D 渲染引擎原理与架构》10.3 反序列化与加载流程

MeshSerializerImpl::importMesh 是加载流程的入口:判定端序、读文件头、进入 while 循环按 chunk id 分发。readMesh 内层循环处理 M_GEOMETRY/M_SUBMESH/M_MESH_BOUNDS 等块,把数据组装进 Mesh。版本兼容靠继承链 MeshSerializerImpl → v1_8 → v1_41 → v1_4 → v1_3 → v1_2 → v1_1,只 override 差异。lab 用 C++ 复现分发循环与 Mesh 组装。

10.3 反序列化与加载流程

10.1/10.2 讲了格式与工具层。这一节看读取的控制流:importMesh 怎么把 .mesh 文件一步步变成内存里的 Mesh,以及不同格式版本如何共用一套解析框架。

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

10.2 讲了版本注册与端序判定;本节讲 MeshSerializerImpl 的分发循环与 Mesh 组装。第 7 章的内存结构(SubMesh/VertexData)是这里的组装目标。

importMesh:外层主循环

MeshSerializerImpl::importMesh 是加载的入口,逻辑是「文件头 → 逐块分发」:

// OgreMain/src/OgreMeshSerializerImpl.cpp:MeshSerializerImpl::importMesh(v14.6.3 源码摘录,已删减)
    void MeshSerializerImpl::importMesh(const DataStreamPtr& stream, Mesh* pMesh, MeshSerializerListener *listener)
    {
        // Determine endianness (must be the first thing we do!)
        determineEndianness(stream);
        ...
        // Check header
        readFileHeader(stream);
        pushInnerChunk(stream);
        unsigned short streamID = readChunk(stream);

        while(!stream->eof())
        {
            switch (streamID)
            {
            case M_MESH:
                readMesh(stream, pMesh, listener);
                break;
            }
            streamID = readChunk(stream);
        }
        popInnerChunk(stream);
    }

流程:

  1. 先判端序——注释明说「must be the first thing we do!」,因为后续所有多字节字段的解读依赖它;
  2. 读文件头——验证 magic 与版本(10.1);
  3. 进入循环——readChunk 读一块的 id+size,按 id 分发;.mesh 最外层通常是 M_MESH 块,读它;循环到 eof 结束。

readMesh:内层分发循环

M_MESH 块内部还有子块:共享几何、子网格、骨架链接、包围盒、LOD 等。readMesh 逐个读取并分发:

// OgreMain/src/OgreMeshSerializerImpl.cpp:MeshSerializerImpl::readMesh(v14.6.3 源码摘录,已删减)
    void MeshSerializerImpl::readMesh(const DataStreamPtr& stream, Mesh* pMesh, MeshSerializerListener *listener)
    {
        // Never automatically build edge lists for this version
        pMesh->mAutoBuildEdgeLists = false;

        // bool skeletallyAnimated
        bool skeletallyAnimated;
        readBools(stream, &skeletallyAnimated, 1);

        // Find all substreams
        if (!stream->eof())
        {
            pushInnerChunk(stream);
            unsigned short streamID = readChunk(stream);
            while(!stream->eof() &&
                (streamID == M_GEOMETRY ||
                 streamID == M_SUBMESH ||
                 streamID == M_MESH_SKELETON_LINK ||
                 streamID == M_MESH_BONE_ASSIGNMENT ||
                 streamID == M_MESH_LOD_LEVEL ||
                 streamID == M_MESH_BOUNDS ||
                 streamID == M_SUBMESH_NAME_TABLE ||
                 streamID == M_EDGE_LISTS ||
                 streamID == M_POSES ||
                 streamID == M_ANIMATIONS ||
                 streamID == M_TABLE_EXTREMES))
            {
                switch(streamID)
                {
                case M_GEOMETRY:
                    pMesh->createVertexData();
                    readGeometry(stream, pMesh, pMesh->sharedVertexData);
                    break;
                case M_SUBMESH:
                    readSubMesh(stream, pMesh, listener);
                    break;
                case M_MESH_SKELETON_LINK:
                    readSkeletonLink(stream, pMesh, listener);
                    break;
                case M_MESH_BONE_ASSIGNMENT:
                    readMeshBoneAssignment(stream, pMesh);
                    break;
                case M_MESH_LOD_LEVEL:
                    readMeshLodLevel(stream, pMesh);
                    break;
                case M_MESH_BOUNDS:
                    readBoundsInfo(stream, pMesh);
                    break;
                case M_SUBMESH_NAME_TABLE:
                    readSubMeshNameTable(stream, pMesh);
                    break;
                ...
                }
                streamID = readChunk(stream);
            }
        }
    }

关键点:chunk id 白名单 + switch 分发。循环条件列出这一版本可能出现的所有子块 id;命中就调用对应 read* 子函数,读完整块 payload 后回到循环读下一块。子函数把数据写进 pMesh(createVertexData 建共享几何、readSubMesh 追加子网格、readBoundsInfo 填包围盒)——文件里的块与内存对象一一对应。

chunk id 常量在 OgreMeshFileFormat.h 集中定义:

// OgreMain/src/OgreMeshFileFormat.h:chunk id(v14.6.3 教学示意,参照上游同名实现,已删减)
    M_HEADER                = 0x1000,
    ...
    M_MESH                = 0x3000,
    // Optional M_GEOMETRY chunk
    M_SUBMESH             = 0x4000,
    ...
    M_SUBMESH_OPERATION = 0x4010, // optional, trilist assumed if missing
    M_SUBMESH_BONE_ASSIGNMENT = 0x4100,
    ...
    M_GEOMETRY          = 0x5000, // NB this chunk is embedded within M_MESH and ...
    M_GEOMETRY_VERTEX_DECLARATION = 0x5100,
    M_GEOMETRY_VERTEX_ELEMENT = 0x5110, // Repeating section
    M_GEOMETRY_VERTEX_BUFFER = 0x5200, // Repeating section
    M_GEOMETRY_VERTEX_BUFFER_DATA = 0x5210,
    ...
    M_MESH_SKELETON_LINK = 0x6000,
    M_MESH_BONE_ASSIGNMENT = 0x7000,
    M_MESH_LOD_LEVEL = 0x8000,
    M_MESH_LOD_USAGE = 0x8100,
    ...
    M_MESH_BOUNDS = 0x9000,
    M_SUBMESH_NAME_TABLE = 0xA000,

版本兼容:继承链只 override 差异

10.2 的版本表把 MeshSerializerImpl 的多个子类按版本注册。这些子类是一条继承链,老版本只 override 与最新版不同的方法:

// OgreMain/src/OgreMeshSerializerImpl.h:实现类继承链(v14.6.3 教学示意,参照上游同名实现,已删减)
    /** Internal implementation of Mesh reading / writing for the latest version of the
    .mesh format.
    ...
    This mesh format was used from Ogre v1.10. */
    class _OgrePrivate MeshSerializerImpl : public Serializer { ... };

    /** Class for providing backwards-compatibility for loading version 1.8 of the .mesh format. */
    class _OgrePrivate MeshSerializerImpl_v1_8 : public MeshSerializerImpl { ... };

    /** Class for providing backwards-compatibility for loading version 1.41 of the .mesh format. */
    class _OgrePrivate MeshSerializerImpl_v1_41 : public MeshSerializerImpl_v1_8 { ... };

    /** Class for providing backwards-compatibility for loading version 1.4 of the .mesh format. */
    class _OgrePrivate MeshSerializerImpl_v1_4 : public MeshSerializerImpl_v1_41 { ... };

    /** Class for providing backwards-compatibility for loading version 1.3 of the .mesh format. */
    class _OgrePrivate MeshSerializerImpl_v1_3 : public MeshSerializerImpl_v1_4 { ... };
    ...

机制:每个历史版本只 override 与最新格式不同的读写方法(如 v1_2 的 readGeometry 直接读 positions/normals,v1_8 的 LOD 处理),相同部分继承父类。这一设计让「最新实现」是唯一的完整实现,老版本只是差量补丁——版本兼容的维护成本与版本差异成正比,而不是与版本数量成正比。

从磁盘流到可提交的 Mesh

Mesh::prepareImpl 打开资源并将文件缓冲到宿主内存。进入 loadImpl 后,Mesh 将准备好的流移交给局部变量,按扩展名取 Codec,再把流和目标 Mesh 交给 Codec。对 .mesh,MeshSerializer::importMesh 判定端序,检查文件标记,读取版本后将流定位回起点。版本专用实现随后填充子网格、索引和共享顶点数据。把流保存在局部变量可使异常退出也能释放这份临时输入。 Mesh 准备与加载 · 序列化分派

flowchart TD
  A["Mesh::prepareImpl 打开并缓冲资源"] --> B["Mesh::loadImpl 取出内存流"]
  B --> C["按扩展名选择 Codec"]
  C --> D["MeshSerializer 判定端序并读取头"]
  D --> E{"文件标记和版本有效?"}
  E -->|"有效"| F["匹配版本实现并填充目标 Mesh"]
  E -->|"无效"| G["抛出异常,退出加载"]
  F --> H["SubMesh、顶点数据与索引可供实体使用"]
  C -->|"找不到 Codec"| G

原生样例把程序生成的平面导出到磁盘,删除生成阶段的 Mesh 登记,再用真实组与文件名创建另一份 Mesh。加载后断言一个 SubMesh、材质名称和六个索引。卸载前先销毁两个引用它的 Entity,随后重载同一资源对象。这个顺序使卸载测试和场景引用生命周期都能独立观察。文件缺失发生在 prepare,版本错误发生在 decode,两者应分别定位。 原生场景样例 。

版本分派与导入验收

导入结果的检验点至少包括网格能否从资源组打开、版本是否能匹配序列化器、索引和顶点数据能否形成合法绘制范围。日志中出现版本警告仍可能得到可用网格。

原生场景用当前写入版本分别导出小端和大端文件,两者解码为相同的 SubMesh 数和索引数。它还确认保留魔数但截断版本行的输入会失败。对旧版格式,应额外选择实际由对应版本生成的文件。

源码定位

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

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

下面复现 importMesh 的分发循环:构造简化 .mesh 文件再读回组装 Mesh。它与 src/10-3-mesh-loading.cpp 逐字节一致:

// file: src/10-3-mesh-loading.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/10-3-mesh-loading.cpp -o bin/10-3-mesh-loading && ./bin/10-3-mesh-loading
//
// 复现 MeshSerializerImpl 的反序列化流程:
//   文件头(magic+版本) → 匹配实现 → 读 M_MESH 块 → 循环 readChunk 分发
//   (M_GEOMETRY / M_SUBMESH / M_MESH_BOUNDS)→ 组装简化 Mesh。
//   chunk id 为 OgreMeshFileFormat.h 的真实值。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstring>
#include <string>
#include <vector>

namespace ogre_repro {

// OgreMeshFileFormat.h 真实 chunk id(部分)
constexpr uint16_t M_HEADER = 0x1000;
constexpr uint16_t M_MESH = 0x3000;
constexpr uint16_t M_SUBMESH = 0x4000;
constexpr uint16_t M_GEOMETRY = 0x5000;
constexpr uint16_t M_MESH_BOUNDS = 0x9000;

// 简化 Mesh 结构(对应 OgreMesh / OgreSubMesh 的关键字段)
struct SubMesh {
  std::string name;
  std::string materialName;
  uint32_t indexCount = 0;
  uint32_t vertexCount = 0;
};
struct Mesh {
  uint32_t sharedVertexCount = 0;
  std::vector<SubMesh> submeshes;
  bool boundsSet = false;
  float boundsMin[3] = {0, 0, 0};
  float boundsMax[3] = {0, 0, 0};
};

// 字节缓冲 + 游标(模拟 DataStream)
struct Stream {
  std::vector<uint8_t> buf;
  size_t pos = 0;
  void write(const void* p, size_t n) {
    const auto* b = static_cast<const uint8_t*>(p);
    buf.insert(buf.end(), b, b + n);
  }
  void read(void* p, size_t n) {
    std::memcpy(p, &buf[pos], n);
    pos += n;
  }
  size_t tell() const { return pos; }
  void seek(size_t p) { pos = p; }
  size_t size() const { return buf.size(); }
  bool eof() const { return pos >= buf.size(); }
};

// 文件构造侧:小端写入
struct ByteWriter {
  Stream s;
  void u16(uint16_t v) {
    uint8_t b[2] = {static_cast<uint8_t>(v & 0xFF), static_cast<uint8_t>((v >> 8) & 0xFF)};
    s.write(b, 2);
  }
  void u32(uint32_t v) {
    uint8_t b[4] = {static_cast<uint8_t>(v & 0xFF), static_cast<uint8_t>((v >> 8) & 0xFF),
                    static_cast<uint8_t>((v >> 16) & 0xFF), static_cast<uint8_t>((v >> 24) & 0xFF)};
    s.write(b, 4);
  }
  void str(const std::string& str) {
    s.write(str.data(), str.size());
    uint8_t nl = '\n';
    s.write(&nl, 1);
  }
  void f32(float f) {
    uint32_t bits = 0;
    std::memcpy(&bits, &f, 4);
    u32(bits);
  }
  void chunkHeader(uint16_t id, uint32_t size) {
    u16(id);
    u32(size);
  }
  void header(const std::string& version) {
    u16(M_HEADER);
    str(version);
  }
};

// 读侧:chunk 分发与 Mesh 组装
class MeshSerializerImpl {
 public:
  uint16_t readChunkHeader(Stream& s, uint32_t& outSize) {
    uint16_t id = 0;
    s.read(&id, 2);
    uint32_t sz = 0;
    s.read(&sz, 4);
    outSize = sz;
    return id;
  }
  uint32_t readU32(Stream& s) {
    uint32_t v = 0;
    s.read(&v, 4);
    return v;
  }
  float readF32(Stream& s) {
    float f = 0;
    s.read(&f, 4);
    return f;
  }
  // \n 终止字符串(对应 Serializer::readString)
  std::string readString(Stream& s) {
    std::string out;
    while (!s.eof()) {
      uint8_t c = 0;
      s.read(&c, 1);
      if (c == '\n') break;
      out.push_back(static_cast<char>(c));
    }
    return out;
  }
  void skip(Stream& s, size_t n) { s.seek(s.tell() + n); }

  // 对应 MeshSerializerImpl::readMesh 的分发循环
  void readMeshChunks(Stream& s, Mesh& mesh) {
    uint32_t chunkSize = 0;
    uint16_t id = readChunkHeader(s, chunkSize);
    while (!s.eof() && (id == M_GEOMETRY || id == M_SUBMESH || id == M_MESH_BOUNDS)) {
      switch (id) {
        case M_GEOMETRY:
          mesh.sharedVertexCount = readU32(s);
          break;
        case M_SUBMESH: {
          SubMesh sub;
          sub.name = readString(s);
          sub.materialName = readString(s);
          sub.indexCount = readU32(s);
          sub.vertexCount = readU32(s);
          mesh.submeshes.push_back(sub);
          break;
        }
        case M_MESH_BOUNDS:
          for (int i = 0; i < 3; ++i) mesh.boundsMin[i] = readF32(s);
          for (int i = 0; i < 3; ++i) mesh.boundsMax[i] = readF32(s);
          mesh.boundsSet = true;
          break;
      }
      id = readChunkHeader(s, chunkSize);
    }
  }

  // 对应 MeshSerializerImpl::importMesh:文件头 → M_MESH → 分发
  void importMesh(Stream& s, Mesh& mesh, const std::string& expectedVersion) {
    uint16_t magic = 0;
    s.read(&magic, 2);
    if (magic != M_HEADER) return;  // 非法文件
    std::string ver = readString(s);
    if (ver != expectedVersion) return;  // 版本不匹配

    uint32_t meshSize = 0;
    uint16_t id = readChunkHeader(s, meshSize);
    if (id != M_MESH) return;

    // M_MESH 内:skeletallyAnimated 标志 + 各子块
    uint8_t skeletallyAnimated = 0;
    s.read(&skeletallyAnimated, 1);
    readMeshChunks(s, mesh);
  }
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // ---- 构造一个简化 .mesh 文件 ----
  ByteWriter w;
  std::string version = "[MeshSerializer_v1.100]";
  w.header(version);  // magic(2) + 版本串+'\n'

  // M_MESH 内嵌:skeletallyAnimated + geometry + submesh + bounds
  std::string subName = "Body";
  std::string matName = "Red";
  uint32_t geometryChunkSize = 4;                              // uint32 vertexCount
  uint32_t submeshChunkSize = static_cast<uint32_t>(
      subName.size() + 1 + matName.size() + 1 + 4 + 4);        // 两个字符串+两个 uint32
  uint32_t boundsChunkSize = 24;                               // 6 float
  uint32_t meshChunkSize = 1 + 6 + geometryChunkSize + 6 + submeshChunkSize + 6 + boundsChunkSize;

  w.chunkHeader(M_MESH, meshChunkSize);
  uint8_t skelAnim = 0;
  w.s.write(&skelAnim, 1);

  w.chunkHeader(M_GEOMETRY, geometryChunkSize);
  w.u32(64);  // sharedVertexCount

  w.chunkHeader(M_SUBMESH, submeshChunkSize);
  w.str(subName);
  w.str(matName);
  w.u32(96);  // indexCount
  w.u32(48);  // vertexCount

  w.chunkHeader(M_MESH_BOUNDS, boundsChunkSize);
  w.f32(-1.0f); w.f32(-2.0f); w.f32(-3.0f);
  w.f32(1.0f); w.f32(2.0f); w.f32(3.0f);

  // ---- 反序列化 ----
  MeshSerializerImpl impl;
  Mesh mesh;
  impl.importMesh(w.s, mesh, version);

  CHECK(mesh.sharedVertexCount == 64u);
  CHECK(mesh.submeshes.size() == 1);
  CHECK(mesh.submeshes[0].name == "Body");
  CHECK(mesh.submeshes[0].materialName == "Red");
  CHECK(mesh.submeshes[0].indexCount == 96u);
  CHECK(mesh.submeshes[0].vertexCount == 48u);
  CHECK(mesh.boundsSet);
  CHECK(mesh.boundsMin[0] == -1.0f && mesh.boundsMin[2] == -3.0f);
  CHECK(mesh.boundsMax[1] == 2.0f);

  // ---- 版本不匹配:不读取任何内容 ----
  Stream s2 = w.s;
  s2.seek(0);
  Mesh mesh2;
  impl.importMesh(s2, mesh2, "[MeshSerializer_v1.8]");
  CHECK(mesh2.submeshes.empty());
  CHECK(!mesh2.boundsSet);

  // ---- 非法文件(magic 不对)----
  Stream s3;
  uint16_t badMagic = 0x1234;
  s3.write(&badMagic, 2);
  Mesh mesh3;
  impl.importMesh(s3, mesh3, version);
  CHECK(mesh3.submeshes.empty());

  return lab::report("10-3 资源序列化:反序列化与加载流程");
}

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

小结

  • importMesh:先判端序,再读文件头,最后外层 while 按 chunk id 分发。
  • readMesh 内层循环处理 M_GEOMETRY/M_SUBMESH/M_MESH_BOUNDS 等子块,逐个写进 Mesh。
  • chunk id 集中在 OgreMeshFileFormat.h,注释标明块的作用与可选项。
  • 版本兼容用继承链:每个历史版本只 override 与最新版不同的方法,共用父类框架。

阅读导航:上一节:10.2 序列化器实现 · 下一节:11.1 Entity 与 SubEntity 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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