1 /* error.c --- error message handling
2 *
3 * Copyright: N. Dessipris
4 * Written on: 18/03/1991
5 * Updated on: 9/7/92 KM
6 * 20/12/2003 JC
7 * - i18n added, domain now separate arg
8 * 14/2/07
9 * - lock around error buffer changes
10 * 20/2/08
11 * - lock around warnings and diagnostics too, why not
12 * 2/10/09
13 * - error_exit() moved here
14 * - gtkdoc comments
15 * 24/6/10
16 * - fmt to error_exit() may be NULL
17 * 12/9/19 [dineshkannaa]
18 * - add vips_error_buffer_copy()
19 */
20
21 /*
22
23 This file is part of VIPS.
24
25 VIPS is free software; you can redistribute it and/or modify
26 it under the terms of the GNU Lesser General Public License as published by
27 the Free Software Foundation; either version 2 of the License, or
28 (at your option) any later version.
29
30 This program is distributed in the hope that it will be useful,
31 but WITHOUT ANY WARRANTY; without even the implied warranty of
32 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
33 GNU Lesser General Public License for more details.
34
35 You should have received a copy of the GNU Lesser General Public License
36 along with this program; if not, write to the Free Software
37 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
38 02110-1301 USA
39
40 */
41
42 /*
43
44 These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
45
46 */
47
48 /*
49 #define VIPS_DEBUG
50 */
51
52 #ifdef HAVE_CONFIG_H
53 #include <config.h>
54 #endif /*HAVE_CONFIG_H*/
55 #include <vips/intl.h>
56
57 #include <stdio.h>
58 #include <stdarg.h>
59 #include <stdlib.h>
60 #include <string.h>
61
62 #include <vips/vips.h>
63 #include <vips/internal.h>
64 #include <vips/buf.h>
65 #include <vips/thread.h>
66 #include <vips/debug.h>
67
68 #ifdef G_OS_WIN32
69 #include <windows.h>
70 #include <lmerr.h>
71 #endif /*G_OS_WIN32*/
72
73 /**
74 * SECTION: errors
75 * @short_description: error messages and error handling
76 * @stability: Stable
77 * @include: vips/vips.h
78 *
79 * VIPS maintains an error buffer (a log of localised text messages),
80 * a set of functions
81 * for adding messages, and a way to access and clear the buffer.
82 *
83 * The error buffer is global, that is, it is shared between all threads. You
84 * can add to the buffer from any thread (there is a lock to prevent
85 * corruption), but it's sensible to only read and clear the buffer from the
86 * main thread of execution.
87 *
88 * The general principle is: if you detect an error, log a message for the
89 * user. If a function you call detects an error, just propogate it and don't
90 * add another message.
91 *
92 * |[
93 * IMAGE *im;
94 *
95 * if( !(im = vips_image_new_from_file( filename, NULL )) )
96 * // vips_image_new_from_file() will set a message, we don't need to
97 * return( -1 );
98 *
99 * if( vips_image_get_width( im ) < 100 ) {
100 * // we have detected an error, we must set a message
101 * vips_error( "myprogram", "%s", _( "width too small" ) );
102 * return( -1 );
103 * }
104 * ]|
105 *
106 * The domain argument most of these functions take is not localised and is
107 * supposed to indicate the component which failed.
108 *
109 * libvips uses g_warning() and g_info() to send warning and information
110 * messages to the user. You can use the usual glib mechanisms to display or
111 * divert these messages. For example, info messages are hidden by default, but
112 * you can see them with:
113 *
114 * |[
115 * $ G_MESSAGES_DEBUG=VIPS vipsthumbnail k2.jpg
116 * VIPS-INFO: thumbnailing k2.jpg
117 * VIPS-INFO: selected loader is VipsForeignLoadJpegFile
118 * VIPS-INFO: input size is 1450 x 2048
119 * VIPS-INFO: loading jpeg with factor 8 pre-shrink
120 * VIPS-INFO: converting to processing space srgb
121 * VIPS-INFO: residual reducev by 0.5
122 * VIPS-INFO: 13 point mask
123 * VIPS-INFO: using vector path
124 * VIPS-INFO: residual reduceh by 0.5
125 * VIPS-INFO: 13 point mask
126 * VIPS-INFO: thumbnailing k2.jpg as ./tn_k2.jpg
127 * ]|
128 *
129 */
130
131 /* Make global array to keep the error message buffer.
132 */
133 #define VIPS_MAX_ERROR (10240)
134 static char vips_error_text[VIPS_MAX_ERROR] = "";
135 static VipsBuf vips_error_buf = VIPS_BUF_STATIC( vips_error_text );
136 static int vips_error_freeze_count = 0;
137
138 /**
139 * vips_error_freeze:
140 *
141 * Stop errors being logged. Use vips_error_thaw() to unfreeze. You can
142 * nest freeze/thaw pairs.
143 */
144 void
vips_error_freeze(void)145 vips_error_freeze( void )
146 {
147 g_mutex_lock( vips__global_lock );
148 g_assert( vips_error_freeze_count >= 0 );
149 vips_error_freeze_count += 1;
150 g_mutex_unlock( vips__global_lock );
151 }
152
153 /**
154 * vips_error_thaw:
155 *
156 * Reenable error logging.
157 */
158 void
vips_error_thaw(void)159 vips_error_thaw( void )
160 {
161 g_mutex_lock( vips__global_lock );
162 vips_error_freeze_count -= 1;
163 g_assert( vips_error_freeze_count >= 0 );
164 g_mutex_unlock( vips__global_lock );
165 }
166
167 /**
168 * vips_error_buffer:
169 *
170 * Get a pointer to the start of the error buffer as a C string.
171 * The string is owned by the error system and must not be freed.
172 *
173 * See also: vips_error_clear().
174 *
175 * Returns: the error buffer as a C string which must not be freed
176 */
177 const char *
vips_error_buffer(void)178 vips_error_buffer( void )
179 {
180 const char *msg;
181
182 g_mutex_lock( vips__global_lock );
183 msg = vips_buf_all( &vips_error_buf );
184 g_mutex_unlock( vips__global_lock );
185
186 return( msg );
187 }
188
189 /**
190 * vips_error_buffer_copy:
191 *
192 * Return a copy of the vips error buffer, and clear it.
193 *
194 * Returns: a copy of the libvips error buffer
195 */
196 char *
vips_error_buffer_copy(void)197 vips_error_buffer_copy( void )
198 {
199 char *msg;
200
201 g_mutex_lock( vips__global_lock );
202 msg = g_strdup( vips_buf_all( &vips_error_buf ) );
203 vips_buf_rewind( &vips_error_buf );
204 g_mutex_unlock( vips__global_lock );
205
206 return( msg );
207 }
208
209 /* Some systems do not have va_copy() ... this might work (it does on MSVC,
210 * apparently).
211 *
212 * FIXME ... this should be in configure.in
213 */
214 #ifndef va_copy
215 #define va_copy(d,s) ((d) = (s))
216 #endif
217
218 /**
219 * vips_verror:
220 * @domain: the source of the error
221 * @fmt: printf()-style format string for the error
222 * @ap: arguments to the format string
223 *
224 * Append a message to the error buffer.
225 *
226 * See also: vips_error().
227 */
228 void
vips_verror(const char * domain,const char * fmt,va_list ap)229 vips_verror( const char *domain, const char *fmt, va_list ap )
230 {
231 #ifdef VIPS_DEBUG
232 {
233 char txt[256];
234 VipsBuf buf = VIPS_BUF_STATIC( txt );
235 va_list ap2;
236
237 vips_buf_appendf( &buf, "%s: ", domain );
238 va_copy( ap2, ap );
239 vips_buf_vappendf( &buf, fmt, ap2 );
240 vips_buf_appends( &buf, "\n" );
241 VIPS_DEBUG_MSG( "vips_verror: %s", vips_buf_all( &buf ) );
242 }
243 #endif /*VIPS_DEBUG*/
244
245 g_mutex_lock( vips__global_lock );
246 g_assert( vips_error_freeze_count >= 0 );
247 if( !vips_error_freeze_count ) {
248 if( domain )
249 vips_buf_appendf( &vips_error_buf, "%s: ", domain );
250 vips_buf_vappendf( &vips_error_buf, fmt, ap );
251 vips_buf_appends( &vips_error_buf, "\n" );
252 }
253 g_mutex_unlock( vips__global_lock );
254
255 if( vips__fatal )
256 vips_error_exit( "vips__fatal" );
257 }
258
259 /**
260 * vips_error:
261 * @domain: the source of the error
262 * @fmt: printf()-style format string for the error
263 * @...: arguments to the format string
264 *
265 * Format the string in the style of printf() and append to the error buffer.
266 *
267 * See also: vips_error_system(), vips_verror().
268 */
269 void
vips_error(const char * domain,const char * fmt,...)270 vips_error( const char *domain, const char *fmt, ... )
271 {
272 va_list ap;
273
274 va_start( ap, fmt );
275 vips_verror( domain, fmt, ap );
276 va_end( ap );
277 }
278
279 /**
280 * vips_verror_system:
281 * @err: the system error code
282 * @domain: the source of the error
283 * @fmt: printf()-style format string for the error
284 * @ap: arguments to the format string
285 *
286 * Format the string in the style of printf() and append to the error buffer.
287 * Then create and append a localised message based on the system error code,
288 * usually the value of errno.
289 *
290 * See also: vips_error_system().
291 */
292 void
vips_verror_system(int err,const char * domain,const char * fmt,va_list ap)293 vips_verror_system( int err, const char *domain, const char *fmt, va_list ap )
294 {
295 vips_verror( domain, fmt, ap );
296
297 #ifdef G_OS_WIN32
298 {
299 char *buf;
300
301 if( FormatMessageA(
302 FORMAT_MESSAGE_ALLOCATE_BUFFER |
303 FORMAT_MESSAGE_IGNORE_INSERTS |
304 FORMAT_MESSAGE_FROM_SYSTEM,
305 NULL,
306 err,
307 MAKELANGID( LANG_NEUTRAL, SUBLANG_DEFAULT ),
308 (LPSTR) &buf, 0, NULL ) ) {
309 vips_error( _( "windows error" ), "%s", buf );
310 LocalFree( buf );
311 }
312 }
313 #else /*!G_OS_WIN32*/
314 {
315 char *buf;
316
317 buf = g_locale_to_utf8( strerror( err ), -1, NULL, NULL, NULL );
318 vips_error( _( "unix error" ), "%s", buf );
319 g_free( buf );
320 }
321 #endif /*G_OS_WIN32*/
322 }
323
324 /**
325 * vips_error_system:
326 * @err: the system error code
327 * @domain: the source of the error
328 * @fmt: printf()-style format string for the error
329 * @...: arguments to the format string
330 *
331 * Format the string in the style of printf() and append to the error buffer.
332 * Then create and append a localised message based on the system error code,
333 * usually the value of errno.
334 *
335 * See also: vips_verror_system().
336 */
337 void
vips_error_system(int err,const char * domain,const char * fmt,...)338 vips_error_system( int err, const char *domain, const char *fmt, ... )
339 {
340 va_list ap;
341
342 va_start( ap, fmt );
343 vips_verror_system( err, domain, fmt, ap );
344 va_end( ap );
345 }
346
347 /**
348 * vips_error_g:
349 * @error: (out): glib error pointer
350 *
351 * This function sets the glib error pointer from the vips error buffer and
352 * clears it. It's handy for returning errors to glib functions from vips.
353 *
354 * See vips_g_error() for the inverse operation.
355 *
356 * See also: g_set_error(), vips_g_error().
357 */
358 void
vips_error_g(GError ** error)359 vips_error_g( GError **error )
360 {
361 static GQuark vips_domain = 0;
362
363 if( !vips_domain )
364 vips_domain = g_quark_from_string( "libvips" );
365
366 /* glib does not expect a trailing '\n' and vips always has one.
367 */
368 g_mutex_lock( vips__global_lock );
369 vips_buf_removec( &vips_error_buf, '\n' );
370 g_mutex_unlock( vips__global_lock );
371
372 g_set_error( error, vips_domain, -1, "%s", vips_error_buffer() );
373 vips_error_clear();
374 }
375
376
377 /**
378 * vips_g_error:
379 * @error: glib error pointer
380 *
381 * This function adds the %GError to the vips error buffer and clears it. It's
382 * the opposite of vips_error_g().
383 *
384 * See also: vips_error_g().
385 */
386 void
vips_g_error(GError ** error)387 vips_g_error( GError **error )
388 {
389 if( error &&
390 *error ) {
391 vips_error( "glib", "%s\n", (*error)->message );
392 g_error_free( *error );
393 *error = NULL;
394 }
395 }
396
397 /**
398 * vips_error_clear:
399 *
400 * Clear and reset the error buffer. This is typically called after presenting
401 * an error to the user.
402 *
403 * See also: vips_error_buffer().
404 */
405 void
vips_error_clear(void)406 vips_error_clear( void )
407 {
408 g_mutex_lock( vips__global_lock );
409 vips_buf_rewind( &vips_error_buf );
410 g_mutex_unlock( vips__global_lock );
411 }
412
413 /**
414 * vips_error_exit:
415 * @fmt: printf()-style format string for the message
416 * @...: arguments to the format string
417 *
418 * Sends a formatted error message to stderr, then sends the contents of the
419 * error buffer, if any, then shuts down vips and terminates the program with
420 * an error code.
421 *
422 * @fmt may be %NULL, in which case only the error buffer is printed before
423 * exiting.
424 *
425 * See also: vips_error().
426 */
427 void
vips_error_exit(const char * fmt,...)428 vips_error_exit( const char *fmt, ... )
429 {
430 if( fmt ) {
431 va_list ap;
432
433 fprintf( stderr, "%s: ", vips_get_prgname() );
434
435 va_start( ap, fmt );
436 (void) vfprintf( stderr, fmt, ap );
437 va_end( ap );
438
439 fprintf( stderr, "\n" );
440 }
441
442 fprintf( stderr, "%s", vips_error_buffer() );
443
444 vips_shutdown();
445
446 if( vips__fatal )
447 abort();
448 else
449 exit( 1 );
450 }
451
452 /**
453 * vips_check_uncoded:
454 * @domain: the originating domain for the error message
455 * @im: image to check
456 *
457 * Check that the image is not coded.
458 * If not, set an error message
459 * and return non-zero.
460 *
461 * See also: vips_error().
462 *
463 * Returns: 0 on OK, or -1 on error.
464 */
465 int
vips_check_uncoded(const char * domain,VipsImage * im)466 vips_check_uncoded( const char *domain, VipsImage *im )
467 {
468 if( im->Coding != VIPS_CODING_NONE ) {
469 vips_error( domain, "%s", _( "image must be uncoded" ) );
470 return( -1 );
471 }
472
473 return( 0 );
474 }
475
476 /**
477 * vips_check_coding_noneorlabq:
478 * @domain: the originating domain for the error message
479 * @im: image to check
480 *
481 * Check that the image is uncoded or LABQ coded.
482 * If not, set an error message
483 * and return non-zero.
484 *
485 * See also: vips_error().
486 *
487 * Returns: 0 on OK, or -1 on error.
488 */
489 int
vips_check_coding_noneorlabq(const char * domain,VipsImage * im)490 vips_check_coding_noneorlabq( const char *domain, VipsImage *im )
491 {
492 /* These all have codings that extract/ifthenelse/etc can ignore.
493 */
494 if( im->Coding != VIPS_CODING_NONE &&
495 im->Coding != VIPS_CODING_LABQ ) {
496 vips_error( domain,
497 "%s", _( "image coding must be 'none' or 'labq'" ) );
498 return( -1 );
499 }
500
501 return( 0 );
502 }
503
504 /**
505 * vips_check_coding_known:
506 * @domain: the originating domain for the error message
507 * @im: image to check
508 *
509 * Check that the image is uncoded, LABQ coded or RAD coded.
510 * If not, set an error message
511 * and return non-zero.
512 *
513 * See also: vips_error().
514 *
515 * Returns: 0 on OK, or -1 on error.
516 */
517 int
vips_check_coding_known(const char * domain,VipsImage * im)518 vips_check_coding_known( const char *domain, VipsImage *im )
519 {
520 /* These all have codings that extract/ifthenelse/etc can ignore.
521 */
522 if( im->Coding != VIPS_CODING_NONE &&
523 im->Coding != VIPS_CODING_LABQ &&
524 im->Coding != VIPS_CODING_RAD ) {
525 vips_error( domain, "%s", _( "unknown image coding" ) );
526 return( -1 );
527 }
528
529 return( 0 );
530 }
531
532 /**
533 * vips_check_coding:
534 * @domain: the originating domain for the error message
535 * @im: image to check
536 * @coding: required coding
537 *
538 * Check that the image has the required @coding.
539 * If not, set an error message
540 * and return non-zero.
541 *
542 * See also: vips_error().
543 *
544 * Returns: 0 on OK, or -1 on error.
545 */
546 int
vips_check_coding(const char * domain,VipsImage * im,VipsCoding coding)547 vips_check_coding( const char *domain, VipsImage *im, VipsCoding coding )
548 {
549 if( im->Coding != coding ) {
550 vips_error( domain, _( "coding '%s' only" ),
551 vips_enum_nick( VIPS_TYPE_CODING, coding ) );
552 return( -1 );
553 }
554
555 return( 0 );
556 }
557
558 /**
559 * vips_check_mono:
560 * @domain: the originating domain for the error message
561 * @im: image to check
562 *
563 * Check that the image has exactly one band.
564 * Otherwise set an error message
565 * and return non-zero.
566 *
567 * See also: vips_error().
568 *
569 * Returns: 0 if OK, -1 otherwise.
570 */
571 int
vips_check_mono(const char * domain,VipsImage * im)572 vips_check_mono( const char *domain, VipsImage *im )
573 {
574 if( im->Bands != 1 ) {
575 vips_error( domain, "%s", _( "image must one band" ) );
576 return( -1 );
577 }
578
579 return( 0 );
580 }
581
582 /**
583 * vips_check_bands:
584 * @domain: the originating domain for the error message
585 * @im: image to check
586 * @bands: must have this many bands
587 *
588 * Check that the image has @bands bands.
589 * Otherwise set an error message
590 * and return non-zero.
591 *
592 * See also: vips_error().
593 *
594 * Returns: 0 if OK, -1 otherwise.
595 */
596 int
vips_check_bands(const char * domain,VipsImage * im,int bands)597 vips_check_bands( const char *domain, VipsImage *im, int bands )
598 {
599 if( im->Bands != bands ) {
600 vips_error( domain, _( "image must have %d bands" ), bands );
601 return( -1 );
602 }
603
604 return( 0 );
605 }
606
607 /**
608 * vips_check_bands_1or3:
609 * @domain: the originating domain for the error message
610 * @im: image to check
611 *
612 * Check that the image has either one or three bands.
613 * Otherwise set an error message
614 * and return non-zero.
615 *
616 * See also: vips_error().
617 *
618 * Returns: 0 if OK, -1 otherwise.
619 */
620 int
vips_check_bands_1or3(const char * domain,VipsImage * im)621 vips_check_bands_1or3( const char *domain, VipsImage *im )
622 {
623 if( im->Bands != 1 && im->Bands != 3 ) {
624 vips_error( domain, "%s",
625 _( "image must have one or three bands" ) );
626 return( -1 );
627 }
628
629 return( 0 );
630 }
631
632 /**
633 * vips_check_bands_atleast:
634 * @domain: the originating domain for the error message
635 * @im: image to check
636 * @bands: at least this many bands
637 *
638 * Check that the image has at least @bands bands.
639 * Otherwise set an error message
640 * and return non-zero.
641 *
642 * See also: vips_error().
643 *
644 * Returns: 0 if OK, -1 otherwise.
645 */
646 int
vips_check_bands_atleast(const char * domain,VipsImage * im,int bands)647 vips_check_bands_atleast( const char *domain, VipsImage *im, int bands )
648 {
649 if( im->Bands < bands ) {
650 vips_error( domain,
651 _( "image must have at least %d bands" ), bands );
652 return( -1 );
653 }
654
655 return( 0 );
656 }
657
658 /**
659 * vips_check_bands_1orn:
660 * @domain: the originating domain for the error message
661 * @im1: first image to check
662 * @im2: second image to check
663 *
664 * Check that the images have the same number of bands, or that one of the
665 * images has just 1 band.
666 * If not, set an error message
667 * and return non-zero.
668 *
669 * See also: vips_error().
670 *
671 * Returns: 0 on OK, or -1 on error.
672 */
673 int
vips_check_bands_1orn(const char * domain,VipsImage * im1,VipsImage * im2)674 vips_check_bands_1orn( const char *domain, VipsImage *im1, VipsImage *im2 )
675 {
676 if( im1->Bands != im2->Bands &&
677 (im1->Bands != 1 && im2->Bands != 1) ) {
678 vips_error( domain, "%s",
679 _( "images must have the same number of bands, "
680 "or one must be single-band" ) );
681 return( -1 );
682 }
683
684 return( 0 );
685 }
686
687 /**
688 * vips_check_bands_1orn_unary:
689 * @domain: the originating domain for the error message
690 * @im: image to check
691 * @n: number of bands, or 1
692 *
693 * Check that an image has 1 or @n bands. Handy for unary operations, cf.
694 * vips_check_bands_1orn().
695 * If not, set an error message
696 * and return non-zero.
697 *
698 * See also: vips_check_bands_1orn().
699 *
700 * Returns: 0 on OK, or -1 on error.
701 */
702 int
vips_check_bands_1orn_unary(const char * domain,VipsImage * im,int n)703 vips_check_bands_1orn_unary( const char *domain, VipsImage *im, int n )
704 {
705 if( im->Bands != 1 && im->Bands != n ) {
706 vips_error( domain, _( "image must have 1 or %d bands" ), n );
707 return( -1 );
708 }
709
710 return( 0 );
711 }
712
713 /**
714 * vips_check_noncomplex:
715 * @domain: the originating domain for the error message
716 * @im: image to check
717 *
718 * Check that the image is not complex.
719 * Otherwise set an error message
720 * and return non-zero.
721 *
722 * See also: vips_error().
723 *
724 * Returns: 0 if OK, -1 otherwise.
725 */
726 int
vips_check_noncomplex(const char * domain,VipsImage * im)727 vips_check_noncomplex( const char *domain, VipsImage *im )
728 {
729 if( vips_band_format_iscomplex( im->BandFmt ) ) {
730 vips_error( domain, "%s", _( "image must be non-complex" ) );
731 return( -1 );
732 }
733
734 return( 0 );
735 }
736
737 /**
738 * vips_check_complex:
739 * @domain: the originating domain for the error message
740 * @im: image to check
741 *
742 * Check that the image is complex.
743 * Otherwise set an error message
744 * and return non-zero.
745 *
746 * See also: vips_error().
747 *
748 * Returns: 0 if OK, -1 otherwise.
749 */
750 int
vips_check_complex(const char * domain,VipsImage * im)751 vips_check_complex( const char *domain, VipsImage *im )
752 {
753 if( !vips_band_format_iscomplex( im->BandFmt ) ) {
754 vips_error( domain, "%s", _( "image must be complex" ) );
755 return( -1 );
756 }
757
758 return( 0 );
759 }
760
761 /**
762 * vips_check_twocomponents:
763 * @domain: the originating domain for the error message
764 * @im: image to check
765 *
766 * Check that the image is has two "components", ie. is a one-band complex or
767 * a two-band non-complex.
768 * Otherwise set an error message
769 * and return non-zero.
770 *
771 * See also: vips_error().
772 *
773 * Returns: 0 if OK, -1 otherwise.
774 */
775 int
vips_check_twocomponents(const char * domain,VipsImage * im)776 vips_check_twocomponents( const char *domain, VipsImage *im )
777 {
778 if( !vips_band_format_iscomplex( im->BandFmt ) &&
779 im->Bands != 2 ) {
780 vips_error( domain,
781 "%s", _( "image must be two-band or complex" ) );
782 return( -1 );
783 }
784
785 return( 0 );
786 }
787
788 /**
789 * vips_check_format:
790 * @domain: the originating domain for the error message
791 * @im: image to check
792 * @fmt: format to test for
793 *
794 * Check that the image has the specified format.
795 * Otherwise set an error message
796 * and return non-zero.
797 *
798 * See also: vips_error().
799 *
800 * Returns: 0 if OK, -1 otherwise.
801 */
802 int
vips_check_format(const char * domain,VipsImage * im,VipsBandFormat fmt)803 vips_check_format( const char *domain, VipsImage *im, VipsBandFormat fmt )
804 {
805 if( im->BandFmt != fmt ) {
806 vips_error( domain,
807 _( "image must be %s" ),
808 vips_enum_string( VIPS_TYPE_BAND_FORMAT, fmt ) );
809 return( -1 );
810 }
811
812 return( 0 );
813 }
814
815 /**
816 * vips_check_int:
817 * @domain: the originating domain for the error message
818 * @im: image to check
819 *
820 * Check that the image is in one of the integer formats.
821 * Otherwise set an error message
822 * and return non-zero.
823 *
824 * See also: vips_error().
825 *
826 * Returns: 0 if OK, -1 otherwise.
827 */
828 int
vips_check_int(const char * domain,VipsImage * im)829 vips_check_int( const char *domain, VipsImage *im )
830 {
831 if( !vips_band_format_isint( im->BandFmt ) ) {
832 vips_error( domain, "%s", _( "image must be integer" ) );
833 return( -1 );
834 }
835
836 return( 0 );
837 }
838
839 /**
840 * vips_check_uint:
841 * @domain: the originating domain for the error message
842 * @im: image to check
843 *
844 * Check that the image is in one of the unsigned integer formats.
845 * Otherwise set an error message
846 * and return non-zero.
847 *
848 * See also: vips_error().
849 *
850 * Returns: 0 if OK, -1 otherwise.
851 */
852 int
vips_check_uint(const char * domain,VipsImage * im)853 vips_check_uint( const char *domain, VipsImage *im )
854 {
855 if( !vips_band_format_isuint( im->BandFmt ) ) {
856 vips_error( domain,
857 "%s", _( "image must be unsigned integer" ) );
858 return( -1 );
859 }
860
861 return( 0 );
862 }
863
864 /**
865 * vips_check_8or16:
866 * @domain: the originating domain for the error message
867 * @im: image to check
868 *
869 * Check that the image is 8 or 16-bit integer, signed or unsigned.
870 * Otherwise set an error message
871 * and return non-zero.
872 *
873 * See also: vips_error().
874 *
875 * Returns: 0 if OK, -1 otherwise.
876 */
877 int
vips_check_8or16(const char * domain,VipsImage * im)878 vips_check_8or16( const char *domain, VipsImage *im )
879 {
880 if( im->BandFmt != VIPS_FORMAT_UCHAR &&
881 im->BandFmt != VIPS_FORMAT_USHORT &&
882 im->BandFmt != VIPS_FORMAT_CHAR &&
883 im->BandFmt != VIPS_FORMAT_SHORT ) {
884 vips_error( domain, "%s",
885 _( "image must be 8- or 16-bit integer, "
886 "signed or unsigned" ) );
887 return( -1 );
888 }
889
890 return( 0 );
891 }
892
893 /**
894 * vips_check_u8or16:
895 * @domain: the originating domain for the error message
896 * @im: image to check
897 *
898 * Check that the image is 8 or 16-bit unsigned integer.
899 * Otherwise set an error message
900 * and return non-zero.
901 *
902 * See also: vips_error().
903 *
904 * Returns: 0 if OK, -1 otherwise.
905 */
906 int
vips_check_u8or16(const char * domain,VipsImage * im)907 vips_check_u8or16( const char *domain, VipsImage *im )
908 {
909 if( im->BandFmt != VIPS_FORMAT_UCHAR &&
910 im->BandFmt != VIPS_FORMAT_USHORT ) {
911 vips_error( domain, "%s",
912 _( "image must be 8- or 16-bit unsigned integer" ) );
913 return( -1 );
914 }
915
916 return( 0 );
917 }
918
919 /**
920 * vips_check_u8or16orf:
921 * @domain: the originating domain for the error message
922 * @im: image to check
923 *
924 * Check that the image is 8 or 16-bit unsigned integer, or float.
925 * Otherwise set an error message and return non-zero.
926 *
927 * See also: vips_error().
928 *
929 * Returns: 0 if OK, -1 otherwise.
930 */
931 int
vips_check_u8or16orf(const char * domain,VipsImage * im)932 vips_check_u8or16orf( const char *domain, VipsImage *im )
933 {
934 if( im->BandFmt != VIPS_FORMAT_UCHAR &&
935 im->BandFmt != VIPS_FORMAT_USHORT &&
936 im->BandFmt != VIPS_FORMAT_FLOAT ) {
937 vips_error( domain, "%s",
938 _( "image must be 8- or 16-bit unsigned integer, "
939 "or float" ) );
940 return( -1 );
941 }
942
943 return( 0 );
944 }
945
946 /**
947 * vips_check_uintorf:
948 * @domain: the originating domain for the error message
949 * @im: image to check
950 *
951 * Check that the image is unsigned int or float.
952 * Otherwise set an error message and return non-zero.
953 *
954 * See also: vips_error().
955 *
956 * Returns: 0 if OK, -1 otherwise.
957 */
958 int
vips_check_uintorf(const char * domain,VipsImage * im)959 vips_check_uintorf( const char *domain, VipsImage *im )
960 {
961 if( im->BandFmt != VIPS_FORMAT_UCHAR &&
962 im->BandFmt != VIPS_FORMAT_USHORT &&
963 im->BandFmt != VIPS_FORMAT_UINT &&
964 im->BandFmt != VIPS_FORMAT_FLOAT ) {
965 vips_error( domain, "%s",
966 _( "image must be unsigned int or float" ) );
967 return( -1 );
968 }
969
970 return( 0 );
971 }
972
973 /**
974 * vips_check_size_same:
975 * @domain: the originating domain for the error message
976 * @im1: first image to check
977 * @im2: second image to check
978 *
979 * Check that the images have the same size.
980 * If not, set an error message
981 * and return non-zero.
982 *
983 * See also: vips_error().
984 *
985 * Returns: 0 if OK, -1 otherwise.
986 */
987 int
vips_check_size_same(const char * domain,VipsImage * im1,VipsImage * im2)988 vips_check_size_same( const char *domain, VipsImage *im1, VipsImage *im2 )
989 {
990 if( im1->Xsize != im2->Xsize || im1->Ysize != im2->Ysize ) {
991 vips_error( domain, "%s", _( "images must match in size" ) );
992 return( -1 );
993 }
994
995 return( 0 );
996 }
997
998 /**
999 * vips_check_oddsquare:
1000 * @domain: the originating domain for the error message
1001 * @im: image to check
1002 *
1003 * Check that the image is square and that the sides are odd.
1004 * If not, set an error message
1005 * and return non-zero.
1006 *
1007 * See also: vips_error().
1008 *
1009 * Returns: 0 if OK, -1 otherwise.
1010 */
1011 int
vips_check_oddsquare(const char * domain,VipsImage * im)1012 vips_check_oddsquare( const char *domain, VipsImage *im )
1013 {
1014 if( im->Xsize != im->Ysize ||
1015 im->Xsize % 2 == 0 ) {
1016 vips_error( domain,
1017 "%s", _( "images must be odd and square" ) );
1018 return( -1 );
1019 }
1020
1021 return( 0 );
1022 }
1023
1024 /**
1025 * vips_check_bands_same:
1026 * @domain: the originating domain for the error message
1027 * @im1: first image to check
1028 * @im2: second image to check
1029 *
1030 * Check that the images have the same number of bands.
1031 * If not, set an error message
1032 * and return non-zero.
1033 *
1034 * See also: vips_error().
1035 *
1036 * Returns: 0 if OK, -1 otherwise.
1037 */
1038 int
vips_check_bands_same(const char * domain,VipsImage * im1,VipsImage * im2)1039 vips_check_bands_same( const char *domain, VipsImage *im1, VipsImage *im2 )
1040 {
1041 if( im1->Bands != im2->Bands ) {
1042 vips_error( domain, "%s",
1043 _( "images must have the same number of bands" ) );
1044 return( -1 );
1045 }
1046
1047 return( 0 );
1048 }
1049
1050 /**
1051 * vips_check_bandno:
1052 * @domain: the originating domain for the error message
1053 * @im: image to check
1054 * @bandno: band number
1055 *
1056 * @bandno should be a valid band number (ie. 0 to im->Bands - 1), or can be
1057 * -1, meaning all bands.
1058 * If not, set an error message
1059 * and return non-zero.
1060 *
1061 * See also: vips_error().
1062 *
1063 * Returns: 0 if OK, -1 otherwise.
1064 */
1065 int
vips_check_bandno(const char * domain,VipsImage * im,int bandno)1066 vips_check_bandno( const char *domain, VipsImage *im, int bandno )
1067 {
1068 if( bandno < -1 ||
1069 bandno > im->Bands - 1 ) {
1070 vips_error( domain, "bandno must be -1, or less than %d",
1071 im->Bands );
1072 return( -1 );
1073 }
1074
1075 return( 0 );
1076 }
1077
1078 /**
1079 * vips_check_format_same:
1080 * @domain: the originating domain for the error message
1081 * @im1: first image to check
1082 * @im2: second image to check
1083 *
1084 * Check that the images have the same format.
1085 * If not, set an error message
1086 * and return non-zero.
1087 *
1088 * See also: vips_error().
1089 *
1090 * Returns: 0 if OK, -1 otherwise.
1091 */
1092 int
vips_check_format_same(const char * domain,VipsImage * im1,VipsImage * im2)1093 vips_check_format_same( const char *domain, VipsImage *im1, VipsImage *im2 )
1094 {
1095 if( im1->BandFmt != im2->BandFmt ) {
1096 vips_error( domain, "%s",
1097 _( "images must have the same band format" ) );
1098 return( -1 );
1099 }
1100
1101 return( 0 );
1102 }
1103
1104 /**
1105 * vips_check_coding_same:
1106 * @domain: the originating domain for the error message
1107 * @im1: first image to check
1108 * @im2: second image to check
1109 *
1110 * Check that the images have the same coding.
1111 * If not, set an error message
1112 * and return non-zero.
1113 *
1114 * See also: vips_error().
1115 *
1116 * Returns: 0 if OK, -1 otherwise.
1117 */
1118 int
vips_check_coding_same(const char * domain,VipsImage * im1,VipsImage * im2)1119 vips_check_coding_same( const char *domain, VipsImage *im1, VipsImage *im2 )
1120 {
1121 if( im1->Coding != im2->Coding ) {
1122 vips_error( domain, "%s",
1123 _( "images must have the same coding" ) );
1124 return( -1 );
1125 }
1126
1127 return( 0 );
1128 }
1129
1130 /**
1131 * vips_check_vector_length:
1132 * @domain: the originating domain for the error message
1133 * @n: number of elements in vector
1134 * @len: number of elements vector should have
1135 *
1136 * Check that @n == @len.
1137 *
1138 * See also: vips_error().
1139 *
1140 * Returns: 0 if OK, -1 otherwise.
1141 */
1142 int
vips_check_vector_length(const char * domain,int n,int len)1143 vips_check_vector_length( const char *domain, int n, int len )
1144 {
1145 if( n != len ) {
1146 vips_error( domain, _( "vector must have %d elements" ), len );
1147 return( -1 );
1148 }
1149
1150 return( 0 );
1151 }
1152
1153 /**
1154 * vips_check_vector:
1155 * @domain: the originating domain for the error message
1156 * @n: number of elements in vector
1157 * @im: image to check against
1158 *
1159 * Operations with a vector constant need a 1-element vector, or a vector with
1160 * the same number of elements as there are bands in the image.
1161 *
1162 * See also: vips_error().
1163 *
1164 * Returns: 0 if OK, -1 otherwise.
1165 */
1166 int
vips_check_vector(const char * domain,int n,VipsImage * im)1167 vips_check_vector( const char *domain, int n, VipsImage *im )
1168 {
1169 if( n != 1 && im->Bands != 1 && n != im->Bands ) {
1170 vips_error( domain,
1171 _( "vector must have 1 or %d elements" ), im->Bands );
1172 return( -1 );
1173 }
1174
1175 return( 0 );
1176 }
1177
1178 /**
1179 * vips_check_hist:
1180 * @domain: the originating domain for the error message
1181 * @im: image to check
1182 *
1183 * Histogram images must have width or height 1, and must not have more than
1184 * 65536 elements. Return 0 if the image will pass as a histogram, or -1 and
1185 * set an error message otherwise.
1186 *
1187 * See also: vips_error().
1188 *
1189 * Returns: 0 if OK, -1 otherwise.
1190 */
1191 int
vips_check_hist(const char * domain,VipsImage * im)1192 vips_check_hist( const char *domain, VipsImage *im )
1193 {
1194 if( im->Xsize != 1 && im->Ysize != 1 ) {
1195 vips_error( domain, "%s",
1196 _( "histograms must have width or height 1" ) );
1197 return( -1 );
1198 }
1199 if( VIPS_IMAGE_N_PELS( im ) > 65536 ) {
1200 vips_error( domain, "%s",
1201 _( "histograms must have not have more than "
1202 "65536 elements" ) );
1203 return( -1 );
1204 }
1205
1206 return( 0 );
1207 }
1208
1209 /**
1210 * vips_check_matrix:
1211 * @domain: the originating domain for the error message
1212 * @im: image to check
1213 * @out: (out): put image as in-memory doubles here
1214 *
1215 * Matrix images must have width and height less than 100000 and have 1 band.
1216 *
1217 * Return 0 if the image will pass as a matrix, or -1 and set an error
1218 * message otherwise.
1219 *
1220 * @out is set to be @im cast to double and stored in memory. Use
1221 * VIPS_MATRIX() to address values in @out.
1222 *
1223 * You must unref @out when you are done with it.
1224 *
1225 * See also: VIPS_MATRIX(), vips_object_local()
1226 *
1227 * Returns: 0 if OK, -1 otherwise.
1228 */
1229 int
vips_check_matrix(const char * domain,VipsImage * im,VipsImage ** out)1230 vips_check_matrix( const char *domain, VipsImage *im, VipsImage **out )
1231 {
1232 VipsImage *t;
1233
1234 *out = NULL;
1235
1236 if( im->Xsize > 100000 ||
1237 im->Ysize > 100000 ) {
1238 vips_error( domain, "%s", _( "matrix image too large" ) );
1239 return( -1 );
1240 }
1241 if( im->Bands != 1 ) {
1242 vips_error( domain,
1243 "%s", _( "matrix image must have one band" ) );
1244 return( -1 );
1245 }
1246
1247 if( vips_cast( im, &t, VIPS_FORMAT_DOUBLE, NULL ) )
1248 return( -1 );
1249 if( !(*out = vips_image_copy_memory( t )) ) {
1250 VIPS_UNREF( t );
1251 return( -1 );
1252 }
1253 VIPS_UNREF( t );
1254
1255 return( 0 );
1256 }
1257
1258 /**
1259 * vips_check_separable:
1260 * @domain: the originating domain for the error message
1261 * @im: image to check
1262 *
1263 * Separable matrix images must have width or height 1.
1264 * Return 0 if the image will pass, or -1 and
1265 * set an error message otherwise.
1266 *
1267 * See also: vips_error().
1268 *
1269 * Returns: 0 if OK, -1 otherwise.
1270 */
1271 int
vips_check_separable(const char * domain,VipsImage * im)1272 vips_check_separable( const char *domain, VipsImage *im )
1273 {
1274 if( im->Xsize != 1 &&
1275 im->Ysize != 1 ) {
1276 vips_error( domain,
1277 "%s", _( "separable matrix images must have "
1278 "width or height 1" ) );
1279 return( -1 );
1280 }
1281
1282 return( 0 );
1283 }
1284
1285 /**
1286 * vips_check_precision_intfloat:
1287 * @domain: the originating domain for the error message
1288 * @precision: precision to check
1289 *
1290 * Check that @prec image is either float or int.
1291 * If not, set an error message
1292 * and return non-zero.
1293 *
1294 * See also: vips_error().
1295 *
1296 * Returns: 0 on OK, or -1 on error.
1297 */
1298 int
vips_check_precision_intfloat(const char * domain,VipsPrecision precision)1299 vips_check_precision_intfloat( const char *domain, VipsPrecision precision )
1300 {
1301 if( precision != VIPS_PRECISION_INTEGER &&
1302 precision != VIPS_PRECISION_FLOAT ) {
1303 vips_error( domain,
1304 "%s", _( "precision must be int or float" ) );
1305 return( -1 );
1306 }
1307
1308 return( 0 );
1309 }
1310