docs for REGION

ChangeLog

@@ -50,11 +50,8 @@
 - better im_check() functions
 - added im_flood_other() as start of simple segmentation operator
 - added im_segment() 
-- gtk-doc comments for meta
-- gtk-doc comments for header
 - im_printlines(), im_debugim() deprecated (use im_vips2csv() instead)
-- callback gtkdocs
+- meta, header, callback, error, REGION gtkdocs
-- error gtkdocs
 - removed printlines tool, vips2csv is much better
 - removed other useless tools as well: debugim, binfile
 

TODO

@@ -1,12 +1,10 @@
-- image.h/im_invalidate() needs docs
+- reached im_prepare() in region.h
-
-- started region.h
 
   
 
 - more stuff from util.c? too much to do it all now
 
-- im_prepare(), im_render()?
+- im_render()?
 
 - memory.c
 

libvips/include/vips/image.h

@@ -272,57 +272,14 @@ const char *im_guess_libdir( const char *, const char * );
 
 VipsImage *im_open( const char *filename, const char *mode );
 
-/**
- * im_open_local:
- * @IM: image to open local to
- * @NAME: filename to open
- * @MODE: mode to open with
- *
- * Just like im_open(), but the #IMAGE will be closed for you automatically
- * when @IM is closed.
- *
- * Returns: a new #IMAGE, or NULL on error
- *
- * See also: im_open(), im_close(), im_local().
- */
 #define im_open_local( IM, NAME, MODE ) \
 	((IMAGE *) im_local( (IM), \
 		(im_construct_fn) im_open, (im_callback_fn) im_close, \
 		(void *) (NAME), (void *) (MODE), NULL ))
 
 
-/** 
- * im_open_local_array:
- * @IM: image to open local to
- * @OUT: array to fill with #IMAGE
- * @N: array size
- * @NAME: filename to open
- * @MODE: mode to open with
- *
- * Just like im_open(), but opens an array of images. Handy for creating a set
- * of temporary images for a function.
- *
- * Example:
- *
- * |[
- * IMAGE *t[5];
- *
- * if( im_open_local_array( out, t, 5, "some-temps", "p" ) ||
- *   im_add( a, b, t[0] ) ||
- *   im_invert( t[0], t[1] ) ||
- *   im_add( t[1], t[0], t[2] ) ||
- *   im_costra( t[2], out ) )
- *   return( -1 );
- * ]|
- *
- * Returns: 0 on sucess, or -1 on error
- *
- * See also: im_open(), im_open_local(), im_local_array().
- */
-
 /* Strange double cast stops bogus warnings from gcc 4.1
  */
