Needs to be merged with Dev:Source/Architecture/SDNA_Notes
The following excerpt functions as basis for DNA Struct documentation.
source/blender/blenloader/intern/genfile.c in pre-blender2.5)
- please note: no builtin security to detect input of double structs
- if you want a struct not to be in DNA file: add two hash marks above it (#[enter]#[enter]) FIXME
Structure DNA data is added to each blender file and to each executable, this to detect
.blend files new variables in structs, changed array sizes, etc. It's also used for
converting endian and pointer size (32-64 bits)
As an extra, Python uses a call to detect run-time the contents of a blender struct.
Create a structDNA: only needed when one of the input include (
.h) files change.
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] ...
Remember to read/write integer and short aligned
While writing a file, the names of a struct is indicated with a type number, to be found with:
type= findstruct_nr(SDNA , char )
The value of
type corresponds with the the index within the structs array.
For the moment: the complete DNA file is included in a
.blend file. For the future we can think of smarter methods, like only included the used structs. Only needed to keep a file short though...
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.
- array (
- Endian compatibility
- Pointer conversion (32-64 bits)
- Do not use
#defines in structs for array lengths, this cannot be read by the dna functions.
- Do not use
#if 0 ... #endifto 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
- Only use a
longin 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.
charsare 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
sdnafunctions have several error prints builtin, always check Blender running from a console.
-- NathanLetwory - 21 May 2004