Dev:Source/Data Structures/DNAStructs

DNAStructs

This page has been marked for development documentation changes.
Feel free to comment on the talk page.

WIP REASON: Needs to be merged with Dev:Source/Architecture/SDNA_Notes

The following excerpt functions as basis for DNA Struct documentation.

from source/blender/makesdna/intern/dna_genfile.c:

(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 in .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.
File Syntax:

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.

NOT YET:

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

DONE:

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

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
• The sdna functions have several error prints builtin, always check Blender running from a console.

-- NathanLetwory - 21 May 2004