《OGRE 3D 渲染引擎原理与架构》10.1 二进制 chunk 格式

OGRE 的 .mesh 文件是 chunked 二进制格式:文件头是 uint16 magic(0x1000/0x0010 区分端序)加 ' ' 终止的版本字符串;每个 chunk 是 uint16 id + uint32 size 的 6 字节头加 payload。Serializer 基类提供写入端序翻转与读取时的 magic 端序判定。lab 用 C++ 复现写读一套 chunked 文件并验证小端/大端往返一致。

10.1 二进制 chunk 格式

OGRE 的 .mesh、.skeleton 等资源文件是分块(chunked)二进制格式:文件不是一个扁平的字节流,而是「文件头 + 一串带长度的数据块」。每一块自带 id 与 size,读侧按块跳读。这一节拆开这个格式的字节布局。

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

7~9 章讲了 Mesh/Skeleton/Animation 的内存结构;这一章讲它们落盘的格式。helio 卷二的资产管线讲编辑器资产,本系列聚焦 OGRE 的 .mesh 二进制规范与 Serializer 工具链。

文件头:magic + 版本

OgreSerializer.h 的 Serializer 是所有二进制资源序列化器的基类,写文件头是两个动作:magic + 版本串。

// OgreMain/src/OgreSerializer.cpp:Serializer::writeFileHeader(v14.6.3 源码摘录,已删减)
    void Serializer::writeFileHeader(void)
    {
        uint16 val = HEADER_STREAM_ID;
        writeShorts(&val, 1);
        writeString(mVersion);
    }

magic 常量定义在同文件顶部,两个值恰好字节相反——这正是端序判定的机关:

// OgreMain/src/OgreSerializer.cpp:magic 常量(v14.6.3 源码摘录,已删减)
    const uint16 HEADER_STREAM_ID = 0x1000;
    const uint16 OTHER_ENDIAN_HEADER_STREAM_ID = 0x0010;

0x1000 在小端机器上是字节 [0x00, 0x10],大端写出来是 [0x10, 0x00]。读侧先以本机字节序读入 magic:读成 0x1000 说明文件端序与本机一致,读成 0x0010 说明相反,需要翻转后续所有多字节字段。

版本字符串用 writeString 写入,以 '\n' 终止:

// OgreMain/include/OgreSerializer.h:Serializer 接口(v14.6.3 源码摘录,已删减)
        void writeFileHeader(void);
        void writeChunkHeader(uint16 id, size_t size);
        static size_t calcChunkHeaderSize() { return sizeof(uint16) + sizeof(uint32); }
        /// string + terminating \n character
        static size_t calcStringSize(const String& string) { return string.length() + 1; }
        ...
        void writeString(const String& string);
        void writeData(const void* const buf, size_t size, size_t count);

.mesh 的版本串是形如 [MeshSerializer_v1.100] 的标识,.skeleton 则是 [Serializer_v1.80]——加载时先读版本,再选对应版本的反序列化实现(10.3 展开)。

chunk:id + size + payload

文件头之后是数据块序列。writeChunkHeader 写 6 字节:uint16 id + uint32 size:

// OgreMain/src/OgreSerializer.cpp:Serializer::writeChunkHeader(v14.6.3 源码摘录,已删减)
    void Serializer::writeChunkHeader(uint16 id, size_t size)
    {
        ...
        writeShorts(&id, 1);
        uint32 uint32size = static_cast<uint32>(size);
        writeInts(&uint32size, 1);
    }

一个 chunk 的字节布局:

┌──────────────────────────────────────┐
│ uint16  id      (2 字节)            │
│ uint32  size    (4 字节,含块头) │
│ ...    payload  (size − 6 字节)         │
└──────────────────────────────────────┘

chunk 头大小固定 6 字节(calcChunkHeaderSize() == sizeof(uint16) + sizeof(uint32))。size 是 整个块的长度,含 6 字节块头。读者读完整块 payload 后再读下一块——readChunk 返回块 id 并记录 mCurrentstreamLen:

