1 /* get, set and copy image header fields
2 *
3 * 9/7/02 JC
4 * - first version
5 * 7/6/05
6 * - now reads meta fields too
7 * - cleaned up
8 * - added im_header_exists(), im_header_map()
9 * 1/8/05
10 * - now im_header_get_type() and im_header_get() rather than
11 * im_header_exists()
12 * 4/1/07
13 * - removed Hist from standard fields ... now a separate function
14 * 29/8/09
15 * - im_header_get_type() renamed as im_header_get_typeof() to prevent
16 * confusion with GObject-style type definers
17 * 1/10/09
18 * - rename as header.c
19 * - gtkdoc comments
20 * 22/3/11
21 * - rename fields for vips8
22 * - move to vips_ prefix
23 * 16/7/15
24 * - auto wrap GString as RefString
25 * 20/10/16
26 * - return header enums as enums, not ints
27 * - vips_image_get_*() all convert everything to target type if they can
28 * - rename "field" as "name" in docs
29 * 21/11/18
30 * - get_string will allow G_STRING and REF_STRING
31 * 28/12/18
32 * - hide deprecated header fields from _map
33 * 17/2/19
34 * - add vips_image_get_page_height()
35 * 19/6/19
36 * - add vips_image_get_n_pages()
37 * 20/6/19
38 * - add vips_image_get/set_array_int()
39 * 31/1/19
40 * - lock for metadata changes
41 */
42
43 /*
44
45 This file is part of VIPS.
46
47 VIPS is free software; you can redistribute it and/or modify
48 it under the terms of the GNU Lesser General Public License as published by
49 the Free Software Foundation; either version 2 of the License, or
50 (at your option) any later version.
51
52 This program is distributed in the hope that it will be useful,
53 but WITHOUT ANY WARRANTY; without even the implied warranty of
54 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
55 GNU Lesser General Public License for more details.
56
57 You should have received a copy of the GNU Lesser General Public License
58 along with this program; if not, write to the Free Software
59 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
60 02110-1301 USA
61
62 */
63
64 /*
65
66 These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
67
68 */
69
70 /*
71 #define VIPS_DEBUG
72 #define DEBUG
73 */
74
75 #ifdef HAVE_CONFIG_H
76 #include <config.h>
77 #endif /*HAVE_CONFIG_H*/
78 #include <vips/intl.h>
79
80 #include <stdio.h>
81 #include <stdlib.h>
82 #include <string.h>
83
84 #include <vips/vips.h>
85 #include <vips/internal.h>
86 #include <vips/debug.h>
87
88 /**
89 * SECTION: header
90 * @short_description: get, set and walk image headers
91 * @stability: Stable
92 * @see_also: <link linkend="libvips-type">type</link>
93 * @include: vips/vips.h
94 *
95 * These functions let you get at image header data (including metadata) in a
96 * uniform way.
97 *
98 * Use vips_image_get_typeof() to test for the
99 * existence and #GType of a header field.
100 *
101 * You can attach arbitrary metadata to images. Metadata is copied as images
102 * are processed, so all images which used this image as input, directly or
103 * indirectly, will have this same bit of metadata attached to them. Copying
104 * is implemented with reference-counted pointers, so it is efficient, even for
105 * large items of data. This does however mean that metadata items need to be
106 * immutable. Metadata is handy for things like ICC profiles or EXIF data.
107 *
108 * Various convenience functions (eg. vips_image_set_int()) let you easily
109 * attach
110 * simple types like
111 * numbers, strings and memory blocks to images. Use vips_image_map() to loop
112 * over an image's fields, including all metadata.
113 *
114 * Items of metadata are identified by strings. Some strings are reserved, for
115 * example the ICC profile for an image is known by convention as
116 * "icc-profile-data".
117 *
118 * If you save an image in VIPS format, all metadata (with a restriction, see
119 * below) is automatically saved for you in a block of XML at the end of the
120 * file. When you load a VIPS image, the metadata is restored. You can use the
121 * `vipsedit` command-line tool to extract or replace this block of XML.
122 *
123 * VIPS metadata is based on %GValue. See the docs for that system if you want
124 * to do fancy stuff such as defining a new metadata type.
125 * VIPS defines a new %GValue called `vips_save_string`, a variety of string,
126 * see vips_value_set_save_string().
127 * If your %GValue can be transformed to `vips_save_string`, it will be
128 * saved and loaded to and from VIPS files for you.
129 *
130 * VIPS provides a couple of base classes which implement
131 * reference-counted areas of memory. If you base your metadata on one of
132 * these types, it can be copied between images efficiently.
133 */
134
135 /* Use in various small places where we need a mutex and it's not worth
136 * making a private one.
137 */
138 static GMutex *vips__meta_lock = NULL;
139
140 /* We have to keep the gtype as a string, since we statically init this.
141 */
142 typedef struct _HeaderField {
143 const char *name;
144 const char *type;
145 glong offset;
146 } HeaderField;
147
148 /* Built in fields and struct offsets.
149 */
150 static HeaderField vips_header_fields[] = {
151 { "width", "gint", G_STRUCT_OFFSET( VipsImage, Xsize ) },
152 { "height", "gint", G_STRUCT_OFFSET( VipsImage, Ysize ) },
153 { "bands", "gint", G_STRUCT_OFFSET( VipsImage, Bands ) },
154 { "format", "VipsBandFormat", G_STRUCT_OFFSET( VipsImage, BandFmt ) },
155 { "coding", "VipsCoding", G_STRUCT_OFFSET( VipsImage, Coding ) },
156 { "interpretation", "VipsInterpretation",
157 G_STRUCT_OFFSET( VipsImage, Type ) },
158 { "xoffset", "gint", G_STRUCT_OFFSET( VipsImage, Xoffset ) },
159 { "yoffset", "gint", G_STRUCT_OFFSET( VipsImage, Yoffset ) },
160 { "xres", "gdouble", G_STRUCT_OFFSET( VipsImage, Xres ) },
161 { "yres", "gdouble", G_STRUCT_OFFSET( VipsImage, Yres ) },
162 { "filename", "gchararray", G_STRUCT_OFFSET( VipsImage, filename ) }
163 };
164
165 /* Old names we keep around for back-compat. We never loop over these with
166 * map, but we do check them when we look up fields by name.
167 */
168 static HeaderField vips_header_fields_old[] = {
169 { "Xsize", "gint", G_STRUCT_OFFSET( VipsImage, Xsize ) },
170 { "Ysize", "gint", G_STRUCT_OFFSET( VipsImage, Ysize ) },
171 { "Bands", "gint", G_STRUCT_OFFSET( VipsImage, Bands ) },
172 { "Bbits", "gint", G_STRUCT_OFFSET( VipsImage, Bbits ) },
173 { "BandFmt", "gint", G_STRUCT_OFFSET( VipsImage, BandFmt ) },
174 { "Coding", "gint", G_STRUCT_OFFSET( VipsImage, Coding ) },
175 { "Type", "gint", G_STRUCT_OFFSET( VipsImage, Type ) },
176 { "Xoffset", "gint", G_STRUCT_OFFSET( VipsImage, Xoffset ) },
177 { "Yoffset", "gint", G_STRUCT_OFFSET( VipsImage, Yoffset ) },
178 { "Xres", "gdouble", G_STRUCT_OFFSET( VipsImage, Xres ) },
179 { "Yres", "gdouble", G_STRUCT_OFFSET( VipsImage, Yres ) }
180 };
181
182 /* This is used by (eg.) VIPS_IMAGE_SIZEOF_ELEMENT() to calculate object
183 * size via vips_format_sizeof().
184 *
185 * It needs to be guint64 and not size_t since we use this as the basis for
186 * image address calcs and they have to be 64-bit, even on 32-bit machines.
187 *
188 * Can't be static, we need this to be visible for vips7 compat.
189 */
190 const guint64 vips__image_sizeof_bandformat[] = {
191 sizeof( unsigned char ), /* VIPS_FORMAT_UCHAR */
192 sizeof( signed char ), /* VIPS_FORMAT_CHAR */
193 sizeof( unsigned short ), /* VIPS_FORMAT_USHORT */
194 sizeof( unsigned short ), /* VIPS_FORMAT_SHORT */
195 sizeof( unsigned int ), /* VIPS_FORMAT_UINT */
196 sizeof( unsigned int ), /* VIPS_FORMAT_INT */
197 sizeof( float ), /* VIPS_FORMAT_FLOAT */
198 2 * sizeof( float ), /* VIPS_FORMAT_COMPLEX */
199 sizeof( double ), /* VIPS_FORMAT_DOUBLE */
200 2 * sizeof( double ) /* VIPS_FORMAT_DPCOMPLEX */
201 };
202
203 /**
204 * vips_format_sizeof:
205 * @format: format type
206 *
207 * Returns: number of bytes for a band format.
208 */
209 guint64
vips_format_sizeof(VipsBandFormat format)210 vips_format_sizeof( VipsBandFormat format )
211 {
212 format = VIPS_CLIP( 0, format, VIPS_FORMAT_DPCOMPLEX );
213
214 return( vips__image_sizeof_bandformat[format] );
215 }
216
217 /**
218 * vips_format_sizeof_unsafe: (skip)
219 * @format: format type
220 *
221 * A fast but dangerous version of vips_format_sizeof(). You must have
222 * previously range-checked @format or you'll crash.
223 *
224 * Returns: number of bytes for a band format.
225 */
226 guint64
vips_format_sizeof_unsafe(VipsBandFormat format)227 vips_format_sizeof_unsafe( VipsBandFormat format )
228 {
229 g_assert( 0 <= format && format <= VIPS_FORMAT_DPCOMPLEX );
230
231 return( vips__image_sizeof_bandformat[format] );
232 }
233
234 #ifdef DEBUG
235 /* Check that this meta is on the hash table.
236 */
237 static void *
meta_sanity_on_hash(VipsMeta * meta,VipsImage * im,void * b)238 meta_sanity_on_hash( VipsMeta *meta, VipsImage *im, void *b )
239 {
240 VipsMeta *found;
241
242 if( meta->im != im )
243 printf( "*** field \"%s\" has incorrect im\n",
244 meta->name );
245
246 if( !(found = g_hash_table_lookup( im->meta, meta->name )) )
247 printf( "*** field \"%s\" is on traverse but not in hash\n",
248 meta->name );
249
250 if( found != meta )
251 printf( "*** meta \"%s\" on traverse and hash do not match\n",
252 meta->name );
253
254 return( NULL );
255 }
256
257 static void
meta_sanity_on_traverse(const char * name,VipsMeta * meta,VipsImage * im)258 meta_sanity_on_traverse( const char *name, VipsMeta *meta, VipsImage *im )
259 {
260 if( meta->name != name )
261 printf( "*** field \"%s\" has incorrect name\n",
262 meta->name );
263
264 if( meta->im != im )
265 printf( "*** field \"%s\" has incorrect im\n",
266 meta->name );
267
268 if( !g_slist_find( im->meta_traverse, meta ) )
269 printf( "*** field \"%s\" is in hash but not on traverse\n",
270 meta->name );
271 }
272
273 static void
meta_sanity(const VipsImage * im)274 meta_sanity( const VipsImage *im )
275 {
276 if( im->meta )
277 g_hash_table_foreach( im->meta,
278 (GHFunc) meta_sanity_on_traverse, (void *) im );
279 vips_slist_map2( im->meta_traverse,
280 (VipsSListMap2Fn) meta_sanity_on_hash, (void *) im, NULL );
281 }
282 #endif /*DEBUG*/
283
284 static void
meta_free(VipsMeta * meta)285 meta_free( VipsMeta *meta )
286 {
287 #ifdef DEBUG
288 {
289 char *str_value;
290
291 str_value = g_strdup_value_contents( &meta->value );
292 printf( "meta_free: name %s, value = %s\n",
293 meta->name, str_value );
294 g_free( str_value );
295 }
296 #endif /*DEBUG*/
297
298 if( meta->im )
299 meta->im->meta_traverse =
300 g_slist_remove( meta->im->meta_traverse, meta );
301
302 g_value_unset( &meta->value );
303 g_free( meta->name );
304 g_free( meta );
305 }
306
307 static VipsMeta *
meta_new(VipsImage * image,const char * name,GValue * value)308 meta_new( VipsImage *image, const char *name, GValue *value )
309 {
310 VipsMeta *meta;
311
312 meta = g_new( VipsMeta, 1 );
313 meta->im = image;
314 meta->name = NULL;
315 memset( &meta->value, 0, sizeof( GValue ) );
316 meta->name = g_strdup( name );
317
318 /* Special case: we don't want to have G_STRING on meta. They will be
319 * copied down pipelines, plus some of our API (like
320 * vips_image_get_string()) assumes that the GValue is a refstring and
321 * that read-only pointers can be handed out.
322 *
323 * Turn G_TYPE_STRING into VIPS_TYPE_REF_STRING.
324 */
325 if( G_VALUE_TYPE( value ) == G_TYPE_STRING )
326 g_value_init( &meta->value, VIPS_TYPE_REF_STRING );
327 else
328 g_value_init( &meta->value, G_VALUE_TYPE( value ) );
329
330 /* We don't do any conversions that can fail.
331 */
332 (void) g_value_transform( value, &meta->value );
333
334 image->meta_traverse = g_slist_append( image->meta_traverse, meta );
335 g_hash_table_replace( image->meta, meta->name, meta );
336
337 #ifdef DEBUG
338 {
339 char *str_value;
340
341 str_value = g_strdup_value_contents( value );
342 printf( "meta_new: name %s, value = %s\n", name, str_value );
343 g_free( str_value );
344 }
345 #endif /*DEBUG*/
346
347 return( meta );
348 }
349
350 /* Destroy all the meta on an image.
351 */
352 void
vips__meta_destroy(VipsImage * image)353 vips__meta_destroy( VipsImage *image )
354 {
355 VIPS_FREEF( g_hash_table_destroy, image->meta );
356 g_assert( !image->meta_traverse );
357 }
358
359 static void
meta_init(VipsImage * im)360 meta_init( VipsImage *im )
361 {
362 if( !im->meta ) {
363 g_assert( !im->meta_traverse );
364 im->meta = g_hash_table_new_full( g_str_hash, g_str_equal,
365 NULL, (GDestroyNotify) meta_free );
366 }
367 }
368
369 /**
370 * vips_image_get_width: (method)
371 * @image: image to get from
372 *
373 * Returns: the number of pixels across the image.
374 */
375 int
vips_image_get_width(const VipsImage * image)376 vips_image_get_width( const VipsImage *image )
377 {
378 return( image->Xsize );
379 }
380
381 /**
382 * vips_image_get_height: (method)
383 * @image: image to get from
384 *
385 * Returns: the number of pixels down the image.
386 */
387 int
vips_image_get_height(const VipsImage * image)388 vips_image_get_height( const VipsImage *image )
389 {
390 return( image->Ysize );
391 }
392
393 /**
394 * vips_image_get_bands: (method)
395 * @image: image to get from
396 *
397 * Returns: the number of bands (channels) in the image.
398 */
399 int
vips_image_get_bands(const VipsImage * image)400 vips_image_get_bands( const VipsImage *image )
401 {
402 return( image->Bands );
403 }
404
405 /**
406 * vips_image_get_format: (method)
407 * @image: image to get from
408 *
409 * Returns: the format of each band element.
410 */
411 VipsBandFormat
vips_image_get_format(const VipsImage * image)412 vips_image_get_format( const VipsImage *image )
413 {
414 return( image->BandFmt );
415 }
416
417 /**
418 * vips_image_get_format_max: (method)
419 * @image: image to get from
420 *
421 * Returns: the maximum numeric value possible for this format.
422 */
423 double
vips_image_get_format_max(VipsBandFormat format)424 vips_image_get_format_max( VipsBandFormat format )
425 {
426 switch( format ) {
427 case VIPS_FORMAT_UCHAR:
428 return( UCHAR_MAX );
429
430 case VIPS_FORMAT_CHAR:
431 return( SCHAR_MAX );
432
433 case VIPS_FORMAT_USHORT:
434 return( USHRT_MAX );
435
436 case VIPS_FORMAT_SHORT:
437 return( SHRT_MAX );
438
439 case VIPS_FORMAT_UINT:
440 return( UINT_MAX );
441
442 case VIPS_FORMAT_INT:
443 return( INT_MAX );
444
445 case VIPS_FORMAT_FLOAT:
446 case VIPS_FORMAT_COMPLEX:
447 return( FLT_MAX );
448
449 case VIPS_FORMAT_DOUBLE:
450 case VIPS_FORMAT_DPCOMPLEX:
451 return( DBL_MAX );
452
453 default:
454 return( -1 );
455 }
456 }
457
458 /**
459 * vips_image_guess_format: (method)
460 * @image: image to guess for
461 *
462 * Return the #VipsBandFormat for an image, guessing a sane value if
463 * the set value looks crazy.
464 *
465 * For example, for a float image tagged as rgb16, we'd return ushort.
466 *
467 * Returns: a sensible #VipsBandFormat for the image.
468 */
469 VipsBandFormat
vips_image_guess_format(const VipsImage * image)470 vips_image_guess_format( const VipsImage *image )
471 {
472 VipsBandFormat format;
473
474 /* Stop a compiler warning.
475 */
476 format = VIPS_FORMAT_UCHAR;
477
478 switch( image->Type ) {
479 case VIPS_INTERPRETATION_B_W:
480 case VIPS_INTERPRETATION_HISTOGRAM:
481 case VIPS_INTERPRETATION_MULTIBAND:
482 format = image->BandFmt;
483 break;
484
485 case VIPS_INTERPRETATION_FOURIER:
486 if( image->BandFmt == VIPS_FORMAT_DOUBLE ||
487 image->BandFmt == VIPS_FORMAT_DPCOMPLEX )
488 format = VIPS_FORMAT_DPCOMPLEX;
489 else
490 format = VIPS_FORMAT_COMPLEX;
491 break;
492
493 case VIPS_INTERPRETATION_sRGB:
494 case VIPS_INTERPRETATION_RGB:
495 format = VIPS_FORMAT_UCHAR;
496 break;
497
498 case VIPS_INTERPRETATION_XYZ:
499 case VIPS_INTERPRETATION_LAB:
500 case VIPS_INTERPRETATION_CMC:
501 case VIPS_INTERPRETATION_LCH:
502 case VIPS_INTERPRETATION_HSV:
503 case VIPS_INTERPRETATION_scRGB:
504 case VIPS_INTERPRETATION_YXY:
505 format = VIPS_FORMAT_FLOAT;
506 break;
507
508 case VIPS_INTERPRETATION_CMYK:
509 if( image->BandFmt == VIPS_FORMAT_USHORT )
510 format = VIPS_FORMAT_USHORT;
511 else
512 format = VIPS_FORMAT_UCHAR;
513 break;
514
515 case VIPS_INTERPRETATION_LABQ:
516 format = VIPS_FORMAT_UCHAR;
517 break;
518
519 case VIPS_INTERPRETATION_LABS:
520 format = VIPS_FORMAT_SHORT;
521 break;
522
523 case VIPS_INTERPRETATION_GREY16:
524 case VIPS_INTERPRETATION_RGB16:
525 format = VIPS_FORMAT_USHORT;
526 break;
527
528 case VIPS_INTERPRETATION_MATRIX:
529 if( image->BandFmt == VIPS_FORMAT_DOUBLE )
530 format = VIPS_FORMAT_DOUBLE;
531 else
532 format = VIPS_FORMAT_FLOAT;
533 break;
534
535 default:
536 format = VIPS_FORMAT_NOTSET;
537 break;
538 }
539
540 return( format );
541 }
542
543 /**
544 * vips_image_get_coding: (method)
545 * @image: image to get from
546 *
547 * Returns: the image coding
548 */
549 VipsCoding
vips_image_get_coding(const VipsImage * image)550 vips_image_get_coding( const VipsImage *image )
551 {
552 return( image->Coding );
553 }
554
555 /**
556 * vips_image_get_interpretation: (method)
557 * @image: image to get from
558 *
559 * Return the #VipsInterpretation set in the image header.
560 * Use vips_image_guess_interpretation() if you want a sanity-checked value.
561 *
562 * Returns: the #VipsInterpretation from the image header.
563 */
564 VipsInterpretation
vips_image_get_interpretation(const VipsImage * image)565 vips_image_get_interpretation( const VipsImage *image )
566 {
567 return( image->Type );
568 }
569
570 /* Try to guess a sane value for interpretation.
571 */
572 static VipsInterpretation
vips_image_default_interpretation(const VipsImage * image)573 vips_image_default_interpretation( const VipsImage *image )
574 {
575 switch( image->Coding ) {
576 case VIPS_CODING_LABQ:
577 return( VIPS_INTERPRETATION_LABQ );
578 case VIPS_CODING_RAD:
579 return( VIPS_INTERPRETATION_sRGB );
580 default:
581 break;
582 }
583
584 /* 1 and 2 bands -> greyscale. The extra band could be alpha.
585 */
586 if( image->Bands < 3 ) {
587 if( image->BandFmt == VIPS_FORMAT_USHORT )
588 return( VIPS_INTERPRETATION_GREY16 );
589 else
590 return( VIPS_INTERPRETATION_B_W );
591 }
592 else {
593 /* 3 or more -> some sort of RGB. You'll need to set CMYK
594 * explicitly if you want that.
595 */
596 if( image->BandFmt == VIPS_FORMAT_USHORT )
597 return( VIPS_INTERPRETATION_RGB16 );
598 else
599 return( VIPS_INTERPRETATION_sRGB );
600 }
601 }
602
603 /**
604 * vips_image_guess_interpretation: (method)
605 * @image: image to guess for
606 *
607 * Return the #VipsInterpretation for an image, guessing a sane value if
608 * the set value looks crazy.
609 *
610 * Returns: a sensible #VipsInterpretation for the image.
611 */
612 VipsInterpretation
vips_image_guess_interpretation(const VipsImage * image)613 vips_image_guess_interpretation( const VipsImage *image )
614 {
615 gboolean sane;
616
617 sane = TRUE;
618
619 /* Coding overrides interpretation.
620 */
621 switch( image->Coding ) {
622 case VIPS_CODING_ERROR:
623 sane = FALSE;
624 break;
625
626 case VIPS_CODING_LABQ:
627 if( image->Type != VIPS_INTERPRETATION_LABQ )
628 sane = FALSE;
629 break;
630
631 case VIPS_CODING_RAD:
632 if( image->Type != VIPS_INTERPRETATION_sRGB )
633 sane = FALSE;
634 break;
635
636 default:
637 break;
638 }
639
640 switch( image->Type ) {
641 case VIPS_INTERPRETATION_ERROR:
642 sane = FALSE;
643 break;
644
645 case VIPS_INTERPRETATION_MULTIBAND:
646 /* This is a pretty useless generic tag. Always reset it.
647 */
648 sane = FALSE;
649 break;
650
651 case VIPS_INTERPRETATION_B_W:
652 /* Don't test bands, we allow bands after the first to be
653 * unused extras, like alpha.
654 */
655 break;
656
657 case VIPS_INTERPRETATION_HISTOGRAM:
658 if( image->Xsize > 1 && image->Ysize > 1 )
659 sane = FALSE;
660 break;
661
662 case VIPS_INTERPRETATION_FOURIER:
663 if( !vips_band_format_iscomplex( image->BandFmt ) )
664 sane = FALSE;
665 break;
666
667 case VIPS_INTERPRETATION_XYZ:
668 case VIPS_INTERPRETATION_LAB:
669 case VIPS_INTERPRETATION_RGB:
670 case VIPS_INTERPRETATION_CMC:
671 case VIPS_INTERPRETATION_LCH:
672 case VIPS_INTERPRETATION_sRGB:
673 case VIPS_INTERPRETATION_HSV:
674 case VIPS_INTERPRETATION_scRGB:
675 case VIPS_INTERPRETATION_YXY:
676 if( image->Bands < 3 )
677 sane = FALSE;
678 break;
679
680 case VIPS_INTERPRETATION_CMYK:
681 if( image->Bands < 4 )
682 sane = FALSE;
683 break;
684
685 case VIPS_INTERPRETATION_LABQ:
686 if( image->Coding != VIPS_CODING_LABQ )
687 sane = FALSE;
688 break;
689
690 case VIPS_INTERPRETATION_LABS:
691 if( image->BandFmt != VIPS_FORMAT_SHORT )
692 sane = FALSE;
693 break;
694
695 case VIPS_INTERPRETATION_RGB16:
696 if( image->BandFmt == VIPS_FORMAT_CHAR ||
697 image->BandFmt == VIPS_FORMAT_UCHAR ||
698 image->Bands < 3 )
699 sane = FALSE;
700 break;
701
702 case VIPS_INTERPRETATION_GREY16:
703 if( image->BandFmt == VIPS_FORMAT_CHAR ||
704 image->BandFmt == VIPS_FORMAT_UCHAR )
705 sane = FALSE;
706 break;
707
708 case VIPS_INTERPRETATION_MATRIX:
709 if( image->Bands != 1 )
710 sane = FALSE;
711 break;
712
713 default:
714 g_assert_not_reached();
715 }
716
717 if( sane )
718 return( vips_image_get_interpretation( image ) );
719 else
720 return( vips_image_default_interpretation( image ) );
721 }
722
723 /**
724 * vips_image_get_xres: (method)
725 * @image: image to get from
726 *
727 * Returns: the horizontal image resolution in pixels per millimeter.
728 */
729 double
vips_image_get_xres(const VipsImage * image)730 vips_image_get_xres( const VipsImage *image )
731 {
732 return( image->Xres );
733 }
734
735 /**
736 * vips_image_get_yres: (method)
737 * @image: image to get from
738 *
739 * Returns: the vertical image resolution in pixels per millimeter.
740 */
741 double
vips_image_get_yres(const VipsImage * image)742 vips_image_get_yres( const VipsImage *image )
743 {
744 return( image->Yres );
745 }
746
747 /**
748 * vips_image_get_xoffset: (method)
749 * @image: image to get from
750 *
751 * Returns: the horizontal position of the image origin, in pixels.
752 */
753 int
vips_image_get_xoffset(const VipsImage * image)754 vips_image_get_xoffset( const VipsImage *image )
755 {
756 return( image->Xoffset );
757 }
758
759 /**
760 * vips_image_get_yoffset: (method)
761 * @image: image to get from
762 *
763 * Returns: the vertical position of the image origin, in pixels.
764 */
765 int
vips_image_get_yoffset(const VipsImage * image)766 vips_image_get_yoffset( const VipsImage *image )
767 {
768 return( image->Yoffset );
769 }
770
771 /**
772 * vips_image_get_filename: (method)
773 * @image: image to get from
774 *
775 * Returns: the name of the file the image was loaded from, or NULL if there
776 * is no filename.
777 */
778 const char *
vips_image_get_filename(const VipsImage * image)779 vips_image_get_filename( const VipsImage *image )
780 {
781 return( image->filename );
782 }
783
784 /**
785 * vips_image_get_mode: (method)
786 * @image: image to get from
787 *
788 * Image modes are things like `"t"`, meaning a memory buffer, and `"p"`
789 * meaning a delayed computation.
790 *
791 * Returns: the image mode.
792 */
793 const char *
vips_image_get_mode(const VipsImage * image)794 vips_image_get_mode( const VipsImage *image )
795 {
796 return( image->mode );
797 }
798
799 /**
800 * vips_image_get_scale: (method)
801 * @image: image to get from
802 *
803 * Matrix images can have an optional `scale` field for use by integer
804 * convolution.
805 *
806 * Returns: the scale.
807 */
808 double
vips_image_get_scale(const VipsImage * image)809 vips_image_get_scale( const VipsImage *image )
810 {
811 double scale;
812
813 scale = 1.0;
814 if( vips_image_get_typeof( image, "scale" ) )
815 vips_image_get_double( image, "scale", &scale );
816
817 return( scale );
818 }
819
820 /**
821 * vips_image_get_offset: (method)
822 * @image: image to get from
823 *
824 * Matrix images can have an optional `offset` field for use by integer
825 * convolution.
826 *
827 * Returns: the offset.
828 */
829 double
vips_image_get_offset(const VipsImage * image)830 vips_image_get_offset( const VipsImage *image )
831 {
832 double offset;
833
834 offset = 0.0;
835 if( vips_image_get_typeof( image, "offset" ) )
836 vips_image_get_double( image, "offset", &offset );
837
838 return( offset );
839 }
840
841 /**
842 * vips_image_get_page_height: (method)
843 * @image: image to get from
844 *
845 * Multi-page images can have a page height. Fetch it, and sanity check it. If
846 * page-height is not set, it defaults to the image height.
847 *
848 * Returns: the page height.
849 */
850 int
vips_image_get_page_height(VipsImage * image)851 vips_image_get_page_height( VipsImage *image )
852 {
853 int page_height;
854
855 if( vips_image_get_typeof( image, VIPS_META_PAGE_HEIGHT ) &&
856 !vips_image_get_int( image, VIPS_META_PAGE_HEIGHT,
857 &page_height ) &&
858 page_height > 0 &&
859 page_height < image->Ysize &&
860 image->Ysize % page_height == 0 )
861 return( page_height );
862
863 return( image->Ysize );
864 }
865
866 /**
867 * vips_image_get_n_pages: (method)
868 * @image: image to get from
869 *
870 * Fetch and sanity-check #VIPS_META_N_PAGES. Default to 1 if not present or
871 * crazy.
872 *
873 * This is the number of pages in the image file, not the number of pages that
874 * have been loaded into @image.
875 *
876 * Returns: the number of pages in the image file
877 */
878 int
vips_image_get_n_pages(VipsImage * image)879 vips_image_get_n_pages( VipsImage *image )
880 {
881 int n_pages;
882
883 if( vips_image_get_typeof( image, VIPS_META_N_PAGES ) &&
884 !vips_image_get_int( image, VIPS_META_N_PAGES, &n_pages ) &&
885 n_pages > 1 &&
886 n_pages < 10000 )
887 return( n_pages );
888
889 return( 1 );
890 }
891
892 /**
893 * vips_image_get_n_subifds: (method)
894 * @image: image to get from
895 *
896 * Fetch and sanity-check #VIPS_META_N_SUBIFDS. Default to 0 if not present or
897 * crazy.
898 *
899 * Returns: the number of subifds in the image file
900 */
901 int
vips_image_get_n_subifds(VipsImage * image)902 vips_image_get_n_subifds( VipsImage *image )
903 {
904 int n_subifds;
905
906 if( vips_image_get_typeof( image, VIPS_META_N_SUBIFDS ) &&
907 !vips_image_get_int( image, VIPS_META_N_SUBIFDS, &n_subifds ) &&
908 n_subifds > 1 &&
909 n_subifds < 1000 )
910 return( n_subifds );
911
912 return( 0 );
913 }
914
915 /**
916 * vips_image_get_orientation: (method)
917 * @image: image to get from
918 *
919 * Fetch and sanity-check #VIPS_META_ORIENTATION. Default to 1 (no rotate,
920 * no flip) if not present or crazy.
921 *
922 * Returns: the image orientation.
923 */
924 int
vips_image_get_orientation(VipsImage * image)925 vips_image_get_orientation( VipsImage *image )
926 {
927 int orientation;
928
929 if( vips_image_get_typeof( image, VIPS_META_ORIENTATION ) &&
930 !vips_image_get_int( image, VIPS_META_ORIENTATION,
931 &orientation ) &&
932 orientation > 0 &&
933 orientation < 9 )
934 return( orientation );
935
936 return( 1 );
937 }
938
939 /**
940 * vips_image_get_orientation_swap: (method)
941 * @image: image to get from
942 *
943 * Return %TRUE if applying the orientation would swap width and height.
944 *
945 * Returns: if width/height will swap
946 */
947 gboolean
vips_image_get_orientation_swap(VipsImage * image)948 vips_image_get_orientation_swap( VipsImage *image )
949 {
950 int orientation = vips_image_get_orientation( image );
951
952 return( orientation >= 5 &&
953 orientation <= 8 );
954 }
955
956 /**
957 * vips_image_get_data: (method)
958 * @image: image to get data for
959 *
960 * Return a pointer to the image's pixel data, if possible. This can involve
961 * allocating large amounts of memory and performing a long computation. Image
962 * pixels are laid out in band-packed rows.
963 *
964 * Since this function modifies @image, it is not threadsafe. Only call it on
965 * images which you are sure have not been shared with another thread.
966 *
967 * See also: vips_image_wio_input(), vips_image_copy_memory().
968 *
969 * Returns: (transfer none): a pointer to pixel data, if possible.
970 */
971 const void *
vips_image_get_data(VipsImage * image)972 vips_image_get_data( VipsImage *image )
973 {
974 if( vips_image_wio_input( image ) )
975 return( NULL );
976
977 return( image->data );
978 }
979
980 /**
981 * vips_image_init_fields: (method)
982 * @image: image to init
983 * @xsize: image width
984 * @ysize: image height
985 * @bands: image bands
986 * @format: band format
987 * @coding: image coding
988 * @interpretation: image type
989 * @xres: horizontal resolution, pixels per millimetre
990 * @yres: vertical resolution, pixels per millimetre
991 *
992 * A convenience function to set the header fields after creating an image.
993 * Normally you copy the fields from your input images with
994 * vips_image_pipelinev() and then make
995 * any adjustments you need, but if you are creating an image from scratch,
996 * for example vips_black() or vips_jpegload(), you do need to set all the
997 * fields yourself.
998 *
999 * See also: vips_image_pipelinev().
1000 */
1001 void
vips_image_init_fields(VipsImage * image,int xsize,int ysize,int bands,VipsBandFormat format,VipsCoding coding,VipsInterpretation interpretation,double xres,double yres)1002 vips_image_init_fields( VipsImage *image,
1003 int xsize, int ysize, int bands,
1004 VipsBandFormat format, VipsCoding coding,
1005 VipsInterpretation interpretation,
1006 double xres, double yres )
1007 {
1008 g_object_set( image,
1009 "width", xsize,
1010 "height", ysize,
1011 "bands", bands,
1012 "format", format,
1013 NULL );
1014
1015 image->Coding = coding;
1016 image->Type = interpretation;
1017 image->Xres = xres;
1018 image->Yres = yres;
1019 }
1020
1021 static void *
meta_cp_field(VipsMeta * meta,VipsImage * dst,void * b)1022 meta_cp_field( VipsMeta *meta, VipsImage *dst, void *b )
1023 {
1024 #ifdef DEBUG
1025 {
1026 char *str_value;
1027
1028 str_value = g_strdup_value_contents( &meta->value );
1029 printf( "vips__meta_cp: copying name %s, value = %s\n",
1030 meta->name, str_value );
1031 g_free( str_value );
1032 }
1033 #endif /*DEBUG*/
1034
1035 (void) meta_new( dst, meta->name, &meta->value );
1036
1037 #ifdef DEBUG
1038 meta_sanity( dst );
1039 #endif /*DEBUG*/
1040
1041 return( NULL );
1042 }
1043
1044 /* Copy meta on to dst.
1045 */
1046 int
vips__image_meta_copy(VipsImage * dst,const VipsImage * src)1047 vips__image_meta_copy( VipsImage *dst, const VipsImage *src )
1048 {
1049 if( src->meta ) {
1050 /* We lock with vips_image_set() to stop races in highly-
1051 * threaded applications.
1052 */
1053 g_mutex_lock( vips__meta_lock );
1054 meta_init( dst );
1055 vips_slist_map2( src->meta_traverse,
1056 (VipsSListMap2Fn) meta_cp_field, dst, NULL );
1057 g_mutex_unlock( vips__meta_lock );
1058 }
1059
1060 return( 0 );
1061 }
1062
1063 /* We have to have this as a separate entry point so we can support the old
1064 * vips7 API.
1065 */
1066 int
vips__image_copy_fields_array(VipsImage * out,VipsImage * in[])1067 vips__image_copy_fields_array( VipsImage *out, VipsImage *in[] )
1068 {
1069 int i;
1070 int ni;
1071
1072 g_assert( in[0] );
1073
1074 /* Copy magic too, handy for knowing the original image's byte order.
1075 */
1076 out->magic = in[0]->magic;
1077
1078 out->Xsize = in[0]->Xsize;
1079 out->Ysize = in[0]->Ysize;
1080 out->Bands = in[0]->Bands;
1081 out->Bbits = in[0]->Bbits;
1082 out->BandFmt = in[0]->BandFmt;
1083 out->Type = in[0]->Type;
1084 out->Coding = in[0]->Coding;
1085 out->Xres = in[0]->Xres;
1086 out->Yres = in[0]->Yres;
1087 out->Xoffset = in[0]->Xoffset;
1088 out->Yoffset = in[0]->Yoffset;
1089
1090 /* Count number of images.
1091 */
1092 for( ni = 0; in[ni]; ni++ )
1093 ;
1094
1095 /* Need to copy last-to-first so that in0 meta will override any
1096 * earlier meta.
1097 *
1098 * Don't destroy the meta on out. Things like foreign.c like setting
1099 * image properties before calling a subclass loader, and those
1100 * subclass loaders will sometimes write to an image.
1101 */
1102 for( i = ni - 1; i >= 0; i-- )
1103 if( vips__image_meta_copy( out, in[i] ) )
1104 return( -1 );
1105
1106 /* Merge hists first to last.
1107 */
1108 for( i = 0; in[i]; i++ )
1109 out->history_list = vips__gslist_gvalue_merge(
1110 out->history_list, in[i]->history_list );
1111
1112 return( 0 );
1113 }
1114
1115 /**
1116 * vips_image_set: (method)
1117 * @image: image to set the metadata on
1118 * @name: the name to give the metadata
1119 * @value: the %GValue to copy into the image
1120 *
1121 * Set a piece of metadata on @image. Any old metadata with that name is
1122 * destroyed. The %GValue is copied into the image, so you need to unset the
1123 * value when you're done with it.
1124 *
1125 * For example, to set an integer on an image (though you would use the
1126 * convenience function vips_image_set_int() in practice), you would do:
1127 *
1128 * |[
1129 * GValue value = { 0 };
1130 *
1131 * g_value_init (&value, G_TYPE_INT);
1132 * g_value_set_int (&value, 42);
1133 * vips_image_set (image, name, &value);
1134 * g_value_unset (&value);
1135 * ]|
1136 *
1137 * See also: vips_image_get().
1138 */
1139 void
vips_image_set(VipsImage * image,const char * name,GValue * value)1140 vips_image_set( VipsImage *image, const char *name, GValue *value )
1141 {
1142 g_assert( name );
1143 g_assert( value );
1144
1145 /* We lock between modifying metadata and copying metadata between
1146 * images, see vips__image_meta_copy().
1147 *
1148 * This prevents modification of metadata by one thread racing with
1149 * metadata copy on another -- this can lead to crashes in
1150 * highly-threaded applications.
1151 */
1152 g_mutex_lock( vips__meta_lock );
1153 meta_init( image );
1154 (void) meta_new( image, name, value );
1155 g_mutex_unlock( vips__meta_lock );
1156
1157 /* If we're setting an EXIF data block, we need to automatically expand
1158 * out all the tags. This will set things like xres/yres too.
1159 *
1160 * We do this here rather than in meta_new() since we don't want to
1161 * trigger on copy_fields.
1162 */
1163 if( strcmp( name, VIPS_META_EXIF_NAME ) == 0 )
1164 if( vips__exif_parse( image ) )
1165 g_warning( "image_set: bad exif data" );
1166
1167 #ifdef DEBUG
1168 meta_sanity( image );
1169 #endif /*DEBUG*/
1170
1171 }
1172
1173 /* Unforunately gvalue seems to have no way of doing this. Just handle the vips
1174 * built-in types.
1175 */
1176 static void
vips_set_value_from_pointer(GValue * value,void * data)1177 vips_set_value_from_pointer( GValue *value, void *data )
1178 {
1179 GType type = G_VALUE_TYPE( value );
1180
1181 /* The fundamental type ... eg. G_TYPE_ENUM for a VIPS_TYPE_KERNEL,
1182 * or G_TYPE_OBJECT for VIPS_TYPE_IMAGE().
1183 */
1184 GType fundamental = G_TYPE_FUNDAMENTAL( type );
1185
1186 if( fundamental == G_TYPE_INT )
1187 g_value_set_int( value, *((int *) data) );
1188 else if( fundamental == G_TYPE_DOUBLE )
1189 g_value_set_double( value, *((double *) data) );
1190 else if( fundamental == G_TYPE_ENUM )
1191 g_value_set_enum( value, *((int *) data) );
1192 else if( fundamental == G_TYPE_STRING )
1193 g_value_set_string( value, *((char **) data) );
1194 else
1195 g_warning( "%s: unimplemented vips_set_value_from_pointer() "
1196 "type %s",
1197 G_STRLOC,
1198 g_type_name( type ) );
1199 }
1200
1201 /**
1202 * vips_image_get: (method)
1203 * @image: image to get the field from from
1204 * @name: the name to fetch
1205 * @value_copy: (transfer full) (out caller-allocates): the %GValue is copied into this
1206 *
1207 * Fill @value_copy with a copy of the header field. @value_copy must be zeroed
1208 * but uninitialised.
1209 *
1210 * This will return -1 and add a message to the error buffer if the field
1211 * does not exist. Use vips_image_get_typeof() to test for the
1212 * existence of a field first if you are not certain it will be there.
1213 *
1214 * For example, to read a double from an image (though of course you would use
1215 * vips_image_get_double() in practice):
1216 *
1217 * |[
1218 * GValue value = { 0 };
1219 * double d;
1220 *
1221 * if (vips_image_get (image, name, &value))
1222 * return -1;
1223 *
1224 * if (G_VALUE_TYPE (&value) != G_TYPE_DOUBLE) {
1225 * vips_error( "mydomain",
1226 * _("field \"%s\" is of type %s, not double"),
1227 * name,
1228 * g_type_name (G_VALUE_TYPE (&value)));
1229 * g_value_unset (&value);
1230 * return -1;
1231 * }
1232 *
1233 * d = g_value_get_double (&value);
1234 * g_value_unset (&value);
1235 * ]|
1236 *
1237 * See also: vips_image_get_typeof(), vips_image_get_double().
1238 *
1239 * Returns: (skip): 0 on success, -1 otherwise.
1240 */
1241 int
vips_image_get(const VipsImage * image,const char * name,GValue * value_copy)1242 vips_image_get( const VipsImage *image, const char *name, GValue *value_copy )
1243 {
1244 int i;
1245 VipsMeta *meta;
1246
1247 g_assert( name );
1248 g_assert( value_copy );
1249
1250 for( i = 0; i < VIPS_NUMBER( vips_header_fields ); i++ ) {
1251 HeaderField *field = &vips_header_fields[i];
1252
1253 if( strcmp( field->name, name ) == 0 ) {
1254 GType gtype = g_type_from_name( field->type );
1255
1256 g_value_init( value_copy, gtype );
1257 vips_set_value_from_pointer( value_copy,
1258 G_STRUCT_MEMBER_P( image, field->offset ) );
1259 return( 0 );
1260 }
1261 }
1262
1263 for( i = 0; i < VIPS_NUMBER( vips_header_fields_old ); i++ ) {
1264 HeaderField *field = &vips_header_fields_old[i];
1265
1266 if( strcmp( field->name, name ) == 0 ) {
1267 GType gtype = g_type_from_name( field->type );
1268
1269 g_value_init( value_copy, gtype );
1270 vips_set_value_from_pointer( value_copy,
1271 G_STRUCT_MEMBER_P( image, field->offset ) );
1272 return( 0 );
1273 }
1274 }
1275
1276 if( image->meta &&
1277 (meta = g_hash_table_lookup( image->meta, name )) ) {
1278 g_value_init( value_copy, G_VALUE_TYPE( &meta->value ) );
1279 g_value_copy( &meta->value, value_copy );
1280
1281 return( 0 );
1282 }
1283
1284 vips_error( "vips_image_get", _( "field \"%s\" not found" ), name );
1285
1286 return( -1 );
1287 }
1288
1289 /**
1290 * vips_image_get_typeof: (method)
1291 * @image: image to test
1292 * @name: the name to search for
1293 *
1294 * Read the %GType for a header field. Returns zero if there is no
1295 * field of that name.
1296 *
1297 * See also: vips_image_get().
1298 *
1299 * Returns: the %GType of the field, or zero if there is no
1300 * field of that name.
1301 */
1302 GType
vips_image_get_typeof(const VipsImage * image,const char * name)1303 vips_image_get_typeof( const VipsImage *image, const char *name )
1304 {
1305 int i;
1306 VipsMeta *meta;
1307
1308 g_assert( name );
1309
1310 for( i = 0; i < VIPS_NUMBER( vips_header_fields ); i++ ) {
1311 HeaderField *field = &vips_header_fields[i];
1312
1313 if( strcmp( field->name, name ) == 0 )
1314 return( g_type_from_name( field->type ) );
1315 }
1316
1317 for( i = 0; i < VIPS_NUMBER( vips_header_fields_old ); i++ ) {
1318 HeaderField *field = &vips_header_fields_old[i];
1319
1320 if( strcmp( field->name, name ) == 0 )
1321 return( g_type_from_name( field->type ) );
1322 }
1323
1324 if( image->meta &&
1325 (meta = g_hash_table_lookup( image->meta, name )) )
1326 return( G_VALUE_TYPE( &meta->value ) );
1327
1328 VIPS_DEBUG_MSG( "vips_image_get_typeof: unknown field %s\n", name );
1329
1330 return( 0 );
1331 }
1332
1333 /**
1334 * vips_image_remove: (method)
1335 * @image: image to test
1336 * @name: the name to search for
1337 *
1338 * Find and remove an item of metadata. Return %FALSE if no metadata of that
1339 * name was found.
1340 *
1341 * See also: vips_image_set(), vips_image_get_typeof().
1342 *
1343 * Returns: %TRUE if an item of metadata of that name was found and removed
1344 */
1345 gboolean
vips_image_remove(VipsImage * image,const char * name)1346 vips_image_remove( VipsImage *image, const char *name )
1347 {
1348 gboolean result;
1349
1350 result = FALSE;
1351
1352 if( image->meta ) {
1353 /* We lock between modifying metadata and copying metadata
1354 * between images, see vips__image_meta_copy().
1355 *
1356 * This prevents modification of metadata by one thread
1357 * racing with metadata copy on another -- this can lead to
1358 * crashes in highly-threaded applications.
1359 */
1360 g_mutex_lock( vips__meta_lock );
1361 result = g_hash_table_remove( image->meta, name );
1362 g_mutex_unlock( vips__meta_lock );
1363 }
1364
1365 return( result );
1366 }
1367
1368 /* Deprecated header fields we hide from _map.
1369 */
1370 static const char *vips_image_header_deprecated[] = {
1371 "ipct-data",
1372 "gif-delay",
1373 "gif-loop"
1374 };
1375
1376 static void *
vips_image_map_fn(VipsMeta * meta,VipsImageMapFn fn,void * a)1377 vips_image_map_fn( VipsMeta *meta, VipsImageMapFn fn, void *a )
1378 {
1379 int i;
1380
1381 /* Hide deprecated fields.
1382 */
1383 for( i = 0; i < VIPS_NUMBER( vips_image_header_deprecated ); i++ )
1384 if( strcmp( meta->name, vips_image_header_deprecated[i] ) == 0 )
1385 return( NULL );
1386
1387 return( fn( meta->im, meta->name, &meta->value, a ) );
1388 }
1389
1390 /**
1391 * vips_image_map: (method)
1392 * @image: image to map over
1393 * @fn: (scope call): function to call for each header field
1394 * @a: (closure fn): user data for function
1395 *
1396 * This function calls @fn for every header field, including every item of
1397 * metadata.
1398 *
1399 * Like all _map functions, the user function should return %NULL to continue
1400 * iteration, or a non-%NULL pointer to indicate early termination.
1401 *
1402 * See also: vips_image_get_typeof(), vips_image_get().
1403 *
1404 * Returns: (transfer none): %NULL on success, the failing pointer otherwise.
1405 */
1406 void *
vips_image_map(VipsImage * image,VipsImageMapFn fn,void * a)1407 vips_image_map( VipsImage *image, VipsImageMapFn fn, void *a )
1408 {
1409 int i;
1410 GValue value = { 0 };
1411 void *result;
1412
1413 for( i = 0; i < VIPS_NUMBER( vips_header_fields ); i++ ) {
1414 HeaderField *field = &vips_header_fields[i];
1415
1416 (void) vips_image_get( image, field->name, &value );
1417 result = fn( image, field->name, &value, a );
1418 g_value_unset( &value );
1419
1420 if( result )
1421 return( result );
1422 }
1423
1424 if( image->meta_traverse &&
1425 (result = vips_slist_map2( image->meta_traverse,
1426 (VipsSListMap2Fn) vips_image_map_fn, fn, a )) )
1427 return( result );
1428
1429 return( NULL );
1430 }
1431
1432 static void *
count_fields(VipsImage * image,const char * field,GValue * value,void * a)1433 count_fields( VipsImage *image, const char *field, GValue *value, void *a )
1434 {
1435 int *n_fields = (int *) a;
1436
1437 *n_fields += 1;
1438
1439 return( NULL );
1440 }
1441
1442 static void *
add_fields(VipsImage * image,const char * field,GValue * value,void * a)1443 add_fields( VipsImage *image, const char *field, GValue *value, void *a )
1444 {
1445 gchar ***p = (gchar ***) a;
1446
1447 **p = g_strdup( field );
1448 *p += 1;
1449
1450 return( NULL );
1451 }
1452
1453 /**
1454 * vips_image_get_fields: (method)
1455 * @image: image to get fields from
1456 *
1457 * Get a %NULL-terminated array listing all the metadata field names on @image.
1458 * Free the return result with g_strfreev().
1459 *
1460 * This is handy for language bindings. From C, it's usually more convenient to
1461 * use vips_image_map().
1462 *
1463 * Returns: (transfer full): metadata fields in image, as a %NULL-terminated
1464 * array.
1465 */
1466 gchar **
vips_image_get_fields(VipsImage * image)1467 vips_image_get_fields( VipsImage *image )
1468 {
1469 int n_fields;
1470 gchar **fields;
1471 gchar **p;
1472
1473 n_fields = 0;
1474 (void) vips_image_map( image, count_fields, &n_fields );
1475 fields = g_new0( gchar *, n_fields + 1 );
1476 p = fields;
1477 (void) vips_image_map( image, add_fields, &p );
1478
1479 return( fields );
1480 }
1481
1482 /**
1483 * vips_image_set_area: (method)
1484 * @image: image to attach the metadata to
1485 * @name: metadata name
1486 * @free_fn: (scope async): free function for @data
1487 * @data: pointer to area of memory
1488 *
1489 * Attaches @data as a metadata item on @image under the name @name. When
1490 * VIPS no longer needs the metadata, it will be freed with @free_fn.
1491 *
1492 * See also: vips_image_get_double(), vips_image_set()
1493 */
1494 void
vips_image_set_area(VipsImage * image,const char * name,VipsCallbackFn free_fn,void * data)1495 vips_image_set_area( VipsImage *image, const char *name,
1496 VipsCallbackFn free_fn, void *data )
1497 {
1498 GValue value = { 0 };
1499
1500 vips_value_set_area( &value, free_fn, data );
1501 vips_image_set( image, name, &value );
1502 g_value_unset( &value );
1503 }
1504
1505 static int
meta_get_value(const VipsImage * image,const char * name,GType type,GValue * value_copy)1506 meta_get_value( const VipsImage *image,
1507 const char *name, GType type, GValue *value_copy )
1508 {
1509 GValue value = { 0 };
1510
1511 if( vips_image_get( image, name, &value ) )
1512 return( -1 );
1513 g_value_init( value_copy, type );
1514 if( !g_value_transform( &value, value_copy ) ) {
1515 vips_error( "VipsImage",
1516 _( "field \"%s\" is of type %s, not %s" ),
1517 name,
1518 g_type_name( G_VALUE_TYPE( &value ) ),
1519 g_type_name( type ) );
1520 g_value_unset( &value );
1521
1522 return( -1 );
1523 }
1524 g_value_unset( &value );
1525
1526 return( 0 );
1527 }
1528
1529 /**
1530 * vips_image_get_area: (method)
1531 * @image: image to get the metadata from
1532 * @name: metadata name
1533 * @data: (out): return metadata value
1534 *
1535 * Gets @data from @image under the name @name. A convenience
1536 * function over vips_image_get(). Use vips_image_get_typeof() to test for
1537 * the existence of a piece of metadata.
1538 *
1539 * See also: vips_image_set_area(), vips_image_get(),
1540 * vips_image_get_typeof()
1541 *
1542 * Returns: 0 on success, -1 otherwise.
1543 */
1544 int
vips_image_get_area(const VipsImage * image,const char * name,const void ** data)1545 vips_image_get_area( const VipsImage *image,
1546 const char *name, const void **data )
1547 {
1548 GValue value_copy = { 0 };
1549
1550 if( !meta_get_value( image, name, VIPS_TYPE_AREA, &value_copy ) ) {
1551 *data = vips_value_get_area( &value_copy, NULL );
1552 g_value_unset( &value_copy );
1553 return( 0 );
1554 }
1555
1556 return( -1 );
1557 }
1558
1559 /**
1560 * vips_image_set_blob: (method)
1561 * @image: image to attach the metadata to
1562 * @name: metadata name
1563 * @free_fn: (scope async): free function for @data
1564 * @data: pointer to area of memory
1565 * @length: length of memory area
1566 *
1567 * Attaches @blob as a metadata item on @image under the name @name. A
1568 * convenience
1569 * function over vips_image_set() using a vips_blob.
1570 *
1571 * See also: vips_image_get_blob(), vips_image_set().
1572 */
1573 void
vips_image_set_blob(VipsImage * image,const char * name,VipsCallbackFn free_fn,const void * data,size_t size)1574 vips_image_set_blob( VipsImage *image, const char *name,
1575 VipsCallbackFn free_fn, const void *data, size_t size )
1576 {
1577 GValue value = { 0 };
1578
1579 g_value_init( &value, VIPS_TYPE_BLOB );
1580 vips_value_set_blob( &value, free_fn, data, size );
1581 vips_image_set( image, name, &value );
1582 g_value_unset( &value );
1583 }
1584
1585 /**
1586 * vips_image_set_blob_copy: (method)
1587 * @image: image to attach the metadata to
1588 * @name: metadata name
1589 * @data: pointer to area of memory
1590 * @length: length of memory area
1591 *
1592 * Attaches @blob as a metadata item on @image under the name @name, taking
1593 * a copy of the memory area. A convenience function over
1594 * vips_image_set_blob().
1595 *
1596 * See also: vips_image_get_blob(), vips_image_set().
1597 */
1598 void
vips_image_set_blob_copy(VipsImage * image,const char * name,const void * data,size_t length)1599 vips_image_set_blob_copy( VipsImage *image,
1600 const char *name, const void *data, size_t length )
1601 {
1602 void *data_copy;
1603
1604 /* Cap at 100mb for sanity.
1605 */
1606 if( !data ||
1607 length == 0 ||
1608 length > 100 * 1024 * 1024 )
1609 return;
1610
1611 /* We add an extra, secret null byte at the end, just in case this blob
1612 * is read as a C string. The libtiff reader attaches
1613 * XMP XML as a blob, for example.
1614 */
1615 if( !(data_copy = vips_malloc( NULL, length + 1 )) )
1616 return;
1617 memcpy( data_copy, data, length );
1618 ((unsigned char *) data_copy)[length] = '\0';
1619
1620 vips_image_set_blob( image,
1621 name, (VipsCallbackFn) vips_area_free_cb, data_copy, length );
1622 }
1623
1624 /**
1625 * vips_image_get_blob: (method)
1626 * @image: image to get the metadata from
1627 * @name: metadata name
1628 * @data: pointer to area of memory
1629 * @length: return the blob length here, optionally
1630 *
1631 * Gets @blob from @image under the name @name, optionally returns its length in
1632 * @length. A convenience
1633 * function over vips_image_get(). Use vips_image_get_typeof() to test for the
1634 * existence
1635 * of a piece of metadata.
1636 *
1637 * See also: vips_image_get(), vips_image_get_typeof(), vips_blob_get(),
1638 *
1639 * Returns: 0 on success, -1 otherwise.
1640 */
1641 int
vips_image_get_blob(const VipsImage * image,const char * name,const void ** data,size_t * length)1642 vips_image_get_blob( const VipsImage *image, const char *name,
1643 const void **data, size_t *length )
1644 {
1645 GValue value_copy = { 0 };
1646
1647 if( !meta_get_value( image, name, VIPS_TYPE_BLOB, &value_copy ) ) {
1648 *data = vips_value_get_blob( &value_copy, length );
1649 g_value_unset( &value_copy );
1650 return( 0 );
1651 }
1652
1653 return( -1 );
1654 }
1655
1656 /**
1657 * vips_image_get_int: (method)
1658 * @image: image to get the header field from
1659 * @name: field name
1660 * @out: (out): return field value
1661 *
1662 * Gets @out from @im under the name @name.
1663 * The value will be transformed into
1664 * an int, if possible.
1665 *
1666 * See also: vips_image_get(), vips_image_get_typeof()
1667 *
1668 * Returns: 0 on success, -1 otherwise.
1669 */
1670 int
vips_image_get_int(const VipsImage * image,const char * name,int * out)1671 vips_image_get_int( const VipsImage *image, const char *name, int *out )
1672 {
1673 GValue value = { 0 };
1674
1675 if( meta_get_value( image, name, G_TYPE_INT, &value ) )
1676 return( -1 );
1677 *out = g_value_get_int( &value );
1678 g_value_unset( &value );
1679
1680 return( 0 );
1681 }
1682
1683 /**
1684 * vips_image_set_int: (method)
1685 * @image: image to attach the metadata to
1686 * @name: metadata name
1687 * @i: metadata value
1688 *
1689 * Attaches @i as a metadata item on @image under the name @name. A
1690 * convenience
1691 * function over vips_image_set().
1692 *
1693 * See also: vips_image_get_int(), vips_image_set()
1694 */
1695 void
vips_image_set_int(VipsImage * image,const char * name,int i)1696 vips_image_set_int( VipsImage *image, const char *name, int i )
1697 {
1698 GValue value = { 0 };
1699
1700 g_value_init( &value, G_TYPE_INT );
1701 g_value_set_int( &value, i );
1702 vips_image_set( image, name, &value );
1703 g_value_unset( &value );
1704 }
1705
1706 /**
1707 * vips_image_get_double: (method)
1708 * @image: image to get the header field from
1709 * @name: field name
1710 * @out: return field value
1711 *
1712 * Gets @out from @im under the name @name.
1713 * The value will be transformed into
1714 * a double, if possible.
1715 *
1716 * See also: vips_image_get(), vips_image_get_typeof()
1717 *
1718 * Returns: 0 on success, -1 otherwise.
1719 */
1720 int
vips_image_get_double(const VipsImage * image,const char * name,double * out)1721 vips_image_get_double( const VipsImage *image, const char *name, double *out )
1722 {
1723 GValue value = { 0 };
1724
1725 if( meta_get_value( image, name, G_TYPE_DOUBLE, &value ) )
1726 return( -1 );
1727 *out = g_value_get_double( &value );
1728 g_value_unset( &value );
1729
1730 return( 0 );
1731 }
1732
1733 /**
1734 * vips_image_set_double: (method)
1735 * @image: image to attach the metadata to
1736 * @name: metadata name
1737 * @d: metadata value
1738 *
1739 * Attaches @d as a metadata item on @image as @name. A
1740 * convenience
1741 * function over vips_image_set().
1742 *
1743 * See also: vips_image_get_double(), vips_image_set()
1744 */
1745 void
vips_image_set_double(VipsImage * image,const char * name,double d)1746 vips_image_set_double( VipsImage *image, const char *name, double d )
1747 {
1748 GValue value = { 0 };
1749
1750 g_value_init( &value, G_TYPE_DOUBLE );
1751 g_value_set_double( &value, d );
1752 vips_image_set( image, name, &value );
1753 g_value_unset( &value );
1754 }
1755
1756 /**
1757 * vips_image_get_string: (method)
1758 * @image: image to get the header field from
1759 * @name: field name
1760 * @out: (transfer none): return field value
1761 *
1762 * Gets @out from @im under the name @name.
1763 * The field must be of type
1764 * G_TYPE_STRING, VIPS_TYPE_REF_STRING.
1765 *
1766 * Do not free @out.
1767 *
1768 * Use vips_image_get_as_string() to fetch any field as a string.
1769 *
1770 * See also: vips_image_get(), vips_image_get_typeof()
1771 *
1772 * Returns: 0 on success, -1 otherwise.
1773 */
1774 int
vips_image_get_string(const VipsImage * image,const char * name,const char ** out)1775 vips_image_get_string( const VipsImage *image, const char *name,
1776 const char **out )
1777 {
1778 GValue value = { 0 };
1779
1780 if( vips_image_get( image, name, &value ) )
1781 return( -1 );
1782
1783 if( G_VALUE_TYPE( &value ) == VIPS_TYPE_REF_STRING ) {
1784 VipsArea *area;
1785
1786 area = g_value_get_boxed( &value );
1787 *out = area->data;
1788 }
1789 else if( G_VALUE_TYPE( &value ) == G_TYPE_STRING ) {
1790 *out = g_value_get_string( &value );
1791 }
1792 else {
1793 vips_error( "VipsImage",
1794 _( "field \"%s\" is of type %s, not VipsRefString" ),
1795 name,
1796 g_type_name( G_VALUE_TYPE( &value ) ) );
1797 g_value_unset( &value );
1798
1799 return( -1 );
1800 }
1801
1802 g_value_unset( &value );
1803
1804 return( 0 );
1805 }
1806
1807 /**
1808 * vips_image_set_string: (method)
1809 * @image: image to attach the metadata to
1810 * @name: metadata name
1811 * @str: metadata value
1812 *
1813 * Attaches @str as a metadata item on @image as @name.
1814 * A convenience
1815 * function over vips_image_set() using #VIPS_TYPE_REF_STRING.
1816 *
1817 * See also: vips_image_get_double(), vips_image_set().
1818 */
1819 void
vips_image_set_string(VipsImage * image,const char * name,const char * str)1820 vips_image_set_string( VipsImage *image, const char *name, const char *str )
1821 {
1822 GValue value = { 0 };
1823
1824 g_value_init( &value, VIPS_TYPE_REF_STRING );
1825 vips_value_set_ref_string( &value, str );
1826 vips_image_set( image, name, &value );
1827 g_value_unset( &value );
1828 }
1829
1830 /**
1831 * vips_image_get_as_string: (method)
1832 * @image: image to get the header field from
1833 * @name: field name
1834 * @out: (transfer full): return field value as string
1835 *
1836 * Returns @name from @image in @out.
1837 * This function will read any field, returning it as a printable string.
1838 * You need to free the string with g_free() when you are done with it.
1839 *
1840 * This will base64-encode BLOBs, for example. Use vips_buf_appendgv() to
1841 * make a string that's for humans.
1842 *
1843 * See also: vips_image_get(), vips_image_get_typeof(), vips_buf_appendgv().
1844 *
1845 * Returns: 0 on success, -1 otherwise.
1846 */
1847 int
vips_image_get_as_string(const VipsImage * image,const char * name,char ** out)1848 vips_image_get_as_string( const VipsImage *image,
1849 const char *name, char **out )
1850 {
1851 GValue value = { 0 };
1852 GType type;
1853
1854 if( vips_image_get( image, name, &value ) )
1855 return( -1 );
1856
1857 /* Display the save form, if there is one. This way we display
1858 * something useful for ICC profiles, xml fields, etc.
1859 */
1860 type = G_VALUE_TYPE( &value );
1861 if( g_value_type_transformable( type, VIPS_TYPE_SAVE_STRING ) ) {
1862 GValue save_value = { 0 };
1863
1864 g_value_init( &save_value, VIPS_TYPE_SAVE_STRING );
1865 if( !g_value_transform( &value, &save_value ) )
1866 return( -1 );
1867 *out = g_strdup( vips_value_get_save_string( &save_value ) );
1868 g_value_unset( &save_value );
1869 }
1870 else
1871 *out = g_strdup_value_contents( &value );
1872
1873 g_value_unset( &value );
1874
1875 return( 0 );
1876 }
1877
1878 /**
1879 * vips_image_print_field: (method)
1880 * @image: image to get the header field from
1881 * @name: field name
1882 *
1883 * Prints field @name to stdout as ASCII. Handy for debugging.
1884 */
1885 void
vips_image_print_field(const VipsImage * image,const char * name)1886 vips_image_print_field( const VipsImage *image, const char *name )
1887 {
1888 char *str;
1889
1890 if( vips_image_get_as_string( image, name, &str ) ) {
1891 printf( "vips_image_print_field: unable to read field\n" );
1892 return;
1893 }
1894
1895 printf( ".%s: %s\n", name, str );
1896
1897 g_free( str );
1898 }
1899
1900 /**
1901 * vips_image_get_image: (method)
1902 * @image: image to get the metadata from
1903 * @name: metadata name
1904 * @out: (transfer full): return metadata value
1905 *
1906 * Gets @out from @im under the name @name.
1907 * The field must be of type
1908 * #VIPS_TYPE_IMAGE. You must unref @out with g_object_unref().
1909 *
1910 * Use vips_image_get_typeof() to test for the
1911 * existence of a piece of metadata.
1912 *
1913 * See also: vips_image_get(), vips_image_set_image()
1914 *
1915 * Returns: 0 on success, -1 otherwise.
1916 */
1917 int
vips_image_get_image(const VipsImage * image,const char * name,VipsImage ** out)1918 vips_image_get_image( const VipsImage *image,
1919 const char *name, VipsImage **out )
1920 {
1921 GValue value = { 0 };
1922
1923 if( meta_get_value( image, name, VIPS_TYPE_IMAGE, &value ) )
1924 return( -1 );
1925 *out = g_value_dup_object( &value );
1926 g_value_unset( &value );
1927
1928 return( 0 );
1929 }
1930
1931 /**
1932 * vips_image_set_image: (method)
1933 * @image: image to attach the metadata to
1934 * @name: metadata name
1935 * @im: metadata value
1936 *
1937 * Attaches @im as a metadata item on @image as @name.
1938 * A convenience function over vips_image_set().
1939 *
1940 * See also: vips_image_get_image(), vips_image_set().
1941 */
1942 void
vips_image_set_image(VipsImage * image,const char * name,VipsImage * im)1943 vips_image_set_image( VipsImage *image, const char *name, VipsImage *im )
1944 {
1945 GValue value = { 0 };
1946
1947 g_value_init( &value, VIPS_TYPE_IMAGE );
1948 g_value_set_object( &value, im );
1949 vips_image_set( image, name, &value );
1950 g_value_unset( &value );
1951 }
1952
1953 /**
1954 * vips_image_get_array_int: (method)
1955 * @image: image to get the metadata from
1956 * @name: metadata name
1957 * @out: (transfer none): return pointer to array
1958 * @n: (allow-none): return the number of elements here, optionally
1959 *
1960 * Gets @out from @im under the name @name.
1961 * The field must be of type
1962 * #VIPS_TYPE_ARRAY_INT.
1963 *
1964 * Do not free @out. @out is valid as long as @image is valid.
1965 *
1966 * Use vips_image_get_typeof() to test for the
1967 * existence of a piece of metadata.
1968 *
1969 * See also: vips_image_get(), vips_image_set_image()
1970 *
1971 * Returns: 0 on success, -1 otherwise.
1972 */
1973 int
vips_image_get_array_int(VipsImage * image,const char * name,int ** out,int * n)1974 vips_image_get_array_int( VipsImage *image, const char *name,
1975 int **out, int *n )
1976 {
1977 GValue value = { 0 };
1978
1979 if( meta_get_value( image, name, VIPS_TYPE_ARRAY_INT, &value ) )
1980 return( -1 );
1981 *out = vips_value_get_array_int( &value, n );
1982 g_value_unset( &value );
1983
1984 return( 0 );
1985 }
1986
1987 /**
1988 * vips_image_set_array_int: (method)
1989 * @image: image to attach the metadata to
1990 * @name: metadata name
1991 * @array: (array length=n) (allow-none): array of ints
1992 * @n: the number of elements
1993 *
1994 * Attaches @array as a metadata item on @image as @name.
1995 * A convenience function over vips_image_set().
1996 *
1997 * See also: vips_image_get_image(), vips_image_set().
1998 */
1999 void
vips_image_set_array_int(VipsImage * image,const char * name,const int * array,int n)2000 vips_image_set_array_int( VipsImage *image, const char *name,
2001 const int *array, int n )
2002 {
2003 GValue value = { 0 };
2004
2005 g_value_init( &value, VIPS_TYPE_ARRAY_INT );
2006 vips_value_set_array_int( &value, array, n );
2007 vips_image_set( image, name, &value );
2008 g_value_unset( &value );
2009 }
2010
2011 /**
2012 * vips_image_get_array_double: (method)
2013 * @image: image to get the metadata from
2014 * @name: metadata name
2015 * @out: (transfer none): return pointer to array
2016 * @n: (allow-none): return the number of elements here, optionally
2017 *
2018 * Gets @out from @im under the name @name.
2019 * The field must be of type
2020 * #VIPS_TYPE_ARRAY_INT.
2021 *
2022 * Do not free @out. @out is valid as long as @image is valid.
2023 *
2024 * Use vips_image_get_typeof() to test for the
2025 * existence of a piece of metadata.
2026 *
2027 * See also: vips_image_get(), vips_image_set_image()
2028 *
2029 * Returns: 0 on success, -1 otherwise.
2030 */
2031 int
vips_image_get_array_double(VipsImage * image,const char * name,double ** out,int * n)2032 vips_image_get_array_double( VipsImage *image, const char *name,
2033 double **out, int *n )
2034 {
2035 GValue value = { 0 };
2036
2037 if( meta_get_value( image, name, VIPS_TYPE_ARRAY_DOUBLE, &value ) )
2038 return( -1 );
2039 *out = vips_value_get_array_double( &value, n );
2040 g_value_unset( &value );
2041
2042 return( 0 );
2043 }
2044
2045 /**
2046 * vips_image_set_array_double: (method)
2047 * @image: image to attach the metadata to
2048 * @name: metadata name
2049 * @array: (array length=n) (allow-none): array of doubles
2050 * @n: the number of elements
2051 *
2052 * Attaches @array as a metadata item on @image as @name.
2053 * A convenience function over vips_image_set().
2054 *
2055 * See also: vips_image_get_image(), vips_image_set().
2056 */
2057 void
vips_image_set_array_double(VipsImage * image,const char * name,const double * array,int n)2058 vips_image_set_array_double( VipsImage *image, const char *name,
2059 const double *array, int n )
2060 {
2061 GValue value = { 0 };
2062
2063 g_value_init( &value, VIPS_TYPE_ARRAY_DOUBLE );
2064 vips_value_set_array_double( &value, array, n );
2065 vips_image_set( image, name, &value );
2066 g_value_unset( &value );
2067 }
2068
2069 /**
2070 * vips_image_history_printf: (method)
2071 * @image: add history line to this image
2072 * @format: printf() format string
2073 * @...: arguments to format string
2074 *
2075 * Add a line to the image history. The @format and arguments are expanded, the
2076 * date and time is appended prefixed with a hash character, and the whole
2077 * string is appended to the image history and terminated with a newline.
2078 *
2079 * For example:
2080 *
2081 * |[
2082 * vips_image_history_printf (image, "vips invert %s %s",
2083 * in->filename, out->filename);
2084 * ]|
2085 *
2086 * Might add the string
2087 *
2088 * |[
2089 * "vips invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35 2009\n"
2090 * ]|
2091 *
2092 * VIPS operations don't add history lines for you because a single action at
2093 * the application level might involve many VIPS operations. History must be
2094 * recorded by the application.
2095 *
2096 * Returns: 0 on success, -1 on error.
2097 */
2098 int
vips_image_history_printf(VipsImage * image,const char * fmt,...)2099 vips_image_history_printf( VipsImage *image, const char *fmt, ... )
2100 {
2101 va_list args;
2102 char str[VIPS_PATH_MAX];
2103 VipsBuf buf = VIPS_BUF_STATIC( str );
2104 time_t timebuf;
2105
2106 va_start( args, fmt );
2107 (void) vips_buf_vappendf( &buf, fmt, args );
2108 va_end( args );
2109 vips_buf_appends( &buf, " # " );
2110
2111 /* Add the date. ctime always attaches a '\n', gah.
2112 */
2113 time( &timebuf );
2114 vips_buf_appends( &buf, ctime( &timebuf ) );
2115 vips_buf_removec( &buf, '\n' );
2116
2117 #ifdef DEBUG
2118 printf( "vips_image_history_printf: "
2119 "adding:\n\t%s\nto history on image %p\n",
2120 vips_buf_all( &buf ), image );
2121 #endif /*DEBUG*/
2122
2123 image->history_list = g_slist_append( image->history_list,
2124 vips__gvalue_ref_string_new( vips_buf_all( &buf ) ) );
2125
2126 return( 0 );
2127 }
2128
2129 /**
2130 * vips_image_history_args: (method)
2131 * @image: image to attach history line to
2132 * @name: program name
2133 * @argc: number of program arguments
2134 * @argv: (array length=argc) (element-type char*): program arguments
2135 *
2136 * Formats the name/argv as a single string and calls
2137 * vips_image_history_printf(). A
2138 * convenience function for command-line prorams.
2139 *
2140 * See also: vips_image_get_history().
2141 *
2142 * Returns: 0 on success, -1 on error.
2143 */
2144 int
vips_image_history_args(VipsImage * image,const char * name,int argc,char * argv[])2145 vips_image_history_args( VipsImage *image,
2146 const char *name, int argc, char *argv[] )
2147 {
2148 int i;
2149 char txt[1024];
2150 VipsBuf buf = VIPS_BUF_STATIC( txt );
2151
2152 vips_buf_appends( &buf, name );
2153
2154 for( i = 0; i < argc; i++ ) {
2155 vips_buf_appends( &buf, " " );
2156 vips_buf_appends( &buf, argv[i] );
2157 }
2158
2159 if( vips_image_history_printf( image, "%s", vips_buf_all( &buf ) ) )
2160 return( -1 );
2161
2162 return( 0 );
2163 }
2164
2165 /**
2166 * vips_image_get_history: (method)
2167 * @image: get history from here
2168 *
2169 * This function reads the image history as a C string. The string is owned
2170 * by VIPS and must not be freed.
2171 *
2172 * VIPS tracks the history of each image, that is, the sequence of operations
2173 * that generated that image. Applications built on VIPS need to call
2174 * vips_image_history_printf() for each action they perform, setting the
2175 * command-line equivalent for the action.
2176 *
2177 * See also: vips_image_history_printf().
2178 *
2179 * Returns: (transfer none): The history of @image as a C string. Do not free!
2180 */
2181 const char *
vips_image_get_history(VipsImage * image)2182 vips_image_get_history( VipsImage *image )
2183 {
2184 if( !image->Hist )
2185 image->Hist = vips__gslist_gvalue_get( image->history_list );
2186
2187 return( image->Hist ? image->Hist : "" );
2188 }
2189
2190 /* Called during vips_init().
2191 */
2192 void
vips__meta_init(void)2193 vips__meta_init( void )
2194 {
2195 if( !vips__meta_lock )
2196 vips__meta_lock = vips_g_mutex_new();
2197 }
2198