1 /* VIPS image class. 2 * 3 * 7/7/09 4 * - from vips.h 5 * 2/3/11 6 * - move to GObject 7 */ 8 9 /* 10 11 This file is part of VIPS. 12 13 VIPS is free software; you can redistribute it and/or modify 14 it under the terms of the GNU Lesser General Public License as published by 15 the Free Software Foundation; either version 2 of the License, or 16 (at your option) any later version. 17 18 This program is distributed in the hope that it will be useful, 19 but WITHOUT ANY WARRANTY; without even the implied warranty of 20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 21 GNU Lesser General Public License for more details. 22 23 You should have received a copy of the GNU Lesser General Public License 24 along with this program; if not, write to the Free Software 25 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 26 02110-1301 USA 27 28 */ 29 30 /* 31 32 These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk 33 34 */ 35 36 #ifndef VIPS_IMAGE_H 37 #define VIPS_IMAGE_H 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif /*__cplusplus*/ 42 43 /* If you read MSB first, you get these two values. 44 * intel order: byte 0 = b6 45 * SPARC order: byte 0 = 08 46 */ 47 #define VIPS_MAGIC_INTEL (0xb6a6f208U) 48 #define VIPS_MAGIC_SPARC (0x08f2a6b6U) 49 50 /* We have a maximum value for a coordinate at various points for sanity 51 * checking. For example, vips_black() has a max with and height. We use int 52 * for width/height so we could go up to 2bn, but it's good to have a lower 53 * value set so we can see crazy numbers early. 54 * 55 * This was 1m for a while, but someone found a use for a 4m wide image. 56 */ 57 #define VIPS_MAX_COORD (10000000) 58 59 typedef enum { 60 VIPS_DEMAND_STYLE_ERROR = -1, 61 VIPS_DEMAND_STYLE_SMALLTILE, 62 VIPS_DEMAND_STYLE_FATSTRIP, 63 VIPS_DEMAND_STYLE_THINSTRIP, 64 VIPS_DEMAND_STYLE_ANY 65 } VipsDemandStyle; 66 67 /* Types of image descriptor we may have. The type field is advisory only: it 68 * does not imply that any fields in IMAGE have valid data. 69 */ 70 typedef enum { 71 VIPS_IMAGE_ERROR = -1, 72 VIPS_IMAGE_NONE, /* no type set */ 73 VIPS_IMAGE_SETBUF, /* malloced memory array */ 74 VIPS_IMAGE_SETBUF_FOREIGN, /* memory array, don't free on close */ 75 VIPS_IMAGE_OPENIN, /* input from fd with a window */ 76 VIPS_IMAGE_MMAPIN, /* memory mapped input file */ 77 VIPS_IMAGE_MMAPINRW, /* memory mapped read/write file */ 78 VIPS_IMAGE_OPENOUT, /* output to fd */ 79 VIPS_IMAGE_PARTIAL /* partial image */ 80 } VipsImageType; 81 82 typedef enum { 83 VIPS_INTERPRETATION_ERROR = -1, 84 VIPS_INTERPRETATION_MULTIBAND = 0, 85 VIPS_INTERPRETATION_B_W = 1, 86 VIPS_INTERPRETATION_HISTOGRAM = 10, 87 VIPS_INTERPRETATION_XYZ = 12, 88 VIPS_INTERPRETATION_LAB = 13, 89 VIPS_INTERPRETATION_CMYK = 15, 90 VIPS_INTERPRETATION_LABQ = 16, 91 VIPS_INTERPRETATION_RGB = 17, 92 VIPS_INTERPRETATION_CMC = 18, 93 VIPS_INTERPRETATION_LCH = 19, 94 VIPS_INTERPRETATION_LABS = 21, 95 VIPS_INTERPRETATION_sRGB = 22, 96 VIPS_INTERPRETATION_YXY = 23, 97 VIPS_INTERPRETATION_FOURIER = 24, 98 VIPS_INTERPRETATION_RGB16 = 25, 99 VIPS_INTERPRETATION_GREY16 = 26, 100 VIPS_INTERPRETATION_MATRIX = 27, 101 VIPS_INTERPRETATION_scRGB = 28, 102 VIPS_INTERPRETATION_HSV = 29, 103 VIPS_INTERPRETATION_LAST = 30 104 } VipsInterpretation; 105 106 typedef enum { 107 VIPS_FORMAT_NOTSET = -1, 108 VIPS_FORMAT_UCHAR = 0, 109 VIPS_FORMAT_CHAR = 1, 110 VIPS_FORMAT_USHORT = 2, 111 VIPS_FORMAT_SHORT = 3, 112 VIPS_FORMAT_UINT = 4, 113 VIPS_FORMAT_INT = 5, 114 VIPS_FORMAT_FLOAT = 6, 115 VIPS_FORMAT_COMPLEX = 7, 116 VIPS_FORMAT_DOUBLE = 8, 117 VIPS_FORMAT_DPCOMPLEX = 9, 118 VIPS_FORMAT_LAST = 10 119 } VipsBandFormat; 120 121 typedef enum { 122 VIPS_CODING_ERROR = -1, 123 VIPS_CODING_NONE = 0, 124 VIPS_CODING_LABQ = 2, 125 VIPS_CODING_RAD = 6, 126 VIPS_CODING_LAST = 7 127 } VipsCoding; 128 129 typedef enum { 130 VIPS_ACCESS_RANDOM, 131 VIPS_ACCESS_SEQUENTIAL, 132 VIPS_ACCESS_SEQUENTIAL_UNBUFFERED, 133 VIPS_ACCESS_LAST 134 } VipsAccess; 135 136 typedef void *(*VipsStartFn)( VipsImage *out, void *a, void *b ); 137 typedef int (*VipsGenerateFn)( VipsRegion *out, 138 void *seq, void *a, void *b, gboolean *stop ); 139 typedef int (*VipsStopFn)( void *seq, void *a, void *b ); 140 141 /* Struct we keep a record of execution time in. Passed to eval signal so 142 * it can assess progress. 143 */ 144 typedef struct _VipsProgress { 145 /*< private >*/ 146 VipsImage *im; /* Image we are part of */ 147 148 /*< public >*/ 149 int run; /* Time we have been running */ 150 int eta; /* Estimated seconds of computation left */ 151 gint64 tpels; /* Number of pels we expect to calculate */ 152 gint64 npels; /* Number of pels calculated so far */ 153 int percent; /* Percent complete */ 154 GTimer *start; /* Start time */ 155 } VipsProgress; 156 157 #define VIPS_TYPE_IMAGE (vips_image_get_type()) 158 #define VIPS_IMAGE( obj ) \ 159 (G_TYPE_CHECK_INSTANCE_CAST( (obj), \ 160 VIPS_TYPE_IMAGE, VipsImage )) 161 #define VIPS_IMAGE_CLASS( klass ) \ 162 (G_TYPE_CHECK_CLASS_CAST( (klass), \ 163 VIPS_TYPE_IMAGE, VipsImageClass)) 164 #define VIPS_IS_IMAGE( obj ) \ 165 (G_TYPE_CHECK_INSTANCE_TYPE( (obj), VIPS_TYPE_IMAGE )) 166 #define VIPS_IS_IMAGE_CLASS( klass ) \ 167 (G_TYPE_CHECK_CLASS_TYPE( (klass), VIPS_TYPE_IMAGE )) 168 #define VIPS_IMAGE_GET_CLASS( obj ) \ 169 (G_TYPE_INSTANCE_GET_CLASS( (obj), \ 170 VIPS_TYPE_IMAGE, VipsImageClass )) 171 172 /* Matching typedef in basic.h. 173 */ 174 struct _VipsImage { 175 VipsObject parent_instance; 176 177 /*< private >*/ 178 179 /* We have to keep these names for compatibility with the old API. 180 * Don't use them though, use vips_image_get_width() and friends. 181 */ 182 183 int Xsize; /* image width, in pixels */ 184 int Ysize; /* image height, in pixels */ 185 int Bands; /* number of image bands */ 186 187 VipsBandFormat BandFmt; /* pixel format */ 188 VipsCoding Coding; /* pixel coding */ 189 VipsInterpretation Type;/* pixel interpretation */ 190 double Xres; /* horizontal pixels per millimetre */ 191 double Yres; /* vertical pixels per millimetre */ 192 193 int Xoffset; /* image origin hint */ 194 int Yoffset; /* image origin hint */ 195 196 /* No longer used, the names are here for compat with very, very old 197 * code. 198 */ 199 int Length; 200 short Compression; 201 short Level; 202 int Bbits; /* was number of bits in this format */ 203 204 /* Old code expects to see this member, newer code has a param on 205 * eval(). 206 */ 207 VipsProgress *time; 208 209 /* Derived fields that some code can fiddle with. New code should use 210 * vips_image_get_history() and friends. 211 */ 212 char *Hist; /* don't use, see vips_image_get_history() */ 213 char *filename; /* pointer to copy of filename */ 214 VipsPel *data; /* start of image data for WIO */ 215 int kill; /* set to non-zero to block eval */ 216 217 /* Everything below this private and only used internally by 218 * VipsImage. 219 */ 220 221 /* During vips image read and write we need temporary float-sized 222 * fields in the struct for staging xres/yres. Don't use these any 223 * other time. 224 */ 225 float Xres_float; 226 float Yres_float; 227 228 char *mode; /* mode string passed to _new() */ 229 VipsImageType dtype; /* descriptor type */ 230 int fd; /* file descriptor */ 231 void *baseaddr; /* pointer to the start of an mmap file */ 232 size_t length; /* size of mmap area */ 233 guint32 magic; /* magic from header, endian-ness of image */ 234 235 /* Partial image stuff. All these fields are initialised 236 * to NULL and ignored unless set by vips_image_generate() etc. 237 */ 238 VipsStartFn start_fn; 239 VipsGenerateFn generate_fn; 240 VipsStopFn stop_fn; 241 void *client1; /* user arguments */ 242 void *client2; 243 GMutex *sslock; /* start-stop lock */ 244 GSList *regions; /* list of regions current for this image */ 245 VipsDemandStyle dhint; /* demand style hint */ 246 247 /* Extra user-defined fields ... see vips_image_get() etc. 248 */ 249 GHashTable *meta; /* GhashTable of GValue */ 250 GSList *meta_traverse; /* traverse order for Meta */ 251 252 /* Part of mmap() read ... the sizeof() the header we skip from the 253 * file start. Usually VIPS_SIZEOF_HEADER, but can be something else 254 * for binary file read. 255 * 256 * guint64 so that we can guarantee to work even on systems with 257 * strange ideas about large files. 258 */ 259 gint64 sizeof_header; 260 261 /* If this is a large disc image, don't map the whole thing, instead 262 * have a set of windows shared between the regions active on the 263 * image. List of VipsWindow. 264 */ 265 GSList *windows; 266 267 /* Upstream/downstream relationships, built from args to 268 * vips_demand_hint(). 269 * 270 * We use these to invalidate downstream pixel buffers. 271 * Use 'serial' to spot circular dependencies. 272 * 273 * See also hint_set below. 274 */ 275 GSList *upstream; 276 GSList *downstream; 277 int serial; 278 279 /* Keep a list of recounted GValue strings so we can share hist 280 * efficiently. 281 */ 282 GSList *history_list; 283 284 /* The VipsImage (if any) we should signal eval progress on. 285 */ 286 VipsImage *progress_signal; 287 288 /* Record the file length here. We use this to stop ourselves mapping 289 * things beyond the end of the file in the case that the file has 290 * been truncated. 291 * 292 * gint64 so that we can guarantee to work even on systems with 293 * strange ideas about large files. 294 */ 295 gint64 file_length; 296 297 /* Set this when vips_demand_hint_array() is called, and check in any 298 * operation that will demand pixels from the image. 299 * 300 * We use vips_demand_hint_array() to build the tree of 301 * upstream/downstream relationships, so it's a mandatory thing. 302 */ 303 gboolean hint_set; 304 305 /* Delete-on-close is hard to do with signals and callbacks since we 306 * really need to do this in finalize after the fd has been closed, 307 * but you can't emit signals then. 308 * 309 * Also keep a private copy of the filename string to be deleted, 310 * since image->filename will be freed in _dispose(). 311 */ 312 gboolean delete_on_close; 313 char *delete_on_close_filename; 314 }; 315 316 typedef struct _VipsImageClass { 317 VipsObjectClass parent_class; 318 319 /* Signals we emit. 320 */ 321 322 /* Evaluation is starting. 323 */ 324 void (*preeval)( VipsImage *image, VipsProgress *progress, void *data ); 325 326 /* Evaluation progress. 327 */ 328 void (*eval)( VipsImage *image, VipsProgress *progress, void *data ); 329 330 /* Evaluation is ending. 331 */ 332 void (*posteval)( VipsImage *image, VipsProgress *progress, void *data ); 333 334 /* An image has been written to. 335 * Used by eg. vips_image_new_mode("x.jpg", "w") to do the 336 * final write to jpeg. 337 * Set *result to non-zero to indicate an error on write. 338 */ 339 void (*written)( VipsImage *image, int *result, void *data ); 340 341 /* An image has been modified in some way and all caches 342 * need dropping. 343 */ 344 void (*invalidate)( VipsImage *image, void *data ); 345 346 /* Minimise this pipeline. 347 * 348 * This is triggered (sometimes) at the end of eval to signal that 349 * we're probably done and that operations involved should try to 350 * minimise memory use by, for example, dropping caches. 351 * 352 * See vips_tilecache(). 353 */ 354 void (*minimise)( VipsImage *image, void *data ); 355 356 } VipsImageClass; 357 358 /* Don't put spaces around void here, it breaks gtk-doc. 359 */ 360 GType vips_image_get_type(void); 361 362 /* Has to be guint64 and not size_t/off_t since we have to be able to address 363 * huge images on platforms with 32-bit files. 364 */ 365 366 /* Pixel address calculation macros. 367 */ 368 #define VIPS_IMAGE_SIZEOF_ELEMENT( I ) \ 369 (vips_format_sizeof_unsafe((I)->BandFmt)) 370 #define VIPS_IMAGE_SIZEOF_PEL( I ) \ 371 (VIPS_IMAGE_SIZEOF_ELEMENT( I ) * (I)->Bands) 372 #define VIPS_IMAGE_SIZEOF_LINE( I ) \ 373 (VIPS_IMAGE_SIZEOF_PEL( I ) * (I)->Xsize) 374 #define VIPS_IMAGE_SIZEOF_IMAGE( I ) \ 375 (VIPS_IMAGE_SIZEOF_LINE( I ) * (I)->Ysize) 376 #define VIPS_IMAGE_N_ELEMENTS( I ) \ 377 ((I)->Bands * (I)->Xsize) 378 #define VIPS_IMAGE_N_PELS( I ) \ 379 ((guint64) (I)->Xsize * (I)->Ysize) 380 381 /* If VIPS_DEBUG is defined, add bounds checking. 382 */ 383 #ifdef VIPS_DEBUG 384 #define VIPS_IMAGE_ADDR( I, X, Y ) \ 385 ( ((X) >= 0 && (X) < VIPS_IMAGE( I )->Xsize && \ 386 (Y) >= 0 && (Y) < VIPS_IMAGE( I )->Ysize && \ 387 VIPS_IMAGE( I )->data) ? \ 388 (VIPS_IMAGE( I )->data + \ 389 (Y) * VIPS_IMAGE_SIZEOF_LINE( I ) + \ 390 (X) * VIPS_IMAGE_SIZEOF_PEL( I )) : \ 391 (fprintf( stderr, \ 392 "VIPS_IMAGE_ADDR: point out of bounds, " \ 393 "file \"%s\", line %d\n" \ 394 "(point x=%d, y=%d\n" \ 395 " should have been within VipsRect left=%d, top=%d, " \ 396 "width=%d, height=%d)\n", \ 397 __FILE__, __LINE__, \ 398 (X), (Y), \ 399 0, 0, \ 400 VIPS_IMAGE( I )->Xsize, \ 401 VIPS_IMAGE( I )->Ysize ), (VipsPel *) NULL) \ 402 ) 403 #else /*!VIPS_DEBUG*/ 404 #define VIPS_IMAGE_ADDR( I, X, Y ) \ 405 ((I)->data + \ 406 (Y) * VIPS_IMAGE_SIZEOF_LINE( I ) + \ 407 (X) * VIPS_IMAGE_SIZEOF_PEL( I )) 408 #endif /*VIPS_DEBUG*/ 409 410 #ifdef VIPS_DEBUG 411 #define VIPS_MATRIX( I, X, Y ) \ 412 ((VIPS_IMAGE( I )->BandFmt == VIPS_FORMAT_DOUBLE && \ 413 VIPS_IMAGE( I )->Bands == 1) ? \ 414 ((double *) VIPS_IMAGE_ADDR( I, X, Y )) : \ 415 (fprintf( stderr, "VIPS_MATRIX: not a matrix image\n" ), \ 416 (double *) NULL)) 417 #else /*!VIPS_DEBUG*/ 418 #define VIPS_MATRIX( I, X, Y ) \ 419 ((double *) VIPS_IMAGE_ADDR( I, X, Y )) 420 #endif /*VIPS_DEBUG*/ 421 422 void vips_progress_set( gboolean progress ); 423 424 void vips_image_invalidate_all( VipsImage *image ); 425 426 void vips_image_minimise_all( VipsImage *image ); 427 428 gboolean vips_image_is_sequential( VipsImage *image ); 429 430 void vips_image_set_progress( VipsImage *image, gboolean progress ); 431 gboolean vips_image_iskilled( VipsImage *image ); 432 void vips_image_set_kill( VipsImage *image, gboolean kill ); 433 434 char *vips_filename_get_filename( const char *vips_filename ); 435 char *vips_filename_get_options( const char *vips_filename ); 436 437 VipsImage *vips_image_new( void ); 438 VipsImage *vips_image_new_memory( void ); 439 VipsImage *vips_image_memory( void ); 440 VipsImage *vips_image_new_from_file( const char *name, ... ) 441 __attribute__((sentinel)); 442 VipsImage *vips_image_new_from_file_RW( const char *filename ); 443 VipsImage *vips_image_new_from_file_raw( const char *filename, 444 int xsize, int ysize, int bands, guint64 offset ); 445 VipsImage *vips_image_new_from_memory( const void *data, size_t size, 446 int width, int height, int bands, VipsBandFormat format ); 447 VipsImage *vips_image_new_from_memory_copy( const void *data, size_t size, 448 int width, int height, int bands, VipsBandFormat format ); 449 VipsImage *vips_image_new_from_buffer( const void *buf, size_t len, 450 const char *option_string, ... ) 451 __attribute__((sentinel)); 452 VipsImage *vips_image_new_from_source( VipsSource *source, 453 const char *option_string, ... ) __attribute__((sentinel)); 454 VipsImage *vips_image_new_matrix( int width, int height ); 455 VipsImage *vips_image_new_matrixv( int width, int height, ... ); 456 VipsImage *vips_image_new_matrix_from_array( int width, int height, 457 const double *array, int size ); 458 VipsImage *vips_image_matrix_from_array( int width, int height, 459 const double *array, int size ); 460 VipsImage *vips_image_new_from_image( VipsImage *image, 461 const double *c, int n ); 462 VipsImage *vips_image_new_from_image1( VipsImage *image, double c ); 463 464 void vips_image_set_delete_on_close( VipsImage *image, 465 gboolean delete_on_close ); 466 guint64 vips_get_disc_threshold( void ); 467 VipsImage *vips_image_new_temp_file( const char *format ); 468 469 int vips_image_write( VipsImage *image, VipsImage *out ); 470 int vips_image_write_to_file( VipsImage *image, const char *name, ... ) 471 __attribute__((sentinel)); 472 int vips_image_write_to_buffer( VipsImage *in, 473 const char *suffix, void **buf, size_t *size, ... ) 474 __attribute__((sentinel)); 475 int vips_image_write_to_target( VipsImage *in, 476 const char *suffix, VipsTarget *target, ... ) 477 __attribute__((sentinel)); 478 void *vips_image_write_to_memory( VipsImage *in, size_t *size ); 479 480 int vips_image_decode_predict( VipsImage *in, 481 int *bands, VipsBandFormat *format ); 482 int vips_image_decode( VipsImage *in, VipsImage **out ); 483 int vips_image_encode( VipsImage *in, VipsImage **out, VipsCoding coding ); 484 485 gboolean vips_image_isMSBfirst( VipsImage *image ); 486 gboolean vips_image_isfile( VipsImage *image ); 487 gboolean vips_image_ispartial( VipsImage *image ); 488 gboolean vips_image_hasalpha( VipsImage *image ); 489 490 VipsImage *vips_image_copy_memory( VipsImage *image ); 491 int vips_image_wio_input( VipsImage *image ); 492 int vips_image_pio_input( VipsImage *image ); 493 int vips_image_pio_output( VipsImage *image ); 494 int vips_image_inplace( VipsImage *image ); 495 int vips_image_write_prepare( VipsImage *image ); 496 497 int vips_image_write_line( VipsImage *image, int ypos, VipsPel *linebuffer ); 498 499 gboolean vips_band_format_isint( VipsBandFormat format ); 500 gboolean vips_band_format_isuint( VipsBandFormat format ); 501 gboolean vips_band_format_is8bit( VipsBandFormat format ); 502 gboolean vips_band_format_isfloat( VipsBandFormat format ); 503 gboolean vips_band_format_iscomplex( VipsBandFormat format ); 504 505 int vips_system( const char *cmd_format, ... ) 506 __attribute__((sentinel)); 507 508 /* Defined in type.c but declared here, since they use VipsImage. 509 */ 510 VipsArrayImage *vips_array_image_new( VipsImage **array, int n ); 511 VipsArrayImage *vips_array_image_newv( int n, ... ); 512 VipsArrayImage *vips_array_image_new_from_string( const char *string, 513 VipsAccess flags ); 514 VipsArrayImage *vips_array_image_empty( void ); 515 VipsArrayImage *vips_array_image_append( VipsArrayImage *array, 516 VipsImage *image ); 517 VipsImage **vips_array_image_get( VipsArrayImage *array, int *n ); 518 VipsImage **vips_value_get_array_image( const GValue *value, int *n ); 519 void vips_value_set_array_image( GValue *value, int n ); 520 521 /* Defined in reorder.c, but really a function on image. 522 */ 523 int vips_reorder_prepare_many( VipsImage *image, 524 VipsRegion **regions, VipsRect *r ); 525 void vips_reorder_margin_hint( VipsImage *image, int margin ); 526 527 void vips_image_free_buffer( VipsImage *image, void *buffer ); 528 529 #ifdef __cplusplus 530 } 531 #endif /*__cplusplus*/ 532 533 #endif /*VIPS_IMAGE_H*/ 534