2.5
[blender-staging.git] / intern / elbeem / extern / elbeem.h
1 /******************************************************************************
2  *
3  * El'Beem - Free Surface Fluid Simulation with the Lattice Boltzmann Method
4  * All code distributed as part of El'Beem is covered by the version 2 of the 
5  * GNU General Public License. See the file COPYING for details.
6  * Copyright 2003-2006 Nils Thuerey
7  *
8  * API header
9  */
10 #ifndef ELBEEM_API_H
11 #define ELBEEM_API_H
12
13
14 // simulation run callback function type (elbeemSimulationSettings->runsimCallback)
15 // best use with FLUIDSIM_CBxxx defines below.
16 // >parameters
17 // return values: 0=continue, 1=stop, 2=abort
18 // data pointer: user data pointer from elbeemSimulationSettings->runsimUserData
19 // status integer: 1=running simulation, 2=new frame saved
20 // frame integer: if status is 1, contains current frame number
21 typedef int (*elbeemRunSimulationCallback)(void *data, int status, int frame);
22 #define FLUIDSIM_CBRET_CONTINUE    0
23 #define FLUIDSIM_CBRET_STOP        1
24 #define FLUIDSIM_CBRET_ABORT       2 
25 #define FLUIDSIM_CBSTATUS_STEP     1 
26 #define FLUIDSIM_CBSTATUS_NEWFRAME 2 
27
28
29 // global settings for the simulation
30 typedef struct elbeemSimulationSettings {
31   /* version number */
32   short version;
33         /* id number of simulation domain, needed if more than a
34          * single domain should be simulated */
35         short domainId; // unused within blender
36
37         /* geometrical extent */
38         float geoStart[3], geoSize[3];
39
40   /* resolutions */
41   short resolutionxyz;
42   short previewresxyz;
43   /* size of the domain in real units (meters along largest resolution x,y,z extent) */
44   float realsize;
45
46   /* fluid properties */
47   double viscosity;
48   /* gravity strength */
49   float gravity[3];
50   /* anim start end time */
51   float animStart, aniFrameTime;
52         /* no. of frames to simulate & output */
53         short noOfFrames;
54   /* g star param (LBM compressibility) */
55   float gstar;
56   /* activate refinement? */
57   short maxRefine;
58   /* probability for surface particle generation (0.0=off) */
59   float generateParticles;
60   /* amount of tracer particles to generate (0=off) */
61   int numTracerParticles;
62
63   /* store output path, and file prefix for baked fluid surface */
64   char outputPath[160+80];
65
66         /* channel for frame time, visc & gravity animations */
67         int channelSizeFrameTime;
68         float *channelFrameTime;
69         int channelSizeViscosity;
70         float *channelViscosity;
71         int channelSizeGravity;
72         float *channelGravity;  // vector
73
74         /* boundary types and settings for domain walls */
75         short domainobsType;
76         float domainobsPartslip;
77         /* generate speed vectors for vertices (e.g. for image based motion blur)*/
78         short generateVertexVectors;
79         /* strength of surface smoothing */
80         float surfaceSmoothing;
81         /* no. of surface subdivisions */
82         int   surfaceSubdivs;
83
84         /* global transformation to apply to fluidsim mesh */
85         float surfaceTrafo[4*4];
86
87         /* development variables, testing for upcoming releases...*/
88         float farFieldSize;
89
90         /* callback function to notify calling program of performed simulation steps
91          * or newly available frame data, if NULL it is ignored */
92         elbeemRunSimulationCallback runsimCallback;
93         /* pointer passed to runsimCallback for user data storage */
94         void* runsimUserData;
95
96 } elbeemSimulationSettings;
97
98
99 // defines for elbeemMesh->type below
100 /* please keep in sync with DNA_object_fluidsim.h */
101 #define OB_FLUIDSIM_FLUID       4
102 #define OB_FLUIDSIM_OBSTACLE    8
103 #define OB_FLUIDSIM_INFLOW      16
104 #define OB_FLUIDSIM_OUTFLOW     32
105 #define OB_FLUIDSIM_PARTICLE    64
106 #define OB_FLUIDSIM_CONTROL     128
107
108 // defines for elbeemMesh->obstacleType below
109 #define FLUIDSIM_OBSTACLE_NOSLIP     1
110 #define FLUIDSIM_OBSTACLE_PARTSLIP   2
111 #define FLUIDSIM_OBSTACLE_FREESLIP   3
112
113 #define OB_VOLUMEINIT_VOLUME 1
114 #define OB_VOLUMEINIT_SHELL  2
115 #define OB_VOLUMEINIT_BOTH   (OB_VOLUMEINIT_SHELL|OB_VOLUMEINIT_VOLUME)
116
117 // a single mesh object
118 typedef struct elbeemMesh {
119   /* obstacle,fluid or inflow or control ... */
120   short type;
121         /* id of simulation domain it belongs to */
122         short parentDomainId;
123
124         /* vertices */
125   int numVertices;
126         float *vertices; // = float[n][3];
127         /* animated vertices */
128   int channelSizeVertices;
129         float *channelVertices; // = float[channelSizeVertices* (n*3+1) ];
130
131         /* triangles */
132         int   numTriangles;
133   int   *triangles; // = int[][3];
134
135         /* animation channels */
136         int channelSizeTranslation;
137         float *channelTranslation;
138         int channelSizeRotation;
139         float *channelRotation;
140         int channelSizeScale;
141         float *channelScale;
142         
143         /* active channel */
144         int channelSizeActive;
145         float *channelActive;
146         /* initial velocity channel (e.g. for inflow) */
147         int channelSizeInitialVel;
148         float *channelInitialVel; // vector
149         /* use initial velocity in object coordinates? (e.g. for rotation) */
150         short localInivelCoords;
151         /* boundary types and settings */
152         short obstacleType;
153         float obstaclePartslip;
154         /* amount of force transfer from fluid to obj, 0=off, 1=normal */
155         float obstacleImpactFactor;
156         /* init volume, shell or both? use OB_VOLUMEINIT_xxx defines above */
157         short volumeInitType;
158
159         /* name of the mesh, mostly for debugging */
160         const char *name;
161         
162         /* fluid control settings */
163         float cpsTimeStart;
164         float cpsTimeEnd;
165         float cpsQuality;
166         
167         int channelSizeAttractforceStrength;
168         float *channelAttractforceStrength;
169         int channelSizeAttractforceRadius;
170         float *channelAttractforceRadius;
171         int channelSizeVelocityforceStrength;
172         float *channelVelocityforceStrength;
173         int channelSizeVelocityforceRadius;
174         float *channelVelocityforceRadius;
175 } elbeemMesh;
176
177 // API functions
178
179 #ifdef __cplusplus
180 extern "C"  {
181 #endif // __cplusplus
182  
183
184 // reset elbeemSimulationSettings struct with defaults
185 void elbeemResetSettings(struct elbeemSimulationSettings*);
186  
187 // start fluidsim init (returns !=0 upon failure)
188 int elbeemInit(void);
189
190 // frees fluidsim
191 int elbeemFree(void);
192
193 // start fluidsim init (returns !=0 upon failure)
194 int elbeemAddDomain(struct elbeemSimulationSettings*);
195
196 // get failure message during simulation or init
197 // if an error occured (the string is copied into buffer,
198 // max. length = 256 chars )
199 void elbeemGetErrorString(char *buffer);
200
201 // reset elbeemMesh struct with zeroes
202 void elbeemResetMesh(struct elbeemMesh*);
203
204 // add mesh as fluidsim object
205 int elbeemAddMesh(struct elbeemMesh*);
206
207 // do the actual simulation
208 int elbeemSimulate(void);
209
210 // continue a previously stopped simulation
211 int elbeemContinueSimulation(void);
212
213
214 // helper functions 
215
216 // simplify animation channels
217 // returns if the channel and its size changed
218 int elbeemSimplifyChannelFloat(float *channel, int *size);
219 int elbeemSimplifyChannelVec3(float *channel, int *size);
220
221 // helper functions implemented in utilities.cpp
222
223 /* set elbeem debug output level (0=off to 10=full on) */
224 void elbeemSetDebugLevel(int level);
225 /* elbeem debug output function, prints if debug level >0 */
226 void elbeemDebugOut(char *msg);
227
228 /* estimate how much memory a given setup will require */
229 double elbeemEstimateMemreq(int res,
230     float sx, float sy, float sz,
231     int refine, char *retstr);
232
233
234
235 #ifdef __cplusplus
236 }
237 #endif // __cplusplus
238
239
240
241 /******************************************************************************/
242 // internal defines, do not use for initializing elbeemMesh
243 // structs, for these use OB_xxx defines above
244
245 /*! fluid geometry init types */
246 // type "int" used, so max is 8
247 #define FGI_FLAGSTART   16
248 #define FGI_FLUID                         (1<<(FGI_FLAGSTART+ 0))
249 #define FGI_NO_FLUID      (1<<(FGI_FLAGSTART+ 1))
250 #define FGI_BNDNO                         (1<<(FGI_FLAGSTART+ 2))
251 #define FGI_BNDFREE               (1<<(FGI_FLAGSTART+ 3))
252 #define FGI_BNDPART               (1<<(FGI_FLAGSTART+ 4))
253 #define FGI_NO_BND                (1<<(FGI_FLAGSTART+ 5))
254 #define FGI_MBNDINFLOW  (1<<(FGI_FLAGSTART+ 6))
255 #define FGI_MBNDOUTFLOW (1<<(FGI_FLAGSTART+ 7))
256 #define FGI_CONTROL     (1<<(FGI_FLAGSTART+ 8))
257
258 // all boundary types at once
259 #define FGI_ALLBOUNDS ( FGI_BNDNO | FGI_BNDFREE | FGI_BNDPART | FGI_MBNDINFLOW | FGI_MBNDOUTFLOW )
260
261
262 #endif // ELBEEM_API_H