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