In this article I will describe the blend-file-format with a request to tool-makers to support blend-file.

First I'll describe how Blender works with blend-files. You'll notice why the blend-file-format is not that well documented, as from Blender's perspective this is not needed. We look at the global file-structure of a blend-file (the file-header and file-blocks). After this is explained, we go deeper to the core of the blend-file, the DNA-structures. They hold the blue-prints of the blend-file and the key asset of understanding blend-files. When that's done we can use these DNA-structures to read information from elsewhere in the blend-file.

In this article we'll be using the default blend-file from Blender 2.54, with the goal to read the output resolution from the Scene. The article is written to be programming language independent and I've setup a web-site for support.

Loading and saving in Blender is very fast and Blender is known to have excellent downward and upward compatibility. Ton Roosendaal demonstrated that in December 2008 by loading a 1.0 blend-file using Blender 2.48a [ref: http://www.blendernation.com/2008/12/01/blender-dna-rna-and-backward-compatibility/].

Saving complex scenes in Blender is done within seconds. Blender achieves this by saving data in memory to disk without any transformations or translations. Blender only adds file-block-headers to this data. A file-block-header contains clues on how to interpret the data. After the data, all internally Blender structures are stored. These structures will act as blue-prints when Blender loads the file. Blend-files can be different when stored on different hardware platforms or Blender releases. There is no effort taken to make blend-files binary the same. Blender creates the blend-files in this manner since release 1.0. Backward and upwards compatibility is not implemented when saving the file, this is done during loading.

When Blender loads a blend-file, the DNA-structures are read first. Blender creates a catalog of these DNA-structures. Blender uses this catalog together with the data in the file, the internal Blender structures of the Blender release you're using and a lot of transformation and translation logic to implement the backward and upward compatibility. In the source code of blender there is actually logic which can transform and translate every structure used by a Blender release to the one of the release you're using [ref: http://download.blender.org/source/blender-2.48a.tar.gz blender/blenloader/intern/readfile.c lines 4946-7960]. The more difference between releases the more logic is executed.

The blend-file-format is not well documented, as it does not differ from internally used structures and the file can really explain itself.

This section explains how the global file-structure can be read.

• A blend-file always start with the file-header
• After the file-header, follows a list of file-blocks (the default blend file of Blender 2.48 contains more than 400 of these file-blocks).
• Each file-block has a file-block header and file-block data
• At the end of the blend-file there is a section called "Structure DNA", which lists all the internal structures of the Blender release the file was created in
• The blend-file ends with a file-block called 'ENDB'

The first 12 bytes of every blend-file is the file-header. The file-header has information on Blender (version-number) and the PC the blend-file was saved on (pointer-size and endianness). This is required as all data inside the blend-file is ordered in that way, because no translation or transformation is done during saving. The next table describes the information in the file-header.

Endianness addresses the way values are ordered in a sequence of bytes(see the example below):

• in a big endian ordering, the largest part of the value is placed on the first byte and the lowest part of the value is placed on the last byte,
• in a little endian ordering, largest part of the value is placed on the last byte and the smallest part of the value is placed on the first byte.

Nowadays, little-endian is the most commonly used.

Blender supports little-endian and big-endian.
This means that when the endianness is different between the blend-file and the PC your using, Blender changes it to the byte ordering of your PC.

File-blocks contain a "file-block header" and "file-block data".

The file-block-header describes:

• the type of information stored in the file-block
• the total length of the data
• the old memory pointer at the moment the data was written to disk
• the number of items of this information

As we can see below, depending on the pointer-size stored in the file-header, a file-block-header can be 20 or 24 bytes long, hence it is always aligned at 4 bytes.

The above table describes how a file-block-header is structured:

• Code describes different types of file-blocks. The code determines with what logic the data must be read.
  These codes also allows fast finding of data like Library, Scenes, Object or Materials as they all have a specific code.
• Size contains the total length of data after the file-block-header. After the data a new file-block starts. The last file-block in the file has code 'ENDB'.
• Old memory address contains the memory address when the structure was last stored. When loading the file the structures can be placed on different memory addresses. Blender updates pointers to these structures to the new memory addresses.
• SDNA index contains the index in the DNA structures to be used when reading this file-block-data.
  More information about this subject will be explained in the Reading scene information section.
• Count tells how many elements of the specific SDNA structure can be found in the data.

Structure DNA is stored in a file-block with code 'DNA1'. It can be just before the 'ENDB' file-block.

The 'DNA1' file-block contains all internal structures of the Blender release the file was created in.
These structure can be described as C-structures: they can hold fields, arrays and pointers to other structures, just like a normal C-structure.

struct SceneRenderLayer { struct SceneRenderLayer *next, *prev; char name[32]; struct Material *mat_override; struct Group *light_override; unsigned int lay; unsigned int lay_zmask; int layflag; int pad; int passflag; int pass_xor; };

For example,a blend-file created with Blender 2.54 the 'DNA1' file-block is 57796 bytes long and contains 398 structures.

The DNA1 file-block header follows the same rules of any other file-block, see the example below.

The next section describes how this information is ordered in the data of the 'DNA1' file-block.

As you can see, the structures are stored in 4 arrays: names, types, lengths and structures. Every structure also contains an array of fields. A field is the combination of a type and a name. From this information a catalog of all structures can be constructed. The names are stored as how a C-developer defines them. This means that the name also defines pointers and arrays. (When a name starts with '*' it is used as a pointer. when the name contains for example '[3]' it is used as a array of 3 long.) In the types you'll find simple-types (like: 'integer', 'char', 'float'), but also complex-types like 'Scene' and 'MetaBall'. 'TLEN' part describes the length of the types. A 'char' is 1 byte, an 'integer' is 4 bytes and a 'Scene' is 1376 bytes long.

The DNA structures inside a Blender 2.48 blend-file can be found at http://www.atmind.nl/blender/blender-sdna.html. If we understand the DNA part of the file it is now possible to read information from other parts file-blocks. The next section will tell us how.

Let us look at the file-block header we have seen earlier:

• the file-block identifier is 'SC'+0x00h
• the SDNA index is 150
• the file-block size is 1404 bytes

Now note that:

• the structure at index 150 in the DNA is a structure of type 'Scene' (counting from 0).
• the associated type ('Scene') in the DNA has the length of 1404 bytes.

We can map the Scene structure on the data of the file-blocks. But before we can do that, we have to flatten the Scene-structure. struct Scene { ID id; // 52 bytes long (ID is different a structure) AnimData *adt; // 4 bytes long (pointer to an AnimData structure) Object *camera; // 4 bytes long (pointer to an Object structure) World *world; // 4 bytes long (pointer to an Object structure) ... float cursor[3]; // 12 bytes long (array of 3 floats) ... }; The first field in the Scene-structure is of type 'ID' with the name 'id'. Inside the list of DNA structures there is a structure defined for type 'ID' (structure index 17). struct ID { void *next, *prev; struct ID *newid; struct Library *lib; char name[24]; short us; short flag; int icon_id; IDProperty *properties; }; The first field in this structure has type 'void' and name '*next'.
Looking in the structure list there is no structure defined for type 'void': it is a simple type and therefore the data should be read. The name '*next' describes a pointer. As we see, the first 4 bytes of the data can be mapped to 'id.next'.

Using this method we'll map a structure to its data. If we want to read a specific field we know at which offset in the data it is located and how much space it takes.
The next table shows the output of this flattening process for some parts of the Scene-structure. Not all rows are described in the table as there is a lot of information in a Scene-structure.

We can now read the X and Y resolution of the Scene:

• the X-resolution is located on offset 382 of the file-block-data and must be read as a short.
• the Y-resolution is located on offset 384 and is also a short