final operators gtk-doc'd

All done! Good Lord. Just some parts of iofuncs/ still to do.

ChangeLog

@@ -25,6 +25,9 @@
 - done gtk-doc for other
 - --vips-progress tells you about nthreads, tile size, nlines
 - gtk-doc for interpolate
+- move im_stretch3() to deprecated
+- move im_clamp() to deprecated
+- gtk-doc for video ... all operators done! amazing argh
 
 30/11/10 started 7.24.0
 - bump for new stable

configure.in

@@ -620,7 +620,6 @@ AC_OUTPUT([
 	libvips/include/Makefile 
 	libvips/include/vips/Makefile 
 	libvips/Makefile 
-	libvips/acquire/Makefile 
 	libvips/arithmetic/Makefile 
 	libvips/boolean/Makefile 
 	libvips/cimg/Makefile 

doc/reference/libvips-docs.sgml.in

@@ -47,13 +47,8 @@
     <xi:include href="xml/morphology.xml"/>
     <xi:include href="xml/mosaicing.xml"/>
     <xi:include href="xml/other.xml"/>
-  </chapter>
-
-  <chapter>
-    <title>VIPS operation API by section (no gtkdoc comments yet)</title>
     <xi:include href="xml/resample.xml"/>
     <xi:include href="xml/video.xml"/>
-    <xi:include href="xml/cimg_funcs.xml"/>
   </chapter>
 
   <chapter>

libvips/Makefile.am

@@ -11,7 +11,6 @@ endif
 
 SUBDIRS = \
 	include \
-	acquire \
 	arithmetic \
 	resample \
 	boolean \
@@ -42,7 +41,6 @@ endif
 
 # DLLs need dependant libs there too ... put @VIPS_LIBS@ at the end
 libvips_la_LIBADD = \
-	acquire/libacquire.la \
 	resample/libresample.la \
 	arithmetic/libarithmetic.la \
 	boolean/libboolean.la \

libvips/acquire/Makefile.am

@@ -1,7 +0,0 @@
-noinst_LTLIBRARIES = libacquire.la
-
-libacquire_la_SOURCES = \
-	im_clamp.c
-
-INCLUDES = -I${top_srcdir}/libvips/include @VIPS_CFLAGS@ @VIPS_INCLUDES@ 
-

libvips/deprecated/Makefile.am

@@ -5,6 +5,8 @@ libdeprecated_la_SOURCES = \
 	im_dif_std.c \
 	im_simcontr.c \
 	im_spatres.c \
+	im_stretch3.c \
+	im_clamp.c \
 	cooc_funcs.c \
 	glds_funcs.c \
 	im_fav4.c \

libvips/include/vips/almostdeprecated.h

@@ -169,6 +169,8 @@ int im_dif_std();
 int im_simcontr( IMAGE *out, int xsize, int ysize );
 int im_spatres( IMAGE *in,  IMAGE *out, int step );
 
+int im_stretch3( IMAGE *in, IMAGE *out, double dx, double dy );
+
 /* Renamed operations.
  */
 

libvips/include/vips/resample.h

@@ -44,8 +44,6 @@ int im_affinei( IMAGE *in, IMAGE *out,
 int im_affinei_all( IMAGE *in, IMAGE *out, VipsInterpolate *interpolate,
 	double a, double b, double c, double d, double dx, double dy ) ;
 
-int im_stretch3( IMAGE *in, IMAGE *out, double dx, double dy );
-
 int im_shrink( IMAGE *in, IMAGE *out, double xshrink, double yshrink );
 int im_rightshift_size( IMAGE *in, IMAGE *out, int xshift, int yshift, int band_fmt );
 

libvips/resample/Makefile.am

@@ -8,7 +8,6 @@ libresample_la_SOURCES = \
 	im_affine.c \
 	interpolate.c \
 	im_shrink.c \
-	im_stretch3.c \
 	im_rightshift_size.c \
 	transform.c \
 	resample_dispatch.c \
@@ -24,7 +23,6 @@ libresample_la_SOURCES = \
 	im_affine.c \
 	interpolate.c \
 	im_shrink.c \
-	im_stretch3.c \
 	im_rightshift_size.c \
 	transform.c \
 	resample_dispatch.c 

libvips/resample/im_rightshift_size.c

@@ -1,16 +1,4 @@
-/* @(#) Decrease the size of an image by a power-of-two factor, summing the
+/* fast shrink by a power of two 
- * @(#) values of pixels, and shifting to give output of the specified band
- * @(#) format.
- * @(#)
- * @(#) int
- * @(#) im_rightshift_size(
- * @(#)   IMAGE *in,
- * @(#)   IMAGE *out,
- * @(#)   int xshift,
- * @(#)   int yshift,
- * @(#)   int band_fmt
- * @(#) );
- * @(#)
  *
  * Copyright: 2006, Tom Vajzovic
  *
@@ -24,6 +12,8 @@
  * 2007-02-02 jc
  *  - added return 0; on success
  *  - FUNCTION_NAME updated
+ * 2/2/11
+ * 	- gtk-doc
  */
 
 /*
@@ -109,10 +99,10 @@ GEN_FUNCS_SIGN( guint )
  * @yshift: vertical shrink
  * @band_fmt: output format
  *
- * Shrink an image by a pair of power-of-two factors and shifting to give 
+ * Shrink @in by a pair of power-of-two factors, shifting to give 
  * output of the specified band format. This is faster than im_shrink(). 
  *
- * See also: im_shrink(), im_affine().
+ * See also: im_shrink(), im_affinei().
  *
  * Returns: 0 on success, -1 on error
  */
@@ -138,25 +128,13 @@ im_rightshift_size( IMAGE *in, IMAGE *out, int xshift, int yshift, int band_fmt
     im_error( FUNCTION_NAME, "%s", _( "would result in zero size output image" ) );
     return -1;
   }
-  if( ! vips_bandfmt_isint( in->BandFmt ) ){
+  if( im_check_int( FUNCTION_NAME, in ) || 
-    im_error( FUNCTION_NAME, "%s", _( "integer type images only" ) );
+	  im_check_uncoded( FUNCTION_NAME, in ) ) 
     return -1;
-  }
+  if( vips_bandfmt_isuint( in->BandFmt ) != vips_bandfmt_isuint( band_fmt ) ) {
-  if( IM_CODING_NONE != in->Coding ){
+      im_error( FUNCTION_NAME, "%s", 
-    im_error( FUNCTION_NAME, "%s", _( "uncoded images only" ) );
+	_( "image and band_fmt must match in sign" ) );
-    return -1;
-  }
-  if( vips_bandfmt_isuint( in->BandFmt ) ){
-    if( IM_BANDFMT_UCHAR != band_fmt && IM_BANDFMT_USHORT != band_fmt && IM_BANDFMT_UINT != band_fmt ){
-      im_error( FUNCTION_NAME, "%s", _( "unsigned input means that output must be unsigned int, short or char" ) );
       return -1;
-    }
-  }
-  else {
-    if( IM_BANDFMT_CHAR != band_fmt && IM_BANDFMT_SHORT != band_fmt && IM_BANDFMT_INT != band_fmt ){
-      im_error( FUNCTION_NAME, "%s", _( "signed input means that output must be signed int, short or char" ) );
-      return -1;
-    }
   }
   outbits= im_bits_of_fmt( band_fmt );
 

libvips/resample/im_shrink.c

@@ -1,13 +1,4 @@
-/* @(#) Shrink any non-complex image by some x, y, factor. No interpolation!
+/* shrink with a box filter
- * @(#) Just average an area. Suitable for making quicklooks only!
- * @(#)
- * @(#) int 
- * @(#) im_shrink( in, out, xshrink, yshrink )
- * @(#) IMAGE *in, *out;
- * @(#) double xshrink, yshrink;
- * @(#)
- * @(#) Returns either 0 (success) or -1 (fail)
- * @(#)
  *
  * Copyright: 1990, N. Dessipris.
  *
@@ -34,6 +25,8 @@
  *	- IM_CODING_LABQ handling added here
  * 20/12/08
  * 	- fall back to im_copy() for 1/1 shrink
+ * 2/2/11
+ * 	- gtk-doc
  */
 
 /*
@@ -240,20 +233,6 @@ shrink( IMAGE *in, IMAGE *out, double xshrink, double yshrink )
 {
 	ShrinkInfo *st;
 
-	/* Check parameters.
-	 */
-	if( !in || vips_bandfmt_iscomplex( in->BandFmt ) ) {
-		im_error( "im_shrink", "%s", _( "non-complex input only" ) );
-		return( -1 );
-	}
-	if( xshrink < 1.0 || yshrink < 1.0 ) {
-		im_error( "im_shrink", 
-			"%s", _( "shrink factors should both be >1" ) );
-		return( -1 );
-	}
-	if( im_piocheck( in, out ) )
-		return( -1 );
-
 	/* Prepare output. Note: we round the output width down!
 	 */
 	if( im_cp_desc( out, in ) )
@@ -293,11 +272,39 @@ shrink( IMAGE *in, IMAGE *out, double xshrink, double yshrink )
 	return( 0 );
 }
 
-/* Wrap up the above: do IM_CODING_LABQ as well.
+/**
+ * im_shrink:
+ * @in: input image
+ * @out: output image
+ * @xshrink: horizontal shrink
+ * @yshrink: vertical shrink
+ *
+ * Shrink @in by a pair of factors with a simple box filter. 
+ *
+ * You will get aliasing for non-integer shrinks. In this case, shrink with
+ * this function to the nearest integer size above the target shrink, then
+ * downsample to the exact size with im_affinei() and your choice of
+ * interpolator.
+ *
+ * im_rightshift_size() is faster for factors which are integer powers of two.
+ *
+ * See also: im_rightshift_size(), im_affinei().
+ *
+ * Returns: 0 on success, -1 on error
  */
 int
 im_shrink( IMAGE *in, IMAGE *out, double xshrink, double yshrink )
 {
+	if( im_check_noncomplex( "im_shrink", in ) ||
+		im_check_coding_known( "im_shrink", in ) ||
+		im_piocheck( in, out ) )
+		return( -1 );
+	if( xshrink < 1.0 || yshrink < 1.0 ) {
+		im_error( "im_shrink", 
+			"%s", _( "shrink factors should be >= 1" ) );
+		return( -1 );
+	}
+
 	if( xshrink == 1 && yshrink == 1 ) {
 		return( im_copy( in, out ) );
 	}
@@ -310,14 +317,9 @@ im_shrink( IMAGE *in, IMAGE *out, double xshrink, double yshrink )
 			im_LabS2LabQ( t[1], out ) )
 			return( -1 );
 	}
-	else if( in->Coding == IM_CODING_NONE ) {
+	else 
 		if( shrink( in, out, xshrink, yshrink ) )
 			return( -1 );
-	}
-	else {
-		im_error( "im_shrink", "%s", _( "unknown coding type" ) );
-		return( -1 );
-	}
 
 	return( 0 );
 }

libvips/video/im_video_test.c

@@ -38,6 +38,16 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * im_video_test:
+ * @im: write image here
+ * @brightness: brightness setting
+ * @error: set this to make the function return an error
+ *
+ * Make a test video image. Set @error to trigger an error.
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int
 im_video_test( IMAGE *im, int brightness, int error )
 {

libvips/video/im_video_v4l1.c

@@ -629,6 +629,34 @@ lgrab_capture( LGrab *lg, IMAGE *im )
 	return( 0 );
 }
 
+/**
+ * im_video_v4l1:
+ * @im: write image here
+ * @device: device to grab from
+ * @channel: channel to grab
+ * @brightness: brightness setting
+ * @colour: colour setting
+ * @contrast: contrast setting
+ * @hue: hue setting
+ * @ngrabs: average this many frames
+ *
+ * Grab an image from a device using the Video4Linux1 interface. It grabs
+ * 24-bit RGB at the maximum size your card allows.
+ *
+ * @device should typically be "/dev/video".
+ * @channel selects the channel to acquire: usually 0 is TV, and 1 is 
+ * composite video. @brightness, @colour, @contrast and @hue 
+ * set grab parameters. Each should be in the range (0 - 32768). 
+ * 32768 is usually the value you want. @ngrabs
+ * sets the number of frames the card should average. 
+ * Higher values are slower, but typically less noisy (and slightly softer).
+ *
+ * This function needs updating to newer video standards.
+ *
+ * See also: im_video_test().
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int
 im_video_v4l1( IMAGE *im, const char *device,
 	int channel, int brightness, int colour, int contrast, int hue,