Serialization DNA restrictions, size and alignment rules

From Physics Simulation Wiki

Jump to: navigation, search

Detailed information of all serialization structures (type information, member names, size of each type), also known as DNA, is added at the end of each .bullet file. The binary representation of these DNA structure information is stored in the Bullet SDK in the file Bullet/src/LinearMath/btSerializer.cpp. There is sBulletDNAstr64 for 64bit systems and sBulletDNAstr32 for 32bit systems. When loading a file, the in-memory DNA of the current version of Bullet is compared against the DNA structures embedded in the .bullet file. The information and differences between file and memory DNA structure information is used to deal with automatic data conversion (little/big-endian and 32/64bit data), automatic pointer resolving, detect new variables in structures, changed array sizes etc.

Contents

DNA structure memory layout

The DNA structure has the following memory layout: 

SDNA (4 bytes) (magic number)
NAME (4 bytes)
[nr] (4 bytes) amount of names (int)
[string]
[string]
...
...
TYPE (4 bytes)
[nr] amount of types (int)
[string]
[string]
...
...
TLEN (4 bytes)
[len] (short) the lengths of types
[len]
...
...
STRC (4 bytes)
[nr] amount of structs (int)
[typenr][nr_of_elems] [typenr][namenr] [typenr][namenr] ...

Rules for DNA structures

  • Remember to read/write integer and short aligned
  • Only C struct are recognized, no C++ classes

ALLOWED AND TESTED CHANGES IN STRUCTS:

  • Type change (a char to float will be divided by 255).
  • Location within a struct (everthing can be randomly mixed up).
  • Struct within struct (within struct etc), this is recursive.
  • Adding new elements, will be default initialized zero.
  • Removing elements.
  • Change of array sizes.
  • Change of a pointer type: When the name doesn't change the contents is copied.

DONE:

  • Endian compatibility
  • Pointer conversion (32-64 bits)

NOT YET:

  • array (vec[3]) to float struct (vec3f)

IMPORTANT:

  • Do not use #defines in structs for array lengths, this cannot be read by the dna functions.
  • Do not use #if 0 ... #endif to remove elements from structs, this cannot be read by the dna functions.
  • Other preprocessor directives may also be unsupported.
  • Typedefs in struct declarations appear to be unsupported.
  • Do not use uint, but unsigned int instead, ushort and ulong are allowed.
  • Only use a long in Blender if you want this to be the size of a pointer. So it is 32 bits or 64 bits, dependant at the CPU architecture.
  • chars are always unsigned.
  • When storing pointers, always put the * next to the variable and not the type (i.e. void *x, not void* x). If you do, you will get a message that makesdna couldn't find whatever structure you did that in.
  • Aligment of variables has to be done in such a way, that any system does not create 'padding' (gaps) in structures. So make sure that:
    • short: 2 aligned
    • int: 4 aligned
    • float: 4 aligned
    • double: 8 aligned
    • long: 8 aligned
    • struct: 8 aligned

Checking for errors during DNA structure generation

  • The makesdna functions have several error prints builtin, always check the output of BulletDNA. If the construction of DNA structures fails, the Bullet/src/LinearMath/btSerializer.cpp contains an error message.

See also

The .bullet format closely resembles the Blender .blend format. The following information is copied from the Blender wiki. You can read the original information from the Blender wiki here:

Retrieved from "http://www.bulletphysics.org/mediawiki-1.5.8/index.php/Serialization_DNA_restrictions,_size_and_alignment_rules"
Personal tools