Binary Mesh File Format

Introduction

The purpose of the BinaryMesh file format is to store 3D geometry in a compact and efficient-to-read form.

Binary Mesh files conventionally use the .binarymesh file extension.

File Layout

Conventions

• All offsets are zero-based (the first byte of the file is at offset 0).
• All offsets and lengths are expressed in bytes.
• All multi-byte fields are using the little-endian (Intel) convention.

High-Level Structure

Field Offset	Field Length	Field Type	Description
0	10	string	File signature. Must be equal to BINARYMESH (in capitals) for the file to be considered valid
10	2	uint16	File format version
12	variable	composite	Data block (see below)

The format of the Data block depends on the value of the Version field.

Data Block Format Version 1

Field Offset	Field Length	Field Type	Description
0	2	uint16	Length of object #1's name
2	variable	string	Name of object #1
	4	uint32	Number of vertices
	8	double	X coordinate of vertex #1
	8	double	Y coordinate of vertex #1
	8	double	Z coordinate of vertex #1
	8	double	X coordinate of vertex #2
			...
	4	uint32	Number of vertex normals
	8	double	X coordinate of normal #1
	8	double	Y coordinate of normal #1
	8	double	Z coordinate of normal #1
	8	double	X coordinate of normal #2
			...
	4	uint32	Number of texture coordinates
	8	double	U coordinate of texcoord #1
	8	double	V coordinate of texcoord #1
	8	double	U coordinate of texcoord #2
			...
	2	uint16	Number of material slots
	2	uint16	Length of material slot #1's name
	variable	string	Name of material slot #1
	2	uint16	Length of material slot #2's name
	variable	string	Name of material slot #2
			...
	4	uint32	Number of faces
	2	uint16	Number of vertices in face #1
	4	uint32	Index of vertex #1 of face #1
	4	uint32	Index of normal #1 of face #1
	4	uint32	Index of texcoord #1 of face #1
	4	uint32	Index of vertex #2 of face #1
	4	uint32	Index of normal #2 of face #1
	4	uint32	Index of texcoord #2 of face #1
			...
	2	uint16	Index of material of face #1
	2	uint16	Number of vertices in face #2
			...

Data Block Format Version 2

In version 2, the data block has the same format as in version 1 but it is compressed with the LZO library.

The data block is split into multiple sub-blocks that are compressed independently. Each sub-block has the following format:

Field Offset	Field Length	Field Type	Description
0	8	uint64	Length of uncompressed sub-block
8	8	uint64	Length of compressed sub-block
16	variable	bytes[]	Compressed sub-block

Note: Version 2 of the BinaryMesh file format is deprecated: no new files should be written using this format.

Data Block Format Version 3

In version 3, the data block has the same format as in version 1 but it is compressed with the LZ4 library.

The data block is split into multiple sub-blocks that are compressed independently. Each sub-block has the following format:

Field Offset	Field Length	Field Type	Description
0	8	uint64	Length of uncompressed sub-block
8	8	uint64	Length of compressed sub-block
16	variable	bytes[]	Compressed sub-block

Data Block Format Version 4

In version 4, vertices and normals are written in single precision instead of double precision. The data block, compressed with LZ4, has the following format:

Field Offset	Field Length	Field Type	Description
0	2	uint16	Length of object #1's name
2	variable	string	Name of object #1
	4	uint32	Number of vertices
	4	float	X coordinate of vertex #1
	4	float	Y coordinate of vertex #1
	4	float	Z coordinate of vertex #1
	4	float	X coordinate of vertex #2
			...
	4	uint32	Number of vertex normals
	4	float	X coordinate of normal #1
	4	float	Y coordinate of normal #1
	4	float	Z coordinate of normal #1
	4	float	X coordinate of normal #2
			...
	4	uint32	Number of texture coordinates
	4	float	U coordinate of texcoord #1
	4	float	V coordinate of texcoord #1
	4	float	U coordinate of texcoord #2
			...
	2	uint16	Number of material slots
	2	uint16	Length of material slot #1's name
	variable	string	Name of material slot #1
	2	uint16	Length of material slot #2's name
	variable	string	Name of material slot #2
			...
	4	uint32	Number of faces
	2	uint16	Number of vertices in face #1
	4	uint32	Index of vertex #1 of face #1
	4	uint32	Index of normal #1 of face #1
	4	uint32	Index of texcoord #1 of face #1
	4	uint32	Index of vertex #2 of face #1
	4	uint32	Index of normal #2 of face #1
	4	uint32	Index of texcoord #2 of face #1
			...
	2	uint16	Index of material of face #1
	2	uint16	Number of vertices in face #2
			...