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