738e61dbe6e0aaba9fc995d494b4ad95a24b96d8
[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  * \brief IMage Buffer module.
34  *
35  * This module offers import/export of several graphical file formats.
36  * \ingroup imbuf
37  *
38  * \page IMB Imbuf module external interface
39  *
40  *
41  * \section about About the IMB module
42  *
43  * External interface of the IMage Buffer module. This module offers
44  * import/export of several graphical file formats. It offers the
45  * ImBuf type as a common structure to refer to different graphical
46  * file formats, and to enable a uniform way of handling them.
47  *
48  * \section issues Known issues with IMB
49  *
50  * - imbuf is written in C.
51  * - Endianness issues are dealt with internally.
52  * - File I/O must be done externally. The module uses FILE*'s to
53  *   direct input/output.
54  * - Platform dependency is limited. Some minor patches for
55  *   amiga and Irix are present. A 'posix-compliance-patch'
56  *   provides the interface to windows.
57  *
58  * \section dependencies Dependencies
59  *
60  * IMB needs:
61  * - \ref DNA module
62  *     The listbase types are used for handling the memory
63  *     management.
64  * - \ref blenlib module
65  *     blenlib handles guarded memory management in blender-style.
66  *     BLI_winstuff.h makes a few windows specific behaviors
67  *     posix-compliant.
68  */
69
70 #ifndef __IMB_IMBUF_H__
71 #define __IMB_IMBUF_H__
72
73 /**
74  *
75  * \attention defined in ???
76  */
77 struct ImBuf;
78
79 /**
80  *
81  * \attention defined in ???
82  */
83 struct anim;
84
85 /**
86  *
87  * \attention Defined in allocimbuf.c
88  */
89 void IMB_init(void);
90 void IMB_exit(void);
91
92 /**
93  *
94  * \attention Defined in readimage.c
95  */
96 struct ImBuf *IMB_ibImageFromMemory(unsigned char *mem, size_t size,
97                                     int flags, const char *descr);
98
99 /**
100  *
101  * \attention Defined in readimage.c
102  */
103 struct ImBuf *IMB_testiffname(const char *filepath, int flags);
104
105 /**
106  *
107  * \attention Defined in readimage.c
108  */
109 struct ImBuf *IMB_loadiffname(const char *filepath, 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 struct ImBuf *IMB_dupImBuf(struct ImBuf *ibuf1);
141
142 /**
143  *
144  * \attention Defined in allocimbuf.c
145  */
146 short addzbufImBuf(struct ImBuf *ibuf);
147 short addzbuffloatImBuf(struct ImBuf *ibuf);
148
149 /**
150  *
151  * \attention Defined in rectop.c
152  */
153
154 typedef enum IMB_BlendMode {
155         IMB_BLEND_MIX = 0,
156         IMB_BLEND_ADD = 1,
157         IMB_BLEND_SUB = 2,
158         IMB_BLEND_MUL = 3,
159         IMB_BLEND_LIGHTEN = 4,
160         IMB_BLEND_DARKEN = 5,
161         IMB_BLEND_ERASE_ALPHA = 6,
162         IMB_BLEND_ADD_ALPHA = 7,
163
164         IMB_BLEND_COPY = 1000,
165         IMB_BLEND_COPY_RGB = 1001,
166         IMB_BLEND_COPY_ALPHA = 1002
167 } IMB_BlendMode;
168
169 unsigned int IMB_blend_color(unsigned int src1, unsigned int src2, int fac,
170         IMB_BlendMode mode);
171 void IMB_blend_color_float(float *dst, float *src1, float *src2, float fac,
172         IMB_BlendMode mode);
173
174 void IMB_rectclip(struct ImBuf *dbuf, struct ImBuf *sbuf, int *destx, 
175         int *desty, int *srcx, int *srcy, int *width, int *height);
176 void IMB_rectcpy(struct ImBuf *drect, struct ImBuf *srect, int destx,
177         int desty, int srcx, int srcy, int width, int height);
178 void IMB_rectblend(struct ImBuf *dbuf, struct ImBuf *sbuf, int destx, 
179         int desty, int srcx, int srcy, int width, int height, IMB_BlendMode mode);
180
181 /**
182  *
183  * \attention Defined in indexer.c
184  */
185
186 typedef enum IMB_Timecode_Type {
187         IMB_TC_NONE       = 0, /* don't use timecode files at all */
188
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 that) */
195         IMB_TC_INTERPOLATED_REC_DATE_FREE_RUN = 4, /* interpolate a global timestamp using the
196                                                     * record date and time written by recording
197                                                     * device (*every* consumer camcorder can do
198                                                     * that :) )*/
199         IMB_TC_RECORD_RUN_NO_GAPS = 8,
200         IMB_TC_MAX_SLOT   = 4
201 } IMB_Timecode_Type;
202
203 typedef enum IMB_Proxy_Size {
204         IMB_PROXY_NONE = 0,
205         IMB_PROXY_25 = 1,
206         IMB_PROXY_50 = 2,
207         IMB_PROXY_75 = 4,
208         IMB_PROXY_100 = 8,
209         IMB_PROXY_MAX_SLOT = 4
210 } IMB_Proxy_Size;
211
212 /* defaults to BL_proxy within the directory of the animation */
213 void IMB_anim_set_index_dir(struct anim * anim, const char * dir);
214
215 int IMB_anim_index_get_frame_index(struct anim * anim, IMB_Timecode_Type tc,
216                                    int position);
217
218 struct IndexBuildContext;
219
220 /* prepare context for proxies/imecodes builder */
221 struct IndexBuildContext *IMB_anim_index_rebuild_context(struct anim *anim, IMB_Timecode_Type tcs_in_use,
222                                                          IMB_Proxy_Size proxy_sizes_in_use, int quality);
223
224 /* will rebuild all used indices and proxies at once */
225 void IMB_anim_index_rebuild(struct IndexBuildContext *context,
226                             short *stop, short *do_update, float *progress);
227
228 /* finish rebuilding proxises/timecodes and free temporary contexts used */
229 void IMB_anim_index_rebuild_finish(struct IndexBuildContext *context, short stop);
230
231 /**
232  * Return the length (in frames) of the given \a anim.
233  */
234 int IMB_anim_get_duration(struct anim *anim, IMB_Timecode_Type tc);
235
236
237 /**
238  * Return the fps contained in movie files (function rval is FALSE,
239  * and frs_sec and frs_sec_base untouched if none available!)
240  */
241 int IMB_anim_get_fps(struct anim * anim, 
242                      short * frs_sec, float * frs_sec_base);
243
244 /**
245  *
246  * \attention Defined in anim_movie.c
247  */
248 struct anim *IMB_open_anim(const char *name, int ib_flags, int streamindex);
249 void IMB_close_anim(struct anim *anim);
250 void IMB_close_anim_proxies(struct anim *anim);
251
252
253 /**
254  *
255  * \attention Defined in anim_movie.c
256  */
257
258 int ismovie(const char *filepath);
259 void IMB_anim_set_preseek(struct anim *anim, int preseek);
260 int IMB_anim_get_preseek(struct anim *anim);
261
262 /**
263  *
264  * \attention Defined in anim_movie.c
265  */
266
267 struct ImBuf *IMB_anim_absolute(
268         struct anim *anim, int position,
269         IMB_Timecode_Type tc        /* = 1 = IMB_TC_RECORD_RUN */, 
270         IMB_Proxy_Size preview_size /* = 0 = IMB_PROXY_NONE */);
271
272 /**
273  *
274  * \attention Defined in anim_movie.c
275  * fetches a define previewframe, usually half way into the movie
276  */
277 struct ImBuf *IMB_anim_previewframe(struct anim *anim);
278
279 /**
280  *
281  * \attention Defined in anim_movie.c
282  */
283 void IMB_free_anim(struct anim *anim);
284
285 /**
286  *
287  * \attention Defined in filter.c
288  */
289
290 #define FILTER_MASK_NULL                0
291 #define FILTER_MASK_MARGIN              1
292 #define FILTER_MASK_USED                2
293
294 void IMB_filter(struct ImBuf *ibuf);
295 void IMB_filterN(struct ImBuf *out, struct ImBuf *in);
296 void IMB_mask_filter_extend(char *mask, int width, int height);
297 void IMB_mask_clear(struct ImBuf *ibuf, char *mask, int val);
298 void IMB_filter_extend(struct ImBuf *ibuf, char *mask, int filter);
299 void IMB_makemipmap(struct ImBuf *ibuf, int use_filter);
300 void IMB_remakemipmap(struct ImBuf *ibuf, int use_filter);
301 struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level);
302
303 /**
304  *
305  * \attention Defined in cache.c
306  */
307
308 void IMB_tile_cache_params(int totthread, int maxmem);
309 unsigned int *IMB_gettile(struct ImBuf *ibuf, int tx, int ty, int thread);
310 void IMB_tiles_to_rect(struct ImBuf *ibuf);
311
312 /**
313  *
314  * \attention Defined in filter.c
315  */
316 void IMB_filtery(struct ImBuf *ibuf);
317
318 /**
319  *
320  * \attention Defined in scaling.c
321  */
322 struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1);
323
324 /**
325  *
326  * \attention Defined in scaling.c
327  */
328 struct ImBuf *IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
329
330 /**
331  *
332  * \attention Defined in scaling.c
333  */
334 struct ImBuf *IMB_scalefastImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
335
336 /**
337  *
338  * \attention Defined in writeimage.c
339  */
340 short IMB_saveiff(struct ImBuf *ibuf, const char *filepath, int flags);
341
342 /**
343  *
344  * \attention Defined in util.c
345  */
346 int IMB_ispic(const char *name);
347
348 /**
349  *
350  * \attention Defined in util.c
351  */
352 int IMB_isanim(const char *name);
353
354 /**
355  *
356  * \attention Defined in util.c
357  */
358 int imb_get_anim_type(const char *name);
359
360 /**
361  *
362  * \attention Defined in divers.c
363  */
364 void IMB_de_interlace(struct ImBuf *ibuf);
365 void IMB_interlace(struct ImBuf *ibuf);
366
367 /* create char buffer, color corrected if necessary, for ImBufs that lack one */ 
368 void IMB_rect_from_float(struct ImBuf *ibuf);
369 /* Create char buffer for part of the image, color corrected if necessary,
370  * Changed part will be stored in buffer. This is expected to be used for texture painting updates */
371 void IMB_partial_rect_from_float(struct ImBuf *ibuf, float *buffer, int x, int y, int w, int h);
372 void IMB_float_from_rect(struct ImBuf *ibuf);
373 void IMB_float_from_rect_simple(struct ImBuf *ibuf); /* no profile conversion */
374 /* note, check that the conversion exists, only some are supported */
375 void IMB_convert_profile(struct ImBuf *ibuf, int profile);
376 float *IMB_float_profile_ensure(struct ImBuf *ibuf, int profile, int *alloc);
377 void IMB_color_to_bw(struct ImBuf *ibuf);
378 void IMB_saturation(struct ImBuf *ibuf, float sat);
379
380 /* converting pixel buffers */
381 void IMB_buffer_byte_from_float(unsigned char *rect_to, const float *rect_from,
382         int channels_from, float dither, int profile_to, int profile_from, int predivide,
383         int width, int height, int stride_to, int stride_from);
384 void IMB_buffer_float_from_byte(float *rect_to, const unsigned char *rect_from,
385         int profile_to, int profile_from, int predivide,
386         int width, int height, int stride_to, int stride_from);
387 void IMB_buffer_float_from_float(float *rect_to, const float *rect_from,
388         int channels_from, int profile_to, int profile_from, int predivide,
389         int width, int height, int stride_to, int stride_from);
390 void IMB_buffer_byte_from_byte(unsigned char *rect_to, const unsigned char *rect_from,
391         int profile_to, int profile_from, int predivide,
392         int width, int height, int stride_to, int stride_from);
393 void IMB_buffer_float_clamp(float *buf, int width, int height);
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  *
405  * \attention defined in imageprocess.c
406  */
407 void bicubic_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
408 void neareast_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
409 void bilinear_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
410
411 void bicubic_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
412 void neareast_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
413 void bilinear_interpolation_color(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
414 void bilinear_interpolation_color_wrap(struct ImBuf *in, unsigned char *col, float *col_float, float u, float v);
415
416 /**
417  *
418  * \attention defined in readimage.c
419  */  
420 struct ImBuf *IMB_loadifffile(int file, int flags, const char *descr);
421
422 /**
423  *
424  * \attention defined in scaling.c
425  */
426 struct ImBuf *IMB_half_x(struct ImBuf *ibuf1);
427
428 /**
429  *
430  * \attention defined in scaling.c
431  */
432 struct ImBuf *IMB_double_fast_x(struct ImBuf *ibuf1);
433
434 /**
435  *
436  * \attention defined in scaling.c
437  */
438 struct ImBuf *IMB_double_x(struct ImBuf *ibuf1);
439
440 /**
441  *
442  * \attention defined in scaling.c
443  */
444 struct ImBuf *IMB_half_y(struct ImBuf *ibuf1);
445
446 /**
447  *
448  * \attention defined in scaling.c
449  */
450 struct ImBuf *IMB_double_fast_y(struct ImBuf *ibuf1);
451
452 /**
453  *
454  * \attention defined in scaling.c
455  */
456 struct ImBuf *IMB_double_y(struct ImBuf *ibuf1);
457
458 /**
459  *
460  * \attention Defined in rotate.c
461  */
462 void IMB_flipx(struct ImBuf *ibuf);
463 void IMB_flipy(struct ImBuf *ibuf);
464
465 /* Premultiply alpha */
466
467 void IMB_premultiply_alpha(struct ImBuf *ibuf);
468
469 /**
470  *
471  * \attention Defined in allocimbuf.c
472  */
473 void IMB_freezbufImBuf(struct ImBuf *ibuf);
474 void IMB_freezbuffloatImBuf(struct ImBuf *ibuf);
475
476 /**
477  *
478  * \attention Defined in rectop.c
479  */
480 void IMB_rectfill(struct ImBuf *drect, const float col[4]);
481 void IMB_rectfill_area(struct ImBuf *ibuf, const float col[4], int x1, int y1, int x2, int y2);
482 void IMB_rectfill_alpha(struct ImBuf *ibuf, const float value);
483
484 /* this should not be here, really, we needed it for operating on render data, IMB_rectfill_area calls it */
485 void buf_rectfill_area(unsigned char *rect, float *rectf, int width, int height,
486                                            const float col[4], const int do_color_management,
487                                            int x1, int y1, int x2, int y2);
488
489 /* defined in metadata.c */
490 int IMB_metadata_change_field(struct ImBuf *img, const char *key, const char *field);
491
492 /* exported for image tools in blender, to quickly allocate 32 bits rect */
493 short imb_addrectImBuf(struct ImBuf *ibuf);
494 void imb_freerectImBuf(struct ImBuf *ibuf);
495
496 short imb_addrectfloatImBuf(struct ImBuf *ibuf);
497 void imb_freerectfloatImBuf(struct ImBuf *ibuf);
498 void imb_freemipmapImBuf(struct ImBuf *ibuf);
499
500 short imb_addtilesImBuf(struct ImBuf *ibuf);
501 void imb_freetilesImBuf(struct ImBuf *ibuf);
502
503 /* threaded processors */
504 void IMB_processor_apply_threaded(int buffer_lines, int handle_size, void *init_customdata,
505                                   void (init_handle) (void *handle, int start_line, int tot_line,
506                                                       void *customdata),
507                                   void *(do_thread) (void *));
508
509 #endif
510