small merge needed for testing new animsys in 2.5 BGE, mixing own changes with merge...
[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 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.
84  *
85  * This program is distributed in the hope that it will be useful,
86  * but WITHOUT ANY WARRANTY; without even the implied warranty of
87  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
88  * GNU General Public License for more details.
89  *
90  * You should have received a copy of the GNU General Public License
91  * along with this program; if not, write to the Free Software Foundation,
92  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
93  *
94  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
95  * All rights reserved.
96  *
97  * The Original Code is: all of this file.
98  *
99  * Contributor(s): none yet.
100  *
101  * ***** END GPL LICENSE BLOCK *****
102  */
103 #ifndef IMB_IMBUF_H
104 #define IMB_IMBUF_H
105
106 /**
107  *
108  * @attention defined in ???
109  */
110 struct ImBuf;
111
112 /**
113  *
114  * @attention defined in ???
115  */
116 struct anim;
117
118 /**
119  *
120  * @attention Defined in cmap.c
121  */
122 void IMB_freeImBufdata(void);
123
124 /**
125  *
126  * @attention Defined in cmap.c
127  */
128 void IMB_applycmap(struct ImBuf *ibuf);
129
130 /**
131  *
132  * @attention Defined in cmap.c
133  */
134 short IMB_converttocmap(struct ImBuf *ibuf);
135
136 /**
137  *
138  * @attention Defined in cmap.c
139  */
140 int IMB_alpha_to_col0(int value);
141
142 /**
143  *
144  * @attention Defined in readimage.c
145  */
146 struct ImBuf *IMB_ibImageFromMemory(int *mem, int size, int flags);
147
148 /**
149  *
150  * @attention Defined in readimage.c
151  */
152 struct ImBuf *IMB_testiffname(char *naam,int flags);
153
154 /**
155  *
156  * @attention Defined in readimage.c
157  */
158 struct ImBuf *IMB_loadiffname(const char *naam, int flags);
159
160 /**
161  *
162  * @attention Defined in allocimbuf.c
163  */
164 void IMB_freeImBuf(struct ImBuf * ibuf);
165
166 /**
167  *
168  * @attention Defined in allocimbuf.c
169  */
170 struct ImBuf *IMB_allocImBuf(short x, short y,
171                                                  unsigned char d, unsigned int flags,
172                                                  unsigned char bitmap);
173
174 /**
175  *
176  * Increase reference count to imbuf
177  * (to delete an imbuf you have to call freeImBuf as many times as it
178  * is referenced)
179  *
180  * @attention Defined in allocimbuf.c
181  */
182
183 void IMB_refImBuf(struct ImBuf * ibuf);
184
185 /**
186  *
187  * @attention Defined in allocimbuf.c
188  */
189 void IMB_cache_limiter_insert(struct ImBuf * i);
190 void IMB_cache_limiter_unmanage(struct ImBuf * i);
191 void IMB_cache_limiter_touch(struct ImBuf * i);
192 void IMB_cache_limiter_ref(struct ImBuf * i);
193 void IMB_cache_limiter_unref(struct ImBuf * i);
194 int IMB_cache_limiter_get_refcount(struct ImBuf * i);
195
196 /**
197  *
198  * @attention Defined in allocimbuf.c
199  */
200 struct ImBuf *IMB_dupImBuf(struct ImBuf *ibuf1);
201
202 /**
203  *
204  * @attention Defined in allocimbuf.c
205  */
206 short addzbufImBuf(struct ImBuf * ibuf);
207 short addzbuffloatImBuf(struct ImBuf * ibuf);
208
209 /**
210  *
211  * @attention Defined in allocimbuf.c
212  */
213 void IMB_freecmapImBuf(struct ImBuf * ibuf);
214
215 /**
216  *
217  * @attention Defined in rectop.c
218  */
219
220 typedef enum IMB_BlendMode {
221         IMB_BLEND_MIX = 0,
222         IMB_BLEND_ADD = 1,
223         IMB_BLEND_SUB = 2,
224         IMB_BLEND_MUL = 3,
225         IMB_BLEND_LIGHTEN = 4,
226         IMB_BLEND_DARKEN = 5,
227         IMB_BLEND_ERASE_ALPHA = 6,
228         IMB_BLEND_ADD_ALPHA = 7,
229
230         IMB_BLEND_COPY = 1000,
231         IMB_BLEND_COPY_RGB = 1001,
232         IMB_BLEND_COPY_ALPHA = 1002
233 } IMB_BlendMode;
234
235 unsigned int IMB_blend_color(unsigned int src1, unsigned int src2, int fac,
236         IMB_BlendMode mode);
237 void IMB_blend_color_float(float *dst, float *src1, float *src2, float fac,
238         IMB_BlendMode mode);
239
240 void IMB_rectclip(struct ImBuf *dbuf, struct ImBuf *sbuf, int *destx, 
241         int *desty, int *srcx, int *srcy, int *width, int *height);
242 void IMB_rectcpy(struct ImBuf *drect, struct ImBuf *srect, int destx,
243         int desty, int srcx, int srcy, int width, int height);
244 void IMB_rectblend(struct ImBuf *dbuf, struct ImBuf *sbuf, int destx, 
245         int desty, int srcx, int srcy, int width, int height, IMB_BlendMode mode);
246 void IMB_rectblend_torus(struct ImBuf *dbuf, struct ImBuf *sbuf, int destx, 
247         int desty, int srcx, int srcy, int width, int height, IMB_BlendMode mode);
248
249 /**
250  * Return the length (in frames) of the given @a anim.
251  */
252 int IMB_anim_get_duration(struct anim *anim);
253
254 /**
255  *
256  * @attention Defined in anim.c
257  */
258 struct anim * IMB_open_anim(const char * name, int ib_flags);
259 void IMB_close_anim(struct anim * anim);
260
261 /**
262  *
263  * @attention Defined in anim.c
264  */
265
266 int ismovie(char *name);
267 void IMB_anim_set_preseek(struct anim * anim, int preseek);
268 int IMB_anim_get_preseek(struct anim * anim);
269
270 /**
271  *
272  * @attention Defined in anim.c
273  */
274
275 struct ImBuf * IMB_anim_absolute(struct anim * anim, int position);
276
277 /**
278  *
279  * @attention Defined in anim.c
280  * fetches a define previewframe, usually half way into the movie
281  */
282 struct ImBuf * IMB_anim_previewframe(struct anim * anim);
283
284 /**
285  *
286  * @attention Defined in anim.c
287  */
288 void IMB_free_anim_ibuf(struct anim * anim);
289
290 /**
291  *
292  * @attention Defined in anim.c
293  */
294 void IMB_free_anim(struct anim * anim);
295
296 /**
297  *
298  * @attention Defined in anim.c
299  */
300 struct ImBuf * IMB_anim_nextpic(struct anim * anim);     
301
302
303 /**
304  *
305  * @attention Defined in antialias.c
306  */
307 void IMB_clever_double (struct ImBuf * ibuf);
308
309 /**
310  *
311  * @attention Defined in antialias.c
312  */
313 void IMB_antialias(struct ImBuf * ibuf);
314
315 /**
316  *
317  * @attention Defined in filter.c
318  */
319 void IMB_filter(struct ImBuf *ibuf);
320 void IMB_filterN(struct ImBuf *out, struct ImBuf *in);
321 void IMB_filter_extend(struct ImBuf *ibuf, char *mask);
322 void IMB_makemipmap(struct ImBuf *ibuf, int use_filter);
323
324 /**
325  *
326  * @attention Defined in filter.c
327  */
328 void IMB_filtery(struct ImBuf *ibuf);
329
330 /**
331  *
332  * @attention Defined in scaling.c
333  */
334 struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1);
335
336 /**
337  *
338  * @attention Defined in scaling.c
339  */
340 struct ImBuf *IMB_scaleImBuf(struct ImBuf * ibuf, short newx, short newy);
341
342 /**
343  *
344  * @attention Defined in scaling.c
345  */
346 struct ImBuf *IMB_scalefieldImBuf(struct ImBuf *ibuf, short newx, short newy);
347
348 /**
349  *
350  * @attention Defined in scaling.c
351  */
352 struct ImBuf *IMB_scalefastImBuf(struct ImBuf *ibuf, short newx, short newy);
353
354 /**
355  *
356  * @attention Defined in writeimage.c
357  */
358 short IMB_saveiff(struct ImBuf *ibuf,char *naam,int flags);
359
360 /**
361  * Encodes a png image from an ImBuf
362  *
363  * @attention Defined in png_encode.c
364  */
365 short IMB_png_encode(struct ImBuf *ibuf, int file, int flags);
366
367 /**
368  *
369  * @attention Defined in util.c
370  */
371 int IMB_ispic(char *name);
372
373 /**
374  *
375  * @attention Defined in util.c
376  */
377 int IMB_isanim(char * name);
378
379 /**
380  *
381  * @attention Defined in util.c
382  */
383 int imb_get_anim_type(char * name);
384
385 /**
386  *
387  * @attention Defined in divers.c
388  */
389 void IMB_de_interlace(struct ImBuf *ibuf);
390 void IMB_interlace(struct ImBuf *ibuf);
391 void IMB_gamwarp(struct ImBuf *ibuf, double gamma);
392 void IMB_rect_from_float(struct ImBuf *ibuf);
393 void IMB_float_from_rect(struct ImBuf *ibuf);
394
395 /**
396  * Change the ordering of the color bytes pointed to by rect from
397  * rgba to abgr. size * 4 color bytes are reordered.
398  *
399  * @attention Defined in imageprocess.c
400  */
401 void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf);
402 /**
403  *
404  * @attention defined in imageprocess.c
405  */
406 void bicubic_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
407 void neareast_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
408 void bilinear_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
409
410 void bicubic_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
411 void neareast_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
412 void bilinear_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
413 void bilinear_interpolation_color_wrap(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
414
415 /**
416  * Change the ordering of the color bytes pointed to by rect from
417  * rgba to abgr. size * 4 color bytes are reordered.
418  *
419  * @attention Defined in imageprocess.c
420  */
421 void IMB_convert_bgra_to_rgba(int size, unsigned int *rect);
422
423 /**
424  *
425  * @attention defined in scaling.c
426  */
427 struct ImBuf *IMB_scalefastfieldImBuf(struct ImBuf *ibuf,
428                                                                           short newx,
429                                                                           short newy);
430
431 /**
432  *
433  * @attention defined in readimage.c
434  * @deprecated Only here for backwards compatibility of the
435  * @deprecated plugin system.
436  */
437 struct ImBuf *IMB_loadiffmem(int *mem, int flags);
438
439 /**
440  *
441  * @attention defined in readimage.c
442  * @deprecated Only here for backwards compatibility of the
443  * @deprecated plugin system.
444  */  
445 struct ImBuf *IMB_loadifffile(int file, int flags);
446
447 /**
448  *
449  * @attention defined in scaling.c
450  */
451 struct ImBuf *IMB_half_x(struct ImBuf *ibuf1);
452
453 /**
454  *
455  * @attention defined in scaling.c
456  */
457 struct ImBuf *IMB_double_fast_x(struct ImBuf *ibuf1);
458
459 /**
460  *
461  * @attention defined in scaling.c
462  */
463 struct ImBuf *IMB_double_x(struct ImBuf *ibuf1);
464
465 /**
466  *
467  * @attention defined in scaling.c
468  */
469 struct ImBuf *IMB_half_y(struct ImBuf *ibuf1);
470
471 /**
472  *
473  * @attention defined in scaling.c
474  */
475 struct ImBuf *IMB_double_fast_y(struct ImBuf *ibuf1);
476
477 /**
478  *
479  * @attention defined in scaling.c
480  */
481 struct ImBuf *IMB_double_y(struct ImBuf *ibuf1);
482
483 /**
484  *
485  * @attention defined in scaling.c
486  */
487 struct ImBuf *IMB_onethird(struct ImBuf *ibuf1);
488
489 /**
490  *
491  * @attention defined in scaling.c
492  */
493 struct ImBuf *IMB_halflace(struct ImBuf *ibuf1);
494
495 /**
496  *
497  * @attention defined in dither.c
498  */
499 void IMB_dit2(struct ImBuf * ibuf, short ofs, short bits);
500
501 /**
502  *
503  * @attention defined in dither.c
504  */
505 void IMB_dit0(struct ImBuf * ibuf, short ofs, short bits);
506
507 /** Externally used vars: fortunately they do not use funny types */
508
509 /**
510  * boolean toggle that tells whether or not to
511  * scale the color map in the y-direction.
512  *
513  * @attention declared in hamx.c
514  */
515 extern int scalecmapY;
516
517 /**
518  * This 'matrix' defines the transformation from rgb to bw color
519  * maps. You need to do a sort of dot-product for that. It is a matrix
520  * with fixed coefficients, extracted from some book.
521  *
522  * @attention Defined in matrix.h, only included in hamx.c
523  */
524 extern float rgb_to_bw[4][4]; 
525
526 /**
527  *
528  * @attention Defined in rotate.c
529  */
530 void IMB_flipx(struct ImBuf *ibuf);
531 void IMB_flipy(struct ImBuf * ibuf);
532
533 /**
534  *
535  * @attention Defined in cspace.c
536  */
537 void IMB_cspace(struct ImBuf *ibuf, float mat[][4]);
538
539 /**
540  *
541  * @attention Defined in allocimbuf.c
542  */
543 void IMB_freezbufImBuf(struct ImBuf * ibuf);
544 void IMB_freezbuffloatImBuf(struct ImBuf * ibuf);
545
546 /**
547  *
548  * @attention Defined in rectop.c
549  */
550 void IMB_rectfill(struct ImBuf *drect, float col[4]);
551 void IMB_rectfill_area(struct ImBuf *ibuf, float *col, int x1, int y1, int x2, int y2);
552
553 /* this should not be here, really, we needed it for operating on render data, IMB_rectfill_area calls it */
554 void buf_rectfill_area(unsigned char *rect, float *rectf, int width, int height, float *col, int x1, int y1, int x2, int y2);
555
556 /* defined in imginfo.c */
557 int IMB_imginfo_change_field(struct ImBuf *img, const char *key, const char *field);
558
559 /* exported for image tools in blender, to quickly allocate 32 bits rect */
560 short imb_addrectImBuf(struct ImBuf * ibuf);
561 void imb_freerectImBuf(struct ImBuf * ibuf);
562
563 short imb_addrectfloatImBuf(struct ImBuf * ibuf);
564 void imb_freerectfloatImBuf(struct ImBuf * ibuf);
565 void imb_freemipmapImBuf(struct ImBuf * ibuf);
566
567 #ifdef WITH_QUICKTIME
568 /**
569  *
570  * @attention Defined in quicktime_import.c
571  */
572 void quicktime_init(void);
573
574 /**
575  *
576  * @attention Defined in quicktime_import.c
577  */
578 void quicktime_exit(void);
579
580 #endif //WITH_QUICKTIME
581
582 /* intern/dynlibtiff.c */
583 void libtiff_init(void);
584 void libtiff_exit(void);
585
586 #endif