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  *
  55  * \section dependencies Dependencies
  56  *
  57  * IMB needs:
  58  * - \ref DNA module
  59  *     The listbase types are used for handling the memory
  60  *     management.
  61  * - \ref blenlib module
  62  *     blenlib handles guarded memory management in blender-style.
  63  *     BLI_winstuff.h makes a few windows specific behaviors
  64  *     posix-compliant.
  65  */
  66
  67 #ifndef __IMB_IMBUF_H__
  68 #define __IMB_IMBUF_H__
  69
  70 #define IM_MAX_SPACE 64
  71
  72 /* for bool */
  73 #include "../blenlib/BLI_sys_types.h"
  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 bool addzbufImBuf(struct ImBuf *ibuf);
 150 bool 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 void IMB_blend_color_byte(unsigned char dst[4], unsigned char src1[4],
 173         unsigned char src2[4], IMB_BlendMode mode);
 174 void IMB_blend_color_float(float dst[4], float src1[4], float src2[4],
 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 *obuf, struct ImBuf *sbuf,
 182         unsigned short *dmask, unsigned short *smask, unsigned short mask_max,
 183         int destx,  int desty, int origx, int origy, int srcx, int srcy,
 184         int width, int height, IMB_BlendMode mode);
 185
 186 /**
 187  *
 188  * \attention Defined in indexer.c
 189  */
 190
 191 typedef enum IMB_Timecode_Type {
 192         IMB_TC_NONE       = 0, /* don't use timecode files at all */
 193
 194         IMB_TC_RECORD_RUN = 1, /* use images in the order as they are recorded
 195                                 * (currently, this is the only one implemented
 196                                 * and is a sane default) */
 197
 198         IMB_TC_FREE_RUN   = 2, /* use global timestamp written by recording
 199                             * device (prosumer camcorders e.g. can do that) */
 200         IMB_TC_INTERPOLATED_REC_DATE_FREE_RUN = 4, /* interpolate a global timestamp using the
 201                                                     * record date and time written by recording
 202                                                     * device (*every* consumer camcorder can do
 203                                                     * that :) )*/
 204         IMB_TC_RECORD_RUN_NO_GAPS = 8,
 205         IMB_TC_MAX_SLOT   = 4
 206 } IMB_Timecode_Type;
 207
 208 typedef enum IMB_Proxy_Size {
 209         IMB_PROXY_NONE = 0,
 210         IMB_PROXY_25 = 1,
 211         IMB_PROXY_50 = 2,
 212         IMB_PROXY_75 = 4,
 213         IMB_PROXY_100 = 8,
 214         IMB_PROXY_MAX_SLOT = 4
 215 } IMB_Proxy_Size;
 216
 217 /* defaults to BL_proxy within the directory of the animation */
 218 void IMB_anim_set_index_dir(struct anim *anim, const char *dir);
 219
 220 int IMB_anim_index_get_frame_index(struct anim *anim, IMB_Timecode_Type tc,
 221                                    int position);
 222
 223 struct IndexBuildContext;
 224
 225 /* prepare context for proxies/imecodes builder */
 226 struct IndexBuildContext *IMB_anim_index_rebuild_context(struct anim *anim, IMB_Timecode_Type tcs_in_use,
 227                                                          IMB_Proxy_Size proxy_sizes_in_use, int quality);
 228
 229 /* will rebuild all used indices and proxies at once */
 230 void IMB_anim_index_rebuild(struct IndexBuildContext *context,
 231                             short *stop, short *do_update, float *progress);
 232
 233 /* finish rebuilding proxises/timecodes and free temporary contexts used */
 234 void IMB_anim_index_rebuild_finish(struct IndexBuildContext *context, short stop);
 235
 236 /**
 237  * Return the length (in frames) of the given \a anim.
 238  */
 239 int IMB_anim_get_duration(struct anim *anim, IMB_Timecode_Type tc);
 240
 241
 242 /**
 243  * Return the fps contained in movie files (function rval is FALSE,
 244  * and frs_sec and frs_sec_base untouched if none available!)
 245  */
 246 int IMB_anim_get_fps(struct anim *anim,
 247                      short *frs_sec, float *frs_sec_base);
 248
 249 /**
 250  *
 251  * \attention Defined in anim_movie.c
 252  */
 253 struct anim *IMB_open_anim(const char *name, int ib_flags, int streamindex, char colorspace[IM_MAX_SPACE]);
 254 void IMB_close_anim(struct anim *anim);
 255 void IMB_close_anim_proxies(struct anim *anim);
 256
 257
 258 /**
 259  *
 260  * \attention Defined in anim_movie.c
 261  */
 262
 263 int ismovie(const char *filepath);
 264 void IMB_anim_set_preseek(struct anim *anim, int preseek);
 265 int IMB_anim_get_preseek(struct anim *anim);
 266
 267 /**
 268  *
 269  * \attention Defined in anim_movie.c
 270  */
 271
 272 struct ImBuf *IMB_anim_absolute(
 273         struct anim *anim, int position,
 274         IMB_Timecode_Type tc        /* = 1 = IMB_TC_RECORD_RUN */,
 275         IMB_Proxy_Size preview_size /* = 0 = IMB_PROXY_NONE */);
 276
 277 /**
 278  *
 279  * \attention Defined in anim_movie.c
 280  * fetches a define previewframe, usually half way into the movie
 281  */
 282 struct ImBuf *IMB_anim_previewframe(struct anim *anim);
 283
 284 /**
 285  *
 286  * \attention Defined in anim_movie.c
 287  */
 288 void IMB_free_anim(struct anim *anim);
 289
 290 /**
 291  *
 292  * \attention Defined in filter.c
 293  */
 294
 295 #define FILTER_MASK_NULL                0
 296 #define FILTER_MASK_MARGIN              1
 297 #define FILTER_MASK_USED                2
 298
 299 void IMB_filter(struct ImBuf *ibuf);
 300 void IMB_filterN(struct ImBuf *out, struct ImBuf *in);
 301 void IMB_mask_filter_extend(char *mask, int width, int height);
 302 void IMB_mask_clear(struct ImBuf *ibuf, char *mask, int val);
 303 void IMB_filter_extend(struct ImBuf *ibuf, char *mask, int filter);
 304 void IMB_makemipmap(struct ImBuf *ibuf, int use_filter);
 305 void IMB_remakemipmap(struct ImBuf *ibuf, int use_filter);
 306 struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level);
 307
 308 /**
 309  *
 310  * \attention Defined in cache.c
 311  */
 312
 313 void IMB_tile_cache_params(int totthread, int maxmem);
 314 unsigned int *IMB_gettile(struct ImBuf *ibuf, int tx, int ty, int thread);
 315 void IMB_tiles_to_rect(struct ImBuf *ibuf);
 316
 317 /**
 318  *
 319  * \attention Defined in filter.c
 320  */
 321 void IMB_filtery(struct ImBuf *ibuf);
 322
 323 /**
 324  *
 325  * \attention Defined in scaling.c
 326  */
 327 struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1);
 328
 329 /**
 330  *
 331  * \attention Defined in scaling.c
 332  */
 333 struct ImBuf *IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
 334
 335 /**
 336  *
 337  * \attention Defined in scaling.c
 338  */
 339 struct ImBuf *IMB_scalefastImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
 340
 341 /**
 342  *
 343  * \attention Defined in scaling.c
 344  */
 345 void IMB_scaleImBuf_threaded(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
 346
 347 /**
 348  *
 349  * \attention Defined in writeimage.c
 350  */
 351 short IMB_saveiff(struct ImBuf *ibuf, const char *filepath, int flags);
 352
 353 /**
 354  *
 355  * \attention Defined in util.c
 356  */
 357 int IMB_ispic(const char *name);
 358
 359 /**
 360  *
 361  * \attention Defined in util.c
 362  */
 363 int IMB_isanim(const char *name);
 364
 365 /**
 366  *
 367  * \attention Defined in util.c
 368  */
 369 int imb_get_anim_type(const char *name);
 370
 371 /**
 372  *
 373  * \attention Defined in divers.c
 374  */
 375 void IMB_de_interlace(struct ImBuf *ibuf);
 376 void IMB_interlace(struct ImBuf *ibuf);
 377
 378 /* create char buffer, color corrected if necessary, for ImBufs that lack one */
 379 void IMB_rect_from_float(struct ImBuf *ibuf);
 380 /* Create char buffer for part of the image, color corrected if necessary,
 381  * Changed part will be stored in buffer. This is expected to be used for texture painting updates */
 382 void IMB_partial_rect_from_float(struct ImBuf *ibuf, float *buffer, int x, int y, int w, int h, int is_data);
 383 void IMB_float_from_rect(struct ImBuf *ibuf);
 384 void IMB_color_to_bw(struct ImBuf *ibuf);
 385 void IMB_saturation(struct ImBuf *ibuf, float sat);
 386
 387 /* converting pixel buffers */
 388 void IMB_buffer_byte_from_float(unsigned char *rect_to, const float *rect_from,
 389         int channels_from, float dither, int profile_to, int profile_from, int predivide,
 390         int width, int height, int stride_to, int stride_from);
 391 void IMB_buffer_float_from_byte(float *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 void IMB_buffer_float_from_float(float *rect_to, const float *rect_from,
 395         int channels_from, int profile_to, int profile_from, int predivide,
 396         int width, int height, int stride_to, int stride_from);
 397 void IMB_buffer_byte_from_byte(unsigned char *rect_to, const unsigned char *rect_from,
 398         int profile_to, int profile_from, int predivide,
 399         int width, int height, int stride_to, int stride_from);
 400 void IMB_buffer_float_clamp(float *buf, int width, int height);
 401 void IMB_buffer_float_unpremultiply(float *buf, int width, int height);
 402 void IMB_buffer_float_premultiply(float *buf, int width, int height);
 403
 404 /**
 405  * Change the ordering of the color bytes pointed to by rect from
 406  * rgba to abgr. size * 4 color bytes are reordered.
 407  *
 408  * \attention Defined in imageprocess.c
 409  */
 410 void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf);
 411
 412 /**
 413  *
 414  * \attention defined in imageprocess.c
 415  */
 416 void bicubic_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
 417 void nearest_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
 418 void bilinear_interpolation(struct ImBuf *in, struct ImBuf *out, float u, float v, int xout, int yout);
 419
 420 void bicubic_interpolation_color(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
 421 void nearest_interpolation_color(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
 422 void bilinear_interpolation_color(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
 423 void bilinear_interpolation_color_wrap(struct ImBuf *in, unsigned char col[4], float col_float[4], float u, float v);
 424
 425 void IMB_alpha_under_color_float(float *rect_float, int x, int y, float backcol[3]);
 426 void IMB_alpha_under_color_byte(unsigned char *rect, int x, int y, float backcol[3]);
 427
 428 /**
 429  *
 430  * \attention defined in readimage.c
 431  */
 432 struct ImBuf *IMB_loadifffile(int file, const char *filepath, int flags, char colorspace[IM_MAX_SPACE], const char *descr);
 433
 434 /**
 435  *
 436  * \attention defined in scaling.c
 437  */
 438 struct ImBuf *IMB_half_x(struct ImBuf *ibuf1);
 439
 440 /**
 441  *
 442  * \attention defined in scaling.c
 443  */
 444 struct ImBuf *IMB_double_fast_x(struct ImBuf *ibuf1);
 445
 446 /**
 447  *
 448  * \attention defined in scaling.c
 449  */
 450 struct ImBuf *IMB_double_x(struct ImBuf *ibuf1);
 451
 452 /**
 453  *
 454  * \attention defined in scaling.c
 455  */
 456 struct ImBuf *IMB_half_y(struct ImBuf *ibuf1);
 457
 458 /**
 459  *
 460  * \attention defined in scaling.c
 461  */
 462 struct ImBuf *IMB_double_fast_y(struct ImBuf *ibuf1);
 463
 464 /**
 465  *
 466  * \attention defined in scaling.c
 467  */
 468 struct ImBuf *IMB_double_y(struct ImBuf *ibuf1);
 469
 470 /**
 471  *
 472  * \attention Defined in rotate.c
 473  */
 474 void IMB_flipx(struct ImBuf *ibuf);
 475 void IMB_flipy(struct ImBuf *ibuf);
 476
 477 /* Premultiply alpha */
 478
 479 void IMB_premultiply_alpha(struct ImBuf *ibuf);
 480 void IMB_unpremultiply_alpha(struct ImBuf *ibuf);
 481
 482 /**
 483  *
 484  * \attention Defined in allocimbuf.c
 485  */
 486 void IMB_freezbufImBuf(struct ImBuf *ibuf);
 487 void IMB_freezbuffloatImBuf(struct ImBuf *ibuf);
 488
 489 /**
 490  *
 491  * \attention Defined in rectop.c
 492  */
 493 void IMB_rectfill(struct ImBuf *drect, const float col[4]);
 494 void IMB_rectfill_area(struct ImBuf *ibuf, const float col[4], int x1, int y1, int x2, int y2, struct ColorManagedDisplay *display);
 495 void IMB_rectfill_alpha(struct ImBuf *ibuf, const float value);
 496
 497 /* this should not be here, really, we needed it for operating on render data, IMB_rectfill_area calls it */
 498 void buf_rectfill_area(unsigned char *rect, float *rectf, int width, int height,
 499                        const float col[4], struct ColorManagedDisplay *display,
 500                        int x1, int y1, int x2, int y2);
 501
 502 /* defined in metadata.c */
 503 bool IMB_metadata_change_field(struct ImBuf *img, const char *key, const char *field);
 504
 505 /* exported for image tools in blender, to quickly allocate 32 bits rect */
 506 bool imb_addrectImBuf(struct ImBuf *ibuf);
 507 void imb_freerectImBuf(struct ImBuf *ibuf);
 508
 509 bool imb_addrectfloatImBuf(struct ImBuf *ibuf);
 510 void imb_freerectfloatImBuf(struct ImBuf *ibuf);
 511 void imb_freemipmapImBuf(struct ImBuf *ibuf);
 512
 513 bool imb_addtilesImBuf(struct ImBuf *ibuf);
 514 void imb_freetilesImBuf(struct ImBuf *ibuf);
 515
 516 /* threaded processors */
 517 void IMB_processor_apply_threaded(int buffer_lines, int handle_size, void *init_customdata,
 518                                   void (init_handle) (void *handle, int start_line, int tot_line,
 519                                                       void *customdata),
 520                                   void *(do_thread) (void *));
 521
 522 /* ffmpeg */
 523 void IMB_ffmpeg_init(void);
 524 const char *IMB_ffmpeg_last_error(void);
 525
 526 #endif
 527