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