ImagePaint Refactoring:
[blender.git] / source / blender / imbuf / IMB_imbuf.h
1 /**
2  * @file IMB_imbuf.h
3  * @brief IMage Buffer module.
4  *
5  * This module offers import/export of several graphical file formats.
6  * \ref IMB
7  * @ingroup imbuf
8  * @ingroup undoc
9  *
10  * @page IMB - Imbuf module external interface
11  *
12  *
13  * @section about About the IMB module
14  *
15  * External interface of the IMage Buffer module. This module offers
16  * import/export of several graphical file formats. It offers the
17  * ImBuf type as a common structure to refer to different graphical
18  * file formats, and to enable a uniform way of handling them.
19  *
20  * @section issues Known issues with IMB
21  *
22  * - imbuf is written in C.
23  * - Endianness issues are dealt with internally.
24  * - File I/O must be done externally. The module uses FILE*'s to
25  *   direct input/output.
26  * - Platform dependency is limited. Some minor patches for
27  *   amiga and Irix are present. A 'posix-compliancy-patch'
28  *   provides the interface to windows.
29  *
30  * @section dependencies Dependencies
31  *
32  * IMB needs:
33  * - SDNA module
34  *     The listbase types are used for handling the memory
35  *     management.
36  * - blenlib module
37  *     blenlib handles guarded memory management in blender-style.
38  *     BLI_winstuff.h makes a few windows specific behaviours
39  *     posix-compliant.
40  * - avi
41  *     avi defines import/export to the avi format. Only anim.c
42  *     needs this. It uses the following functions:
43  *       - avi_close
44  *       - avi_is_avi
45  *       - avi_print_error
46  *       - avi_open_movie
47  *       - avi_read_frame
48  *       - avi_get_stream
49  *     Additionally, it needs the types from the avi module.
50  * - external jpeg library
51  *     The jpeg lib defines import/export to the jpeg format.
52  *     only jpeg.c needs these. Used functions are:
53  *       - jpeg_destroy
54  *       - jpeg_resync_to_restart
55  *       - jpeg_set_marker_processor
56  *       - jpeg_read_header
57  *       - jpeg_start_decompress
58  *       - jpeg_abort_decompress
59  *       - jpeg_read_scanlines
60  *       - jpeg_finish_decompress
61  *       - jpeg_std_error
62  *       - jpeg_create_decompress
63  *       - jpeg_stdio_src
64  *       - jpeg_start_compress
65  *       - jpeg_write_marker
66  *       - jpeg_write_scanlines
67  *       - jpeg_finish_compress
68  *       - jpeg_create_compress
69  *       - jpeg_stdio_dest
70  *       - jpeg_set_defaults
71  *       - jpeg_set_quality
72  *       - jpeg_destroy_compress
73  *     Additionally, it needs the types from the jpeg lib.
74  */
75 /*
76  * $Id$ 
77  *
78  * ***** BEGIN GPL/BL DUAL LICENSE BLOCK *****
79  *
80  * This program is free software; you can redistribute it and/or
81  * modify it under the terms of the GNU General Public License
82  * as published by the Free Software Foundation; either version 2
83  * of the License, or (at your option) any later version. The Blender
84  * Foundation also sells licenses for use in proprietary software under
85  * the Blender License.  See http://www.blender.org/BL/ for information
86  * about this.
87  *
88  * This program is distributed in the hope that it will be useful,
89  * but WITHOUT ANY WARRANTY; without even the implied warranty of
90  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
91  * GNU General Public License for more details.
92  *
93  * You should have received a copy of the GNU General Public License
94  * along with this program; if not, write to the Free Software Foundation,
95  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
96  *
97  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
98  * All rights reserved.
99  *
100  * The Original Code is: all of this file.
101  *
102  * Contributor(s): none yet.
103  *
104  * ***** END GPL/BL DUAL LICENSE BLOCK *****
105  */
106 #ifndef IMB_IMBUF_H
107 #define IMB_IMBUF_H
108
109 /**
110  *
111  * @attention defined in ???
112  */
113 struct ImBuf;
114
115 /**
116  *
117  * @attention defined in ???
118  */
119 struct anim;
120
121 /**
122  *
123  * @attention Defined in cmap.c
124  */
125 void IMB_freeImBufdata(void);
126
127 /**
128  *
129  * @attention Defined in cmap.c
130  */
131 void IMB_applycmap(struct ImBuf *ibuf);
132
133 /**
134  *
135  * @attention Defined in cmap.c
136  */
137 short IMB_converttocmap(struct ImBuf *ibuf);
138
139 /**
140  *
141  * @attention Defined in cmap.c
142  */
143 int IMB_alpha_to_col0(int value);
144
145 /**
146  *
147  * @attention Defined in readimage.c
148  */
149 struct ImBuf *IMB_ibImageFromMemory(int *mem, int size, int flags);
150
151 /**
152  *
153  * @attention Defined in readimage.c
154  */
155 struct ImBuf *IMB_testiffname(char *naam,int flags);
156
157 /**
158  *
159  * @attention Defined in readimage.c
160  */
161 struct ImBuf *IMB_loadiffname(char *naam, int flags);
162
163 /**
164  *
165  * @attention Defined in allocimbuf.c
166  */
167 void IMB_freeImBuf(struct ImBuf * ibuf);
168
169 /**
170  *
171  * @attention Defined in allocimbuf.c
172  */
173 struct ImBuf *IMB_allocImBuf(short x, short y,
174                                                  unsigned char d, unsigned int flags,
175                                                  unsigned char bitmap);
176
177 /**
178  *
179  * Increase reference count to imbuf
180  * (to delete an imbuf you have to call freeImBuf as many times as it
181  * is referenced)
182  *
183  * @attention Defined in allocimbuf.c
184  */
185
186 void IMB_refImBuf(struct ImBuf * ibuf);
187
188 /**
189  *
190  * @attention Defined in allocimbuf.c
191  */
192 void IMB_cache_limiter_insert(struct ImBuf * i);
193 void IMB_cache_limiter_unmanage(struct ImBuf * i);
194 void IMB_cache_limiter_touch(struct ImBuf * i);
195 void IMB_cache_limiter_ref(struct ImBuf * i);
196 void IMB_cache_limiter_unref(struct ImBuf * i);
197 int IMB_cache_limiter_get_refcount(struct ImBuf * i);
198
199 /**
200  *
201  * @attention Defined in allocimbuf.c
202  */
203 struct ImBuf *IMB_dupImBuf(struct ImBuf *ibuf1);
204
205 /**
206  *
207  * @attention Defined in allocimbuf.c
208  */
209 short addzbufImBuf(struct ImBuf * ibuf);
210 short addzbuffloatImBuf(struct ImBuf * ibuf);
211
212 /**
213  *
214  * @attention Defined in allocimbuf.c
215  */
216 void IMB_freecmapImBuf(struct ImBuf * ibuf);
217
218 /**
219  *
220  * @attention Defined in rectop.c
221  */
222
223 typedef enum IMB_BlendMode {
224         IMB_BLEND_MIX = 0,
225         IMB_BLEND_ADD = 1,
226         IMB_BLEND_SUB = 2,
227         IMB_BLEND_MUL = 3,
228         IMB_BLEND_LIGHTEN = 4,
229         IMB_BLEND_DARKEN = 5,
230
231         IMB_BLEND_COPY = 1000,
232         IMB_BLEND_COPY_RGB = 1001,
233         IMB_BLEND_COPY_ALPHA = 1002
234 } IMB_BlendMode;
235
236 unsigned int IMB_blend_color(unsigned int src1, unsigned int src2, int fac,
237         IMB_BlendMode mode);
238 void IMB_blend_color_float(float *dst, float *src1, float *src2, float fac,
239         IMB_BlendMode mode);
240
241 void IMB_rectclip(struct ImBuf *dbuf, struct ImBuf *sbuf, int *destx, 
242         int *desty, int *srcx, int *srcy, int *width, int *height);
243 void IMB_rectcpy(struct ImBuf *drect, struct ImBuf *srect, int destx,
244         int desty, int srcx, int srcy, int width, int height);
245 void IMB_rectblend(struct ImBuf *dbuf, struct ImBuf *sbuf, int destx, 
246         int desty, int srcx, int srcy, int width, int height, IMB_BlendMode mode);
247 void IMB_rectblend_torus(struct ImBuf *dbuf, struct ImBuf *sbuf, int destx, 
248         int desty, int srcx, int srcy, int width, int height, IMB_BlendMode mode);
249
250 /**
251  * Return the length (in frames) of the given @a anim.
252  */
253 int IMB_anim_get_duration(struct anim *anim);
254
255 /**
256  *
257  * @attention Defined in anim.c
258  */
259 struct anim * IMB_open_anim(char * name, int ib_flags);
260 void IMB_close_anim(struct anim * anim);
261
262 /**
263  *
264  * @attention Defined in anim.c
265  */
266
267 int ismovie(char *name);
268 void IMB_anim_set_preseek(struct anim * anim, int preseek);
269 int IMB_anim_get_preseek(struct anim * anim);
270
271 /**
272  *
273  * @attention Defined in anim.c
274  */
275
276 struct ImBuf * IMB_anim_absolute(struct anim * anim, int position);
277
278 /**
279  *
280  * @attention Defined in anim.c
281  */
282 void IMB_free_anim_ibuf(struct anim * anim);
283
284 /**
285  *
286  * @attention Defined in anim.c
287  */
288 void IMB_free_anim(struct anim * anim);
289
290 /**
291  *
292  * @attention Defined in anim.c
293  */
294 struct ImBuf * IMB_anim_nextpic(struct anim * anim);     
295
296
297 /**
298  *
299  * @attention Defined in antialias.c
300  */
301 void IMB_clever_double (struct ImBuf * ibuf);
302
303 /**
304  *
305  * @attention Defined in antialias.c
306  */
307 void IMB_antialias(struct ImBuf * ibuf);
308
309 /**
310  *
311  * @attention Defined in filter.c
312  */
313 void IMB_filter(struct ImBuf *ibuf);
314 void IMB_filterN(struct ImBuf *out, struct ImBuf *in);
315
316 /**
317  *
318  * @attention Defined in filter.c
319  */
320 void IMB_filtery(struct ImBuf *ibuf);
321
322 /**
323  *
324  * @attention Defined in scaling.c
325  */
326 struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1);
327
328 /**
329  *
330  * @attention Defined in scaling.c
331  */
332 struct ImBuf *IMB_scaleImBuf(struct ImBuf * ibuf, short newx, short newy);
333
334 /**
335  *
336  * @attention Defined in scaling.c
337  */
338 struct ImBuf *IMB_scalefieldImBuf(struct ImBuf *ibuf, short newx, short newy);
339
340 /**
341  *
342  * @attention Defined in scaling.c
343  */
344 struct ImBuf *IMB_scalefastImBuf(struct ImBuf *ibuf, short newx, short newy);
345
346 /**
347  *
348  * @attention Defined in writeimage.c
349  */
350 short IMB_saveiff(struct ImBuf *ibuf,char *naam,int flags);
351
352 /**
353  * Encodes a png image from an ImBuf
354  *
355  * @attention Defined in png_encode.c
356  */
357 short IMB_png_encode(struct ImBuf *ibuf, int file, int flags);
358
359 /**
360  *
361  * @attention Defined in util.c
362  */
363 int IMB_ispic(char *name);
364
365 /**
366  *
367  * @attention Defined in util.c
368  */
369 int IMB_isanim(char * name);
370
371 /**
372  *
373  * @attention Defined in util.c
374  */
375 int imb_get_anim_type(char * name);
376
377 /**
378  *
379  * @attention Defined in divers.c
380  */
381 void IMB_de_interlace(struct ImBuf *ibuf);
382 void IMB_interlace(struct ImBuf *ibuf);
383 void IMB_gamwarp(struct ImBuf *ibuf, double gamma);
384 void IMB_rect_from_float(struct ImBuf *ibuf);
385 void IMB_float_from_rect(struct ImBuf *ibuf);
386
387 /**
388  * Change the ordering of the colour bytes pointed to by rect from
389  * rgba to abgr. size * 4 colour bytes are reordered.
390  *
391  * @attention Defined in imageprocess.c
392  */
393 void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf);
394
395 /**
396  * Change the ordering of the colour bytes pointed to by rect from
397  * rgba to abgr. size * 4 colour bytes are reordered.
398  *
399  * @attention Defined in imageprocess.c
400  */
401 void IMB_convert_bgra_to_rgba(int size, unsigned int *rect);
402
403 /**
404  *
405  * @attention defined in scaling.c
406  */
407 struct ImBuf *IMB_scalefastfieldImBuf(struct ImBuf *ibuf,
408                                                                           short newx,
409                                                                           short newy);
410
411 /**
412  *
413  * @attention defined in readimage.c
414  * @deprecated Only here for backwards compatibility of the
415  * @deprecated plugin system.
416  */
417 struct ImBuf *IMB_loadiffmem(int *mem, int flags);
418
419 /**
420  *
421  * @attention defined in readimage.c
422  * @deprecated Only here for backwards compatibility of the
423  * @deprecated plugin system.
424  */  
425 struct ImBuf *IMB_loadifffile(int file, int flags);
426
427 /**
428  *
429  * @attention defined in scaling.c
430  */
431 struct ImBuf *IMB_half_x(struct ImBuf *ibuf1);
432
433 /**
434  *
435  * @attention defined in scaling.c
436  */
437 struct ImBuf *IMB_double_fast_x(struct ImBuf *ibuf1);
438
439 /**
440  *
441  * @attention defined in scaling.c
442  */
443 struct ImBuf *IMB_double_x(struct ImBuf *ibuf1);
444
445 /**
446  *
447  * @attention defined in scaling.c
448  */
449 struct ImBuf *IMB_half_y(struct ImBuf *ibuf1);
450
451 /**
452  *
453  * @attention defined in scaling.c
454  */
455 struct ImBuf *IMB_double_fast_y(struct ImBuf *ibuf1);
456
457 /**
458  *
459  * @attention defined in scaling.c
460  */
461 struct ImBuf *IMB_double_y(struct ImBuf *ibuf1);
462
463 /**
464  *
465  * @attention defined in scaling.c
466  */
467 struct ImBuf *IMB_onethird(struct ImBuf *ibuf1);
468
469 /**
470  *
471  * @attention defined in scaling.c
472  */
473 struct ImBuf *IMB_halflace(struct ImBuf *ibuf1);
474
475 /**
476  *
477  * @attention defined in dither.c
478  */
479 void IMB_dit2(struct ImBuf * ibuf, short ofs, short bits);
480
481 /**
482  *
483  * @attention defined in dither.c
484  */
485 void IMB_dit0(struct ImBuf * ibuf, short ofs, short bits);
486
487 /** Externally used vars: fortunately they do not use funny types */
488
489 /**
490  * boolean toggle that tells whether or not to
491  * scale the colour map in the y-direction.
492  *
493  * @attention declared in hamx.c
494  */
495 extern int scalecmapY;
496
497 /**
498  * This 'matrix' defines the transformation from rgb to bw colour
499  * maps. You need to do a sort of dot-product for that. It is a matrix
500  * with fixed coefficients, extracted from some book.
501  *
502  * @attention Defined in matrix.h, only included in hamx.c
503  */
504 extern float rgb_to_bw[4][4]; 
505
506 /**
507  *
508  * @attention Defined in rotate.c
509  */
510 void IMB_flipy(struct ImBuf * ibuf);
511
512 /**
513  *
514  * @attention Defined in cspace.c
515  */
516 void IMB_cspace(struct ImBuf *ibuf, float mat[][4]);
517
518 /**
519  *
520  * @attention Defined in allocimbuf.c
521  */
522 void IMB_freezbufImBuf(struct ImBuf * ibuf);
523 void IMB_freezbuffloatImBuf(struct ImBuf * ibuf);
524
525 /**
526  *
527  * @attention Defined in rectop.c
528  */
529 void IMB_rectfill(struct ImBuf *drect, float col[4]);
530
531 /* exported for image tools in blender, to quickly allocate 32 bits rect */
532 short imb_addrectImBuf(struct ImBuf * ibuf);
533 void imb_freerectImBuf(struct ImBuf * ibuf);
534
535 short imb_addrectfloatImBuf(struct ImBuf * ibuf);
536 void imb_freerectfloatImBuf(struct ImBuf * ibuf);
537
538 #ifdef WITH_QUICKTIME
539 /**
540  *
541  * @attention Defined in quicktime_import.c
542  */
543 void quicktime_init(void);
544
545 /**
546  *
547  * @attention Defined in quicktime_import.c
548  */
549 void quicktime_exit(void);
550
551 #endif //WITH_QUICKTIME
552
553 /* intern/dynlibtiff.c */
554 void libtiff_init(void);
555 void libtiff_exit(void);
556
557 #endif