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["以文件端序处理下一块"]
源码定位
OgreMain/src/OgreSerializer.cpp:HEADER_STREAM_ID/OTHER_ENDIAN_HEADER_STREAM_ID、writeFileHeader、writeChunkHeader、readChunkOgreMain/include/OgreSerializer.h:Serializer(Endian枚举、calcChunkHeaderSize、calcStringSize)OgreMain/src/OgreMeshSerializer.cpp:HEADER_CHUNK_ID、MeshSerializer::importMesh开头
上游引用固定到 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 序列化器实现 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。