stuff

TODO

@@ -1,3 +1,11 @@
+- added protos to the end of image.h, need gtkdoc comments on them
+
+  im_setbox.c -> deprecated, plus the associated struct
+
+  im_open_local() -> image.h ? also _array()
+
+  what else in util.h needs docs?
+
 - constant images:
 
 	we make them with im_black(), then m_lintra(), then im_clip(). How

libvips/arithmetic/arith_dispatch.c

@@ -1043,21 +1043,19 @@ static im_arg_desc measure_args[] = {
 static int
 measure_vec( im_object *argv )
 {
-	IMAGE_BOX box;
-	int h, v;
 	im_mask_object *mo = argv[1];
 
-	box.xstart = *((int *) argv[2]);
+	int x = *((int *) argv[2]);
-	box.ystart = *((int *) argv[3]);
+	int y = *((int *) argv[3]);
-	box.xsize = *((int *) argv[4]);
+	int w = *((int *) argv[4]);
-	box.ysize = *((int *) argv[5]);
+	int h = *((int *) argv[5]);
-	box.chsel = 0;
 
-	h = *((int *) argv[6]);
+	int u = *((int *) argv[6]);
-	v = *((int *) argv[7]);
+	int v = *((int *) argv[7]);
 
 	if( !(mo->mask = 
-		im_measure( argv[0], &box, h, v, NULL, 0, mo->name )) ) {
+		im_measure_area( argv[0], 
+			x, y, w, h, u, v, NULL, 0, mo->name )) ) {
 		return( -1 );
 	}
 

libvips/arithmetic/im_measure.c

@@ -59,32 +59,33 @@
 /* Measure into array.
  */
 static int
-measure_patches( IMAGE *im, double *coeff, IMAGE_BOX *box, 
+measure_patches( IMAGE *im, double *coeff, 
-	int h, int v, int *sel, int nsel )
+	int left, int top, int width, int height, 
+	int u, int v, int *sel, int nsel )
 {	
 	IMAGE *tmp;
 	int patch;
-	IMAGE_BOX sub;
 	int i, j;
 	int m, n;
 	double avg, dev;
+	int x, y, w, h;
 
 	/* How large are the patches we are to measure?
 	 */
-	double pw = (double) box->xsize / (double) h;
+	double pw = (double) width / (double) u;
-	double ph = (double) box->ysize / (double) v;
+	double ph = (double) height / (double) v;
 
 	/* Set up sub to be the size we need for a patch.
 	 */
-	sub.xsize = (pw + 1) / 2;
+	w = (pw + 1) / 2;
-	sub.ysize = (ph + 1) / 2;
+	h = (ph + 1) / 2;
 
 	/* Loop through sel, picking out areas to measure.
 	 */
 	for( j = 0, patch = 0; patch < nsel; patch++ ) {
 		/* Sanity check. Is the patch number sensible?
 		 */
-		if( sel[patch] <= 0 || sel[patch] > h*v ) {
+		if( sel[patch] <= 0 || sel[patch] > u * v ) {
 			im_error( "im_measure", 
 				_( "patch %d is out of range" ),
 				sel[patch] );
@@ -93,13 +94,13 @@ measure_patches( IMAGE *im, double *coeff, IMAGE_BOX *box,
 
 		/* Patch coordinates.
 		 */
-		m = (sel[patch] - 1) % h;  
+		m = (sel[patch] - 1) % u;  
-		n = (sel[patch] - 1) / h;
+		n = (sel[patch] - 1) / u;
 
 		/* Move sub to correct position.
 		 */
-		sub.xstart = box->xstart + m*pw + (pw + 2)/4;
+		x = left + m * pw + (pw + 2) / 4;
-		sub.ystart = box->ystart + n*ph + (ph + 2)/4;
+		y = top + n * ph + (ph + 2) / 4;
 
 		/* Loop through bands.
 		 */
@@ -111,8 +112,7 @@ measure_patches( IMAGE *im, double *coeff, IMAGE_BOX *box,
 			
 			/* Extract and measure.
 			 */
-			sub.chsel = i;
+			if( im_extract_area( im, tmp, x, y, w, h ) ||
-			if( im_extract( im, tmp, &sub ) ||
 				im_avg( tmp, &avg ) ||
 				im_deviate( tmp, &dev ) ) {
 				im_close( tmp );
@@ -126,7 +126,7 @@ measure_patches( IMAGE *im, double *coeff, IMAGE_BOX *box,
 			 * <0, or averages near zero (can get these if use
 			 * im_measure() on IM_TYPE_LAB images).
 			 */
-			if( dev*5 > fabs( avg ) && fabs( avg ) > 3 )
+			if( dev * 5 > fabs( avg ) && fabs( avg ) > 3 )
 				im_warn( "im_measure",
 					_( "patch %d, band %d: "
 						"avg = %g, sdev = %g" ), 
@@ -142,9 +142,12 @@ measure_patches( IMAGE *im, double *coeff, IMAGE_BOX *box,
 }
 
 /**
- * im_measure:
+ * im_measure_area:
  * @im: image to measure
- * @box: box containing chart
+ * @left: area of image containing chart
+ * @top: area of image containing chart
+ * @width: area of image containing chart
+ * @height: area of image containing chart
  * @h: patches across chart
  * @v: patches down chart
  * @sel: array of patch numbers to measure (numbered from 1 in row-major order)
@@ -186,7 +189,9 @@ measure_patches( IMAGE *im, double *coeff, IMAGE_BOX *box,
  * Returns: #DOUBLEMASK of measurements.
  */
 DOUBLEMASK *
-im_measure( IMAGE *im, IMAGE_BOX *box, int h, int v, 
+im_measure_area( IMAGE *im, 
+	int left, int top, int width, int height, 
+	int u, int v, 
 	int *sel, int nsel, const char *name )
 {	
 	DOUBLEMASK *mask;
@@ -199,8 +204,10 @@ im_measure( IMAGE *im, IMAGE_BOX *box, int h, int v,
 		if( !(t1 = im_open( "measure-temp", "p" )) )
 			return( NULL );
 		if( im_LabQ2Lab( im, t1 ) ||
-			!(mask = im_measure( t1, 
+			!(mask = im_measure_area( t1, 
-				box, h, v, sel, nsel, name )) ) {
+				left, top, width, height,
+				u, v, 
+				sel, nsel, name )) ) {
 			im_close( t1 );
 			return( NULL );
 		}
@@ -219,7 +226,7 @@ im_measure( IMAGE *im, IMAGE_BOX *box, int h, int v,
 	if( sel == NULL ) {
 		int i;
 
-		nsel = h * v;
+		nsel = u * v;
 		if( !(sel = IM_ARRAY( im, nsel, int )) )
 			return( NULL );
 		for( i = 0; i < nsel; i++ )
@@ -233,7 +240,8 @@ im_measure( IMAGE *im, IMAGE_BOX *box, int h, int v,
 
 	/* Perform measure and return.
 	 */
-	if( measure_patches( im, mask->coeff, box, h, v, sel, nsel ) ) {
+	if( measure_patches( im, mask->coeff, left, top, width, height, 
+		u, v, sel, nsel ) ) {
 		im_free_dmask( mask );
 		return( NULL );
 	}

libvips/conversion/im_extract.c

@@ -230,21 +230,6 @@ im_extract_areabands( IMAGE *in, IMAGE *out,
         return( 0 );
 }
 
-/* Legacy interface.
- */
-int
-im_extract( IMAGE *in, IMAGE *out, IMAGE_BOX *box )
-{	
-	if( box->chsel == -1 )
-		return( im_extract_areabands( in, out, 
-			box->xstart, box->ystart, box->xsize, box->ysize,
-			0, in->Bands ) );
-	else
-		return( im_extract_areabands( in, out, 
-			box->xstart, box->ystart, box->xsize, box->ysize,
-			box->chsel, 1 ) );
-}
-
 /* Convenience functions.
  */
 int

libvips/deprecated/Makefile.am

@@ -9,6 +9,7 @@ libdeprecated_la_SOURCES = \
     im_printlines.c \
     im_debugim.c \
     im_gfadd.c \
+    im_setbox.c \
     rename.c \
     im_litecor.c 
 

libvips/deprecated/rename.c

@@ -159,3 +159,28 @@ im_similarity( IMAGE *in, IMAGE *out,
 		vips_interpolate_bilinear_static(), 
 		a, -b, b, a, dx, dy ) ); 
 }
+
+DOUBLEMASK *
+im_measure( IMAGE *im, IMAGE_BOX *box, int h, int v, 
+	int *sel, int nsel, const char *name )
+{
+	return( im_measure_area( im,
+		box->xstart,
+		box->ystart,
+		box->xsize,
+		box->ysize,
+		h, v, sel, nsel, name ) ); 
+}
+
+int
+im_extract( IMAGE *in, IMAGE *out, IMAGE_BOX *box )
+{	
+	if( box->chsel == -1 )
+		return( im_extract_areabands( in, out, 
+			box->xstart, box->ystart, box->xsize, box->ysize,
+			0, in->Bands ) );
+	else
+		return( im_extract_areabands( in, out, 
+			box->xstart, box->ystart, box->xsize, box->ysize,
+			box->chsel, 1 ) );
+}

libvips/include/vips/almostdeprecated.h

@@ -67,6 +67,10 @@ typedef VipsDemandStyle im_demand_type;
 typedef VipsProgress im_time_t;
 typedef VipsImage IMAGE;
 
+int im_extract( IMAGE *, IMAGE *, IMAGE_BOX * );
+DOUBLEMASK *im_measure( IMAGE *im, IMAGE_BOX *box, int h, int v, 
+	int *sel, int nsel, const char *name );
+
 #ifdef __cplusplus
 }
 #endif /*__cplusplus*/

libvips/include/vips/arithmetic.h

@@ -39,7 +39,9 @@ extern "C" {
 
 /* arithmetic
  */
-DOUBLEMASK *im_measure( IMAGE *im, IMAGE_BOX *box, int h, int v, 
+DOUBLEMASK *im_measure_area( IMAGE *im, 
+	int left, int top, int width, int height, 
+	int h, int v, 
 	int *sel, int nsel, const char *name );
 DOUBLEMASK *im_stats( IMAGE *in );
 int im_abs( IMAGE *in, IMAGE *out );

libvips/include/vips/header.h

@@ -42,9 +42,15 @@ int im_header_double( IMAGE *im, const char *field, double *out );
 int im_header_string( IMAGE *im, const char *field, char **out );
 GType im_header_get_typeof( IMAGE *im, const char *field );
 int im_header_get( IMAGE *im, const char *field, GValue *value_copy );
+
 typedef void *(*im_header_map_fn)( IMAGE *, const char *, GValue *, void * );
 void *im_header_map( IMAGE *im, im_header_map_fn fn, void *a );
 
+int im_histlin( IMAGE *image, const char *fmt, ... )
+	__attribute__((format(printf, 2, 3)));
+int im_updatehist( IMAGE *out, const char *name, int argc, char *argv[] );
+const char *im_history_get( IMAGE *im );
+
 #ifdef __cplusplus
 }
 #endif /*__cplusplus*/

libvips/include/vips/image.h

@@ -261,6 +261,20 @@ typedef struct _VipsImage {
 	 (X) * IM_IMAGE_SIZEOF_PEL(I))
 #endif /*DEBUG*/
 
+int im_init_world( const char *argv0 );
+GOptionGroup *im_get_option_group( void );
+
+const char *im_version_string( void );
+int im_version( int flag );
+
+const char *im_guess_prefix( const char *, const char * );
+const char *im_guess_libdir( const char *, const char * );
+
+void im_progress_set( int progress );
+
+VipsImage *im_open( const char *filename, const char *mode );
+int im_close( VipsImage *im );
+
 #ifdef __cplusplus
 }
 #endif /*__cplusplus*/

libvips/include/vips/proto.h

@@ -66,20 +66,7 @@ extern "C" {
 
 /* iofuncs
  */
-int im_init_world( const char *argv0 );
-GOptionGroup *im_get_option_group( void );
 
-/* Turn progress feedback on and off.
- */
-void im_progress_set( int progress );
-
-int im_debugim( IMAGE * );
-int im_printlines( IMAGE * );
-
-const char *im_version_string( void );
-int im_version( int flag );
-const char *im_guess_prefix( const char *, const char * );
-const char *im_guess_libdir( const char *, const char * );
 IMAGE *im_init( const char * );
 IMAGE *im_openout( const char * );
 IMAGE *im_open_vips( const char * );
@@ -95,14 +82,11 @@ int im_mapfile( IMAGE * );
 int im_mapfilerw( IMAGE * );
 int im_remapfilerw( IMAGE *image );
 
-IMAGE *im_open( const char *, const char * );
 IMAGE *im_open_header( const char * );
-int im_image_sanity( IMAGE * );
 
 void *im_malloc( IMAGE *im, size_t sz );
 int im_free( void * );
 
-int im_close( IMAGE * );
 int im_rwcheck( IMAGE * );
 int im_iocheck( IMAGE *, IMAGE * );
 int im_incheck( IMAGE * );
@@ -149,14 +133,9 @@ int im_isvips( const char * );
 int im_bits_of_fmt( VipsBandFmt fmt );
 
 int im_unmapfile( IMAGE * );
-void im_printdesc( IMAGE * );
 void im_initdesc( IMAGE *,
 	int, int, int, int, int, int, int, float, float,
 	int, int );
-int im_histlin( IMAGE *image, const char *fmt, ... )
-	__attribute__((format(printf, 2, 3)));
-int im_updatehist( IMAGE *out, const char *name, int argc, char *argv[] );
-const char *im_history_get( IMAGE *im );
 
 int im_render( IMAGE *in, IMAGE *out, IMAGE *mask,
 	int width, int height, int max,
@@ -330,7 +309,6 @@ int im_copy_morph( IMAGE *, IMAGE *, int, int, int );
 int im_copy( IMAGE *, IMAGE * );
 int im_copy_swap( IMAGE *in, IMAGE *out );
 int im_copy_from( IMAGE *in, IMAGE *out, im_arch_type architecture );
-int im_extract( IMAGE *, IMAGE *, IMAGE_BOX * );
 int im_extract_band( IMAGE *in, IMAGE *out, int band );
 int im_extract_bands( IMAGE *in, IMAGE *out, int band, int nbands );
 int im_extract_area( IMAGE *in, IMAGE *out, int x, int y, int w, int h );

libvips/iofuncs/Makefile.am

@@ -29,11 +29,9 @@ libiofuncs_la_SOURCES = \
 	im_piocheck.c \
 	im_prepare.c \
 	im_render.c \
-	im_setbox.c \
 	im_setbuf.c \
 	im_setupout.c \
 	im_unmapfile.c \
-	im_updatehist.c \
 	im_guess_prefix.c \
 	im_wbuffer.c \
 	im_wrapmany.c \

libvips/iofuncs/im_binfile.c

@@ -1,13 +1,5 @@
-/* @(#) Function to read a binary file with no header to vasari file
+/* im_bnfile.c --- load a raw binary file
- * @(#) Usage:
+ *
- * @(#)
- * @(#) IMAGE *
- * @(#) im_binfile(in, xs, ys, bands, offset)
- * @(#) char *in;
- * @(#) int xs, ys, bands, offset;
- * @(#)
- * @(#) The function returns NULL on error.
- * @(#) Works for uchar input only.
  * Author: N. Dessipris
  * Written on: 31/7/91
  * Modified on:
@@ -81,6 +73,24 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * im_binfile:
+ * @name: filename to open
+ * @xs: image width
+ * @ys: image height
+ * @bands: image bands (or bytes per pixel)
+ * @offset: bytes to skip at start of file
+ *
+ * This function maps the named file and returns an #IMAGE you can use to
+ * read it.
+ *
+ * It returns an 8-bit image with @bands bands. If the image is not 8-bit, use 
+ * im_copy_set() to transform the descriptor after loading it.
+ *
+ * See also: im_copy_set(), im_raw2vips(), im_open().
+ *
+ * Returns: the new #IMAGE, or NULL on error.
+ */
 IMAGE *
 im_binfile( const char *name, int xs, int ys, int bands, int offset )
 {

libvips/iofuncs/im_generate.c

@@ -94,6 +94,7 @@
 #include <vips/vips.h>
 #include <vips/internal.h>
 #include <vips/thread.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>

libvips/iofuncs/im_histlin.c

@@ -76,6 +76,39 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+#define IM_MAX_LINE (4096)
+
+/**
+ * im_histlin:
+ * @im: add history liine to this image
+ * @fmt: printf() format string
+ * @Varargs: arguments to format string
+ *
+ * Add a line to the image history. The @fmt and arguments are expanded, the
+ * date and time is appended prefixed with a hash character, and the whole
+ * string is appended to the image history and terminated with a newline.
+ *
+ * For example:
+ *
+ * |[
+ * im_histlin( im, "vips im_invert %s %s", in->filename, out->filename );
+ * ]|
+ *
+ * Might add the string
+ *
+ * |[
+ * "vips im_invert /home/john/fred.v /home/john/jim.v # Fri Apr  3 23:30:35
+ * 2009\n"
+ * ]|
+ *
+ * VIPS operations don't add history lines for you because a single action at 
+ * the application level might involve many VIPS operations. History must be
+ * recorded by the application.
+ *
+ * See also: im_updatehist().
+ *
+ * Returns: 0 on success, -1 on error.
+ */
 int 
 im_histlin( IMAGE *im, const char *fmt, ... )
 {
@@ -108,7 +141,56 @@ im_histlin( IMAGE *im, const char *fmt, ... )
 	return( 0 );
 }
 
-/* Read an image's history.
+/**
+ * im_updatehist:
+ * @out: image to attach history line to
+ * @name: program name
+ * @argc: number of program arguments
+ * @argv: program arguments
+ *
+ * Formats the name/argv as a single string and calls im_histlin(). A
+ * convenience function for command-line prorams.
+ *
+ * See also: im_history_get().
+ *
+ * Returns: 0 on success, -1 on error.
+ */
+int 
+im_updatehist( IMAGE *out, const char *name, int argc, char *argv[] )
+{	
+	int i;
+	char txt[IM_MAX_LINE];
+	VipsBuf buf;
+
+	vips_buf_init_static( &buf, txt, IM_MAX_LINE );
+	vips_buf_appends( &buf, name );
+
+	for( i = 0; i < argc; i++ ) {
+		vips_buf_appends( &buf, " " );
+		vips_buf_appends( &buf, argv[i] );
+	}
+
+	if( im_histlin( out, "%s", vips_buf_all( &buf ) ) ) 
+		return( -1 );
+
+	return( 0 );
+}
+
+/**
+ * im_history_get:
+ * @im: get history from here
+ *
+ * This function reads the image history as a C string. The string is owned
+ * by VIPS and must not be freed.
+ *
+ * VIPS tracks the history of each image, that is, the sequence of operations
+ * that generated that image. Applications built on VIPS need to call
+ * im_histlin() for each action they perform setting the command-line
+ * equivalent for the action.
+ *
+ * See also: im_histlin().
+ *
+ * Returns: The history of @im as a C string. Do not free!
  */
 const char *
 im_history_get( IMAGE *im )

libvips/iofuncs/im_iocheck.c

@@ -90,6 +90,7 @@
 
 #include <vips/vips.h>
 #include <vips/internal.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>

libvips/iofuncs/im_iterate.c

@@ -65,6 +65,7 @@
 
 #include <vips/vips.h>
 #include <vips/internal.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>

libvips/iofuncs/im_piocheck.c

@@ -67,6 +67,7 @@
 
 #include <vips/vips.h>
 #include <vips/internal.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>

libvips/iofuncs/im_prepare.c

@@ -64,6 +64,7 @@
 #include <assert.h>
 
 #include <vips/vips.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>

libvips/iofuncs/im_setupout.c

@@ -75,6 +75,7 @@
 
 #include <vips/vips.h>
 #include <vips/internal.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>

libvips/iofuncs/im_updatehist.c

@@ -1,80 +0,0 @@
-/* @(#)  
- * @(#) int 
- * @(#) im_updatehist( IMAGE *out, const char *name, int argc, char *argv[] )
- * @(#) 
- * @(#)  Returns either 0 (success) or -1 (fail)
- * @(#) 
- *
- * Copyright: Nicos Dessipris
- * Written on: 16/01/1990
- * Modified on : 28/10/1992 J. Cupitt
- *	- now calls im_histlin, much simpler
- *	- many bugs in old version ...
- * 22/8/05
- * 	- pass argv0 separately
- */
-
-/*
-
-    This file is part of VIPS.
-    
-    VIPS is free software; you can redistribute it and/or modify
-    it under the terms of the GNU Lesser General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Lesser General Public License for more details.
-
-    You should have received a copy of the GNU Lesser General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-
- */
-
-/*
-
-    These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
-
- */
-
-#ifdef HAVE_CONFIG_H
-#include <config.h>
-#endif /*HAVE_CONFIG_H*/
-#include <vips/intl.h>
-
-#include <stdio.h>
-#include <string.h>
-#include <time.h>
-
-#include <vips/vips.h>
-#include <vips/buf.h>
-
-#ifdef WITH_DMALLOC
-#include <dmalloc.h>
-#endif /*WITH_DMALLOC*/
-
-#define IM_MAX_LINE (4096)
-
-int 
-im_updatehist( IMAGE *out, const char *name, int argc, char *argv[] )
-{	
-	int i;
-	char txt[IM_MAX_LINE];
-	VipsBuf buf;
-
-	vips_buf_init_static( &buf, txt, IM_MAX_LINE );
-	vips_buf_appends( &buf, name );
-
-	for( i = 0; i < argc; i++ ) {
-		vips_buf_appends( &buf, " " );
-		vips_buf_appends( &buf, argv[i] );
-	}
-
-	if( im_histlin( out, "%s", vips_buf_all( &buf ) ) ) 
-		return( -1 );
-
-	return( 0 );
-}

libvips/iofuncs/im_writeline.c

@@ -71,6 +71,7 @@
 
 #include <vips/vips.h>
 #include <vips/internal.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>

libvips/iofuncs/predicate.c

@@ -81,6 +81,7 @@
 
 #include <vips/vips.h>
 #include <vips/internal.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>

libvips/iofuncs/region.c

@@ -90,6 +90,7 @@
 #include <vips/vips.h>
 #include <vips/internal.h>
 #include <vips/thread.h>
+#include <vips/debug.h>
 
 #ifdef OS_WIN32
 #include <windows.h>

libvips/iofuncs/time.c

@@ -45,6 +45,7 @@
 
 #include <vips/vips.h>
 #include <vips/internal.h>
+#include <vips/debug.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>