more docs argh

doc/reference/extending.xml

@@ -364,6 +364,10 @@ if( negative( in, &out, "image_max", 128, NULL ) )
       #VipsRect in _generate().
     </para>
 
+    <para>
+      Make zero-copy operations, like vips_insert(), with vips_region_region().
+    </para>
+
   </refsect1>
 
 </refentry>

doc/reference/using-C.xml

@@ -24,14 +24,14 @@
     </para>
 
     <para>
-      When your program starts, use <function>vips_init()</function> to set up 
+      When your program starts, use <function>VIPS_INIT()</function> to set up 
       the VIPS library. You should pass it the name of your program, usually 
       <literal>argv[0]</literal>. Use <function>vips_shutdown()</function> 
       when you exit. 
     </para>
 
     <para>
-      You can add the VIPS flags to your GObject command-line processing
+      You can add the VIPS flags to your %GObject command-line processing
       with vips_get_option_group(), see below.
     </para>
 
@@ -73,6 +73,13 @@
       C-style memory array. See vips_image_write_to_file() and friends.
     </para>
 
+    <para>
+      Use #VipsRegion to read pixels out of images. You can use 
+      VIPS_IMAGE_ADDR() as well, but this can need a large amount of 
+      memory to work. See <link linkend="extending">extending</link> 
+      for an introduxction to writing your own operations. 
+    </para>
+
     <para>
       VIPS keeps a log of error message, see  <link
       linkend="libvips-error">VIPS Error</link> to find out how to get and
@@ -100,7 +107,7 @@ main( int argc, char **argv )
 	double mean;
 	VipsImage *out;
 
-	if( vips_init( argv[0] ) )
+	if( VIPS_INIT( argv[0] ) )
 		vips_error_exit( NULL ); 
 
 	context = g_option_context_new( "hello infile outfile - VIPS demo" );

libvips/arithmetic/add.c

@@ -200,7 +200,7 @@ vips_add_init( VipsAdd *add )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/arithmetic/boolean.c

@@ -260,7 +260,7 @@ vips_booleanv( VipsImage *left, VipsImage *right, VipsImage **out,
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>).
+ * <link linkend="libvips-arithmetic">arithmetic</link>).
  *
  * See also: vips_boolean_const().
  *

libvips/arithmetic/divide.c

@@ -254,7 +254,7 @@ vips_divide_init( VipsDivide *divide )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/arithmetic/math2.c

@@ -247,7 +247,7 @@ vips_math2v( VipsImage *left, VipsImage *right, VipsImage **out,
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), and that format is the
+ * <link linkend="libvips-arithmetic">arithmetic</link>), and that format is the
  * result type.
  *
  * See also: vips_math2_const().

libvips/arithmetic/multiply.c

@@ -200,7 +200,7 @@ vips_multiply_init( VipsMultiply *multiply )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/arithmetic/relational.c

@@ -270,7 +270,7 @@ vips_relationalv( VipsImage *left, VipsImage *right, VipsImage **out,
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>).
+ * <link linkend="libvips-arithmetic">arithmetic</link>).
  *
  * To decide if pixels match exactly, that is have the same value in every
  * band, use vips_bandbool() after this operation to AND or OR image bands 

libvips/arithmetic/remainder.c

@@ -207,7 +207,7 @@ vips_remainder_init( VipsRemainder *remainder )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), and that format is the
+ * <link linkend="libvips-arithmetic">arithmetic</link>), and that format is the
  * result type.
  *
  * See also: vips_remainder_const(), vips_divide(), vips_round().

libvips/arithmetic/subtract.c

@@ -190,7 +190,7 @@ vips_subtract_init( VipsSubtract *subtract )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/arithmetic/sum.c

@@ -179,7 +179,7 @@ vips_sumv( VipsImage **in, VipsImage **out, int n, va_list ap )
  * @n: number of input images
  * @...: %NULL-terminated list of optional named arguments
  *
