-
Notifications
You must be signed in to change notification settings - Fork 330
Binary Mesh File Format
The purpose of the BinaryMesh file format is to store tessellated 3D surfaces in a compact and efficient-to-read form.
Binary Mesh files conventionally use the .binarymesh file extension.
- 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.
| Field Length | Field Type | Description |
|---|---|---|
| 10 | string | File signature. Must be equal to BINARYMESH (in capitals) for the file to be considered valid. |
| 2 | uint16 | File format version |
| variable | composite | Data block (see below) |
The format of the data block depends on the value of the file format version field.
| Field Length | Field Type | Description |
|---|---|---|
| 2 | uint16 | Length of object #1's name |
| 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 |
| ... |
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 Length | Field Type | Description |
|---|---|---|
| 8 | uint64 | Length of uncompressed sub-block |
| 8 | uint64 | Length of compressed sub-block |
| variable | bytes[] | Compressed sub-block |
Note: Version 2 of the BinaryMesh file format is deprecated: no new files should be written using this format.
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 Length | Field Type | Description |
|---|---|---|
| 8 | uint64 | Length of uncompressed sub-block |
| 8 | uint64 | Length of compressed sub-block |
| variable | bytes[] | Compressed sub-block |
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 Length | Field Type | Description |
|---|---|---|
| 2 | uint16 | Length of object #1's name |
| 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 |
| ... |