// OgreMain/src/OgreSerializer.cpp:Serializer::readChunk(v14.6.3 源码摘录,已删减)
    unsigned short Serializer::readChunk(const DataStreamPtr& stream)
    {
        size_t pos = stream->tell();
        unsigned short id;
        readShorts(stream, &id, 1);
        readInts(stream, &mCurrentstreamLen, 1);

        if (!stream->eof())
        {
            // chunk size cant be smaller than the header size, and must fit within the stream
            if (mCurrentstreamLen < calcChunkHeaderSize())
                OGRE_EXCEPT(Exception::ERR_INTERNAL_ERROR, "Corrupt chunk length");
            ...
        }
        return id;
    }

mesh 专用:HEADER_CHUNK_ID

MeshSerializer 的 .mesh 文件首块 id 也是 0x1000(与 magic 数值相同但角色不同),importMesh 先读它验证文件身份:

// OgreMain/src/OgreMeshSerializer.cpp:MeshSerializer::importMesh 开头(v14.6.3 源码摘录,已删减)
    const unsigned short HEADER_CHUNK_ID = 0x1000;
    ...
    void MeshSerializer::importMesh(const DataStreamPtr& stream, Mesh* pDest)
    {
        determineEndianness(stream);
        // Read header and determine the version
        unsigned short headerID;
        readShorts(stream, &headerID, 1);
        if (headerID != HEADER_CHUNK_ID)
        {
            OGRE_EXCEPT(Exception::ERR_INTERNAL_ERROR, "File header not found",
                "MeshSerializer::importMesh");
        }
        // Read version
        String ver = readString(stream);
        // Jump back to start
        stream->seek(0);
        ...
    }

注意最后 seek(0):读完版本后把流指针跳回文件起点,因为后续解析按版本选实现、从文件头重读。.mesh 的实际块 id 如 M_GEOMETRY、M_SUBMESH、M_MATERIAL 等,在 MeshSerializerImpl 的分发里逐个处理(10.2/10.3)。

Mesh 文件与块边界

flowchart LR
  H["文件头:magic 与版本行"] --> M["M_MESH 块"]
  M --> A["6 字节块头:ID 与总长度"]
  M --> B["数据及嵌套块"]
  A --> C["当前块结束 = 块起点 + size"]
  B --> C
  C --> D["以文件端序处理下一块"]

源码定位

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

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

下面复现 chunked 格式的写入与读取,包含小端/大端两种端序的往返。它与 src/10-1-mesh-serializer.cpp 逐字节一致:

// file: src/10-1-mesh-serializer.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/10-1-mesh-serializer.cpp -o bin/10-1-mesh-serializer && ./bin/10-1-mesh-serializer
//
// 复现 OgreSerializer 的 chunked 二进制格式(.mesh 文件):
//   文件头 = uint16 magic(0x1000/0x0010) + 版本字符串('\n' 终止);
//   chunk 头 = uint16 id + uint32 size(共 6 字节)+ payload;
//   端序:写侧按 Endian 翻转,读侧由 magic 判定是否翻转。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

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

namespace ogre_repro {

constexpr uint16_t HEADER_STREAM_ID = 0x1000;             // 与 OgreSerializer.cpp 一致
constexpr uint16_t OTHER_ENDIAN_HEADER_STREAM_ID = 0x0010;

// 模拟 DataStream:字节缓冲 + 读写游标
struct Stream {
  std::vector<uint8_t> buf;
  size_t pos = 0;

  void write(const void* p, size_t n) {
    const auto* bytes = static_cast<const uint8_t*>(p);
    buf.insert(buf.end(), bytes, bytes + 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(); }
};

// 逐元素翻转字节序(对应 Serializer::flipToLittleEndian)
static void flipBytes(void* p, size_t elemSize, size_t count) {
  auto* b = static_cast<uint8_t*>(p);
  for (size_t e = 0; e < count; ++e) {
    uint8_t* lo = b + e * elemSize;
    uint8_t* hi = lo + elemSize - 1;
    while (lo < hi) {
      uint8_t t = *lo;
      *lo = *hi;
      *hi = t;
      ++lo;
      --hi;
    }
  }
}

// 对应 Serializer 写侧(mFlipEndian 由 determineEndianness 设置)
class Serializer {
 public:
  std::string mVersion = "[Serializer_v1.00]";
  bool mFlipEndian = false;

