Dev:Source/Data Structures/DNAStructs
DNAStructs
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]
) tofloat
struct (vec3f
)
DONE:
- Endian compatibility
- Pointer conversion (32-64 bits)
IMPORTANT:
- Do not use
#define
s 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
, butunsigned int
instead,ushort
andulong
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