Filling in branch from trunk
[blender.git] / extern / ode / dist / ode / README
1 Dynamics Library.
2 =================
3
4 CONVENTIONS
5 -----------
6
7 matrix storage
8 --------------
9
10 matrix operations like factorization are expensive, so we must store the data
11 in a way that is most useful to the matrix code. we want the ability to update
12 the dynamics library without recompiling applications, e.g. so users can take
13 advantage of new floating point hardware. so we must settle on a single
14 format. because of the prevalence of 4-way SIMD, the format is this: store
15 the matrix by rows or columns, and each column is rounded up to a multiple of
16 4 elements. the extra "padding" elements at the end of each row/column are set
17 to 0. this is called the "standard format". to indicate if the data is stored
18 by rows or columns, we will say "standard row format" or "standard column
19 format". hopefully this decision will remain good in the future, as more and
20 more processors have 4-way SIMD, and 3D graphics always needs fast 4x4
21 matrices.
22
23 exception: matrices that have only one column or row (vectors), are always
24 stored as consecutive elements in standard row format, i.e. there is no
25 interior padding, only padding at the end.
26
27 thus: all 3x1 floating point vectors are stored as 4x1 vectors: (x,x,x,0).
28 also: all 6x1 spatial velocities and accelerations are split into 3x1 position
29   and angular components, which are stored as contiguous 4x1 vectors.
30
31 ALL matrices are stored by in standard row format.
32
33
34 arguments
35 ---------
36
37 3x1 vector arguments to set() functions are supplied as x,y,z.
38 3x1 vector result arguments to get() function are pointers to arrays.
39 larger vectors are always supplied and returned as pointers.
40 all coordinates are in the global frame except where otherwise specified.
41 output-only arguments are usually supplied at the end.
42
43
44 memory allocation
45 -----------------
46
47 with many C/C++ libraries memory allocation is a difficult problem to solve.
48 who allocates the memory? who frees it? must objects go on the heap or can
49 they go on the stack or in static storage? to provide the maximum flexibility,
50 the dynamics and collision libraries do not do their own memory allocation.
51 you must pass in pointers to externally allocated chunks of the right sizes.
52 the body, joint and colllision object structures are all exported, so you
53 can make instances of those structure and pass pointers to them.
54
55 there are helper functions which allocate objects out of areans, in case you
56 need loots of dynamic creation and deletion.
57
58 BUT!!! this ties us down to the body/joint/collision representation.
59
60 a better approach is to supply custom memory allocation functions
61 (e.g. dlAlloc() etc).
62
63
64 C versus C++ ... ?
65 ------------------
66
67 everything should be C linkable, and there should be C header files for
68 everything. but we want to develop in C++. so do this:
69   * all comments are "//". automatically convert to /**/ for distribution.
70   * structures derived from other structures --> automatically convert?
71
72
73 WORLDS
74 ------
75
76 might want better terminology here.
77
78 the dynamics world (DWorld) is a list of systems. each system corresponds to
79 one or more bodies, or perhaps some other kinds of physical object.
80 each system corresponds to one or more objects in the collision world
81 (there does not have to be a one-to-one correspondence between bodies and
82 collision objects).
83
84 systems are simulated separately, perhaps using completely different
85 techniques. we must do something special when systems collide.
86 systems collide when collision objects belonging to system A touch
87 collision objects belonging to system B.
88
89 for each collision point, the system must provide matrix equation data
90 that is used to compute collision forces. once those forces are computed,
91 the system must incorporate the forces into its timestep.
92 PROBLEM: what if we intertwine the LCP problems of the two systems - then
93 this simple approach wont work.
94
95 the dynamics world contains two kinds of objects: bodies and joints.
96 joints connect two bodies together.
97
98 the world contains one of more partitions. each partition is a collection of
99 bodies and joints such that each body is attached (through one or more joints)
100 to every other body.
101
102 Joints
103 ------
104
105 a joint can be connected to one or two bodies.
106 if the joint is only connected to one body, joint.node[1].body == 0.
107 joint.node[0].body is always valid.
108
109
110 Linkage
111 -------
112
113 this library will always be statically linked with the app, for these reasons:
114   * collision space is selected at compile time, it adds data to the geom
115     objects.
116
117
118 Optimization
119 ------------
120
121 doubles must be aligned on 8 byte boundaries!
122
123
124 MinGW on Windows issues
125 -----------------------
126
127 * the .rc file for drawstuff needs a different include, try winresrc.h.
128
129 * it seems we can't have both main() and WinMain() without the entry point
130   defaulting to main() and having resource loading problems. this screws up
131   what i was trying to do in the drawstuff library. perhaps main2() ?
132
133 * remember to compile resources to COFF format RES files.
134
135
136
137 Collision
138 ---------
139
140 to plug in your own collision handling, replace (some of?) these functions
141 with your own. collision should be a separate library that you can link in
142 or not. your own library can call components in this collision library, e.g.
143 if you want polymorphic spaces instead of a single statically called space.
144
145 creating an object will automatically register the appropriate
146 class (if necessary). how can we ensure that the minimum amount of code is
147 linked in? e.g. only one space handler, and sphere-sphere and sphere-box and
148 box-box collision code (if spheres and boxes instanced).
149
150 the user creates a collision space, and for each dynamics object that is
151 created a collision object is inserted into the space. the collision
152 object's pos and R pointers are set to the corresponding dynamics
153 variables.
154
155 there should be utility functions which create the dynamics and collision
156 objects at the same time, e.g. dMakeSphere().
157
158 collision objects and dynamics objects keep pointers to each other.