-
 #define im_open_local_array( IM, OUT, N, NAME, MODE ) \
 	(im_local_array( (IM), (void **)((void*)(OUT)), (N),\
 		(im_construct_fn) im_open, (im_callback_fn) im_close, \

libvips/include/vips/private.h

@@ -129,6 +129,48 @@ im_buffer_t *im_buffer_unref_ref( im_buffer_t *buffer,
 	struct _VipsImage *im, Rect *area );
 void im_buffer_print( im_buffer_t *buffer );
 
+/* Sections of region.h that are private to VIPS.
+ */
+
+/* Region types.
+ */
+typedef enum region_type {
+	IM_REGION_NONE,
+	IM_REGION_BUFFER,	/* a pixel buffer */
+	IM_REGION_OTHER_REGION, /* memory on another region */
+	IM_REGION_OTHER_IMAGE,	/* memory on another image */
+	IM_REGION_WINDOW	/* mmap() buffer on fd on another image */
+} RegionType;
+
+/* Private to iofuncs: the size of the `tiles' requested by im_generate()
+ * when acting as a data sink.
+ */
+#define IM__TILE_WIDTH (64)
+#define IM__TILE_HEIGHT (64)
+
+/* The height of the strips for the other two request styles.
+ */
+#define IM__THINSTRIP_HEIGHT (1)
+#define IM__FATSTRIP_HEIGHT (16)
+
+/* Functions on regions.
+ */
+struct _REGION;
+void im__region_take_ownership( struct _REGION *reg );
+void im__region_check_ownership( struct _REGION *reg );
+void im__region_no_ownership( struct _REGION *reg );
+
+void im__copy_region( struct _REGION *reg, struct _REGION *dest, Rect *r, int x, int y );
+void im__find_demand_size( struct _VipsImage *im, int *pw, int *ph );
+
+int im__call_start( struct _REGION *reg );
+void im__call_stop( struct _REGION *reg );
+
+typedef int (*im_region_fill_fn)( struct _REGION *, void * );
+int im_region_fill( struct _REGION *reg, Rect *r, im_region_fill_fn fn, void *a );
+void im_region_print( struct _REGION *region );
+
+void im_region_print( struct _REGION *region ); 
 #ifdef __cplusplus
 }
 #endif /*__cplusplus*/

libvips/include/vips/region.h

@@ -36,19 +36,10 @@
 extern "C" {
 #endif /*__cplusplus*/
 
-/* Region types.
- */
-typedef enum region_type {
-	IM_REGION_NONE,
-	IM_REGION_BUFFER,	/* a pixel buffer */
-	IM_REGION_OTHER_REGION, /* memory on another region */
-	IM_REGION_OTHER_IMAGE,	/* memory on another image */
-	IM_REGION_WINDOW	/* mmap() buffer on fd on another image */
-} RegionType;
-
 /* Sub-area of image.
  */
-typedef struct region_struct {
+typedef struct _REGION {
+	/*< public >*/
 	/* Users may read these two fields.
 	 */
 	IMAGE *im;		/* Link back to parent image */
@@ -56,6 +47,7 @@ typedef struct region_struct {
 
 	/* The rest of REGION is private.
 	 */
+	/*< private >*/
 	RegionType type;	/* What kind of attachment */
 	char *data;		/* Off here to get data */
 	int bpl;		/* Bytes-per-line for data */
@@ -75,34 +67,14 @@ typedef struct region_struct {
 	im_buffer_t *buffer;
 } REGION;
 
-/* Private to iofuncs: the size of the `tiles' requested by im_generate()
- * when acting as a data sink.
- */
-#define IM__TILE_WIDTH (64)
-#define IM__TILE_HEIGHT (64)
-
-/* The height of the strips for the other two request styles.
- */
-#define IM__THINSTRIP_HEIGHT (1)
-#define IM__FATSTRIP_HEIGHT (16)
-
-/* Functions on regions.
- */
-void im__region_take_ownership( REGION *reg );
-void im__region_check_ownership( REGION *reg );
-void im__region_no_ownership( REGION *reg );
-
 REGION *im_region_create( IMAGE *im );
 void im_region_free( REGION *reg );
+
 int im_region_buffer( REGION *reg, Rect *r );
 int im_region_image( REGION *reg, Rect *r );
 int im_region_region( REGION *reg, REGION *to, Rect *r, int x, int y );
 int im_region_equalsregion( REGION *reg1, REGION *reg2 );
 int im_region_position( REGION *reg1, int x, int y );
-typedef int (*im_region_fill_fn)( REGION *, void * );
-int im_region_fill( REGION *reg, Rect *r, im_region_fill_fn fn, void *a );
-
-void im_region_print( REGION *region );
 
 /* IMAGE functions which use regions. 
  */
@@ -120,7 +92,6 @@ int im_iterate( IMAGE *im,
 	im_start_fn start, im_generate_fn generate, im_stop_fn stop,
 	void *a, void *b
 );
-void im__copy_region( REGION *reg, REGION *dest, Rect *r, int x, int y );
 
 /* Convenience functions for im_generate()/im_iterate().
  */
@@ -134,29 +105,24 @@ int im_demand_hint( IMAGE *im, im_demand_type hint, ... )
 int im_demand_hint_array( IMAGE *im, im_demand_type hint, IMAGE **in );
 void im_free_region_array( REGION **regs );
 REGION **im_allocate_region_array( IMAGE *im, int count );
-void im__find_demand_size( IMAGE *im, int *pw, int *ph );
 
 /* Buffer processing.
  */
 typedef void (*im_wrapone_fn)( void *in, void *out, int width,
 	void *a, void *b );
-typedef void (*im_wraptwo_fn)( void *in1, void *in2, void *out, 
-        int width, void *a, void *b );
-typedef void (*im_wrapmany_fn)( void **in, void *out, int width,
-	void *a, void *b );
-
 int im_wrapone( IMAGE *in, IMAGE *out,
 	im_wrapone_fn fn, void *a, void *b );
+
+typedef void (*im_wraptwo_fn)( void *in1, void *in2, void *out, 
+        int width, void *a, void *b );
 int im_wraptwo( IMAGE *in1, IMAGE *in2, IMAGE *out,
 	im_wraptwo_fn fn, void *a, void *b );
+
+typedef void (*im_wrapmany_fn)( void **in, void *out, int width,
+	void *a, void *b );
 int im_wrapmany( IMAGE **in, IMAGE *out,
 	im_wrapmany_fn fn, void *a, void *b );
 
-/* Internal VIPS functions shared by partials.
- */
-int im__call_start( REGION *reg );
-void im__call_stop( REGION *reg );
-
 /* Macros on REGIONs.
  *	IM_REGION_LSKIP()		add to move down line
  *	IM_REGION_N_ELEMENTS()		number of elements across region

libvips/iofuncs/buffer.c

@@ -569,7 +569,14 @@ im_invalidate_image( IMAGE *im )
 	return( NULL );
 }
 
-/* Invalidate all pixel caches on an IMAGE and any parents.
+/**
+ * im_invalidate:
+ * @im: #IMAGE to invalidate
+ *
+ * Invalidate all pixel caches on an #IMAGE and any derived images. The 
+ * "invalidate" callback is triggered for all invalidated images.
+ *
+ * See also: im_add_invalidate_callback().
  */
 void
 im_invalidate( IMAGE *im )

libvips/iofuncs/im_open_vips.c

@@ -84,7 +84,7 @@
  * SECTION: image
  * @short_description: the VIPS image class
  * @stability: Stable
- * @see_also: vips
+ * @see_also: <link linkend="libvips-region">region</link>
  * @include: vips/vips.h
  *
  * The VIPS image class and associated types and macros.
@@ -134,7 +134,7 @@
  * These values are set by operations as hints to user-interfaces built on top 
  * of VIPS to help them show images to the user in a meaningful way. 
  * Operations do not use these values to decide their action.
- **/
+ */
 
 /**
  * VipsBandFmt: 
@@ -153,7 +153,7 @@
  *
  * Each corresponnds to a native C type for the current machine. For example,
  * %IM_BANDFMT_USHORT is <type>unsigned short</type>.
- **/
+ */
 
 /**
  * VipsCoding: 
@@ -208,28 +208,28 @@
  * @I: a #VipsImage
  *
  * Returns: sizeof() a band element.
- **/
+ */
 
 /**
  * IM_IMAGE_SIZEOF_PEL:
  * @I: a #VipsImage
  *
  * Returns: sizeof() a pixel.
- **/
+ */
 
 /**
  * IM_IMAGE_SIZEOF_LINE:
  * @I: a #VipsImage
  *
  * Returns: sizeof() a scanline of pixels.
- **/
+ */
 
 /**
  * IM_IMAGE_N_ELEMENTS:
  * @I: a #VipsImage
  *
  * Returns: the number of band elements in a scanline.
- **/
+ */
 
 /**
  * IM_IMAGE_ADDR:
@@ -244,7 +244,50 @@
  * If DEBUG is defined, you get a version that checks bounds for you.
  *
  * Returns: the address of pixel (x,y) in the image.
- **/
+ */
+
+/** 
+ * im_open_local_array:
+ * @IM: image to open local to
+ * @OUT: array to fill with #IMAGE
+ * @N: array size
+ * @NAME: filename to open
+ * @MODE: mode to open with
+ *
+ * Just like im_open(), but opens an array of images. Handy for creating a set
+ * of temporary images for a function.
+ *
+ * Example:
+ *
+ * |[
+ * IMAGE *t[5];
+ *
+ * if( im_open_local_array( out, t, 5, "some-temps", "p" ) ||
+ *   im_add( a, b, t[0] ) ||
+ *   im_invert( t[0], t[1] ) ||
+ *   im_add( t[1], t[0], t[2] ) ||
+ *   im_costra( t[2], out ) )
+ *   return( -1 );
+ * ]|
+ *
+ * Returns: 0 on sucess, or -1 on error
+ *
+ * See also: im_open(), im_open_local(), im_local_array().
+ */
+
+/**
+ * im_open_local:
+ * @IM: image to open local to
+ * @NAME: filename to open
+ * @MODE: mode to open with
+ *
+ * Just like im_open(), but the #IMAGE will be closed for you automatically
+ * when @IM is closed.
+ *
+ * Returns: a new #IMAGE, or NULL on error
+ *
+ * See also: im_open(), im_close(), im_local().
+ */
 
 /* Try to make an O_BINARY ... sometimes need the leading '_'.
  */

libvips/iofuncs/region.c

@@ -35,6 +35,8 @@
  * 	- gah, im_region_image() could still break (thanks Mikkel)
  * 23/7/08
  * 	- added im_region_print()
+ * 7/10/09
+ * 	- gtkdoc comments
  */
 
 /*
@@ -100,6 +102,77 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * SECTION: region
+ * @short_description: small, rectangular parts of images
+ * @stability: Stable
+ * @see_also: <link linkend="libvips-image">image</link>
+ * @include: vips/vips.h
+ *
+ * A #REGION is a small part of an image and some pixels. You use regions to
+ * read pixels out of images without having to have the whole image in memory
+ * at once.
+ *
+ * A region can be a memory buffer, part of a memory-mapped file, part of some
+ * other image, or part of some other region.
+ */
+
+/**
+ * REGION:
+ * @im: the #IMAGE that this region is defined on
+ * @valid: the #Rect of pixels that this region represents
+ *
+ * A small part of an #IMAGE. @valid holds the left/top/width/height of the
+ * area of pixels that are available from the region. 
+ *
+ * See also: IM_REGION_ADDR(), im_region_create(), im_prepare().
+ */
+
+/**
+ * IM_REGION_LSKIP:
+ * @R: a #REGION
+ *
+ * Returns: the number of bytes to add to move down a scanline.
+ */
+
+/**
+ * IM_REGION_N_ELEMENTS:
+ * @R: a #REGION
+ *
+ * Returns: the number of band elements across a region.
+ */
+
+/**
+ * IM_REGION_SIZEOF_LINE:
+ * @R: a #REGION
+ *
+ * Returns: the number of bytes across a region.
+ */
+
+/**
+ * IM_REGION_ADDR:
+ * @R: a #REGION
+ * @X: x coordinate
+ * @Y: y coordinate
+ *
+ * This macro returns a pointer to a pixel in a region. The (x, y) coordinates
+ * need to be within the #Rect (@R->valid).
+ * 
+ * If DEBUG is defined, you get a version that checks bounds for you.
+ *
+ * Returns: the address of pixel (x,y) in the region.
+ */
+
+/**
+ * IM_REGION_ADDR_TOPLEFT:
+ * @R: a #REGION
+ *
+ * This macro returns a pointer to the top-left pixel in the #REGION, that is,
+ * the pixel at (@R->valid.left, @R->valid.top).
+ * 
+ * Returns: the address of the top-left pixel in the region.
+ */
+
 #ifdef DEBUG
 /* Track all regions here for debugging.
  */
@@ -208,9 +281,14 @@ im__region_no_ownership( REGION *reg )
 	g_mutex_unlock( reg->im->sslock );
 }
 
-/* Create a region. Set no attachments. Either im_prepare() or im_generate()
+/**
- * are responsible for getting regions ready for user functions to read
+ * im_region_create:
- * from/write to.
+ * @im: image to create this region on
+ *
+ * Create a region. #REGION s start out empty, you need to call im_prepare() to
+ * fill them with pixels.
+ *
+ * See also: im_prepare(), im_region_free().
  */
 REGION *
 im_region_create( IMAGE *im )
@@ -262,6 +340,15 @@ im_region_reset( REGION *reg )
 	IM_FREEF( im_buffer_unref, reg->buffer );
 }
 
+/**
+ * im_region_free:
+ * @reg: #REGION to free
+ *
+ * Free a region and any resources it holds.
+ *
+ * If @im has previously been closed, then freeing the last #REGION on @in can
+ * cause @im to finally be freed as well.
+ */
 void 
 im_region_free( REGION *reg )
 {	
@@ -315,6 +402,17 @@ im_region_free( REGION *reg )
  * reg->buffer->done to see if there are pixels there already. Otherwise, you
  * need to calculate.
  */
+
+/**
+ * im_region_buffer:
+ * @reg: region to operate upon
+ * @r: #Rect 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. 
+ *
+ * Returns: 0 on success, or -1 for error.
+ */
 int
 im_region_buffer( REGION *reg, Rect *r )
 {
@@ -366,9 +464,16 @@ im_region_buffer( REGION *reg, Rect *r )
 	return( 0 );
 }
 
-/* Attach a region to a small section of the image on which it is defined.
+/**
- * The IMAGE we are attached to should be im_mmapin(), im_mmapinrw() or 
+ * im_region_image:
- * im_setbuf(). The Rect is clipped against the image size.
+ * @reg: region to operate upon
+ * @r: #Rect of pixels you need to be able to address
+ *
+ * The region is transformed so that at least @r pixels are available directly
+ * from the 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.
  */
 int
 im_region_image( REGION *reg, Rect *r )
@@ -445,18 +550,29 @@ im_region_image( REGION *reg, Rect *r )
 	return( 0 );
 }
 
-/* Make IM_REGION_ADDR() stuff to reg go to dest instead. 
+/**
+ * im_region_region:
+ * @reg: region to operate upon
+ * @dest: region to connect to
+ * @r: #Rect of pixels you need to be able to address
+ * @x: postion of @r in @dest
+ * @y: postion of @r in @dest
  *
- * r is the part of the reg image which you want to be able to write to (this
+ * Make IM_REGION_ADDR() on @reg go to @dest instead. 
- * effectively becomes the valid field), (x,y) is the top LH corner of the
- * corresponding area in dest.
  *
- * Performs all clippings necessary to ensure that &reg->valid is indeed
+ * @r is the part of @reg which you want to be able to address (this
+ * effectively becomes the valid field), (@x, @y) is the top LH corner of the
+ * corresponding area in @dest.
+ *
+ * Performs all clipping necessary to ensure that @reg->valid is indeed
  * valid.
  *
- * If the region we attach to is modified, we are left with dangling pointers!
+ * If the region we attach to is modified, we can be left with dangling 
- * If the region we attach to is on another image, the two images must have 
+ * pointers! If the region we attach to is on another image, the two images 
+ * must have 
  * the same sizeof( pel ).
+ *
+ * Returns: 0 on success, or -1 for error.
  */
 int
 im_region_region( REGION *reg, REGION *dest, Rect *r, int x, int y )
@@ -540,10 +656,20 @@ im_region_region( REGION *reg, REGION *dest, Rect *r, int x, int y )
 	return( 0 );
 }
 
-/* Do two regions point to the same piece of image? ie. 
+/**
+ * im_region_equalsregion:
+ * @reg1: region to test
+ * @reg2: region to test
+ *
+ * Do two regions point to the same piece of image? ie. 
+ *
+ * |[
  * 	IM_REGION_ADDR( reg1, x, y ) == IM_REGION_ADDR( reg2, x, y ) &&
  * 	*IM_REGION_ADDR( reg1, x, y ) == 
  * 		*IM_REGION_ADDR( reg2, x, y ) for all x, y, reg1, reg2.
+ * ]|
+ *
+ * Returns: non-zero on equality.
  */
 int
 im_region_equalsregion( REGION *reg1, REGION *reg2 )
@@ -553,10 +679,18 @@ im_region_equalsregion( REGION *reg1, REGION *reg2 )
 		reg1->data == reg2->data );
 }
 
-/* Set the position of a region. This only affects reg->valid, ie. the way
+/**
+ * im_region_position:
+ * @reg: region to operate upon
+ * @x: position to move to
+ * @y: position to move to
+ *
+ * Set the position of a region. This only affects reg->valid, ie. the way
  * pixels are addressed, not reg->data, the pixels which are addressed. Clip
  * against the size of the image. Do not allow negative positions, or
  * positions outside the image.
+ *
+ * Returns: 0 on success, or -1 for error.
  */
 int
 im_region_position( REGION *reg, int x, int y )