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