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