  // 对应 Serializer::writeFileHeader
  void writeFileHeader(Stream& s) {
    uint16_t val = HEADER_STREAM_ID;
    writeShorts(s, &val, 1);
    writeString(s, mVersion);
  }
  // 对应 Serializer::writeChunkHeader:id(2) + size(4) = 6 字节
  void writeChunkHeader(Stream& s, uint16_t id, size_t size) {
    writeShorts(s, &id, 1);
    uint32_t sz = static_cast<uint32_t>(size);
    writeInts(s, &sz, 1);
  }
  void writeShorts(Stream& s, const uint16_t* p, size_t count) {
    std::vector<uint16_t> tmp(p, p + count);
    if (mFlipEndian) flipBytes(tmp.data(), sizeof(uint16_t), count);
    s.write(tmp.data(), sizeof(uint16_t) * count);
  }
  void writeInts(Stream& s, const uint32_t* p, size_t count) {
    std::vector<uint32_t> tmp(p, p + count);
    if (mFlipEndian) flipBytes(tmp.data(), sizeof(uint32_t), count);
    s.write(tmp.data(), sizeof(uint32_t) * count);
  }
  void writeFloats(Stream& s, const float* p, size_t count) {
    std::vector<float> tmp(p, p + count);
    if (mFlipEndian) flipBytes(tmp.data(), sizeof(float), count);
    s.write(tmp.data(), sizeof(float) * count);
  }
  // 对应 Serializer::writeString:字符串字节 + '\n' 终止符
  void writeString(Stream& s, const std::string& str) {
    s.write(str.data(), str.size());
    char terminator = '\n';
    s.write(&terminator, 1);
  }
};

// 对应 Serializer 读侧(readFileHeader / readChunk)
class DeSerializer {
 public:
  std::string mVersion = "[Serializer_v1.00]";
  bool mFlipEndian = false;
  uint32_t mCurrentstreamLen = 0;

  // 对应 Serializer::determineEndianness:由 magic 判定端序
  void determineEndianness(Stream& s) {
    uint16_t headerID = 0;
    readShortsRaw(s, &headerID, 1);
    if (headerID == HEADER_STREAM_ID) mFlipEndian = false;
    else if (headerID == OTHER_ENDIAN_HEADER_STREAM_ID) mFlipEndian = true;
    s.seek(0);
  }
  // 对应 Serializer::readFileHeader:验证 magic 与版本
  void readFileHeader(Stream& s) {
    determineEndianness(s);
    uint16_t headerID = 0;
    readShortsRaw(s, &headerID, 1);
    if (headerID != HEADER_STREAM_ID && headerID != OTHER_ENDIAN_HEADER_STREAM_ID)
      return;  // 非合法文件
    std::string ver = readString(s);
    // 版本匹配(简化:仅要求与自身版本相同)
    if (ver != mVersion) return;
  }
  // 对应 Serializer::readChunk:读 id 与 size,返回 id
  uint16_t readChunk(Stream& s) {
    uint16_t id = 0;
    readShorts(s, &id, 1);
    readInts(s, &mCurrentstreamLen, 1);
    return id;
  }
  void readShortsRaw(Stream& s, uint16_t* p, size_t count) {
    s.read(p, sizeof(uint16_t) * count);
  }
  void readShorts(Stream& s, uint16_t* p, size_t count) {
    readShortsRaw(s, p, count);
    if (mFlipEndian) flipBytes(p, sizeof(uint16_t), count);
  }
  void readInts(Stream& s, uint32_t* p, size_t count) {
    s.read(p, sizeof(uint32_t) * count);
    if (mFlipEndian) flipBytes(p, sizeof(uint32_t), count);
  }
  void readFloats(Stream& s, float* p, size_t count) {
    s.read(p, sizeof(float) * count);
    if (mFlipEndian) flipBytes(p, sizeof(float), count);
  }
  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;
  }
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // ---- 写侧:小端文件(ENDIAN_LITTLE,mFlipEndian = false)----
  Stream s1;
  Serializer ser;
  ser.mVersion = "[MeshSerializer_v1.100]";
  ser.writeFileHeader(s1);                       // magic(2) + 版本串+'\n'
  const uint16_t MESH_CHUNK = 0x1A00;
  float verts[2] = {1.5f, -2.25f};
  ser.writeChunkHeader(s1, MESH_CHUNK, 6 + sizeof(verts));
  ser.writeFloats(s1, verts, 2);

