Did all of the .h's in source
[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 #ifdef HAVE_CONFIG_H
69 #include <config.h>
70 #endif
71
72 #include "DNA_listBase.h" /* braindamage for the masses... needed
73                              because fillvlakbase and fillvertbase are
74                              used outside */
75
76 extern ListBase fillvlakbase;
77 extern ListBase fillvertbase;
78 /**
79  * @attention Defined in scanfill.c
80  */
81 extern ListBase filledgebase;
82 extern int totblock;
83
84 struct chardesc;
85 struct direntry;
86 struct rctf;
87 struct rcti;
88 struct EditVert;
89 struct PackedFile;
90 struct LinkNode;
91
92 #ifdef __cplusplus
93 extern "C" {
94 #endif
95
96 /* BLI_util.h */
97 char *BLI_gethome(void);
98 void BLI_make_file_string(char *relabase, char *string,  char *dir,  char *file);
99 void BLI_make_exist(char *dir);
100 void BLI_split_dirfile(char *string, char *dir, char *file);
101 int BLI_testextensie(char *str, char *ext);
102 void addlisttolist(ListBase *list1, ListBase *list2);
103 void BLI_insertlink(struct ListBase *listbase, void *vprevlink, void *vnewlink);
104 void * BLI_findlink(struct ListBase *listbase, int number);
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_newname(char * name, int add);
109 int BLI_stringdec(char *string, char *kop, char *staart, unsigned short *numlen);
110 void BLI_stringenc(char *string, char *kop, char *staart, unsigned short numlen, int pic);
111 void BLI_addhead(struct ListBase *listbase, void *vlink);
112 void BLI_insertlinkbefore(struct ListBase *listbase, void *vnextlink, void *vnewlink);
113 void BLI_freelist(struct ListBase *listbase);
114 int BLI_countlist(struct ListBase *listbase);
115 void BLI_freelinkN(ListBase *listbase, void *vlink);
116 void BLI_splitdirstring(char *di,char *fi);
117
118         /**
119          * Blender's path code replacement function.
120          * Bases @a path strings leading with "//" by the
121          * directory @a basepath, and replaces instances of
122          * '#' with the @a framenum. Results are written
123          * back into @a path.
124          * 
125          * @a path The path to convert
126          * @a basepath The directory to base relative paths with.
127          * @a framenum The framenumber to replace the frame code with.
128          * @retval Returns true if the path was relative (started with "//").
129          */
130 int BLI_convertstringcode(char *path, char *basepath, int framenum);
131
132 void BLI_makestringcode(char *fromfile, char *str);
133
134         /**
135          * Duplicates the cstring @a str into a newly mallocN'd
136          * string and returns it.
137          * 
138          * @param str The string to be duplicated
139          * @retval Returns the duplicated string
140          */
141 char* BLI_strdup(char *str);
142
143         /**
144          * Duplicates the first @a len bytes of cstring @a str 
145          * into a newly mallocN'd string and returns it. @a str
146          * is assumed to be at least len bytes long.
147          * 
148          * @param str The string to be duplicated
149          * @param len The number of bytes to duplicate
150          * @retval Returns the duplicated string
151          */
152 char* BLI_strdupn(char *str, int len);
153
154         /**
155          * Like strncpy but ensures dst is always
156          * '\0' terminated.
157          * 
158          * @param dst Destination for copy
159          * @param src Source string to copy
160          * @param maxncpy Maximum number of characters to copy (generally
161          *   the size of dst)
162          * @retval Returns dst
163          */
164 char* BLI_strncpy(char *dst, char *src, int maxncpy);
165
166         /**
167          * Compare two strings
168          * 
169          * @retval True if the strings are equal, false otherwise.
170          */
171 int BLI_streq(char *a, char *b);
172
173         /**
174          * Compare two strings without regard to case.
175          * 
176          * @retval True if the strings are equal, false otherwise.
177          */
178 int BLI_strcaseeq(char *a, char *b);
179
180         /**
181          * Read a file as ASCII lines. An empty list is
182          * returned if the file cannot be opened or read.
183          * 
184          * @attention The returned list should be free'd with
185          * BLI_free_file_lines.
186          * 
187          * @param name The name of the file to read.
188          * @retval A list of strings representing the file lines.
189          */
190 struct LinkNode *BLI_read_file_as_lines(char *name);
191
192         /**
193          * Free the list returned by BLI_read_file_as_lines.
194          */
195 void BLI_free_file_lines(struct LinkNode *lines);
196
197         /**
198          * Checks if name is a fully qualified filename to an executable.
199          * If not it searches $PATH for the file. On Windows it also
200          * adds the correct extension (.com .exe etc) from
201          * $PATHEXT if necessary. Also on Windows it translates
202          * the name to its 8.3 version to prevent problems with
203          * spaces and stuff. Final result is returned in fullname.
204          *
205          * @param fullname The full path and full name of the executable
206          * @param name The name of the executable (usually argv[0]) to be checked
207          */
208 void BLI_where_am_i(char *fullname, char *name);
209
210 /* BLI_storage.h */
211 int    BLI_filesize(int file);
212 double BLI_diskfree(char *dir);
213 char * BLI_getwdN(char * dir);
214 void BLI_hide_dot_files(int set);
215 unsigned int BLI_getdir(char *dirname,  struct direntry **filelist);
216
217 /**
218  * @attention Do not confuse with BLI_exists
219  */
220 int    BLI_exist(char *name);
221
222 /* BLI_fileops.h */
223 void  BLI_recurdir_fileops(char *dirname);
224 int BLI_link(char *file, char *to);
225 int BLI_backup(char *file, char *from, char *to);
226
227
228 /**
229  * @attention Do not confuse with BLI_exist
230  */
231 int   BLI_exists(char *file);
232 int   BLI_copy_fileops(char *file, char *to);
233 int   BLI_rename(char *from, char *to);
234 int   BLI_delete(char *file, int dir, int recursive);
235 int   BLI_move(char *file, char *to);
236 int   BLI_touch(char *file);
237 char *BLI_last_slash(char *string);
238
239 /* BLI_rct.c */
240 /**
241  * Determine if a rect is empty. An empty
242  * rect is one with a zero (or negative)
243  * width or height.
244  *
245  * @return True if @a rect is empty.
246  */
247 int BLI_rcti_is_empty(struct rcti * rect);
248 void BLI_init_rctf(struct rctf *rect, float xmin, float xmax, float ymin, float ymax);
249 int  BLI_in_rcti(struct rcti * rect, int x, int y);
250 int  BLI_in_rctf(struct rctf *rect, float x, float y);
251 int  BLI_isect_rctf(struct rctf *src1, struct rctf *src2, struct rctf *dest);
252 /* why oh why doesn't this work? */
253 //void BLI_union_rctf(struct rctf *rct1, struct rctf *rct2);
254 void BLI_union_rctf(struct rctf *rcta, struct rctf *rctb);
255
256 /* scanfill.c: used in displist only... */
257 struct EditVert *BLI_addfillvert(float *vec);
258 struct EditEdge *BLI_addfilledge(struct EditVert *v1, struct EditVert *v2);
259 int BLI_edgefill(int mode);  /* DE HOOFD FILL ROUTINE */
260 void BLI_end_edgefill(void);
261
262 /* noise.h: */
263 float BLI_hnoise(float noisesize, float x, float y, float z);
264 float BLI_hnoisep(float noisesize, float x, float y, float z);
265 float BLI_turbulence(float noisesize, float x, float y, float z, int nr);
266 float BLI_turbulence1(float noisesize, float x, float y, float z, int nr);
267
268 /* These callbacks are needed to make the lib finction properly */
269
270 /**
271  * Set a function taking a char* as argument to flag errors. If the
272  * callback is not set, the error is discarded.
273  * @param f The function to use as callback
274  * @attention used in creator.c
275  */
276 void BLI_setErrorCallBack(void (*f)(char*));
277
278 /**
279  * Set a function to be able to interrupt the execution of processing
280  * in this module. If the function returns true, the execution will
281  * terminate gracefully. If the callback is not set, interruption is
282  * not possible.
283  * @param f The function to use as callback
284  * @attention used in creator.c
285  */
286 void BLI_setInterruptCallBack(int (*f)(void));
287
288 /**
289  * Before scanfilling is done, these two references need to be set. If
290  * the object reference is NULL, the function will fail. If the object
291  * is set, but no colour is available, colour can be omitted. 
292  *
293  * @attention Also see BLI_setScanFillColourRef
294  */
295 void BLI_setScanFillObjectRef(void* ob); 
296
297 /**
298  * Before scanfilling is done, these two references need to be set. If
299  * the object reference is NULL, the function will fail. If the object
300  * is set, but no colour is available, colour can be omitted. 
301  *
302  * @attention Also see BLI_setScanFillObjectRef
303  */
304 void BLI_setScanFillColourRef(char* c);
305
306 #define PRNTSUB(type,arg)                       printf(#arg ": %" #type " ", arg)
307 #define PRINT(t,v)                                      {PRNTSUB(t,v); printf("\n");}
308 #define PRINT2(t1,v1,t2,v2)                     {PRNTSUB(t1,v1); PRNTSUB(t2,v2); printf("\n");}
309 #define PRINT3(t1,v1,t2,v2,t3,v3)       {PRNTSUB(t1,v1); PRNTSUB(t2,v2); PRNTSUB(t3,v3); printf("\n");}
310 #define PRINT4(t1,v1,t2,v2,t3,v3,t4,v4) {PRNTSUB(t1,v1); PRNTSUB(t2,v2); PRNTSUB(t3,v3); PRNTSUB(t4,v4); printf("\n");}
311
312 /**
313  * @param array The array in question
314  * @retval The number of elements in the array.
315  */
316 #define BLI_ARRAY_NELEMS(array)         (sizeof((array))/sizeof((array)[0]))
317
318 /**
319  * @param strct The structure of interest
320  * @param member The name of a member field of @a strct
321  * @retval The offset in bytes of @a member within @a strct
322  */
323 #define BLI_STRUCT_OFFSET(strct, member)        (((struct) 0).(membr))
324
325 #ifdef __cplusplus
326 }
327 #endif
328
329 #endif
330