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