patch [#27909] Added constants in bge.constraints by Solano Felicio (solano) + some...
[blender.git] / doc / blender_file_format / mystery_of_the_blend.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <head>
4     <link rel="stylesheet" type="text/css" href="mystery_of_the_blend.css" media="screen, print">
5     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6     <title>The mystery of the blend</title>
7 </head>
8
9 <body>
10 <div class="title">The mystery of the blend</div>
11 <div class="subtitle">The blender file-format explained</div>
12 <div class="contact">
13 <label>Author</label> Jeroen Bakker<br>
14 <label>Email</label> <a href="mailto:j.bakker@atmind.nl">j.bakker@atmind.nl</a><br>
15 <label>Website</label> <a href="http://www.atmind.nl/blender/">http://www.atmind.nl/blender</a><br>
16 <label>Version</label> 06-10-2010<br>
17 </div>
18
19 <a name="introduction" href="#introduction" ><h2>Introduction</h2></a>
20 </a>
21
22 <p>In this article I will describe the
23  blend-file-format with a request to tool-makers to support blend-file. 
24    
25 </p>
26 <p>First I'll describe how Blender works with blend-files. You'll notice
27  why the blend-file-format is not that well documented, as from 
28 Blender's perspective this is not needed.
29 We look at the global file-structure of a blend-file (the file-header 
30 and file-blocks).
31 After this is explained, we go deeper to the core of the blend-file, the
32  DNA-structures. They hold the blue-prints of the blend-file and the key
33  asset of understanding blend-files.
34 When that's done we can use these DNA-structures to read information 
35 from elsewhere in the blend-file.
36
37 </p>
38 <p>
39 In this article we'll be using the default blend-file from Blender 2.54,
40  with the goal to read the output resolution from the Scene. 
41 The article is written to be programming language independent and I've 
42 setup a web-site for support.
43 </p>
44
45 <a name="loading-and-saving-in-blender" href="#loading-and-saving-in-blender">
46 <h2>Loading and saving in Blender</h2>
47 </a>
48
49 <p>
50 Loading and saving in Blender is very fast and Blender is known to 
51 have excellent downward and upward compatibility. Ton Roosendaal 
52 demonstrated that in December 2008 by loading a 1.0 blend-file using 
53 Blender 2.48a [ref: <a href="http://www.blendernation.com/2008/12/01/blender-dna-rna-and-backward-compatibility/">http://www.blendernation.com/2008/12/01/blender-dna-rna-and-backward-compatibility/</a>].
54 </p>
55
56 <p>
57 Saving complex scenes in Blender is done within seconds. Blender 
58 achieves this by saving data in memory to disk without any 
59 transformations or translations. Blender only adds file-block-headers to
60  this data. A file-block-header contains clues on how to interpret the 
61 data. After the data, all internally Blender structures are stored. 
62 These structures will act as blue-prints when Blender loads the file. 
63 Blend-files can be different when stored on different hardware platforms
64  or Blender releases. There is no effort taken to make blend-files 
65 binary the same. Blender creates the blend-files in this manner since 
66 release 1.0. Backward and upwards compatibility is not implemented when 
67 saving the file, this is done during loading.
68 </p>
69
70 <p>
71 When Blender loads a blend-file, the DNA-structures are read first. 
72 Blender creates a catalog of these DNA-structures. Blender uses this 
73 catalog together with the data in the file, the internal Blender 
74 structures of the Blender release you're using and a lot of 
75 transformation and translation logic to implement the backward and 
76 upward compatibility. In the source code of blender there is actually 
77 logic which can transform and translate every structure used by a 
78 Blender release to the one of the release you're using [ref: <a href="http://download.blender.org/source/blender-2.48a.tar.gz">http://download.blender.org/source/blender-2.48a.tar.gz</a>
79  <a href="https://svn.blender.org/svnroot/bf-blender/tags/blender-2.48-release/source/blender/blenloader/intern/readfile.c">blender/blenloader/intern/readfile.c</a> lines 
80 4946-7960]. The more difference between releases the more logic is 
81 executed. 
82 </p>
83
84 <p>
85 The blend-file-format is not well documented, as it does not differ from
86  internally used structures and the file can really explain itself.
87 </p>
88
89 <a name="global-file-structure" href="#global-file-structure">
90 <h2>Global file-structure</h2>
91 </a>
92
93 <p>
94 This section explains how the global file-structure can be read.
95 </p>
96
97 <ul>
98 <li>A blend-file always start with the <b>file-header</b></li>
99 <li>After the file-header, follows a list of <b>file-blocks</b> (the default blend file of Blender 2.48 contains more than 400 of these file-blocks).</li>
100 <li>Each file-block has a <b>file-block header</b> and <b>file-block data</b></li>
101 <li>At the end of the blend-file there is a section called "<a href="#structure-DNA" style="font-weight:bold">Structure DNA</a>", which lists all the internal structures of the Blender release the file was created in</li>
102 <li>The blend-file ends with a file-block called 'ENDB'</li>
103 </ul>
104
105 <!-- file scheme -->
106 <div class="box-solid" style="width:20%; margin-left:35%; font-size:0.8em;">
107
108     <p class="code"><b>File.blend</b></p>
109
110     <div class="box"><p class="code">File-header</p></div>
111
112     <div class="box-solid"><p class="code">File-block</p>
113         <div class="box"><p class="code">Header</p></div>
114         <div class="box"><p class="code">Data</p></div>
115     </div>
116     
117     <div class="box" style="border-style:dashed"><p class="code">File-block</p></div>
118     <div class="box" style="border-style:dashed"><p class="code">File-block</p></div>
119
120     <div class="box-solid"><p class="code">File-block 'Structure DNA'</p>
121         <div class="box"><p class="code">Header ('DNA1')</p></div>
122         <div class="box-solid">
123             <p class="code">Data ('SDNA')</p>
124             <div class="box">
125                 <p class="code">Names ('NAME')</p>
126             </div>
127             <div class="box">
128                 <p class="code">Types ('TYPE')</p>
129             </div>
130             <div class="box">
131                 <p class="code">Lengths ('TLEN')</p>
132             </div>
133             <div class="box">
134                 <p class="code">Structures ('STRC')</p>
135             </div>
136         </div>
137     </div>
138
139     <div class="box-solid"><p class="code">File-Block 'ENDB'</p></div>
140
141 </div><!-- end of file scheme -->
142
143 <a name="file-header" href="#file-header">
144 <h3>File-Header</h3>
145 </a>
146
147 <p>
148 The first 12 bytes of every blend-file is the file-header. The 
149 file-header has information on Blender (version-number) and the PC the 
150 blend-file was saved on (pointer-size and endianness). This is required 
151 as all data inside the blend-file is ordered in that  way, because no  
152 translation or transformation  is done during saving. 
153 The next table describes the information in the file-header.
154 </p>
155
156 <table>
157 <caption>File-header</caption>
158 <thead>
159 <tr><th>reference</th>
160     <th>structure</th>
161     <th>type</th>
162     <th>offset</th>
163     <th>size</th></tr>
164 </thead>
165 <tbody>
166 <tr><td>identifier</td>
167     <td>char[7]</td>
168     <td>File identifier (always 'BLENDER')</td>
169     <td>0</td>
170     <td>7</td></tr>
171 <tr><td>pointer-size</td>
172     <td>char</td>
173     <td>Size of a pointer; all pointers in the file are stored in this format. '_' means 4 bytes or 32 bit and '-' means 8 bytes or 64 bits.</td>
174     <td>7</td>
175     <td>1</td></tr>
176 <tr><td>endianness</td>
177     <td>char</td>
178     <td>Type of byte ordering used; 'v' means little endian and 'V' means big endian.</td>
179     <td>8</td>
180     <td>1</td></tr>
181 <tr><td>version-number</td>
182     <td>char[3]</td>
183     <td>Version of Blender the file was created in; '254' means version 2.54</td>
184     <td>9</td>
185     <td>3</td></tr>
186 </tbody>
187 </table>
188
189 <p>
190 <a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> addresses the way values are ordered in a sequence of bytes(see the <a href="#example-endianess">example</a> below):
191 </p>
192
193 <ul>
194     <li>in a big endian ordering, the largest part of the value is placed on the first byte and 
195     the lowest part of the value is placed on the last byte,</li>
196     <li>in a little endian ordering, largest part of the value is placed on the last byte
197     and the smallest part of the value is placed on the first byte.</li>
198 </ul>
199
200 <p> 
201 Nowadays, little-endian is the most commonly used.
202 </p>
203
204 <a name="example-endianess"></a>
205 <div class="box">
206 <p onclick="location.href='#example-endianess'" class="box-title">
207 Endianess Example
208 </p>
209 <p>
210 Writing the integer <code class="evidence">0x4A3B2C1Dh</code>, will be ordered:
211 <ul>
212 <li>in big endian as <code class="evidence">0x4Ah</code>, <code class="evidence">0x3Bh</code>, <code class="evidence">0x2Ch</code>, <code class="evidence">0x1Dh</code></li>
213 <li>in little endian as <code class="evidence">0x1Dh</code>, <code class="evidence">0x2Ch</code>, <code class="evidence">0x3Bh</code>, <code class="evidence">0x4Ah</code></li>
214 </ul>
215 </p>
216 </div>
217
218 <p>
219 Blender supports little-endian and big-endian.<br>
220 This means that when the endianness 
221 is different between the blend-file and the PC your using, Blender changes it to the byte ordering 
222 of your PC.
223 </p>
224
225 <a name="example-file-header"></a>
226 <div class="box">
227 <p onclick="location.href='#example-file-header'" class="box-title">
228 File-header Example
229 </p>
230
231 <p>
232 This hex-dump describes a file-header created with <code>blender</code> <code>2.54.0</code> on <code>little-endian</code> hardware with a <code>32 bits</code> pointer length.
233 <code class="block">                               <span class="descr">pointer-size  version-number
234                                      |             |</span>
235 0000 0000: [42 4C 45 4E 44 45 52]  [5F]  [76]  [32 35 34]        BLENDER_v254  <span class="descr">
236                       |                   |
237                   identifier          endianness</span></code>
238 </p>
239 </div>
240
241 <a name="file-blocks" href="#file-blocks"><h3>File-blocks</h3></a>
242
243 <p>
244 File-blocks contain a "<a href="#file-block-header">file-block header</a>" and "file-block data". 
245 </p>
246
247 <a name="file-block-header" href="#file-block-header"><h3>File-block headers</h3></a>
248
249 <p>
250 The file-block-header describes:
251 </p>
252
253 <ul>
254 <li>the type of information stored in the 
255 file-block</li>
256 <li>the total length of the data</li>
257 <li>the old memory 
258 pointer at the moment the data was written to disk</li>
259 <li>the number of items of this information</li>
260 </ul>
261
262 <p>
263 As we can see below, depending on the pointer-size stored in the file-header, a file-block-header 
264 can be 20 or 24 bytes long, hence it is always aligned at 4 bytes.
265 </p>
266
267 <table>
268 <caption>File-block-header</caption>
269 <thead>
270 <tr>
271 <th>reference</th>
272     <th>structure</th>
273     <th>type</th>
274     <th>offset</th>
275     <th>size</th></tr></thead>
276 <tbody>
277 <tr><td>code</td>
278     <td>char[4]</td>
279     <td>File-block identifier</td>
280     <td>0</td>
281     <td>4</td></tr>
282 <tr><td>size</td>
283     <td>integer</td>
284     <td>Total length of the data after the file-block-header</td>
285     <td>4</td>
286     <td>4</td></tr>
287 <tr><td>old memory address</td>
288     <td>void*</td>
289     <td>Memory address the structure was located when written to disk</td>
290     <td>8</td>
291     <td>pointer-size (4/8)</td></tr>
292 <tr><td>SDNA index</td>
293     <td>integer</td>
294     <td>Index of the SDNA structure</td>
295     <td>8+pointer-size</td>
296     <td>4</td></tr>
297 <tr><td>count</td>
298     <td>integer</td>
299     <td>Number of structure located in this file-block</td>
300     <td>12+pointer-size</td>
301     <td>4</td></tr>
302 </tbody>
303 </table>
304
305 <p>
306 The above table describes how a file-block-header is structured:
307 </p>
308
309 <ul>
310 <li><code>Code</code> describes different types of file-blocks. The code determines with what logic the data must be read. <br>  
311 These codes also allows fast finding of data like Library, Scenes, Object or Materials as they all have a specific code. </li>
312 <li><code>Size</code> contains the total length of data after the file-block-header. 
313 After the data a new file-block starts. The last file-block in the file 
314 has code 'ENDB'.</li>
315 <li><code>Old memory address</code> contains the memory address when the structure 
316 was last stored. When loading the file the structures can be placed on 
317 different memory addresses. Blender updates pointers to these structures
318  to the new memory addresses.</li>
319 <li><code>SDNA index</code> contains the index in the DNA structures to be used when 
320 reading this file-block-data. <br>
321 More information about this subject will be explained in the <a href="#reading-scene-information">Reading scene information section</a>.</li>
322 <li><code>Count</code> tells how many elements of the specific SDNA structure can be found in the data.</li> 
323 </ul>
324
325 <a name="example-file-block-header"></a>
326 <div class="box">
327 <p onclick="location.href='#example-file-block-header'" class="box-title">
328 Example
329 </p>
330 <p>
331 This hex-dump describes a File-block (= <span class="header">File-block header</span> + <span class="data">File-block data</span>) created with <code>blender</code> <code>2.54</code> on <code>little-endian</code> hardware with a <code>32 bits</code> pointer length.<br>
332 <code class="block"><span class="descr">             file-block 
333            identifier='SC'  data size=1404  old pointer   SDNA index=150
334                  |              |              |              |</span>
335 0000 4420: <span class="header">[53 43 00 00]  [7C 05 00 00]  [68 34 FB 0B]  [96 00 00 00]</span>    SC.. `... ./.. .... 
336 0000 4430: <span class="header">[01 00 00 00]</span>  <span class="data">[xx xx xx xx    xx xx xx xx    xx xx xx xx</span>     .... xxxx xxxx xxxx<span class="descr">
337                  |              |
338               count=1      file-block data (next 1404 bytes)</span>
339 </code>
340 </p>
341
342 <ul>
343 <li>The code <code>'SC'+0x00h</code> identifies that it is a Scene. </li>
344 <li>Size of the data is 1404 bytes (0x0000057Ch = 0x7Ch + 0x05h * 256 = 124 + 1280)</li>
345 <li>The old pointer is 0x0BFB3468h</li>
346 <li>The SDNA index is 150 (0x00000096h = 6 + 9 * 16 = 6 + 144)</li>
347 <li>The section contains a single scene (count = 1).</li>
348 </ul>
349
350 <p>
351 Before we can interpret the data of this file-block we first have to read the DNA structures in the file. 
352 The section "<a href="#structure-DNA">Structure DNA</a>" will show how to do that. 
353 </p>
354 </div>
355
356 <a name="structure-DNA" href="#structure-DNA"><h2>Structure DNA</h2></a>
357
358 <a name="DNA1-file-block" href="#DNA1-file-block"><h3>The DNA1 file-block</h3></a>
359
360 <p>
361 Structure DNA is stored in a file-block with code 'DNA1'. It can be just before the 'ENDB' file-block.
362 </p>
363
364 <p>
365 The 'DNA1' file-block contains all internal structures of the Blender release the 
366 file was created in. <br>
367 These structure can be described as C-structures: they can hold fields, arrays and 
368 pointers to other structures, just like a normal C-structure.
369
370 <p>
371 <code class="block">struct SceneRenderLayer {
372     struct SceneRenderLayer *next, *prev;
373     char name[32];
374     struct Material *mat_override;
375     struct Group *light_override;
376     unsigned int lay;
377     unsigned int lay_zmask;
378     int layflag;
379     int pad;
380     int passflag;
381     int pass_xor;
382 };
383 </code>
384 </p>
385
386 <p>
387 For example,a blend-file created with Blender 2.54 the 'DNA1' file-block is 57796 bytes long and contains 398 structures.
388 </p>
389
390 <a name="DNA1-file-block-header" href="#DNA1-file-block-header"><h3>DNA1 file-block-header</h3></a>
391
392 <p>
393 The DNA1 file-block header follows the same rules of any other file-block, see the example below.
394 </p>
395
396 <a name="example-DNA1-file-block-header"></a>
397 <div class="box">
398 <p onclick="location.href='#example-DNA1-file-block-header'" class="box-title">
399 Example
400 </p>
401 <p>
402 This hex-dump describes the file-block 'DNA1' header created with <code>blender</code> <code>2.54.0</code> on <code>little-endian</code> hardware with a <code>32 bits</code> pointer length.<br>
403 <code class="block"><span class="descr">      (file-block 
404        identifier='DNA1') data size=57796   old pointer   SDNA index=0
405                   |              |              |              |</span>
406 0004 B060   <span class="header">[44 4E 41 31]  [C4 E1 00 00]  [C8 00 84 0B]  [00 00 00 00]</span>  DNA1............
407 0004 B070   <span class="header">[01 00 00 00]</span>  <span class="fade">[53 44 4E 41    4E 41 4D 45    CB 0B 00 00</span>   ....<span class="fade">SDNANAME....</span><span class="descr">
408                   |              |
409               count=1    'DNA1' file-block data (next 57796 bytes)</span>
410 </code>
411 </p>
412 </div>
413
414 <a name="DNA1-file-block-data" href="#DNA1-file-block-data"><h3>DNA1 file-block data</h3></a>
415 <p>
416 The next section describes how this information is ordered in the <b>data</b> of the 'DNA1' file-block.
417 </p>
418
419 <table>
420 <caption>Structure of the DNA file-block-data</caption>
421 <thead>
422     <tr><th colspan="2">repeat condition</th>
423     <th>name</th>
424     <th>type</th>
425     <th>length</th>
426     <th>description</th></tr>
427 </thead>
428 <tbody>
429 <tr><td></td>
430     <td></td>
431     <td>identifier</td>
432     <td>char[4]</td>
433     <td>4</td>
434     <td>'SDNA'</td></tr>
435 <tr><td></td>
436     <td></td>
437     <td>name identifier</td>
438     <td>char[4]</td>
439     <td>4</td>
440     <td>'NAME'</td></tr>
441 <tr><td></td>
442     <td></td>
443     <td>#names</td>
444     <td>integer</td>
445     <td>4</td>
446     <td>Number of names follows</td></tr>
447 <tr><td>for(#names)</td>
448     <td></td>
449     <td>name</td>
450     <td>char[]</td>
451     <td>?</td>
452     <td>Zero terminating string of name, also contains pointer and simple array definitions (e.g. '*vertex[3]\0')</td></tr>
453 <tr><td></td>
454     <td></td>
455     <td>type identifier</td>
456     <td>char[4]</td>
457     <td>4</td>
458     <td>'TYPE' this field is aligned at 4 bytes</td></tr>
459 <tr><td></td>
460     <td></td>
461     <td>#types</td>
462     <td>integer</td>
463     <td>4</td>
464     <td>Number of types follows</td></tr>
465 <tr><td>for(#types)</td>
466     <td></td>
467     <td>type</td>
468     <td>char[]</td>
469     <td>?</td>
470     <td>Zero terminating string of type (e.g. 'int\0')</td></tr>
471 <tr><td></td>
472     <td></td>
473     <td>length identifier</td>
474     <td>char[4]</td>
475     <td>4</td>
476     <td>'TLEN' this field is aligned at 4 bytes</td></tr>
477 <tr><td>for(#types)</td>
478     <td></td>
479     <td>length</td>
480     <td>short</td>
481     <td>2</td>
482     <td>Length in bytes of type (e.g. 4)</td></tr>
483 <tr><td></td>
484     <td></td>
485     <td>structure identifier</td>
486     <td>char[4]</td>
487     <td>4</td>
488     <td>'STRC' this field is aligned at 4 bytes</td></tr>
489 <tr><td></td>
490     <td></td>
491     <td>#structures</td>
492     <td>integer</td>
493     <td>4</td>
494     <td>Number of structures follows</td></tr>
495 <tr><td>for(#structures)</td>
496     <td></td>
497     <td>structure type</td>
498     <td>short</td>
499     <td>2</td>
500     <td>Index in types containing the name of the structure</td></tr>
501 <tr><td>..</td>
502     <td></td>
503     <td>#fields</td>
504     <td>short</td>
505     <td>2</td>
506     <td>Number of fields in this structure</td></tr>
507 <tr><td>..</td>
508     <td>for(#field)</td>
509     <td>field type</td>
510     <td>short</td>
511     <td>2</td>
512     <td>Index in type</td></tr>
513 <tr><td>for end</td>
514     <td>for end</td>
515     <td>field name</td>
516     <td>short</td>
517     <td>2</td>
518     <td>Index in name</td></tr>
519 </tbody>
520 </table>
521
522 <p>
523 As you can see, the structures are stored in 4 arrays: names, types, 
524 lengths and structures. Every structure also contains an array of 
525 fields. A field is the combination of a type and a name. From this 
526 information a catalog of all structures can be constructed. 
527 The names are stored as how a C-developer defines them. This means that 
528 the name also defines pointers and arrays.
529 (When a name starts with '*' it is used as a pointer. when the name 
530 contains for example '[3]' it is used as a array of 3 long.)
531 In the types you'll find simple-types (like: 'integer', 'char', 
532 'float'), but also complex-types like 'Scene' and 'MetaBall'. 
533 'TLEN' part describes the length of the types. A 'char' is 1 byte, an 
534 'integer' is 4 bytes and a 'Scene' is 1376 bytes long.
535 </p>
536
537 <div class="box">
538 <p class="box-title">
539 Note
540 </p>
541 <p>
542 All identifiers, are arrays of 4 chars, hence they are all aligned at 4 bytes.
543 </p>
544 </div>
545
546 <a name="example-DNA1-file-block-data"></a>
547 <div class="box">
548 <p onclick="location.href='#example-DNA1-file-block-data'" class="box-title">
549 Example
550 </p>
551 <p>
552 Created with <code>blender</code> <code>2.54.0</code> on <code>little-endian</code> hardware with a <code>32 bits</code> pointer length.
553 </p>
554
555 <a name="DNA1-data-array-names" href="#DNA1-data-array-names"><h4>The names array</h4></a>
556 <p>
557 The first names are: *next, *prev, *data, *first, *last, x, y, xmin, xmax, ymin, ymax, *pointer, group, val, val2, type, subtype, flag, name[32], ...
558 <code class="block"><span class="descr">    file-block-data identifier='SDNA'  array-id='NAME'     number of names=3019
559                                 |              |             |</span>
560 0004 B070    <span class="fade">01 00  00 00 [53 44  4E 41]</span><span class="data">[4E  41 4D 45] [CB 0B 00  00]</span>  <span class="fade">....SDNA</span>NAME....
561 0004 B080   <span class="data">[2A 6E  65 78  74 00][2A 70  72  65 76 00] [2A 64 61  74</span>   *next.*prev.*dat<span class="descr">
562                       |                    |                   | 
563                   '*next\0'            '*prev\0'            '*dat'</span><span class="fade">
564                                   ....
565                                   .... (3019 names)</span>
566 </code>
567 </p>
568
569 <div class="box">
570 <p class="box-title">
571 Note
572 </p>
573 <p>
574 While reading the DNA you'll will come across some strange 
575 names like '(*doit)()'. These are method pointers and Blender updates 
576 them to the correct methods.
577 </p>
578 </div>
579
580 <a name="DNA1-data-array-types" href="#DNA1-data-array-types"><h4>The types array</h4></a>
581 <p>
582 The first types are: char, uchar, short, ushort, int, long, ulong, float, double, void, Link, LinkData, ListBase, vec2s, vec2f, ...
583 <code class="block"><span class="descr">                                                      array-id='TYPE'
584                                                             |</span>
585 0005 2440    <span class="fade">6F 6C 64 5B   34 5D 5B 34 5D 00 00 00</span>   [54 59 50  45]  <span class="fade">old[4][4]...</span>TYPE
586 0005 2450   [C9 01 00 00] [63 68 61 72 00]  [75 63 68 61 72 00][73   ....char.uchar.s<span class="descr">
587                   |                |                 |           |
588        number of types=457     'char\0'          'uchar\0'      's'</span><span class="fade">
589                                   ....
590                                   .... (457 types)</span>
591 </code>
592 </p>
593
594 <a name="DNA1-data-array-lengths" href="#DNA1-data-array-lengths"><h4>The lengths array</h4></a>
595 <p>
596 <code class="block"><span class="descr">                                                 char    uchar    ushort   short
597                                  array-id       length   length   length   length
598                                    'TLEN'          1        1        2        2</span>
599 0005 3AA0    <span class="fade">45 00    00 00</span>   [54 4C    45 4E]  [01 00]  [01 00]  [02 00]  [02 00]  <span class="fade">E...</span>TLEN........
600                                   <span class="fade">....</span>
601 0005 3AC0   [08 00]  [04 00]  [08 00]  [10 00]  [10 00]  [14 00]  [4C 00]  [34 00]  ............L.4.<span class="descr">
602                8        4        8       
603            ListBase   vec2s    vec2f    ... etc
604            length     len      length   </span><span class="fade">
605                                   ....
606                                   .... (457 lengths, same as number of types)</span>
607 </code>
608 </p>
609
610 <a name="DNA1-data-array-structures" href="#DNA1-data-array-structures"><h4>The structures array</h4></a>
611 <p>
612 <code class="block"><span class="descr">                                                                 array-id='STRC'
613                                                                         |</span>
614 0005 3E30    <span class="fade">40 00 38 00   60 00   00 00     00 00     00 00</span>    [53 54     52 43]  <span class="fade">@.8.`.......</span>STRC
615 0005 3E40   [8E 01 00 00] [0A 00] [02 00]   [0A 00]   [00 00]   [0A 00]   [01 00]  ................<span class="descr">
616                  398         10      2         10        0         10        0  
617               number of    index    fields    index     index     index     index
618              structures   in <a href="#DNA1-data-array-types">types</a>           in <a href="#DNA1-data-array-types">types</a>  in <a href="#DNA1-data-array-names">names</a>  in <a href="#DNA1-data-array-types">types</a>   in <a href="#DNA1-data-array-names">names</a></span><span class="fade">
619                           '                  '----------------'  '-----------------'                                    '
620                           '                      field 0                field 1    '
621                           '--------------------------------------------------------'
622                                              structure 0
623                                   ....
624                                   .... (398 structures, each one describeing own type, and type/name for each field)</span>
625 </code>
626 </p>
627 </div>
628
629 <p>
630 The DNA structures inside a Blender 2.48 blend-file can be found at <a href="http://www.atmind.nl/blender/blender-sdna.html">http://www.atmind.nl/blender/blender-sdna.html</a>.
631
632 If we understand the DNA part of the file it is now possible to read 
633 information from other parts file-blocks. The next section will tell us 
634 how.
635 </p>
636
637 <a name="reading-scene-information" href="#reading-scene-information"><h2>Reading scene information</h2></a>
638
639 <p>
640 Let us look at <a href="#example-file-block-header">the file-block header we have seen earlier</a>:<br>
641 </p>
642 <ul>
643 <li>the file-block identifier is <code>'SC'+0x00h</code></li>
644 <li>the SDNA index is 150</li>
645 <li>the file-block size is 1404 bytes</li>
646 </ul>
647 <p>
648 Now note that:
649 <ul>
650 <li>the structure at index 150 in the DNA is a structure of type 'Scene' (counting from 0).</li>
651 <li>the associated type ('Scene') in the DNA has the length of 1404 bytes.</li>
652 </ul>
653 </p>
654
655 <p> 
656 We can map the Scene structure on the data of the file-blocks. 
657 But before we can do that, we have to flatten the Scene-structure.
658
659 <code class="block">struct Scene {
660     ID id;              <span class="descr">// 52 bytes long (ID is different a structure)</span>
661     AnimData *adt;      <span class="descr">// 4 bytes long (pointer to an AnimData structure)</span>
662     Object *camera;     <span class="descr">// 4 bytes long (pointer to an Object structure)</span>
663     World *world;       <span class="descr">// 4 bytes long (pointer to an Object structure)</span>
664     ...
665     float cursor[3];    <span class="descr">// 12 bytes long (array of 3 floats)</span>
666     ...
667 };
668 </code>
669
670 The first field in the Scene-structure is of type 'ID' with the name 'id'.
671 Inside the list of DNA structures there is a structure defined for type 'ID' (structure index 17).
672  
673 <code class="block">struct ID {
674     void *next, *prev;
675     struct ID *newid;
676     struct Library *lib;
677     char name[24];
678     short us;
679     short flag;
680     int icon_id;
681     IDProperty *properties;
682 };
683 </code>
684
685 The first field in this structure has type 'void' and name '*next'. <br>
686 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. 
687 The name '*next' describes a pointer.
688 As we see, the first 4 bytes of the data can be mapped to 'id.next'.
689 </p>
690
691 <p>
692 Using this method we'll map a structure to its data. If we want to 
693 read a specific field we know at which offset in the data it is located 
694 and how much space it takes.<br>
695 The next table shows the output of this flattening process for some 
696 parts of the Scene-structure. Not all rows are described in the table as
697  there is a lot of information in a Scene-structure.
698 </p>
699
700 <table>
701 <caption>Flattened SDNA structure 150: Scene</caption>
702 <thead>
703 <tr><th>reference</th>
704     <th>structure</th>
705     <th>type</th><th>name</th>
706     <th>offset</th><th>size</th>
707     <th>description</th></tr>
708 </thead>
709 <tbody>
710 <tr><td>id.next</td><td><a href="#struct:ID">ID</a></td>
711     <td>void</td><td>*next</td>
712     <td>0</td>
713     <td>4</td>
714     <td>Refers to the next scene</td></tr>
715 <tr><td>id.prev</td><td><a href="#struct:ID">ID</a></td>
716     <td>void</td><td>*prev</td>
717     <td>4</td>
718     <td>4</td>
719     <td>Refers to the previous scene</td></tr>
720 <tr><td>id.newid</td><td><a href="#struct:ID">ID</a></td>
721     <td>ID</td><td>*newid</td>
722     <td>8</td>
723     <td>4</td>
724     <td></td></tr>
725 <tr><td>id.lib</td><td><a href="#struct:ID">ID</a></td>
726     <td>Library</td><td>*lib</td>
727     <td>12</td>
728     <td>4</td>
729     <td></td></tr>
730 <tr><td>id.name</td><td><a href="#struct:ID">ID</a></td>
731     <td>char</td><td>name[24]</td>
732     <td>16</td>
733     <td>24</td>
734     <td>'SC'+the name of the scene as displayed in Blender</td></tr>
735 <tr><td>id.us</td><td><a href="#struct:ID">ID</a></td>
736     <td>short</td><td>us</td>
737     <td>40</td>
738     <td>2</td>
739     <td></td></tr>
740 <tr><td>id.flag</td><td><a href="#struct:ID">ID</a></td>
741     <td>short</td><td>flag</td><td>42</td><td>2</td>
742     <td></td></tr>
743 <tr><td>id.icon_id</td><td><a href="#struct:ID">ID</a></td>
744     <td>int</td><td>icon_id</td><td>44</td>
745     <td>4</td>
746     <td></td></tr>
747 <tr><td>id.properties</td><td><a href="#struct:ID">ID</a></td>
748     <td>IDProperty</td><td>*properties</td>
749     <td>48</td>
750     <td>4</td>
751     <td></td></tr>
752 <tr><td>adt</td><td>Scene</td><td>AnimData</td>
753     <td>*adt</td>
754     <td>52</td>
755     <td>4</td>
756     <td></td></tr>
757 <tr><td>camera</td><td>Scene</td>
758     <td>Object</td>
759     <td>*camera</td>
760     <td>56</td>
761     <td>4</td>
762     <td>Pointer to the current camera</td></tr>
763 <tr><td>world</td><td>Scene</td>
764     <td>World</td>
765     <td>*world</td>
766     <td>60</td>
767     <td>4</td>
768     <td>Pointer to the current world</td></tr>
769
770 <tr><td class="skip" colspan="7">Skipped rows</td></tr>
771
772 <tr><td>r.xsch</td><td><a href="#struct:RenderData">RenderData</a>
773     </td><td>short</td><td>xsch</td><td>382</td><td>2</td>
774     <td>X-resolution of the output when rendered at 100%</td></tr>
775 <tr><td>r.ysch</td><td><a href="#struct:RenderData">RenderData</a>
776     </td><td>short</td><td>ysch</td><td>384</td><td>2</td>
777     <td>Y-resolution of the output when rendered at 100%</td></tr>
778 <tr><td>r.xparts</td><td><a href="#struct:RenderData">RenderData</a>
779     </td><td>short</td><td>xparts</td><td>386</td><td>2</td>
780     <td>Number of x-part used by the renderer</td></tr>
781 <tr><td>r.yparts</td><td><a href="#struct:RenderData">RenderData</a>
782     </td><td>short</td><td>yparts</td><td>388</td><td>2</td>
783     <td>Number of x-part used by the renderer</td></tr>
784
785 <tr><td class="skip" colspan="7">Skipped rows</td></tr>
786
787 <tr><td>gpd</td><td>Scene</td><td>bGPdata</td><td>*gpd</td><td>1376</td><td>4</td>
788     <td></td></tr>
789 <tr><td>physics_settings.gravity</td><td><a href="#struct:PhysicsSettings">PhysicsSettings</a>
790     </td><td>float</td><td>gravity[3]</td><td>1380</td><td>12</td>
791     <td></td></tr>
792 <tr><td>physics_settings.flag</td><td><a href="#struct:PhysicsSettings">PhysicsSettings</a>
793     </td><td>int</td><td>flag</td><td>1392</td><td>4</td>
794     <td></td></tr>
795 <tr><td>physics_settings.quick_cache_step</td><td><a href="#struct:PhysicsSettings">PhysicsSettings</a>
796     </td><td>int</td><td>quick_cache_step</td><td>1396</td><td>4</td>
797     <td></td></tr>
798 <tr><td>physics_settings.rt</td><td><a href="#struct:PhysicsSettings">PhysicsSettings</a>
799     </td><td>int</td><td>rt</td><td>1400</td><td>4</td>
800     <td></td></tr>
801 </tbody>
802 </table>
803
804 <p>
805 We can now read the X and Y resolution of the Scene:
806 <ul>
807 <li>the X-resolution is located on offset 382 of the file-block-data and must be read as a 
808 short.</li>
809 <li>the Y-resolution is located on offset 384 and is also a short</li>
810 </ul>
811 </p>
812
813 <div class="box">
814 <p class="box-title">
815 Note
816 </p>
817 <p>
818 An array of chars can mean 2 things. The field contains readable 
819 text or it contains an array of flags (not humanly readable).
820 </p>
821 </div>
822
823 <div class="box">
824 <p class="box-title">
825 Note
826 </p>
827 <p>
828 A file-block containing a list refers to the DNA structure and has a count larger
829 than 1. For example Vertexes and Faces are stored in this way.
830 </p>
831 </div>
832
833 </body>
834 </html>
835