  // 文件布局:magic(2) + 版本串+'\n' + chunk 头(6) + payload(8)
  CHECK(s1.size() == 2 + ser.mVersion.size() + 1 + 6 + 8);
  // magic 小端字节序:0x1000 → [0x00, 0x10]
  CHECK(s1.buf[0] == 0x00 && s1.buf[1] == 0x10);

  // ---- 读侧:同端序(magic 0x1000 → 不翻转)----
  DeSerializer des;
  des.mVersion = "[MeshSerializer_v1.100]";
  des.readFileHeader(s1);
  CHECK(!des.mFlipEndian);
  uint16_t id = des.readChunk(s1);
  CHECK(id == MESH_CHUNK);
  CHECK(des.mCurrentstreamLen == 6 + sizeof(verts));
  float back[2] = {0, 0};
  des.readFloats(s1, back, 2);
  CHECK(back[0] == 1.5f && back[1] == -2.25f);

  // ---- 写侧:大端文件(ENDIAN_BIG,mFlipEndian = true)----
  Stream s2;
  Serializer serBig;
  serBig.mVersion = "[MeshSerializer_v1.100]";
  serBig.mFlipEndian = true;                     // 平台小端 → 写大端需翻转
  serBig.writeFileHeader(s2);
  serBig.writeChunkHeader(s2, MESH_CHUNK, 6 + sizeof(verts));
  serBig.writeFloats(s2, verts, 2);

  // magic 大端字节序:0x1000 → [0x10, 0x00]
  CHECK(s2.buf[0] == 0x10 && s2.buf[1] == 0x00);

  // ---- 读侧:读入 raw magic 为 0x0010 → 判定需翻转 ----
  DeSerializer desBig;
  desBig.mVersion = "[MeshSerializer_v1.100]";
  desBig.determineEndianness(s2);
  CHECK(desBig.mFlipEndian);
  desBig.readFileHeader(s2);
  uint16_t idBig = desBig.readChunk(s2);
  CHECK(idBig == MESH_CHUNK);
  CHECK(desBig.mCurrentstreamLen == 6 + sizeof(verts));
  float backBig[2] = {0, 0};
  desBig.readFloats(s2, backBig, 2);
  CHECK(backBig[0] == 1.5f && backBig[1] == -2.25f);

  // ---- chunk 头大小常量:id(2) + size(4) = 6 ----
  CHECK(sizeof(uint16_t) + sizeof(uint32_t) == 6);

  return lab::report("10-1 资源序列化:二进制 chunk 格式");
}

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

小结

  • .mesh 是 chunked 二进制格式:文件头 = magic + 版本串,数据是一串带 id/size 的块。
  • magic 0x1000 与 0x0010 字节相反,读侧据此判定端序是否需要翻转。
  • chunk 头 6 字节(uint16 id + uint32 size),size 包含块头与 payload。
  • 版本串如 [MeshSerializer_v1.100],读侧用它选择对应的反序列化实现。

阅读导航:上一节:9.3 AnimationState 与动画播放 · 下一节:10.2 序列化器实现 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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