revise region docs

libvips/include/vips/private.h

@@ -178,10 +178,14 @@ void vips__demand_hint_array( struct _VipsImage *image,
 int vips__image_copy_fields_array( struct _VipsImage *out, 
 	struct _VipsImage *in[] );
 
+void vips__region_count_pixels( struct _VipsRegion *region, const char *nickname );
+void vips_region_dump_all( void );
+
 /* Deprecated.
  */
 int vips__init( const char *argv0 );
 size_t vips__get_sizeof_vipsobject( void );
+int vips_region_prepare_many( struct _VipsRegion **reg, VipsRect *r );
 
 #ifdef __cplusplus
 }

libvips/include/vips/region.h

@@ -121,16 +121,9 @@ int vips_region_shrink( VipsRegion *from, VipsRegion *to, VipsRect *target );
 int vips_region_prepare( VipsRegion *reg, VipsRect *r );
 int vips_region_prepare_to( VipsRegion *reg, 
 	VipsRegion *dest, VipsRect *r, int x, int y );
-int vips_region_prepare_many( VipsRegion **reg, VipsRect *r );
 
 void vips_region_invalidate( VipsRegion *reg );
 
-void vips_region_dump_all( void );
-
-#ifdef DEBUG_LEAK
-void vips__region_count_pixels( VipsRegion *region, const char *nickname );
-#endif /*DEBUG_LEAK*/
-
 /* Use this to count pixels passing through key points. Handy for spotting bad
  * overcomputation.
  */

libvips/iofuncs/region.c

@@ -105,7 +105,7 @@
  * <link linkend="libvips-generate">generate</link>
  * @include: vips/vips.h
  *
- * A #VipsRegion is a small part of an image and some pixels. You use regions to
+ * A #VipsRegion is a small part of an image. You use regions to
  * read pixels out of images without having to have the whole image in memory
  * at once.
  *
@@ -558,7 +558,7 @@ vips_region_new( VipsImage *image )
  * @r: #VipsRect of pixels you need to be able to address
  *
  * The region is transformed so that at least @r pixels are available as a
- * memory buffer. 
+ * memory buffer that can be written to. 
  *
  * Returns: 0 on success, or -1 for error.
  */
@@ -626,8 +626,8 @@ vips_region_buffer( VipsRegion *reg, VipsRect *r )
  * @reg: region to operate upon
  * @r: #VipsRect of pixels you need to be able to address
  *
- * The region is transformed so that at least @r pixels are available directly
+ * The region is transformed so that at least @r pixels are available to be read from
- * from the image. The image needs to be a memory buffer or represent a file
+ * image. The image needs to be a memory buffer or represent a file
  * on disc that has been mapped or can be mapped. 
  *
  * Returns: 0 on success, or -1 for error.
@@ -725,7 +725,7 @@ vips_region_image( VipsRegion *reg, VipsRect *r )
  * Performs all clipping necessary to ensure that @reg->valid is indeed
  * valid.
  *
- * If the region we attach to is modified, we can be left with dangling 
+ * If the region we attach to is moved or destroyed, we can be left with dangling 
  * pointers! If the region we attach to is on another image, the two images 
  * must have 
  * the same sizeof( pel ).
@@ -933,7 +933,11 @@ vips_region_fill( VipsRegion *reg, VipsRect *r, VipsRegionFillFn fn, void *a )
  * @r: area to paint
  * @value: value to paint
  *
- * Paints @value into @reg covering rectangle @r. For int images, @value is 
+ * Paints @value into @reg covering rectangle @r. 
+ * @r is clipped against 
+ * @reg->valid.
+ *
+ * For int images, @value is 
  * passed to memset(), so it usually needs to be 0 or 255. For float images,
  * value is cast to a float and copied in to each band element. 
  *
@@ -955,7 +959,6 @@ vips_region_paint( VipsRegion *reg, VipsRect *r, int value )
 		int y;
 
 		if( vips_band_format_isint( reg->im->BandFmt ) ) { 
-
 			for( y = 0; y < clipped.height; y++ ) {
 				memset( (char *) q, value, wd );
 				q += ls;
@@ -1519,19 +1522,17 @@ vips_region_prepare_to_generate( VipsRegion *reg,
  * @x: postion of @r in @dest
  * @y: postion of @r in @dest
  *
- * Like vips_region_prepare(): fill @reg with data, ready to be read from by 
+ * Like vips_region_prepare(): fill @reg with the pixels in area @r. 
- * our caller. Unlike vips_region_prepare(), rather than allocating memory 
+ * Unlike vips_region_prepare(), rather than writing the result to @reg, the pixels are
- * local to @reg for the result, we guarantee that we will fill the pixels 
+ * written into @dest
- * in @dest at offset @x, @y. In other words, we generate an extra copy 
+ * at offset @x, @y. 
- * operation if necessary. 
  *
  * Also unlike vips_region_prepare(), @dest is not set up for writing for 
  * you with
  * vips_region_buffer(). You can
  * point @dest at anything, and pixels really will be written there. 
  * This makes vips_region_prepare_to() useful for making the ends of 
- * pipelines, since
+ * pipelines.
- * it (effectively) makes a break in the pipe.
  *
  * See also: vips_region_prepare(), vips_sink_disc().
  *
@@ -1671,6 +1672,8 @@ vips_region_prepare_to( VipsRegion *reg,
 	return( 0 );
 }
 
+/* Don't use this, use vips_reorder_prepare_many() instead.
+ */
 int
 vips_region_prepare_many( VipsRegion **reg, VipsRect *r )
 {