SVN maintenance.
[blender.git] / source / blender / imbuf / IMB_imbuf.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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 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
30 /** \file blender/imbuf/IMB_imbuf.h
31  *  \ingroup imbuf
32  */
33
34 /**
35  * @file IMB_imbuf.h
36  * @brief IMage Buffer module.
37  *
38  * This module offers import/export of several graphical file formats.
39  * @ingroup imbuf
40  *
41  * @page IMB Imbuf module external interface
42  *
43  *
44  * @section about About the IMB module
45  *
46  * External interface of the IMage Buffer module. This module offers
47  * import/export of several graphical file formats. It offers the
48  * ImBuf type as a common structure to refer to different graphical
49  * file formats, and to enable a uniform way of handling them.
50  *
51  * @section issues Known issues with IMB
52  *
53  * - imbuf is written in C.
54  * - Endianness issues are dealt with internally.
55  * - File I/O must be done externally. The module uses FILE*'s to
56  *   direct input/output.
57  * - Platform dependency is limited. Some minor patches for
58  *   amiga and Irix are present. A 'posix-compliancy-patch'
59  *   provides the interface to windows.
60  *
61  * @section dependencies Dependencies
62  *
63  * IMB needs:
64  * - \ref DNA module
65  *     The listbase types are used for handling the memory
66  *     management.
67  * - \ref blenlib module
68  *     blenlib handles guarded memory management in blender-style.
69  *     BLI_winstuff.h makes a few windows specific behaviours
70  *     posix-compliant.
71  */
72
73 #ifndef IMB_IMBUF_H
74 #define IMB_IMBUF_H
75
76 /**
77  *
78  * @attention defined in ???
79  */
80 struct ImBuf;
81
82 /**
83  *
84  * @attention defined in ???
85  */
86 struct anim;
87
88 /**
89  *
90  * @attention Defined in allocimbuf.c
91  */
92 void IMB_init(void);
93 void IMB_exit(void);
94
95 /**
96  *
97  * @attention Defined in readimage.c
98  */
99 struct ImBuf *IMB_ibImageFromMemory(unsigned char *mem, size_t size, int flags);
100
101 /**
102  *
103  * @attention Defined in readimage.c
104  */
105 struct ImBuf *IMB_testiffname(char *naam,int flags);
106
107 /**
108  *
109  * @attention Defined in readimage.c
110  */
111 struct ImBuf *IMB_loadiffname(const char *naam, int flags);
112
113 /**
114  *
115  * @attention Defined in allocimbuf.c
116  */
117 void IMB_freeImBuf(struct ImBuf *ibuf);
118
119 /**
120  *
121  * @attention Defined in allocimbuf.c
122  */
123 struct ImBuf *IMB_allocImBuf(unsigned int x, unsigned int y,
124                                                  unsigned char d, unsigned int flags);
125
126 /**
127  *
128  * Increase reference count to imbuf
129  * (to delete an imbuf you have to call freeImBuf as many times as it
130  * is referenced)
131  *
132  * @attention Defined in allocimbuf.c
133  */
134
135 void IMB_refImBuf(struct ImBuf *ibuf);
136 struct ImBuf * IMB_makeSingleUser(struct ImBuf *ibuf);
137
138 /**
139  *
140  * @attention Defined in allocimbuf.c
141  */
142 void IMB_cache_limiter_insert(struct ImBuf *i);
143 void IMB_cache_limiter_unmanage(struct ImBuf *i);
144 void IMB_cache_limiter_touch(struct ImBuf *i);
145 void IMB_cache_limiter_ref(struct ImBuf *i);
146 void IMB_cache_limiter_unref(struct ImBuf *i);
147 int IMB_cache_limiter_get_refcount(struct ImBuf *i);
148
149 void IMB_free_cache_limiter(void);
150
151 /**
152  *
153  * @attention Defined in allocimbuf.c
154  */
155 struct ImBuf *IMB_dupImBuf(struct ImBuf *ibuf1);
156
157 /**
158  *
159  * @attention Defined in allocimbuf.c
160  */
161 short addzbufImBuf(struct ImBuf *ibuf);
162 short addzbuffloatImBuf(struct ImBuf *ibuf);
163
164 /**
165  *
166  * @attention Defined in rectop.c
167  */
168
169 typedef enum IMB_BlendMode {
170         IMB_BLEND_MIX = 0,
171         IMB_BLEND_ADD = 1,
172         IMB_BLEND_SUB = 2,
173         IMB_BLEND_MUL = 3,
174         IMB_BLEND_LIGHTEN = 4,
175         IMB_BLEND_DARKEN = 5,
176         IMB_BLEND_ERASE_ALPHA = 6,
177         IMB_BLEND_ADD_ALPHA = 7,
178
179         IMB_BLEND_COPY = 1000,
180         IMB_BLEND_COPY_RGB = 1001,
181         IMB_BLEND_COPY_ALPHA = 1002
182 } IMB_BlendMode;
183
184 unsigned int IMB_blend_color(unsigned int src1, unsigned int src2, int fac,
185         IMB_BlendMode mode);
186 void IMB_blend_color_float(float *dst, float *src1, float *src2, float fac,
187         IMB_BlendMode mode);
188
189 void IMB_rectclip(struct ImBuf *dbuf, struct ImBuf *sbuf, int *destx, 
190         int *desty, int *srcx, int *srcy, int *width, int *height);
191 void IMB_rectcpy(struct ImBuf *drect, struct ImBuf *srect, int destx,
192         int desty, int srcx, int srcy, int width, int height);
193 void IMB_rectblend(struct ImBuf *dbuf, struct ImBuf *sbuf, int destx, 
194         int desty, int srcx, int srcy, int width, int height, IMB_BlendMode mode);
195
196 /**
197  *
198  * @attention Defined in indexer.c
199  */
200
201 typedef enum IMB_Timecode_Type {
202         IMB_TC_NONE       = 0, /* don't use timecode files at all */
203         IMB_TC_RECORD_RUN = 1, /* use images in the order as they are recorded 
204                                   (currently, this is the only one implemented
205                                   and is a sane default)
206                                */
207         IMB_TC_FREE_RUN   = 2, /* use global timestamp written by recording
208                                   device (prosumer camcorders e.g. can do
209                                   that) */
210         IMB_TC_INTERPOLATED_REC_DATE_FREE_RUN = 4, 
211                                /* interpolate a global timestamp using the
212                                   record date and time written by recording
213                                   device (*every* consumer camcorder can do
214                                   that :) )*/
215         IMB_TC_MAX_SLOT   = 3
216 } IMB_Timecode_Type;
217
218 typedef enum IMB_Proxy_Size {
219         IMB_PROXY_NONE = 0,
220         IMB_PROXY_25 = 1,
221         IMB_PROXY_50 = 2,
222         IMB_PROXY_75 = 4,
223         IMB_PROXY_100 = 8,
224         IMB_PROXY_MAX_SLOT = 4
225 } IMB_Proxy_Size;
226
227 /* defaults to BL_proxy within the directory of the animation */
228 void IMB_anim_set_index_dir(struct anim * anim, const char * dir);
229
230 int IMB_anim_index_get_frame_index(struct anim * anim, IMB_Timecode_Type tc,
231                                    int position);
232
233 /* will rebuild all used indices and proxies at once */
234 void IMB_anim_index_rebuild(struct anim * anim, 
235                             IMB_Timecode_Type build_tcs,
236                             IMB_Proxy_Size build_preview_sizes, 
237                             int build_quality,
238                             short *stop, short *do_update, float *progress);
239
240 /**
241  * Return the length (in frames) of the given @a anim.
242  */
243 int IMB_anim_get_duration(struct anim *anim, IMB_Timecode_Type tc);
244
245
246 /**
247  * Return the fps contained in movie files (function rval is FALSE,
248  * and frs_sec and frs_sec_base untouched if none available!)
249  */
250 int IMB_anim_get_fps(struct anim * anim, 
251                      short * frs_sec, float * frs_sec_base);
252
253 /**
254  *
255  * @attention Defined in anim.c
256  */
257 struct anim *IMB_open_anim(const char *name, int ib_flags, int streamindex);
258 void IMB_close_anim(struct anim *anim);
259
260
261 /**
262  *
263  * @attention Defined in anim.c
264  */
265
266 int ismovie(const 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(
276         struct anim *anim, int position,
277         IMB_Timecode_Type tc        /* = 1 = IMB_TC_RECORD_RUN */, 
278         IMB_Proxy_Size preview_size /* = 0 = IMB_PROXY_NONE */);
279
280 /**
281  *
282  * @attention Defined in anim.c
283  * fetches a define previewframe, usually half way into the movie
284  */
285 struct ImBuf *IMB_anim_previewframe(struct anim *anim);
286
287 /**
288  *
289  * @attention Defined in anim.c
290  */
291 void IMB_free_anim(struct anim *anim);
292
293 /**
294  *
295  * @attention Defined in filter.c
296  */
297
298 #define FILTER_MASK_NULL                0
299 #define FILTER_MASK_MARGIN              1
300 #define FILTER_MASK_USED                2
301
302 void IMB_filter(struct ImBuf *ibuf);
303 void IMB_filterN(struct ImBuf *out, struct ImBuf *in);
304 void IMB_mask_filter_extend(char *mask, int width, int height);
305 void IMB_mask_clear(struct ImBuf *ibuf, char *mask, int val);
306 void IMB_filter_extend(struct ImBuf *ibuf, char *mask, int filter);
307 void IMB_makemipmap(struct ImBuf *ibuf, int use_filter);
308 void IMB_remakemipmap(struct ImBuf *ibuf, int use_filter);
309 struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level);
310
311 /**
312  *
313  * @attention Defined in cache.c
314  */
315
316 void IMB_tile_cache_params(int totthread, int maxmem);
317 unsigned int *IMB_gettile(struct ImBuf *ibuf, int tx, int ty, int thread);
318 void IMB_tiles_to_rect(struct ImBuf *ibuf);
319
320 /**
321  *
322  * @attention Defined in filter.c
323  */
324 void IMB_filtery(struct ImBuf *ibuf);
325
326 /**
327  *
328  * @attention Defined in scaling.c
329  */
330 struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1);
331
332 /**
333  *
334  * @attention Defined in scaling.c
335  */
336 struct ImBuf *IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
337
338 /**
339  *
340  * @attention Defined in scaling.c
341  */
342 struct ImBuf *IMB_scalefastImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
343
344 /**
345  *
346  * @attention Defined in writeimage.c
347  */
348 short IMB_saveiff(struct ImBuf *ibuf, const char *filepath, int flags);
349
350 /**
351  * Encodes a png image from an ImBuf
352  *
353  * @attention Defined in png_encode.c
354  */
355 short IMB_png_encode(struct ImBuf *ibuf, int file, int flags);
356
357 /**
358  *
359  * @attention Defined in util.c
360  */
361 int IMB_ispic(const char *name);
362
363 /**
364  *
365  * @attention Defined in util.c
366  */
367 int IMB_isanim(const char *name);
368
369 /**
370  *
371  * @attention Defined in util.c
372  */
373 int imb_get_anim_type(const char *name);
374
375 /**
376  *
377  * @attention Defined in divers.c
378  */
379 void IMB_de_interlace(struct ImBuf *ibuf);
380 void IMB_interlace(struct ImBuf *ibuf);
381
382 /* create char buffer, color corrected if necessary, for ImBufs that lack one */ 
383 void IMB_rect_from_float(struct ImBuf *ibuf);
384 /* create char buffer for part of the image, color corrected if necessary,
385    Changed part will be stored in buffer. This is expected to be used for texture painting updates */ 
386 void IMB_partial_rect_from_float(struct ImBuf *ibuf, float *buffer, int x, int y, int w, int h);
387 void IMB_float_from_rect(struct ImBuf *ibuf);
388 void IMB_float_from_rect_simple(struct ImBuf *ibuf); /* no profile conversion */
389 /* note, check that the conversion exists, only some are supported */
390 void IMB_convert_profile(struct ImBuf *ibuf, int profile);
391 float *IMB_float_profile_ensure(struct ImBuf *ibuf, int profile, int *alloc);
392 void IMB_color_to_bw(struct ImBuf *ibuf);
393
394 /**
395  * Change the ordering of the color bytes pointed to by rect from
396  * rgba to abgr. size * 4 color bytes are reordered.
397  *
398  * @attention Defined in imageprocess.c
399  */
400 void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf);
401
402 /**
403  * Change the ordering of the color bytes pointed to by rect from
404  * rgba to abgr. size * 4 color bytes are reordered.
405  *
406  * @attention Defined in imageprocess.c
407  */
408 void IMB_convert_bgra_to_rgba(int size, unsigned int *rect);
409
410 /**
411  *
412  * @attention defined in imageprocess.c
413  */
414 void bicubic_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
415 void neareast_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
416 void bilinear_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
417
418 void bicubic_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
419 void neareast_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
420 void bilinear_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
421 void bilinear_interpolation_color_wrap(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
422
423 /**
424  *
425  * @attention defined in readimage.c
426  * @deprecated Only here for backwards compatibility of the
427  * @deprecated plugin system.
428  */
429 struct ImBuf *IMB_loadiffmem(int *mem, int flags);
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_loadifffile(int file, int flags);
438
439 /**
440  *
441  * @attention defined in scaling.c
442  */
443 struct ImBuf *IMB_half_x(struct ImBuf *ibuf1);
444
445 /**
446  *
447  * @attention defined in scaling.c
448  */
449 struct ImBuf *IMB_double_fast_x(struct ImBuf *ibuf1);
450
451 /**
452  *
453  * @attention defined in scaling.c
454  */
455 struct ImBuf *IMB_double_x(struct ImBuf *ibuf1);
456
457 /**
458  *
459  * @attention defined in scaling.c
460  */
461 struct ImBuf *IMB_half_y(struct ImBuf *ibuf1);
462
463 /**
464  *
465  * @attention defined in scaling.c
466  */
467 struct ImBuf *IMB_double_fast_y(struct ImBuf *ibuf1);
468
469 /**
470  *
471  * @attention defined in scaling.c
472  */
473 struct ImBuf *IMB_double_y(struct ImBuf *ibuf1);
474
475 /**
476  *
477  * @attention Defined in rotate.c
478  */
479 void IMB_flipx(struct ImBuf *ibuf);
480 void IMB_flipy(struct ImBuf *ibuf);
481
482 /* Premultiply alpha */
483
484 void IMB_premultiply_alpha(struct ImBuf *ibuf);
485
486 /**
487  *
488  * @attention Defined in allocimbuf.c
489  */
490 void IMB_freezbufImBuf(struct ImBuf *ibuf);
491 void IMB_freezbuffloatImBuf(struct ImBuf *ibuf);
492
493 /**
494  *
495  * @attention Defined in rectop.c
496  */
497 void IMB_rectfill(struct ImBuf *drect, const float col[4]);
498 void IMB_rectfill_area(struct ImBuf *ibuf, float *col, int x1, int y1, int x2, int y2);
499 void IMB_rectfill_alpha(struct ImBuf *ibuf, const float value);
500
501 /* this should not be here, really, we needed it for operating on render data, IMB_rectfill_area calls it */
502 void buf_rectfill_area(unsigned char *rect, float *rectf, int width, int height, float *col, int x1, int y1, int x2, int y2);
503
504 /* defined in metadata.c */
505 int IMB_metadata_change_field(struct ImBuf *img, const char *key, const char *field);
506
507 /* exported for image tools in blender, to quickly allocate 32 bits rect */
508 short imb_addrectImBuf(struct ImBuf *ibuf);
509 void imb_freerectImBuf(struct ImBuf *ibuf);
510
511 short imb_addrectfloatImBuf(struct ImBuf *ibuf);
512 void imb_freerectfloatImBuf(struct ImBuf *ibuf);
513 void imb_freemipmapImBuf(struct ImBuf *ibuf);
514
515 short imb_addtilesImBuf(struct ImBuf *ibuf);
516 void imb_freetilesImBuf(struct ImBuf *ibuf);
517
518 #endif
519