more warning cleanup:
[blender.git] / source / blender / blenlib / BLI_blenlib.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN GPL/BL DUAL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version. The Blender
10  * Foundation also sells licenses for use in proprietary software under
11  * the Blender License.  See http://www.blender.org/BL/ for information
12  * about this.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software Foundation,
21  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
22  *
23  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
24  * All rights reserved.
25  *
26  * The Original Code is: all of this file.
27  *
28  * Contributor(s): none yet.
29  *
30  * ***** END GPL/BL DUAL LICENSE BLOCK *****
31  *
32  * @mainpage BLI - Blender LIbrary external interface
33  *
34  * @section about About the BLI module
35  *
36  * This is the external interface of the Blender Library. If you find
37  * a call to a BLI function that is not prototyped here, please add a
38  * prototype here. The library offers mathematical operations (mainly
39  * vector and matrix calculus), an abstraction layer for file i/o,
40  * functions for calculating Perlin noise, scanfilling services for
41  * triangles, and a system for guarded memory
42  * allocation/deallocation. There is also a patch to make MS Windows
43  * behave more or less Posix-compliant.
44  *
45  * @section issues Known issues with BLI
46  *
47  * - blenlib is written in C.
48  * - The posix-compliancy may move to a separate lib that deals with 
49  *   platform dependencies. (There are other platform-dependent 
50  *   fixes as well.)
51  * - The file i/o has some redundant code. It should be cleaned.
52  * - arithb.c is a very messy matrix library. We need a better 
53  *   solution.
54  * - vectorops.c is close to superfluous. It may disappear in the 
55  *   near future.
56  * 
57  * @section dependencies Dependencies
58  *
59  * - The blenlib uses type defines from makesdna/, and functions from
60  * standard libraries.
61  * 
62  * $Id$ 
63 */
64
65 #ifndef BLI_BLENLIB_H
66 #define BLI_BLENLIB_H
67
68 /* braindamage for the masses... needed
69         because fillfacebase and fillvertbase are used outside */
70 #include "DNA_listBase.h" 
71
72 #include <stdlib.h>
73
74 extern ListBase fillfacebase;
75 extern ListBase fillvertbase;
76 /**
77  * @attention Defined in scanfill.c
78  */
79 extern ListBase filledgebase;
80 extern int totblock;
81
82 struct chardesc;
83 struct direntry;
84 struct rctf;
85 struct rcti;
86 struct EditVert;
87 struct PackedFile;
88 struct LinkNode;
89 struct DynamicList;
90
91 #ifdef __cplusplus
92 extern "C" {
93 #endif
94
95 /* BLI_util.h */
96 char *BLI_gethome(void);
97 void BLI_make_file_string(const char *relabase, char *string,  const char *dir, const char *file);
98 void BLI_make_exist(char *dir);
99 void BLI_make_existing_file(char *name);
100 void BLI_split_dirfile(const char *string, char *dir, char *file);
101 void BLI_join_dirfile(char *string, const char *dir, const char *file);
102 int BLI_testextensie(const char *str, const char *ext);
103 void addlisttolist(ListBase *list1, ListBase *list2);
104 void BLI_insertlink(struct ListBase *listbase, void *vprevlink, void *vnewlink);
105 void * BLI_findlink(struct ListBase *listbase, int number);
106 void BLI_freelistN(struct ListBase *listbase);
107 void BLI_addtail(struct ListBase *listbase, void *vlink);
108 void BLI_remlink(struct ListBase *listbase, void *vlink);
109 void BLI_newname(char * name, int add);
110 int BLI_stringdec(char *string, char *kop, char *staart, unsigned short *numlen);
111 void BLI_stringenc(char *string, char *kop, char *staart, unsigned short numlen, int pic);
112 void BLI_addhead(struct ListBase *listbase, void *vlink);
113 void BLI_insertlinkbefore(struct ListBase *listbase, void *vnextlink, void *vnewlink);
114 void BLI_freelist(struct ListBase *listbase);
115 int BLI_countlist(struct ListBase *listbase);
116 void BLI_freelinkN(ListBase *listbase, void *vlink);
117 void BLI_splitdirstring(char *di,char *fi);
118
119 struct DynamicList *BLI_dlist_from_listbase(struct ListBase *lb);
120 struct ListBase *BLI_listbase_from_dlist(struct DynamicList *dlist, struct ListBase *lb);
121 void * BLI_dlist_find_link(struct DynamicList *dlist, unsigned int index);
122 unsigned int BLI_count_items(struct DynamicList *dlist);
123 void BLI_dlist_free_item(struct DynamicList *dlist, unsigned int index);
124 void BLI_dlist_rem_item(struct DynamicList *dlist, unsigned int index);
125 void * BLI_dlist_add_item_index(struct DynamicList *dlist, void *item, unsigned int index);
126 void BLI_dlist_destroy(struct DynamicList *dlist);
127 void BLI_dlist_init(struct DynamicList *dlist);
128 void BLI_dlist_reinit(struct DynamicList *dlist);
129
130         /**
131          * dir can be any input, like from buttons, and this function
132          * converts it to a regular full path.
133          * Also removes garbage from directory paths, like /../ or double slashes etc 
134          */
135 void BLI_cleanup_dir(const char *relabase, char *dir);
136
137         /**
138          * Blender's path code replacement function.
139          * Bases @a path strings leading with "//" by the
140          * directory @a basepath, and replaces instances of
141          * '#' with the @a framenum. Results are written
142          * back into @a path.
143          * 
144          * @a path The path to convert
145          * @a basepath The directory to base relative paths with.
146          * @a framenum The framenumber to replace the frame code with.
147          * @retval Returns true if the path was relative (started with "//").
148          */
149 int BLI_convertstringcode(char *path, const char *basepath, int framenum);
150
151 void BLI_makestringcode(const char *relfile, char *file);
152
153         /**
154          * Change every @a from in @a string into @a to. The
155          * result will be in @a string
156          *
157          * @a string The string to work on
158          * @a from The character to replace
159          * @a to The character to replace with
160          */
161 void BLI_char_switch(char *string, char from, char to);
162
163         /**
164          * Makes sure @a path has platform-specific slashes.
165          * 
166          * @a path The path to 'clean'
167          */
168 void BLI_clean(char *path);
169         /**
170          * Duplicates the cstring @a str into a newly mallocN'd
171          * string and returns it.
172          * 
173          * @param str The string to be duplicated
174          * @retval Returns the duplicated string
175          */
176 char* BLI_strdup(const char *str);
177
178         /**
179          * Duplicates the first @a len bytes of cstring @a str 
180          * into a newly mallocN'd string and returns it. @a str
181          * is assumed to be at least len bytes long.
182          * 
183          * @param str The string to be duplicated
184          * @param len The number of bytes to duplicate
185          * @retval Returns the duplicated string
186          */
187 char* BLI_strdupn(const char *str, int len);
188
189         /**
190          * Like strncpy but ensures dst is always
191          * '\0' terminated.
192          * 
193          * @param dst Destination for copy
194          * @param src Source string to copy
195          * @param maxncpy Maximum number of characters to copy (generally
196          *   the size of dst)
197          * @retval Returns dst
198          */
199 char* BLI_strncpy(char *dst, const char *src, int maxncpy);
200
201         /* 
202          * Replacement for snprintf
203          */
204 int BLI_snprintf(char *buffer, size_t count, const char *format, ...);
205
206         /**
207          * Compare two strings
208          * 
209          * @retval True if the strings are equal, false otherwise.
210          */
211 int BLI_streq(char *a, char *b);
212
213         /**
214          * Compare two strings without regard to case.
215          * 
216          * @retval True if the strings are equal, false otherwise.
217          */
218 int BLI_strcaseeq(char *a, char *b);
219
220 /* in util.c */
221 #ifdef WITH_ICONV
222 void BLI_string_to_utf8(char *original, char *utf_8, char *code);
223 #endif
224
225         /**
226          * Read a file as ASCII lines. An empty list is
227          * returned if the file cannot be opened or read.
228          * 
229          * @attention The returned list should be free'd with
230          * BLI_free_file_lines.
231          * 
232          * @param name The name of the file to read.
233          * @retval A list of strings representing the file lines.
234          */
235 struct LinkNode *BLI_read_file_as_lines(char *name);
236
237         /**
238          * Free the list returned by BLI_read_file_as_lines.
239          */
240 void BLI_free_file_lines(struct LinkNode *lines);
241
242         /**
243          * Checks if name is a fully qualified filename to an executable.
244          * If not it searches $PATH for the file. On Windows it also
245          * adds the correct extension (.com .exe etc) from
246          * $PATHEXT if necessary. Also on Windows it translates
247          * the name to its 8.3 version to prevent problems with
248          * spaces and stuff. Final result is returned in fullname.
249          *
250          * @param fullname The full path and full name of the executable
251          * @param name The name of the executable (usually argv[0]) to be checked
252          */
253 void BLI_where_am_i(char *fullname, char *name);
254
255         /**
256          * determines the full path to the application bundle on OS X
257          *
258          * @return path to application bundle
259          */
260 #ifdef __APPLE__
261 char* BLI_getbundle(void);
262 #endif
263
264 #ifdef WIN32
265 int BLI_getInstallationDir( char * str );
266 #endif
267                 
268 /* BLI_storage.h */
269 int    BLI_filesize(int file);
270 double BLI_diskfree(char *dir);
271 char * BLI_getwdN(char * dir);
272 void BLI_hide_dot_files(int set);
273 unsigned int BLI_getdir(char *dirname,  struct direntry **filelist);
274
275 /**
276  * @attention Do not confuse with BLI_exists
277  */
278 int    BLI_exist(char *name);
279
280 /* BLI_fileops.h */
281 void  BLI_recurdir_fileops(char *dirname);
282 int BLI_link(char *file, char *to);
283 int BLI_backup(char *file, char *from, char *to);
284 int BLI_is_writable(char *filename);
285
286 /**
287  * @attention Do not confuse with BLI_exist
288  */
289 int   BLI_exists(char *file);
290 int   BLI_copy_fileops(char *file, char *to);
291 int   BLI_rename(char *from, char *to);
292 int   BLI_gzip(char *from, char *to);
293 int   BLI_delete(char *file, int dir, int recursive);
294 int   BLI_move(char *file, char *to);
295 int   BLI_touch(char *file);
296 char *BLI_last_slash(char *string);
297
298 /* BLI_rct.c */
299 /**
300  * Determine if a rect is empty. An empty
301  * rect is one with a zero (or negative)
302  * width or height.
303  *
304  * @return True if @a rect is empty.
305  */
306 int  BLI_rcti_is_empty(struct rcti * rect);
307 void BLI_init_rctf(struct rctf *rect, float xmin, float xmax, float ymin, float ymax);
308 void BLI_init_rcti(struct rcti *rect, int xmin, int xmax, int ymin, int ymax);
309 void BLI_translate_rctf(struct rctf *rect, float x, float y);
310 void BLI_translate_rcti(struct rcti *rect, int x, int y);
311 int  BLI_in_rcti(struct rcti * rect, int x, int y);
312 int  BLI_in_rctf(struct rctf *rect, float x, float y);
313 int  BLI_isect_rctf(struct rctf *src1, struct rctf *src2, struct rctf *dest);
314 int  BLI_isect_rcti(struct rcti *src1, struct rcti *src2, struct rcti *dest);
315 void BLI_union_rctf(struct rctf *rcta, struct rctf *rctb);
316
317 /* scanfill.c: used in displist only... */
318 struct EditVert *BLI_addfillvert(float *vec);
319 struct EditEdge *BLI_addfilledge(struct EditVert *v1, struct EditVert *v2);
320 int BLI_edgefill(int mode, int mat_nr);
321 void BLI_end_edgefill(void);
322
323 /* noise.h: */
324 float BLI_hnoise(float noisesize, float x, float y, float z);
325 float BLI_hnoisep(float noisesize, float x, float y, float z);
326 float BLI_turbulence(float noisesize, float x, float y, float z, int nr);
327 float BLI_turbulence1(float noisesize, float x, float y, float z, int nr);
328 /* newnoise: generic noise & turbulence functions to replace the above BLI_hnoise/p & BLI_turbulence/1.
329  * This is done so different noise basis functions can be used */
330 float BLI_gNoise(float noisesize, float x, float y, float z, int hard, int noisebasis);
331 float BLI_gTurbulence(float noisesize, float x, float y, float z, int oct, int hard, int noisebasis);
332 /* newnoise: musgrave functions */
333 float mg_fBm(float x, float y, float z, float H, float lacunarity, float octaves, int noisebasis);
334 float mg_MultiFractal(float x, float y, float z, float H, float lacunarity, float octaves, int noisebasis);
335 float mg_VLNoise(float x, float y, float z, float distortion, int nbas1, int nbas2);
336 float mg_HeteroTerrain(float x, float y, float z, float H, float lacunarity, float octaves, float offset, int noisebasis);
337 float mg_HybridMultiFractal(float x, float y, float z, float H, float lacunarity, float octaves, float offset, float gain, int noisebasis);
338 float mg_RidgedMultiFractal(float x, float y, float z, float H, float lacunarity, float octaves, float offset, float gain, int noisebasis);
339 /* newnoise: voronoi */
340 void voronoi(float x, float y, float z, float* da, float* pa, float me, int dtype);
341 /* newnoise: cellNoise & cellNoiseV (for vector/point/color) */
342 float cellNoise(float x, float y, float z);
343 void cellNoiseV(float x, float y, float z, float *ca);
344
345 /* These callbacks are needed to make the lib finction properly */
346
347 /**
348  * Set a function taking a char* as argument to flag errors. If the
349  * callback is not set, the error is discarded.
350  * @param f The function to use as callback
351  * @attention used in creator.c
352  */
353 void BLI_setErrorCallBack(void (*f)(char*));
354
355 /**
356  * Set a function to be able to interrupt the execution of processing
357  * in this module. If the function returns true, the execution will
358  * terminate gracefully. If the callback is not set, interruption is
359  * not possible.
360  * @param f The function to use as callback
361  * @attention used in creator.c
362  */
363 void BLI_setInterruptCallBack(int (*f)(void));
364
365 char *BLI_strcasestr(const char *s, const char *find);
366 int BLI_strcasecmp(const char *s1, const char *s2);
367 int BLI_strncasecmp(const char *s1, const char *s2, int n);
368 void BLI_timestr(double time, char *str);
369
370 /** 
371   * Trick to address 32 GB with an int (only for malloced pointers)
372   */
373 int BLI_int_from_pointer(void *poin);
374 void *BLI_pointer_from_int(int val);
375
376
377 #define PRNTSUB(type,arg)                       printf(#arg ": %" #type " ", arg)
378
379 #ifndef PRINT
380 #define PRINT(t,v)                                      {PRNTSUB(t,v); printf("\n");}
381 #define PRINT2(t1,v1,t2,v2)                     {PRNTSUB(t1,v1); PRNTSUB(t2,v2); printf("\n");}
382 #define PRINT3(t1,v1,t2,v2,t3,v3)       {PRNTSUB(t1,v1); PRNTSUB(t2,v2); PRNTSUB(t3,v3); printf("\n");}
383 #define PRINT4(t1,v1,t2,v2,t3,v3,t4,v4) {PRNTSUB(t1,v1); PRNTSUB(t2,v2); PRNTSUB(t3,v3); PRNTSUB(t4,v4); printf("\n");}
384 #endif
385
386 /**
387  * @param array The array in question
388  * @retval The number of elements in the array.
389  */
390 #define BLI_ARRAY_NELEMS(array)         (sizeof((array))/sizeof((array)[0]))
391
392 /**
393  * @param strct The structure of interest
394  * @param member The name of a member field of @a strct
395  * @retval The offset in bytes of @a member within @a strct
396  */
397 #define BLI_STRUCT_OFFSET(strct, member)        ((int) &((strct*) 0)->member)
398
399 #ifdef __cplusplus
400 }
401 #endif
402
403 #endif