Merge branch 'blender2.7'
[blender.git] / source / blender / imbuf / IMB_imbuf.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
17  * All rights reserved.
18  */
19
20 /** \file \ingroup imbuf
21  */
22
23 /**
24  * \brief IMage Buffer module.
25  *
26  * This module offers import/export of several graphical file formats.
27  * \ingroup imbuf
28  *
29  * \page IMB Imbuf module external interface
30  * \section imb_about About the IMB module
31  *
32  * External interface of the IMage Buffer module. This module offers
33  * import/export of several graphical file formats. It offers the
34  * ImBuf type as a common structure to refer to different graphical
35  * file formats, and to enable a uniform way of handling them.
36  *
37  * \section imb_issues Known issues with IMB
38  *
39  * - imbuf is written in C.
40  * - Endianness issues are dealt with internally.
41  * - File I/O must be done externally. The module uses FILE*'s to
42  *   direct input/output.
43  *
44  * \section imb_dependencies Dependencies
45  *
46  * IMB needs:
47  * - \ref DNA module
48  *     The listbase types are used for handling the memory
49  *     management.
50  * - \ref blenlib module
51  *     blenlib handles guarded memory management in blender-style.
52  *     BLI_winstuff.h makes a few windows specific behaviors
53  *     posix-compliant.
54  */
55
56 #ifndef __IMB_IMBUF_H__
57 #define __IMB_IMBUF_H__
58
59 #define IM_MAX_SPACE 64
60
61 /* for bool */
62 #include "../blenlib/BLI_sys_types.h"
63
64 /**
65  *
66  * \attention defined in ???
67  */
68 struct ImBuf;
69
70 /**
71  *
72  * \attention defined in ???
73  */
74 struct anim;
75
76 struct ColorManagedDisplay;
77
78 struct GSet;
79 /**
80  *
81  * \attention defined in DNA_scene_types.h
82  */
83 struct ImageFormatData;
84 struct Stereo3dFormat;
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, char colorspace[IM_MAX_SPACE], 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, char colorspace[IM_MAX_SPACE]);
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 planes, unsigned int flags);
123
124 /**
125  * Initialize given ImBuf.
126  *
127  * Use in cases when temporary image buffer is allocated on stack.
128  *
129  * \attention Defined in allocimbuf.c
130  */
131 bool IMB_initImBuf(struct ImBuf *ibuf,
132                    unsigned int x, unsigned int y,
133                    unsigned char planes, unsigned int flags);
134
135 /**
136  * Create a copy of a pixel buffer and wrap it to a new ImBuf
137  * \attention Defined in allocimbuf.c
138  */
139 struct ImBuf *IMB_allocFromBuffer(const unsigned int *rect, const float *rectf,
140                                   unsigned int w, unsigned int h);
141
142 /**
143  *
144  * Increase reference count to imbuf
145  * (to delete an imbuf you have to call freeImBuf as many times as it
146  * is referenced)
147  *
148  * \attention Defined in allocimbuf.c
149  */
150
151 void IMB_refImBuf(struct ImBuf *ibuf);
152 struct ImBuf *IMB_makeSingleUser(struct ImBuf *ibuf);
153
154 /**
155  *
156  * \attention Defined in allocimbuf.c
157  */
158 struct ImBuf *IMB_dupImBuf(const struct ImBuf *ibuf1);
159
160 /**
161  *
162  * \attention Defined in allocimbuf.c
163  */
164 bool addzbufImBuf(struct ImBuf *ibuf);
165 bool addzbuffloatImBuf(struct ImBuf *ibuf);
166
167 /**
168  *
169  * \attention Defined in rectop.c
170  */
171
172 typedef enum IMB_BlendMode {
173         IMB_BLEND_MIX = 0,
174         IMB_BLEND_ADD = 1,
175         IMB_BLEND_SUB = 2,
176         IMB_BLEND_MUL = 3,
177         IMB_BLEND_LIGHTEN = 4,
178         IMB_BLEND_DARKEN = 5,
179         IMB_BLEND_ERASE_ALPHA = 6,
180         IMB_BLEND_ADD_ALPHA = 7,
181         IMB_BLEND_OVERLAY = 8,
182         IMB_BLEND_HARDLIGHT     = 9,
183         IMB_BLEND_COLORBURN     = 10,
184         IMB_BLEND_LINEARBURN = 11,
185         IMB_BLEND_COLORDODGE = 12,
186         IMB_BLEND_SCREEN = 13,
187         IMB_BLEND_SOFTLIGHT     = 14,
188         IMB_BLEND_PINLIGHT = 15,
189         IMB_BLEND_VIVIDLIGHT = 16,
190         IMB_BLEND_LINEARLIGHT = 17,
191         IMB_BLEND_DIFFERENCE = 18,
192         IMB_BLEND_EXCLUSION     = 19,
193         IMB_BLEND_HUE = 20,
194         IMB_BLEND_SATURATION = 21,
195         IMB_BLEND_LUMINOSITY = 22,
196         IMB_BLEND_COLOR = 23,
197         IMB_BLEND_INTERPOLATE = 24,
198
199         IMB_BLEND_COPY = 1000,
200         IMB_BLEND_COPY_RGB = 1001,
201         IMB_BLEND_COPY_ALPHA = 1002,
202 } IMB_BlendMode;
203
204 void IMB_blend_color_byte(unsigned char dst[4], unsigned char src1[4],
205         unsigned char src2[4], IMB_BlendMode mode);
206 void IMB_blend_color_float(float dst[4], float src1[4], float src2[4],
207         IMB_BlendMode mode);
208
209 void IMB_rectclip(struct ImBuf *dbuf, struct ImBuf *sbuf, int *destx,
210         int *desty, int *srcx, int *srcy, int *width, int *height);
211 void IMB_rectcpy(struct ImBuf *drect, struct ImBuf *srect, int destx,
212         int desty, int srcx, int srcy, int width, int height);
213 void IMB_rectblend(struct ImBuf *dbuf, struct ImBuf *obuf, struct ImBuf *sbuf,
214         unsigned short *dmask, unsigned short *curvemask, unsigned short *mmask, float mask_max,
215         int destx,  int desty, int origx, int origy, int srcx, int srcy,
216         int width, int height, IMB_BlendMode mode, bool accumulate);
217 void IMB_rectblend_threaded(struct ImBuf *dbuf, struct ImBuf *obuf, struct ImBuf *sbuf,
218         unsigned short *dmask, unsigned short *curvemask, unsigned short *mmask, float mask_max,
219         int destx,  int desty, int origx, int origy, int srcx, int srcy,
220         int width, int height, IMB_BlendMode mode, bool accumulate);
221
222 /**
223  *
224  * \attention Defined in indexer.c
225  */
226
227 typedef enum IMB_Timecode_Type {
228         IMB_TC_NONE       = 0, /* don't use timecode files at all */
229
230         IMB_TC_RECORD_RUN = 1, /* use images in the order as they are recorded
231                                 * (currently, this is the only one implemented
232                                 * and is a sane default) */
233
234         IMB_TC_FREE_RUN   = 2, /* use global timestamp written by recording
235                                 * device (prosumer camcorders e.g. can do that) */
236         IMB_TC_INTERPOLATED_REC_DATE_FREE_RUN = 4, /* interpolate a global timestamp using the
237                                                     * record date and time written by recording
238                                                     * device (*every* consumer camcorder can do
239                                                     * that :) )*/
240         IMB_TC_RECORD_RUN_NO_GAPS = 8,
241         IMB_TC_MAX_SLOT   = 4,
242 } IMB_Timecode_Type;
243
244 typedef enum IMB_Proxy_Size {
245         IMB_PROXY_NONE = 0,
246         IMB_PROXY_25 = 1,
247         IMB_PROXY_50 = 2,
248         IMB_PROXY_75 = 4,
249         IMB_PROXY_100 = 8,
250         IMB_PROXY_MAX_SLOT = 4,
251 } IMB_Proxy_Size;
252
253 /* defaults to BL_proxy within the directory of the animation */
254 void IMB_anim_set_index_dir(struct anim *anim, const char *dir);
255 void IMB_anim_get_fname(struct anim *anim, char *file, int size);
256
257 int IMB_anim_index_get_frame_index(struct anim *anim, IMB_Timecode_Type tc,
258                                    int position);
259
260 IMB_Proxy_Size IMB_anim_proxy_get_existing(struct anim *anim);
261
262 struct IndexBuildContext;
263
264 /* prepare context for proxies/imecodes builder */
265 struct IndexBuildContext *IMB_anim_index_rebuild_context(struct anim *anim, IMB_Timecode_Type tcs_in_use,
266                                                          IMB_Proxy_Size proxy_sizes_in_use, int quality,
267                                                          const bool overwite, struct GSet *file_list);
268
269 /* will rebuild all used indices and proxies at once */
270 void IMB_anim_index_rebuild(struct IndexBuildContext *context,
271                             short *stop, short *do_update, float *progress);
272
273 /* finish rebuilding proxises/timecodes and free temporary contexts used */
274 void IMB_anim_index_rebuild_finish(struct IndexBuildContext *context, short stop);
275
276 /**
277  * Return the length (in frames) of the given \a anim.
278  */
279 int IMB_anim_get_duration(struct anim *anim, IMB_Timecode_Type tc);
280
281
282 /**
283  * Return the fps contained in movie files (function rval is false,
284  * and frs_sec and frs_sec_base untouched if none available!)
285  */
286 bool IMB_anim_get_fps(struct anim *anim,
287                       short *frs_sec, float *frs_sec_base, bool no_av_base);
288
289 /**
290  *
291  * \attention Defined in anim_movie.c
292  */
293 struct anim *IMB_open_anim(const char *name, int ib_flags, int streamindex, char colorspace[IM_MAX_SPACE]);
294 void IMB_suffix_anim(struct anim *anim, const char *suffix);
295 void IMB_close_anim(struct anim *anim);
296 void IMB_close_anim_proxies(struct anim *anim);
297
298 /**
299  *
300  * \attention Defined in anim_movie.c
301  */
302
303 int ismovie(const char *filepath);
304 void IMB_anim_set_preseek(struct anim *anim, int preseek);
305 int IMB_anim_get_preseek(struct anim *anim);
306
307 /**
308  *
309  * \attention Defined in anim_movie.c
310  */
311
312 struct ImBuf *IMB_anim_absolute(
313         struct anim *anim, int position,
314         IMB_Timecode_Type tc        /* = 1 = IMB_TC_RECORD_RUN */,
315         IMB_Proxy_Size preview_size /* = 0 = IMB_PROXY_NONE */);
316
317 /**
318  *
319  * \attention Defined in anim_movie.c
320  * fetches a define previewframe, usually half way into the movie
321  */
322 struct ImBuf *IMB_anim_previewframe(struct anim *anim);
323
324 /**
325  *
326  * \attention Defined in anim_movie.c
327  */
328 void IMB_free_anim(struct anim *anim);
329
330 /**
331  *
332  * \attention Defined in filter.c
333  */
334
335 #define FILTER_MASK_NULL                0
336 #define FILTER_MASK_MARGIN              1
337 #define FILTER_MASK_USED                2
338
339 void IMB_filter(struct ImBuf *ibuf);
340 void IMB_mask_filter_extend(char *mask, int width, int height);
341 void IMB_mask_clear(struct ImBuf *ibuf, char *mask, int val);
342 void IMB_filter_extend(struct ImBuf *ibuf, char *mask, int filter);
343 void IMB_makemipmap(struct ImBuf *ibuf, int use_filter);
344 void IMB_remakemipmap(struct ImBuf *ibuf, int use_filter);
345 struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level);
346
347 /**
348  *
349  * \attention Defined in cache.c
350  */
351
352 void IMB_tile_cache_params(int totthread, int maxmem);
353 unsigned int *IMB_gettile(struct ImBuf *ibuf, int tx, int ty, int thread);
354 void IMB_tiles_to_rect(struct ImBuf *ibuf);
355
356 /**
357  *
358  * \attention Defined in filter.c
359  */
360 void IMB_filtery(struct ImBuf *ibuf);
361
362 /**
363  *
364  * \attention Defined in scaling.c
365  */
366 struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1);
367
368 /**
369  *
370  * \attention Defined in scaling.c
371  */
372 bool IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
373
374 /**
375  *
376  * \attention Defined in scaling.c
377  */
378 bool IMB_scalefastImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
379
380 /**
381  *
382  * \attention Defined in scaling.c
383  */
384 void IMB_scaleImBuf_threaded(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
385
386 /**
387  *
388  * \attention Defined in writeimage.c
389  */
390 short IMB_saveiff(struct ImBuf *ibuf, const char *filepath, int flags);
391 bool IMB_prepare_write_ImBuf(const bool isfloat, struct ImBuf *ibuf);
392
393 /**
394  *
395  * \attention Defined in util.c
396  */
397 bool IMB_ispic(const char *name);
398 int  IMB_ispic_type(const char *name);
399
400 /**
401  *
402  * \attention Defined in util.c
403  */
404 bool IMB_isanim(const char *name);
405
406 /**
407  *
408  * \attention Defined in util.c
409  */
410 int imb_get_anim_type(const char *name);
411
412 /**
413  *
414  * \attention Defined in util.c
415  */
416 bool IMB_isfloat(struct ImBuf *ibuf);
417
418 /* create char buffer, color corrected if necessary, for ImBufs that lack one */
419 void IMB_rect_from_float(struct ImBuf *ibuf);
420 /* Create char buffer for part of the image, color corrected if necessary,
421  * Changed part will be stored in buffer. This is expected to be used for texture painting updates */
422 void IMB_partial_rect_from_float(struct ImBuf *ibuf, float *buffer, int x, int y, int w, int h, bool is_data);
423 void IMB_float_from_rect(struct ImBuf *ibuf);
424 void IMB_color_to_bw(struct ImBuf *ibuf);
425 void IMB_saturation(struct ImBuf *ibuf, float sat);
426
427 /* converting pixel buffers */
428 void IMB_buffer_byte_from_float(unsigned char *rect_to, const float *rect_from,
429         int channels_from, float dither, int profile_to, int profile_from, bool predivide,
430         int width, int height, int stride_to, int stride_from);
431 void IMB_buffer_byte_from_float_mask(unsigned char *rect_to, const float *rect_from,
432         int channels_from, float dither, bool predivide,
433         int width, int height, int stride_to, int stride_from, char *mask);
434 void IMB_buffer_float_from_byte(float *rect_to, const unsigned char *rect_from,
435         int profile_to, int profile_from, bool predivide,
436         int width, int height, int stride_to, int stride_from);
437 void IMB_buffer_float_from_float(float *rect_to, const float *rect_from,
438         int channels_from, int profile_to, int profile_from, bool predivide,
439         int width, int height, int stride_to, int stride_from);
440 void IMB_buffer_float_from_float_threaded(float *rect_to, const float *rect_from,
441         int channels_from, int profile_to, int profile_from, bool predivide,
442         int width, int height, int stride_to, int stride_from);
443 void IMB_buffer_float_from_float_mask(float *rect_to, const float *rect_from,
444         int channels_from, int width, int height, int stride_to, int stride_from, char *mask);
445 void IMB_buffer_byte_from_byte(unsigned char *rect_to, const unsigned char *rect_from,
446         int profile_to, int profile_from, bool predivide,
447         int width, int height, int stride_to, int stride_from);
448 void IMB_buffer_float_clamp(float *buf, int width, int height);
449 void IMB_buffer_float_unpremultiply(float *buf, int width, int height);
450 void IMB_buffer_float_premultiply(float *buf, int width, int height);
451
452 /**
453  * Change the ordering of the color bytes pointed to by rect from
454  * rgba to abgr. size * 4 color bytes are reordered.
455  *
456  * \attention Defined in imageprocess.c
457  */
458 void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf);
459
460 /**
461  *
462  * \attention defined in imageprocess.c
463  */
464 void bicubic_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
465 void nearest_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
466 void bilinear_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
467
468 void bicubic_interpolation_color(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
469 void nearest_interpolation_color(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
470 void nearest_interpolation_color_wrap(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
471 void bilinear_interpolation_color(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
472 void bilinear_interpolation_color_wrap(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
473
474 void IMB_alpha_under_color_float(float *rect_float, int x, int y, float backcol[3]);
475 void IMB_alpha_under_color_byte(unsigned char *rect, int x, int y, float backcol[3]);
476
477 /**
478  *
479  * \attention defined in readimage.c
480  */
481 struct ImBuf *IMB_loadifffile(int file, const char *filepath, int flags, char colorspace[IM_MAX_SPACE], const char *descr);
482
483 /**
484  *
485  * \attention defined in scaling.c
486  */
487 struct ImBuf *IMB_half_x(struct ImBuf *ibuf1);
488
489 /**
490  *
491  * \attention defined in scaling.c
492  */
493 struct ImBuf *IMB_double_fast_x(struct ImBuf *ibuf1);
494
495 /**
496  *
497  * \attention defined in scaling.c
498  */
499 struct ImBuf *IMB_double_x(struct ImBuf *ibuf1);
500
501 /**
502  *
503  * \attention defined in scaling.c
504  */
505 struct ImBuf *IMB_half_y(struct ImBuf *ibuf1);
506
507 /**
508  *
509  * \attention defined in scaling.c
510  */
511 struct ImBuf *IMB_double_fast_y(struct ImBuf *ibuf1);
512
513 /**
514  *
515  * \attention defined in scaling.c
516  */
517 struct ImBuf *IMB_double_y(struct ImBuf *ibuf1);
518
519 /**
520  *
521  * \attention Defined in rotate.c
522  */
523 void IMB_flipx(struct ImBuf *ibuf);
524 void IMB_flipy(struct ImBuf *ibuf);
525
526 /* Premultiply alpha */
527
528 void IMB_premultiply_alpha(struct ImBuf *ibuf);
529 void IMB_unpremultiply_alpha(struct ImBuf *ibuf);
530
531 /**
532  *
533  * \attention Defined in allocimbuf.c
534  */
535 void IMB_freezbufImBuf(struct ImBuf *ibuf);
536 void IMB_freezbuffloatImBuf(struct ImBuf *ibuf);
537
538 /**
539  *
540  * \attention Defined in rectop.c
541  */
542 void IMB_rectfill(struct ImBuf *drect, const float col[4]);
543 void IMB_rectfill_area(struct ImBuf *ibuf, const float col[4], int x1, int y1, int x2, int y2, struct ColorManagedDisplay *display);
544 void IMB_rectfill_alpha(struct ImBuf *ibuf, const float value);
545
546 /* this should not be here, really, we needed it for operating on render data, IMB_rectfill_area calls it */
547 void buf_rectfill_area(unsigned char *rect, float *rectf, int width, int height,
548                        const float col[4], struct ColorManagedDisplay *display,
549                        int x1, int y1, int x2, int y2);
550
551 /* exported for image tools in blender, to quickly allocate 32 bits rect */
552 void *imb_alloc_pixels(unsigned int x,
553                        unsigned int y,
554                        unsigned int channels,
555                        size_t typesize,
556                        const char *name);
557
558 bool imb_addrectImBuf(struct ImBuf *ibuf);
559 void imb_freerectImBuf(struct ImBuf *ibuf);
560
561 bool imb_addrectfloatImBuf(struct ImBuf *ibuf);
562 void imb_freerectfloatImBuf(struct ImBuf *ibuf);
563 void imb_freemipmapImBuf(struct ImBuf *ibuf);
564
565 bool imb_addtilesImBuf(struct ImBuf *ibuf);
566 void imb_freetilesImBuf(struct ImBuf *ibuf);
567
568 /* threaded processors */
569 void IMB_processor_apply_threaded(int buffer_lines, int handle_size, void *init_customdata,
570                                   void (init_handle) (void *handle, int start_line, int tot_line,
571                                                       void *customdata),
572                                   void *(do_thread) (void *));
573
574 typedef void (*ScanlineThreadFunc) (void *custom_data,
575                                     int start_scanline,
576                                     int num_scanlines);
577 void IMB_processor_apply_threaded_scanlines(int total_scanlines,
578                                             ScanlineThreadFunc do_thread,
579                                             void *custom_data);
580
581
582 /* ffmpeg */
583 void IMB_ffmpeg_init(void);
584 const char *IMB_ffmpeg_last_error(void);
585
586 /**
587  *
588  * \attention defined in stereoimbuf.c
589  */
590 void IMB_stereo3d_write_dimensions(
591         const char mode, const bool is_squeezed, const size_t width, const size_t height,
592         size_t *r_width, size_t *r_height);
593 void IMB_stereo3d_read_dimensions(
594         const char mode, const bool is_squeezed, const size_t width, const size_t height,
595         size_t *r_width, size_t *r_height);
596 int *IMB_stereo3d_from_rect(
597         struct ImageFormatData *im_format, const size_t x, const size_t y, const size_t channels,
598         int *rect_left, int *rect_right);
599 float *IMB_stereo3d_from_rectf(
600         struct ImageFormatData *im_format, const size_t x, const size_t y, const size_t channels,
601         float *rectf_left, float *rectf_right);
602 struct ImBuf *IMB_stereo3d_ImBuf(
603         struct ImageFormatData *im_format,
604         struct ImBuf *ibuf_left, struct ImBuf *ibuf_right);
605 void IMB_ImBufFromStereo3d(
606         struct Stereo3dFormat *s3d, struct ImBuf *ibuf_stereo,
607         struct ImBuf **r_ibuf_left, struct ImBuf **r_ibuf_right);
608
609 #endif