From 573b94e3ec49eed71d069d7c6fc0dbeca564fedd Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Tue, 19 Aug 2014 17:57:27 +0100 Subject: [PATCH] more docs argh --- doc/reference/extending.xml | 4 ++++ doc/reference/using-C.xml | 13 ++++++++--- libvips/arithmetic/add.c | 2 +- libvips/arithmetic/boolean.c | 2 +- libvips/arithmetic/divide.c | 2 +- libvips/arithmetic/math2.c | 2 +- libvips/arithmetic/multiply.c | 2 +- libvips/arithmetic/relational.c | 2 +- libvips/arithmetic/remainder.c | 2 +- libvips/arithmetic/subtract.c | 2 +- libvips/arithmetic/sum.c | 4 ++-- libvips/include/vips/internal.h | 2 ++ libvips/include/vips/threadpool.h | 2 -- libvips/include/vips/type.h | 3 --- libvips/iofuncs/object.c | 11 +++++---- libvips/iofuncs/region.c | 15 ++++++++----- libvips/iofuncs/type.c | 37 ++++++++++++------------------- 17 files changed, 56 insertions(+), 51 deletions(-) diff --git a/doc/reference/extending.xml b/doc/reference/extending.xml index 24b4940d..39ebf79a 100644 --- a/doc/reference/extending.xml +++ b/doc/reference/extending.xml @@ -364,6 +364,10 @@ if( negative( in, &out, "image_max", 128, NULL ) ) #VipsRect in _generate(). + + Make zero-copy operations, like vips_insert(), with vips_region_region(). + + diff --git a/doc/reference/using-C.xml b/doc/reference/using-C.xml index bd5d2548..5beb21ac 100644 --- a/doc/reference/using-C.xml +++ b/doc/reference/using-C.xml @@ -24,14 +24,14 @@ - When your program starts, use vips_init() to set up + When your program starts, use VIPS_INIT() to set up the VIPS library. You should pass it the name of your program, usually argv[0]. Use vips_shutdown() when you exit. - 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. @@ -73,6 +73,13 @@ C-style memory array. See vips_image_write_to_file() and friends. + + 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 extending + for an introduxction to writing your own operations. + + VIPS keeps a log of error message, see VIPS Error 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" ); diff --git a/libvips/arithmetic/add.c b/libvips/arithmetic/add.c index cc84a8f0..16a1a45a 100644 --- a/libvips/arithmetic/add.c +++ b/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 - * arithmetic), then the + * arithmetic), then the * following table is used to determine the output type: * * diff --git a/libvips/arithmetic/boolean.c b/libvips/arithmetic/boolean.c index 4fab4f12..9c749c83 100644 --- a/libvips/arithmetic/boolean.c +++ b/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 - * arithmetic). + * arithmetic). * * See also: vips_boolean_const(). * diff --git a/libvips/arithmetic/divide.c b/libvips/arithmetic/divide.c index b9ba7532..6242f53f 100644 --- a/libvips/arithmetic/divide.c +++ b/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 - * arithmetic), then the + * arithmetic), then the * following table is used to determine the output type: * *
diff --git a/libvips/arithmetic/math2.c b/libvips/arithmetic/math2.c index 740ea82f..6bc36093 100644 --- a/libvips/arithmetic/math2.c +++ b/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 - * arithmetic), and that format is the + * arithmetic), and that format is the * result type. * * See also: vips_math2_const(). diff --git a/libvips/arithmetic/multiply.c b/libvips/arithmetic/multiply.c index e3cbd730..e0b78ffd 100644 --- a/libvips/arithmetic/multiply.c +++ b/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 - * arithmetic), then the + * arithmetic), then the * following table is used to determine the output type: * *
diff --git a/libvips/arithmetic/relational.c b/libvips/arithmetic/relational.c index c12672d7..d9c78a04 100644 --- a/libvips/arithmetic/relational.c +++ b/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 - * arithmetic). + * arithmetic). * * 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 diff --git a/libvips/arithmetic/remainder.c b/libvips/arithmetic/remainder.c index 3abae74c..b208d621 100644 --- a/libvips/arithmetic/remainder.c +++ b/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 - * arithmetic), and that format is the + * arithmetic), and that format is the * result type. * * See also: vips_remainder_const(), vips_divide(), vips_round(). diff --git a/libvips/arithmetic/subtract.c b/libvips/arithmetic/subtract.c index 16ece78a..bf881baf 100644 --- a/libvips/arithmetic/subtract.c +++ b/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 - * arithmetic), then the + * arithmetic), then the * following table is used to determine the output type: * *
diff --git a/libvips/arithmetic/sum.c b/libvips/arithmetic/sum.c index 47e59097..0572ff44 100644 --- a/libvips/arithmetic/sum.c +++ b/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 - * arithmetic), then the + * arithmetic), then the * following table is used to determine the output type: * *
diff --git a/libvips/include/vips/internal.h b/libvips/include/vips/internal.h index ae39e7b7..71d9c485 100644 --- a/libvips/include/vips/internal.h +++ b/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 * ); diff --git a/libvips/include/vips/threadpool.h b/libvips/include/vips/threadpool.h index 46dd1e4e..236e5495 100644 --- a/libvips/include/vips/threadpool.h +++ b/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 ); diff --git a/libvips/include/vips/type.h b/libvips/include/vips/type.h index 83a5095e..5ec3278f 100644 --- a/libvips/include/vips/type.h +++ b/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*/ diff --git a/libvips/iofuncs/object.c b/libvips/iofuncs/object.c index 59ccb348..80f6f5da 100644 --- a/libvips/iofuncs/object.c +++ b/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. diff --git a/libvips/iofuncs/region.c b/libvips/iofuncs/region.c index 42152971..fdcd7656 100644 --- a/libvips/iofuncs/region.c +++ b/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. diff --git a/libvips/iofuncs/type.c b/libvips/iofuncs/type.c index af7ff785..8206dd71 100644 --- a/libvips/iofuncs/type.c +++ b/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: header, - * @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(). *