svn merge ^/trunk/blender -r42927:42931
[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,
98                                     int flags, const char *descr);
99
100 /**
101  *
102  * @attention Defined in readimage.c
103  */
104 struct ImBuf *IMB_testiffname(const char *filepath, int flags);
105
106 /**
107  *
108  * @attention Defined in readimage.c
109  */
110 struct ImBuf *IMB_loadiffname(const char *filepath, int flags);
111
112 /**
113  *
114  * @attention Defined in allocimbuf.c
115  */
116 void IMB_freeImBuf(struct ImBuf *ibuf);
117
118 /**
119  *
120  * @attention Defined in allocimbuf.c
121  */
122 struct ImBuf *IMB_allocImBuf(unsigned int x, unsigned int y,
123                              unsigned char d, unsigned int flags);
124
125 /**
126  *
127  * Increase reference count to imbuf
128  * (to delete an imbuf you have to call freeImBuf as many times as it
129  * is referenced)
130  *
131  * @attention Defined in allocimbuf.c
132  */
133
134 void IMB_refImBuf(struct ImBuf *ibuf);
135 struct ImBuf * IMB_makeSingleUser(struct ImBuf *ibuf);
136
137 /**
138  *
139  * @attention Defined in allocimbuf.c
140  */
141 struct ImBuf *IMB_dupImBuf(struct ImBuf *ibuf1);
142
143 /**
144  *
145  * @attention Defined in allocimbuf.c
146  */
147 short addzbufImBuf(struct ImBuf *ibuf);
148 short addzbuffloatImBuf(struct ImBuf *ibuf);
149
150 /**
151  *
152  * @attention Defined in rectop.c
153  */
154
155 typedef enum IMB_BlendMode {
156         IMB_BLEND_MIX = 0,
157         IMB_BLEND_ADD = 1,
158         IMB_BLEND_SUB = 2,
159         IMB_BLEND_MUL = 3,
160         IMB_BLEND_LIGHTEN = 4,
161         IMB_BLEND_DARKEN = 5,
162         IMB_BLEND_ERASE_ALPHA = 6,
163         IMB_BLEND_ADD_ALPHA = 7,
164
165         IMB_BLEND_COPY = 1000,
166         IMB_BLEND_COPY_RGB = 1001,
167         IMB_BLEND_COPY_ALPHA = 1002
168 } IMB_BlendMode;
169
170 unsigned int IMB_blend_color(unsigned int src1, unsigned int src2, int fac,
171         IMB_BlendMode mode);
172 void IMB_blend_color_float(float *dst, float *src1, float *src2, float fac,
173         IMB_BlendMode mode);
174
175 void IMB_rectclip(struct ImBuf *dbuf, struct ImBuf *sbuf, int *destx, 
176         int *desty, int *srcx, int *srcy, int *width, int *height);
177 void IMB_rectcpy(struct ImBuf *drect, struct ImBuf *srect, int destx,
178         int desty, int srcx, int srcy, int width, int height);
179 void IMB_rectblend(struct ImBuf *dbuf, struct ImBuf *sbuf, int destx, 
180         int desty, int srcx, int srcy, int width, int height, IMB_BlendMode mode);
181
182 /**
183  *
184  * @attention Defined in indexer.c
185  */
186
187 typedef enum IMB_Timecode_Type {
188         IMB_TC_NONE       = 0, /* don't use timecode files at all */
189         IMB_TC_RECORD_RUN = 1, /* use images in the order as they are recorded 
190                                   (currently, this is the only one implemented
191                                   and is a sane default)
192                                */
193         IMB_TC_FREE_RUN   = 2, /* use global timestamp written by recording
194                                   device (prosumer camcorders e.g. can do
195                                   that) */
196         IMB_TC_INTERPOLATED_REC_DATE_FREE_RUN = 4, 
197                                /* interpolate a global timestamp using the
198                                   record date and time written by recording
199                                   device (*every* consumer camcorder can do
200                                   that :) )*/
201         IMB_TC_RECORD_RUN_NO_GAPS = 8,
202         IMB_TC_MAX_SLOT   = 8
203 } IMB_Timecode_Type;
204
205 typedef enum IMB_Proxy_Size {
206         IMB_PROXY_NONE = 0,
207         IMB_PROXY_25 = 1,
208         IMB_PROXY_50 = 2,
209         IMB_PROXY_75 = 4,
210         IMB_PROXY_100 = 8,
211         IMB_PROXY_MAX_SLOT = 4
212 } IMB_Proxy_Size;
213
214 /* defaults to BL_proxy within the directory of the animation */
215 void IMB_anim_set_index_dir(struct anim * anim, const char * dir);
216
217 int IMB_anim_index_get_frame_index(struct anim * anim, IMB_Timecode_Type tc,
218                                    int position);
219
220 /* will rebuild all used indices and proxies at once */
221 void IMB_anim_index_rebuild(struct anim * anim, 
222                             IMB_Timecode_Type build_tcs,
223                             IMB_Proxy_Size build_preview_sizes,
224                             int build_quality,
225                             short *stop, short *do_update, float *progress);
226
227 /**
228  * Return the length (in frames) of the given @a anim.
229  */
230 int IMB_anim_get_duration(struct anim *anim, IMB_Timecode_Type tc);
231
232
233 /**
234  * Return the fps contained in movie files (function rval is FALSE,
235  * and frs_sec and frs_sec_base untouched if none available!)
236  */
237 int IMB_anim_get_fps(struct anim * anim, 
238                      short * frs_sec, float * frs_sec_base);
239
240 /**
241  *
242  * @attention Defined in anim_movie.c
243  */
244 struct anim *IMB_open_anim(const char *name, int ib_flags, int streamindex);
245 void IMB_close_anim(struct anim *anim);
246
247
248 /**
249  *
250  * @attention Defined in anim_movie.c
251  */
252
253 int ismovie(const char *filepath);
254 void IMB_anim_set_preseek(struct anim *anim, int preseek);
255 int IMB_anim_get_preseek(struct anim *anim);
256
257 /**
258  *
259  * @attention Defined in anim_movie.c
260  */
261
262 struct ImBuf *IMB_anim_absolute(
263         struct anim *anim, int position,
264         IMB_Timecode_Type tc        /* = 1 = IMB_TC_RECORD_RUN */, 
265         IMB_Proxy_Size preview_size /* = 0 = IMB_PROXY_NONE */);
266
267 /**
268  *
269  * @attention Defined in anim_movie.c
270  * fetches a define previewframe, usually half way into the movie
271  */
272 struct ImBuf *IMB_anim_previewframe(struct anim *anim);
273
274 /**
275  *
276  * @attention Defined in anim_movie.c
277  */
278 void IMB_free_anim(struct anim *anim);
279
280 /**
281  *
282  * @attention Defined in filter.c
283  */
284
285 #define FILTER_MASK_NULL                0
286 #define FILTER_MASK_MARGIN              1
287 #define FILTER_MASK_USED                2
288
289 void IMB_filter(struct ImBuf *ibuf);
290 void IMB_filterN(struct ImBuf *out, struct ImBuf *in);
291 void IMB_mask_filter_extend(char *mask, int width, int height);
292 void IMB_mask_clear(struct ImBuf *ibuf, char *mask, int val);
293 void IMB_filter_extend(struct ImBuf *ibuf, char *mask, int filter);
294 void IMB_makemipmap(struct ImBuf *ibuf, int use_filter);
295 void IMB_remakemipmap(struct ImBuf *ibuf, int use_filter);
296 struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level);
297
298 /**
299  *
300  * @attention Defined in cache.c
301  */
302
303 void IMB_tile_cache_params(int totthread, int maxmem);
304 unsigned int *IMB_gettile(struct ImBuf *ibuf, int tx, int ty, int thread);
305 void IMB_tiles_to_rect(struct ImBuf *ibuf);
306
307 /**
308  *
309  * @attention Defined in filter.c
310  */
311 void IMB_filtery(struct ImBuf *ibuf);
312
313 /**
314  *
315  * @attention Defined in scaling.c
316  */
317 struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1);
318
319 /**
320  *
321  * @attention Defined in scaling.c
322  */
323 struct ImBuf *IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
324
325 /**
326  *
327  * @attention Defined in scaling.c
328  */
329 struct ImBuf *IMB_scalefastImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
330
331 /**
332  *
333  * @attention Defined in writeimage.c
334  */
335 short IMB_saveiff(struct ImBuf *ibuf, const char *filepath, int flags);
336
337 /**
338  * Encodes a png image from an ImBuf
339  *
340  * @attention Defined in png_encode.c
341  */
342 short IMB_png_encode(struct ImBuf *ibuf, int file, int flags);
343
344 /**
345  *
346  * @attention Defined in util.c
347  */
348 int IMB_ispic(const char *name);
349
350 /**
351  *
352  * @attention Defined in util.c
353  */
354 int IMB_isanim(const char *name);
355
356 /**
357  *
358  * @attention Defined in util.c
359  */
360 int imb_get_anim_type(const char *name);
361
362 /**
363  *
364  * @attention Defined in divers.c
365  */
366 void IMB_de_interlace(struct ImBuf *ibuf);
367 void IMB_interlace(struct ImBuf *ibuf);
368
369 /* create char buffer, color corrected if necessary, for ImBufs that lack one */ 
370 void IMB_rect_from_float(struct ImBuf *ibuf);
371 /* create char buffer for part of the image, color corrected if necessary,
372    Changed part will be stored in buffer. This is expected to be used for texture painting updates */ 
373 void IMB_partial_rect_from_float(struct ImBuf *ibuf, float *buffer, int x, int y, int w, int h);
374 void IMB_float_from_rect(struct ImBuf *ibuf);
375 void IMB_float_from_rect_simple(struct ImBuf *ibuf); /* no profile conversion */
376 /* note, check that the conversion exists, only some are supported */
377 void IMB_convert_profile(struct ImBuf *ibuf, int profile);
378 float *IMB_float_profile_ensure(struct ImBuf *ibuf, int profile, int *alloc);
379 void IMB_color_to_bw(struct ImBuf *ibuf);
380
381 /* converting pixel buffers */
382 void IMB_buffer_byte_from_float(unsigned char *rect_to, const float *rect_from,
383         int channels_from, int dither, int profile_to, int profile_from, int predivide,
384         int width, int height, int stride_to, int stride_from);
385 void IMB_buffer_float_from_byte(float *rect_to, const unsigned char *rect_from,
386         int profile_to, int profile_from, int predivide,
387         int width, int height, int stride_to, int stride_from);
388 void IMB_buffer_float_from_float(float *rect_to, const float *rect_from,
389         int channels_from, int profile_to, int profile_from, int predivide,
390         int width, int height, int stride_to, int stride_from);
391 void IMB_buffer_byte_from_byte(unsigned char *rect_to, const unsigned char *rect_from,
392         int profile_to, int profile_from, int predivide,
393         int width, int height, int stride_to, int stride_from);
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  * Change the ordering of the color bytes pointed to by rect from
405  * rgba to abgr. size * 4 color bytes are reordered.
406  *
407  * @attention Defined in imageprocess.c
408  */
409 void IMB_convert_bgra_to_rgba(int size, unsigned int *rect);
410
411 /**
412  *
413  * @attention defined in imageprocess.c
414  */
415 void bicubic_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
416 void neareast_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
417 void bilinear_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
418
419 void bicubic_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
420 void neareast_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
421 void bilinear_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
422 void bilinear_interpolation_color_wrap(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
423
424 /**
425  *
426  * @attention defined in readimage.c
427  * @deprecated Only here for backwards compatibility of the
428  * @deprecated plugin system.
429  */
430 struct ImBuf *IMB_loadiffmem(int *mem, int flags);
431
432 /**
433  *
434  * @attention defined in readimage.c
435  * @deprecated Only here for backwards compatibility of the
436  * @deprecated plugin system.
437  */  
438 struct ImBuf *IMB_loadifffile(int file, int flags, const char *descr);
439
440 /**
441  *
442  * @attention defined in scaling.c
443  */
444 struct ImBuf *IMB_half_x(struct ImBuf *ibuf1);
445
446 /**
447  *
448  * @attention defined in scaling.c
449  */
450 struct ImBuf *IMB_double_fast_x(struct ImBuf *ibuf1);
451
452 /**
453  *
454  * @attention defined in scaling.c
455  */
456 struct ImBuf *IMB_double_x(struct ImBuf *ibuf1);
457
458 /**
459  *
460  * @attention defined in scaling.c
461  */
462 struct ImBuf *IMB_half_y(struct ImBuf *ibuf1);
463
464 /**
465  *
466  * @attention defined in scaling.c
467  */
468 struct ImBuf *IMB_double_fast_y(struct ImBuf *ibuf1);
469
470 /**
471  *
472  * @attention defined in scaling.c
473  */
474 struct ImBuf *IMB_double_y(struct ImBuf *ibuf1);
475
476 /**
477  *
478  * @attention Defined in rotate.c
479  */
480 void IMB_flipx(struct ImBuf *ibuf);
481 void IMB_flipy(struct ImBuf *ibuf);
482
483 /* Premultiply alpha */
484
485 void IMB_premultiply_alpha(struct ImBuf *ibuf);
486
487 /**
488  *
489  * @attention Defined in allocimbuf.c
490  */
491 void IMB_freezbufImBuf(struct ImBuf *ibuf);
492 void IMB_freezbuffloatImBuf(struct ImBuf *ibuf);
493
494 /**
495  *
496  * @attention Defined in rectop.c
497  */
498 void IMB_rectfill(struct ImBuf *drect, const float col[4]);
499 void IMB_rectfill_area(struct ImBuf *ibuf, float *col, int x1, int y1, int x2, int y2);
500 void IMB_rectfill_alpha(struct ImBuf *ibuf, const float value);
501
502 /* this should not be here, really, we needed it for operating on render data, IMB_rectfill_area calls it */
503 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);
504
505 /* defined in metadata.c */
506 int IMB_metadata_change_field(struct ImBuf *img, const char *key, const char *field);
507
508 /* exported for image tools in blender, to quickly allocate 32 bits rect */
509 short imb_addrectImBuf(struct ImBuf *ibuf);
510 void imb_freerectImBuf(struct ImBuf *ibuf);
511
512 short imb_addrectfloatImBuf(struct ImBuf *ibuf);
513 void imb_freerectfloatImBuf(struct ImBuf *ibuf);
514 void imb_freemipmapImBuf(struct ImBuf *ibuf);
515
516 short imb_addtilesImBuf(struct ImBuf *ibuf);
517 void imb_freetilesImBuf(struct ImBuf *ibuf);
518
519 #endif
520