- * This operation sums @in1 + @in2 and writes the result to @out. 
+ * This operation sums all images in @in and writes the result to @out. 
  *
  * If the images differ in size, the smaller images are enlarged to match the
  * largest by adding zero pixels along the bottom and right.
@@ -191,7 +191,7 @@ vips_sumv( VipsImage **in, VipsImage **out, int n, va_list ap )
  *
  * The input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/include/vips/internal.h

@@ -104,6 +104,8 @@ extern gboolean vips__cache_trace;
 
 void vips__cache_init( void );
 
+void vips__print_renders( void );
+
 void vips__type_leak( void );
 
 typedef int (*im__fftproc_fn)( VipsImage *, VipsImage *, VipsImage * );

libvips/include/vips/threadpool.h

@@ -131,8 +131,6 @@ int vips_threadpool_run( VipsImage *im,
 void vips_get_tile_size( VipsImage *im, 
 	int *tile_width, int *tile_height, int *nlines );
 
-void vips__print_renders( void );
-
 void vips_concurrency_set( int concurrency );
 int vips_concurrency_get( void );
 

libvips/include/vips/type.h

@@ -91,7 +91,6 @@ typedef struct _VipsArea {
 
 VipsArea *vips_area_copy( VipsArea *area );
 void vips_area_unref( VipsArea *area );
-void vips__type_leak( void );
 
 VipsArea *vips_area_new( VipsCallbackFn free_fn, void *data );
 VipsArea *vips_area_new_blob( VipsCallbackFn free_fn, 
@@ -198,8 +197,6 @@ int vips_value_set_array_object( GValue *value, int n );
  * vips_value_set_array_image(). They need to be declared after VipsImage. 
  */
 
-void vips__meta_init_types( void );
-
 #ifdef __cplusplus
 }
 #endif /*__cplusplus*/

libvips/iofuncs/object.c

@@ -105,11 +105,11 @@
  * The stages inside vips_object_build() are:
  *
  * 1. Chain up through the object's @build class methods. At each stage,
- * each object does any initial setup and checking, then chains up to its
+ * each class does any initial setup and checking, then chains up to its
  * superclass.
  *
- * 2. The innermost @build method in #VipsObject itself checks that all input
- * arguments have been set and then returns. 
+ * 2. The innermost @build method inside #VipsObject itself checks that all 
+ * input arguments have been set and then returns. 
  *
  * 3. All object @build methods now finish executing, from innermost to
  * outermost. They know all input arguments have been checked and supplied, so
@@ -120,7 +120,10 @@
  * signal. #VipsObject::postbuild only runs if the object has constructed
  * successfuly.
  *
- * And the stages inside close are:
+ * #VipsOperation has a cache of recent operation objects, see that class for
+ * an explanation of vips_cache_operation_build(). 
+ *
+ * Finally the stages inside close are:
  *
  * 1. #VipsObject::preclose. This is emitted at the start of
  * the #VipsObject dispose. The object is still functioning. 

libvips/iofuncs/region.c

@@ -158,12 +158,14 @@
  * @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 #VipsRect (@R->valid).
+ * This macro returns a pointer to a pixel in a region. The (@X, @Y) 
+ * coordinates need to be within the #VipsRect (@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.
+ * See also: vips_region_prepare().
+ *
+ * Returns: The address of pixel (@X,@Y) in @R.
  */
 
 /**
@@ -172,6 +174,8 @@
  *
  * This macro returns a pointer to the top-left pixel in the #VipsRegion, that 
  * is, the pixel at (@R->valid.left, @R->valid.top).
+ *
+ * See also: vips_region_prepare().
  * 
  * Returns: The address of the top-left pixel in the region.
  */
@@ -1090,11 +1094,10 @@ vips_region_generate( VipsRegion *reg )
  * the calling thread, no new threads are involved, and computation 
  * blocks until the pixels are ready.
  *
- * Use vips_region_prepare_thread() to calculate an area of pixels with many
- * threads. Use vips_sink_screen() to calculate an area of pixels in the 
+ * Use vips_sink_screen() to calculate an area of pixels in the 
  * background.
  *
- * See also: vips_region_prepare_thread(), vips_sink_screen(), 
+ * See also: vips_sink_screen(), 
  * vips_region_prepare_to().
  *
  * Returns: 0 on success, or -1 on error.

libvips/iofuncs/type.c

@@ -138,21 +138,6 @@ vips_thing_get_type( void )
 	return( type );
 }
 
-/**
- * SECTION: VipsArea
- * @short_description: an area of memory
- * @stability: Stable
- * @see_also: <link linkend="libvips-meta">header</link>,
- * @include: vips/vips.h
- *
- * A VipsArea wraps a chunk of memory. It adds reference counting and a free
- * function. It also keeps a count and a GType, so the area can be an array.
- *
- * This type is used for things like passing an array of double or an array of
- * VipsObject pointers to operations, and for reference-counted immutable
- * strings. 
- */
-
 static GSList *vips_area_all = NULL;
 
 VipsArea *
@@ -227,8 +212,14 @@ vips_area_unref( VipsArea *area )
  * @free_fn: (scope async): @data will be freed with this function
  * @data: data will be freed with this function
  *
- * An area of memory with a free function. (eg. \0-terminated string, or a 
- * struct). Inital count == 1, so _unref() after attaching somewhere.
+ * A VipsArea wraps a chunk of memory. It adds reference counting and a free
+ * function. It also keeps a count and a %GType, so the area can be an array.
+ *
+ * This type is used for things like passing an array of double or an array of
+ * #VipsObject pointers to operations, and for reference-counted immutable
+ * strings. 
+ *
+ * Inital count == 1, so _unref() after attaching somewhere.
  *
  * See also: vips_area_unref().
  *
@@ -313,7 +304,7 @@ vips_area_new_blob( VipsCallbackFn free_fn, void *data, size_t length )
  * @sizeof_type: sizeof() an element in the array
  * @n: number of elements in the array
  *
- * An area which holds an array of elements of some GType. To set values for
+ * An area which holds an array of elements of some %GType. To set values for
  * the elements, get the pointer and write.
  *
  * See also: vips_area_unref().
@@ -351,7 +342,7 @@ vips_area_free_array_object( GObject **array, VipsArea *area )
  * vips_area_new_array_object:
  * @n: number of elements in the array
  *
- * An area which holds an array of GObjects. See vips_area_new_array(). When
+ * An area which holds an array of %GObjects. See vips_area_new_array(). When
  * the area is freed, each %GObject will be unreffed.
  *
  * See also: vips_area_unref().
@@ -934,7 +925,7 @@ vips_value_set_save_stringf( GValue *value, const char *fmt, ... )
  * @value: %GValue to get from
  * @length: (allow-none): return length here, optionally
  *
- * Get the C string held internally by the GValue.
+ * Get the C string held internally by the %GValue.
  *
  * Returns: (transfer none): The C string held by @value. 
  */
@@ -946,14 +937,14 @@ vips_value_get_ref_string( const GValue *value, size_t *length )
 
 /** 
  * vips_value_set_ref_string:
- * @value: (out): GValue to set
+ * @value: (out): %GValue to set
  * @str: C string to copy into the GValue
  *
  * Copies the C string @str into @value. 
  *
  * vips_ref_string are immutable C strings that are copied between images by
  * copying reference-counted pointers, making the much more efficient than
- * regular GValue strings.
+ * regular %GValue strings.
  *
  * Returns: 0 on success, -1 otherwise.
  */
@@ -1353,7 +1344,7 @@ vips_value_get_array_object( const GValue *value, int *n )
  * @value: (out): %GValue to set
  * @n: the number of elements 
  *
- * Set @value to hold an array of GObject. Pass in the array length in @n. 
+ * Set @value to hold an array of %GObject. Pass in the array length in @n. 
  *
  * See also: vips_array_object_get().
  *