diff --git a/ChangeLog b/ChangeLog index 096b329c..80f84de1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -7,6 +7,7 @@ - more doc fixes - fix similarity rotate+scale, thanks Topochicho - fix 16-bit PNG save, thanks John +- fix dzsave date on Windows, thanks John 25/7/14 started 7.40.5 - fix a race in im_maxpos_avg() diff --git a/TODO b/TODO index dcc74eb6..29ee2780 100644 --- a/TODO +++ b/TODO @@ -1,18 +1,17 @@ - can we pick the vipsthumbnail int shrink factor more intelligently? +- vips_resize() should use vipsthumbnail's block/cache/affine/sharpen chain + - vips_object_unref_outputs() needs docs ... bindings will need it - rewrite im_conv() etc. as vips_conv() finally finish --disable-deprecated option - - - -- vips_init() has a deprecation warning, bizarre - -- vips_affine() for simple resize is slow at the command-line, since it has to - be non-seq ... make a seq version that can only up/down size +- vips_object_unref_outputs() needs docs ... bindings will need it + +- where should we explain VIPS_IMAGE_ADDR(), VIPS_REGION_ADDR(), + vips_region_region() etc.? 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/deprecated/wrapvips7.c b/libvips/deprecated/wrapvips7.c index bcb15c91..f30d541f 100644 --- a/libvips/deprecated/wrapvips7.c +++ b/libvips/deprecated/wrapvips7.c @@ -36,7 +36,7 @@ TODO: - masks would be hard, vips8 won't really have these - - keep for testing, mostly ... iofuncs/init.c has a commeted-out + - keep for testing, mostly ... iofuncs/init.c has a commented-out call to init this thing */ diff --git a/libvips/foreign/dzsave.c b/libvips/foreign/dzsave.c index 65078e77..568ed723 100644 --- a/libvips/foreign/dzsave.c +++ b/libvips/foreign/dzsave.c @@ -45,6 +45,8 @@ * 25/6/14 * - stop on zip write >4gb, thanks bgilbert * - save metadata, see https://github.com/jcupitt/libvips/issues/137 + * 18/8/14 + * - use g_ date funcs, helps Windows */ /* @@ -809,17 +811,13 @@ write_vips_meta( VipsForeignSaveDz *dz ) { VipsObjectClass *class = VIPS_OBJECT_GET_CLASS( dz ); - time_t now; - char time_string[50]; xmlDoc *doc; + GTimeVal now; + char *date; char *dump; int dump_size; GsfOutput *out; - time( &now ); - strftime( time_string, sizeof( time_string ), - "%FT%TZ", gmtime( &now ) ); - if( !(doc = xmlNewDoc( (xmlChar *) "1.0" )) ) { vips_error( class->nickname, "%s", _( "xml save error" ) ); return( -1 ); @@ -830,14 +828,19 @@ write_vips_meta( VipsForeignSaveDz *dz ) xmlFreeDoc( doc ); return( -1 ); } + + g_get_current_time( &now ); + date = g_time_val_to_iso8601( &now ); if( set_prop( dz, doc->children, "xmlns", "http://www.vips.ecs.soton.ac.uk/dzsave" ) || - set_prop( dz, doc->children, "date", time_string ) || + set_prop( dz, doc->children, "date", date ) || set_prop( dz, doc->children, "version", VIPS_VERSION ) || write_vips_properties( dz, doc->children ) ) { + g_free( date ); xmlFreeDoc( doc ); return( -1 ); } + g_free( date ); xmlDocDumpFormatMemory( doc, (xmlChar **) &dump, &dump_size, 1 ); if( !dump ) { diff --git a/libvips/include/vips/generate.h b/libvips/include/vips/generate.h index f7af6884..ed81c89d 100644 --- a/libvips/include/vips/generate.h +++ b/libvips/include/vips/generate.h @@ -56,10 +56,9 @@ typedef void (*VipsSinkNotify)( VipsImage *im, VipsRect *rect, void *a ); int vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask, int tile_width, int tile_height, int max_tiles, int priority, - VipsSinkNotify notify, void *a ); + VipsSinkNotify notify_fn, void *a ); int vips_sink_memory( VipsImage *im ); -int vips_sink_memory2( VipsImage *image ); void *vips_start_one( VipsImage *out, void *a, void *b ); int vips_stop_one( void *seq, void *a, void *b ); diff --git a/libvips/include/vips/internal.h b/libvips/include/vips/internal.h index 5ec1a5b1..317dc1d1 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/generate.c b/libvips/iofuncs/generate.c index f23dccc1..e9467ce9 100644 --- a/libvips/iofuncs/generate.c +++ b/libvips/iofuncs/generate.c @@ -112,12 +112,12 @@ * SECTION: generate * @short_description: calculate pixels and pixel buffers * @stability: Stable - * @see_also: image, - * region + * @see_also: VipsImage, + * VipsRegion * @include: vips/vips.h * - * These functions let you generate regions of pixels in an image - * processing operation, and ask for regions of image to be calculated. + * These functions let you attach generate functions to images + * and ask for regions of images to be calculated. */ /* Max number of images we can handle. @@ -349,7 +349,7 @@ vips__demand_hint_array( VipsImage *image, * @image prefers to supply pixels according to @hint. * * Operations can set demand hints, that is, hints to the VIPS IO system about - * the type of region geometry this operation works best with. For example, + * the type of region geometry they work best with. For example, * operations which transform coordinates will usually work best with * %VIPS_DEMAND_STYLE_SMALLTILE, operations which work on local windows of * pixels will like %VIPS_DEMAND_STYLE_FATSTRIP. @@ -642,13 +642,14 @@ write_vips( VipsRegion *region, VipsRect *area, void *a, void *b ) * * Generates an image. The action depends on the image type. * - * For images opened with "p", vips_image_generate() just attaches the - * start/generate/stop callbacks and returns. + * For images created with vips_image_new(), vips_image_generate() just + * attaches the start/generate/stop callbacks and returns. * - * For "t" images, memory is allocated for the whole image and it is entirely - * generated using vips_sink(). + * For images created with vips_image_new_memory(), memory is allocated for + * the whole image and it is entirely generated using vips_sink_memory(). * - * For "w" images, memory for a few scanlines is allocated and + * For images created with vips_image_new_temp_file() and friends, memory for + * a few scanlines is allocated and * vips_sink_disc() used to generate the image in small chunks. As each * chunk is generated, it is written to disc. * diff --git a/libvips/iofuncs/header.c b/libvips/iofuncs/header.c index 99bdcf87..197865cc 100644 --- a/libvips/iofuncs/header.c +++ b/libvips/iofuncs/header.c @@ -71,41 +71,22 @@ * SECTION: header * @short_description: get, set and walk image headers * @stability: Stable - * @see_also: meta, - * check + * @see_also: type * @include: vips/vips.h * * These functions let you get at image header data (including metadata) in a - * uniform way. They are handy for language bindings but less useful for C - * users. + * uniform way. * - * They first search the - * VIPS header - * fields (see image), then search for - * a metadata field of that name (see - * meta). * Use vips_image_get_typeof() to test for the * existance and #GType * of a header field. * - * See meta - * for a set of functions for adding new metadata to an image. - */ - -/** - * SECTION: meta - * @short_description: get and set image metadata - * @stability: Stable - * @see_also: header - * @include: vips/vips.h - * - * You can attach arbitrary metadata to images. VipsMetadata is copied as images + * You can attach arbitrary metadata to images. Metadata is copied as images * are processed, so all images which used this image as input, directly or * indirectly, will have this same bit of metadata attached to them. Copying * is implemented with reference-counted pointers, so it is efficient, even for * large items of data. This does however mean that metadata items need to be - * immutable. VipsMetadata - * is handy for things like ICC profiles or EXIF data. + * immutable. Metadata is handy for things like ICC profiles or EXIF data. * * Various convenience functions (eg. vips_image_set_int()) let you easily * attach @@ -120,13 +101,14 @@ * If you save an image in VIPS format, all metadata (with a restriction, see * below) is automatically saved for you in a block of XML at the end of the * file. When you load a VIPS image, the metadata is restored. You can use the - * 'edvips' command-line tool to extract or replace this block of XML. + * `vipsedit` command-line tool to extract or replace this block of XML. * - * VIPS metadata is based on GValue. See the docs for that system if you want + * VIPS metadata is based on %GValue. See the docs for that system if you want * to do fancy stuff such as defining a new metadata type. - * VIPS defines a new GValue called "vips_save_string", a variety of string. If - * your GValue can be transformed to vips_save_string, it will be saved and - * loaded to and from VIPS files for you. + * VIPS defines a new %GValue called `vips_save_string`, a variety of string, + * see vips_value_set_save_string(). + * If your %GValue can be transformed to `vips_save_string`, it will be + * saved and loaded to and from VIPS files for you. * * VIPS provides a couple of base classes which implement * reference-counted areas of memory. If you base your metadata on one of @@ -201,7 +183,11 @@ const guint64 vips__image_sizeof_bandformat[] = { 2 * sizeof( double ) /* VIPS_FORMAT_DPCOMPLEX */ }; -/* Return number of bytes for a band format, or -1 on error. +/** + * vips_format_sizeof: + * @format: format type + * + * Returns: number of bytes for a band format, or -1 on error. */ guint64 vips_format_sizeof( VipsBandFormat format ) @@ -335,38 +321,69 @@ meta_init( VipsImage *im ) } } +/** + * vips_image_get_width: + * @image: image to get from + * + * Returns: the number of pixels across the image. + */ int vips_image_get_width( const VipsImage *image ) { return( image->Xsize ); } +/** + * vips_image_get_height: + * @image: image to get from + * + * Returns: the number of pixels down the image. + */ int vips_image_get_height( const VipsImage *image ) { return( image->Ysize ); } +/** + * vips_image_get_bands: + * @image: image to get from + * + * Returns: the number of bands (channels) in the image. + */ int vips_image_get_bands( const VipsImage *image ) { return( image->Bands ); } +/** + * vips_image_get_format: + * @image: image to get from + * + * Returns: the format of each band element. + */ VipsBandFormat vips_image_get_format( const VipsImage *image ) { return( image->BandFmt ); } +/** + * vips_image_get_coding: + * @image: image to get from + * + * Returns: the image coding + */ VipsCoding vips_image_get_coding( const VipsImage *image ) { return( image->Coding ); } -/* vips_image_get_interpretation: - * @image: image to guess for +/** + * vips_image_get_interpretation: + * @image: image to get from * * Return the #VipsInterpretation set in the image header. * Use vips_image_guess_interpretation() if you want a sanity-checked value. @@ -400,11 +417,12 @@ vips_image_default_interpretation( const VipsImage *image ) return( VIPS_INTERPRETATION_MULTIBAND ); } -/* vips_image_guess_interpretation: +/** + * vips_image_guess_interpretation: * @image: image to guess for * - * Return the #VipsInterpretation for an image, guessing a default value if - * the set value looks wrong. + * Return the #VipsInterpretation for an image, guessing a sane value if + * the set value looks crazy. * * Returns: a sensible #VipsInterpretation for the image. */ @@ -510,42 +528,90 @@ vips_image_guess_interpretation( const VipsImage *image ) return( vips_image_default_interpretation( image ) ); } +/** + * vips_image_get_xres: + * @image: image to get from + * + * Returns: the horizontal image resolution in pixels per millimeter. + */ double vips_image_get_xres( const VipsImage *image ) { return( image->Xres ); } +/** + * vips_image_get_yres: + * @image: image to get from + * + * Returns: the vertical image resolution in pixels per millimeter. + */ double vips_image_get_yres( const VipsImage *image ) { return( image->Yres ); } +/** + * vips_image_get_xoffset: + * @image: image to get from + * + * Returns: the horizontal position of the image origin, in pixels. + */ int vips_image_get_xoffset( const VipsImage *image ) { return( image->Xoffset ); } +/** + * vips_image_get_yoffset: + * @image: image to get from + * + * Returns: the vertical position of the image origin, in pixels. + */ int vips_image_get_yoffset( const VipsImage *image ) { return( image->Yoffset ); } +/** + * vips_image_get_filename: + * @image: image to get from + * + * Returns: the name of the file the image was loaded from. + */ const char * vips_image_get_filename( const VipsImage *image ) { return( image->filename ); } +/** + * vips_image_get_mode: + * @image: image to get from + * + * Image modes are things like `"t"`, meaning a memory buffer, and `"p"` + * meaning a delayed computation. + * + * Returns: the image mode. + */ const char * vips_image_get_mode( const VipsImage *image ) { return( image->mode ); } +/** + * vips_image_get_scale: + * @image: image to get from + * + * Matrix images can have an optional `scale` field for use by integer + * convolution. + * + * Returns: the scale. + */ double vips_image_get_scale( const VipsImage *array ) { @@ -558,6 +624,15 @@ vips_image_get_scale( const VipsImage *array ) return( scale ); } +/** + * vips_image_get_offset: + * @image: image to get from + * + * Matrix images can have an optional `offset` field for use by integer + * convolution. + * + * Returns: the offset. + */ double vips_image_get_offset( const VipsImage *array ) { @@ -571,7 +646,7 @@ vips_image_get_offset( const VipsImage *array ) } /** - * vips_image_get_data: (skip) + * vips_image_get_data: * @image: image to get data for * * Return a pointer to the image's pixel data, if possible. This can involve @@ -607,7 +682,7 @@ vips_image_get_data( VipsImage *image ) * Normally you copy the fields from your input images with * vips_image_pipelinev() and then make * any adjustments you need, but if you are creating an image from scratch, - * for example im_black() or im_jpeg2vips(), you do need to set all the + * for example vips_black() or vips_jpegload(), you do need to set all the * fields yourself. * * See also: vips_image_pipelinev(). @@ -724,24 +799,22 @@ vips__image_copy_fields_array( VipsImage *out, VipsImage *in[] ) * vips_image_set: * @image: image to set the metadata on * @field: the name to give the metadata - * @value: the GValue to copy into the image + * @value: the %GValue to copy into the image * * Set a piece of metadata on @image. Any old metadata with that name is - * destroyed. The GValue is copied into the image, so you need to unset the + * destroyed. The %GValue is copied into the image, so you need to unset the * value when you're done with it. * * For example, to set an integer on an image (though you would use the - * convenience function vips_image_set_int() in practice), you would need: + * convenience function vips_image_set_int() in practice), you would do: * * |[ * GValue value = { 0 }; * - * g_value_init( &value, G_TYPE_INT ); - * g_value_set_int( &value, 42 ); - * vips_image_set( image, field, &value ); - * g_value_unset( &value ); - * - * return( 0 ); + * g_value_init (&value, G_TYPE_INT); + * g_value_set_int (&value, 42); + * vips_image_set (image, field, &value); + * g_value_unset (&value); * ]| * * See also: vips_image_get(). @@ -764,15 +837,14 @@ vips_image_set( VipsImage *image, const char *field, GValue *value ) * vips_image_get: * @image: image to get the field from from * @field: the name to give the metadata - * @value_copy: the GValue is copied into this + * @value_copy: the %GValue is copied into this * * Fill @value_copy with a copy of the header field. @value_copy must be zeroed * but uninitialised. * * This will return -1 and add a message to the error buffer if the field * does not exist. Use vips_image_get_typeof() to test for the - * existence - * of a field first if you are not certain it will be there. + * existence of a field first if you are not certain it will be there. * * For example, to read a double from an image (though of course you would use * vips_image_get_double() in practice): @@ -781,22 +853,20 @@ vips_image_set( VipsImage *image, const char *field, GValue *value ) * GValue value = { 0 }; * double d; * - * if( vips_image_get( image, field, &value ) ) - * return( -1 ); + * if (vips_image_get (image, field, &value)) + * return -1; * - * if( G_VALUE_TYPE( &value ) != G_TYPE_DOUBLE ) { + * if (G_VALUE_TYPE (&value) != G_TYPE_DOUBLE) { * vips_error( "mydomain", - * _( "field \"%s\" is of type %s, not double" ), + * _("field \"%s\" is of type %s, not double"), * field, - * g_type_name( G_VALUE_TYPE( &value ) ) ); - * g_value_unset( &value ); - * return( -1 ); + * g_type_name (G_VALUE_TYPE (&value))); + * g_value_unset (&value); + * return -1; * } * - * d = g_value_get_double( &value ); - * g_value_unset( &value ); - * - * return( 0 ); + * d = g_value_get_double (&value); + * g_value_unset (&value); * ]| * * See also: vips_image_get_typeof(), vips_image_get_double(). @@ -875,12 +945,12 @@ vips_image_get( const VipsImage *image, const char *field, GValue *value_copy ) * @image: image to test * @field: the name to search for * - * Read the GType for a header field. Returns zero if there is no + * Read the %GType for a header field. Returns zero if there is no * field of that name. * * See also: vips_image_get(). * - * Returns: the GType of the field, or zero if there is no + * Returns: the %GType of the field, or zero if there is no * field of that name. */ GType @@ -945,7 +1015,7 @@ vips_image_map_fn( VipsMeta *meta, VipsImageMapFn fn, void *a ) } /** - * vips_image_map: (skip) + * vips_image_map: * @image: image to map over * @fn: function to call for each header field * @a: user data for function @@ -1101,7 +1171,7 @@ vips_image_set_blob( VipsImage *image, const char *field, } /** - * vips_image_get_blob: (skip) + * vips_image_get_blob: * @image: image to get the metadata from * @field: metadata name * @data: pointer to area of memory @@ -1333,7 +1403,7 @@ vips_image_set_string( VipsImage *image, const char *field, const char *str ) * vips_image_get_as_string: * @image: image to get the header field from * @field: field name - * @out: return field value as string + * @out: (transfer full): return field value as string * * Gets @out from @im under the name @field. * This function will read any field, returning it as a printable string. @@ -1378,7 +1448,7 @@ vips_image_get_as_string( const VipsImage *image, * vips_image_history_printf: * @image: add history line to this image * @format: printf() format string - * @Varargs: arguments to format string + * @...: arguments to format string * * Add a line to the image history. The @format and arguments are expanded, the * date and time is appended prefixed with a hash character, and the whole @@ -1387,15 +1457,14 @@ vips_image_get_as_string( const VipsImage *image, * For example: * * |[ - * vips_image_history_printf( image, "vips im_invert %s %s", - * in->filename, out->filename ); + * vips_image_history_printf (image, "vips invert %s %s", + * in->filename, out->filename); * ]| * * Might add the string * * |[ - * "vips im_invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35 - * 2009\n" + * "vips invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35 2009\n" * ]| * * VIPS operations don't add history lines for you because a single action at @@ -1486,7 +1555,7 @@ vips_image_history_args( VipsImage *image, * * See also: vips_image_history_printf(). * - * Returns: The history of @image as a C string. Do not free! + * Returns: (transfer none): The history of @image as a C string. Do not free! */ const char * vips_image_get_history( VipsImage *image ) diff --git a/libvips/iofuncs/image.c b/libvips/iofuncs/image.c index 4ce62305..02050ae8 100644 --- a/libvips/iofuncs/image.c +++ b/libvips/iofuncs/image.c @@ -58,7 +58,10 @@ * SECTION: image * @short_description: the VIPS image class * @stability: Stable - * @see_also: region + * @see_also: header + * VipsRegion + * generate + * VipsOperation * @include: vips/vips.h * * The image class and associated types and macros. @@ -78,7 +81,7 @@ * height and bands. Each dimension can be up to 2 ** 31 pixels (or band * elements). An image has a format, meaning the machine number type used * to represent each value. VIPS supports 10 formats, from 8-bit unsigned - * integer up to 128-bit double complex, see vips_image_get_format().. + * integer up to 128-bit double complex, see vips_image_get_format(). * * In VIPS, images are uninterpreted arrays, meaning that from the point of * view of most operations, they are just large collections of numbers. @@ -96,7 +99,7 @@ * VIPS has a feature to help (a little) with this: it sets a * #VipsInterpretation hint for each image (see * vips_image_get_interpretation()); a hint which says how pixels should - * probably be interpreted. For example, vips_Lab2XYZ() will set the + * be interpreted. For example, vips_Lab2XYZ() will set the * interpretation of the output image to #VIPS_INTERPRETATION_XYZ. A * few utility operations will also use interpretation as a guide. For * example, you can give vips_colourspace() an input image and a desired @@ -108,6 +111,11 @@ * to formatted memory buffers (with vips_image_write_to_buffer()) and to * C-style memory arrays (with vips_image_write_to_memory(). * + * You can also write image to other images. Create, for example, a temporary + * disc image with vips_image_new_temp_file(), then write your image to that + * with vips_image_write(). You can create several other types of image and + * write to them, see vips_image_new_memory(), for example. + * * See operation for an introduction to * running operations on images, see header for getting and setting image @@ -152,8 +160,8 @@ * @VIPS_DEMAND_STYLE_THINSTRIP: demand in thin (typically 1 pixel high) strips * @VIPS_DEMAND_STYLE_ANY: demand geometry does not matter * - * See vips_image_pipelinev(). Operations can hint to the VIPS image IO system about - * the kind of demand geometry they prefer. + * See vips_image_pipelinev(). Operations can hint to the VIPS image IO + * system about the kind of demand geometry they prefer. * * These demand styles are given below in order of increasing * restrictiveness. When demanding output from a pipeline, @@ -213,7 +221,7 @@ * of VIPS to help them show images to the user in a meaningful way. * Operations do not use these values to decide their action. * - * The gaps in the numbering are historical and must be maintained. Allocate + * The gaps in numbering are historical and must be maintained. Allocate * new numbers from the end. */ @@ -233,7 +241,7 @@ * * The format used for each band element. * - * Each corresponnds to a native C type for the current machine. For example, + * Each corresponds to a native C type for the current machine. For example, * #VIPS_FORMAT_USHORT is unsigned short. */ @@ -322,9 +330,9 @@ * * If VIPS_DEBUG is defined, you get a version that checks bounds for you. * - * See also: VIPS_REGION_ADDR(). + * See also: vips_image_wio_input(), vips_image_inplace(), VIPS_REGION_ADDR(). * - * Returns: The address of pixel (x,y) in the image. + * Returns: The address of pixel (@X,@Y) in @I. */ /** @@ -341,9 +349,9 @@ * If VIPS_DEBUG is defined, you get a version that checks bounds and image * type for you. * - * See also: VIPS_IMAGE_ADDR(). + * See also: vips_image_wio_input(), vips_image_inplace(), vips_check_matrix(). * - * Returns: The address of pixel (x,y) in the image. + * Returns: The address of pixel (@X,@Y) in @I. */ /* Our signals. @@ -1245,8 +1253,8 @@ vips_image_class_init( VipsImageClass *class ) * 128 area of pixels) during image computation. * * You can use this signal to update user-interfaces with progress - * feedback. Beware of updating too frequently: there will usually - * need to be some mechanism to limit update frequency. + * feedback. Beware of updating too frequently: you will usually + * need some throttling mechanism. * * Use vips_image_set_progress() to turn on progress reporting for an * image. @@ -1285,9 +1293,10 @@ vips_image_class_init( VipsImageClass *class ) * @image: the image that was calculated * @result: set to non-zero to indicate error * - * The ::written signal is emitted when an image is written to. It is - * used by things like vips_image_new_mode("x.jpg", "w") to do the - * final write of @image. + * The ::written signal is emitted just after an image has been + * written to. It is + * used by vips to implement things like write to foreign file + * formats. */ vips_image_signals[SIG_WRITTEN] = g_signal_new( "written", G_TYPE_FROM_CLASS( class ), @@ -1662,8 +1671,9 @@ vips_image_temp_name( void ) * If you write to one of these images, vips will just attach some callbacks, * no pixels will be generated. * - * It is the equivalent of - * vips_image_new_mode() with @mode "p". + * Write pixels to an image with vips_image_generate() or + * vips_image_write_line(). Write a whole image to another image with + * vips_image_write(). * * Returns: the new #VipsImage, or %NULL on error. */ @@ -1716,10 +1726,6 @@ vips_image_new_mode( const char *filename, const char *mode ) * vips_image_new_memory() creates a new #VipsImage which, when written to, will * create a memory image. * - * It is a convenience function for - * vips_image_new_mode() with @filename set by vips_image_temp_name() and - * @mode "t". - * * See also: vips_image_new(). * * Returns: the new #VipsImage, or %NULL on error. @@ -2080,7 +2086,7 @@ vips_image_new_matrixv( int width, int height, ... ) * * Sets the delete_on_close flag for the image. If this flag is set, when * @image is finalized, the filename held in @image->filename at the time of - * this call is unlinked. + * this call is deleted. * * This function is clearly extremely dangerous, use with great caution. * @@ -2102,8 +2108,9 @@ vips_image_set_delete_on_close( VipsImage *image, gboolean delete_on_close ) * vips_image_new_temp_file: * @format: format of file * - * Make a "w" disc #VipsImage which will be automatically unlinked when it is - * destroyed. @format is something like "%s.v" for a vips file. + * Make a #VipsImage which, when written to, will create a temporary file on + * disc. The file will be automatically deleted when the image is destroyed. + * @format is something like "%s.v" for a vips file. * * The file is created in the temporary directory. This is set with the * environment variable TMPDIR. If this is not set, then on Unix systems, vips @@ -2113,6 +2120,8 @@ vips_image_set_delete_on_close( VipsImage *image, gboolean delete_on_close ) * vips uses g_mkstemp() to make the temporary filename. They generally look * something like "vips-12-EJKJFGH.v". * + * See also: vips_image_new(). + * * Returns: the new #VipsImage, or %NULL on error. */ VipsImage * @@ -2292,10 +2301,10 @@ vips_image_write_to_buffer( VipsImage *in, /** * vips_image_write_to_memory: * @in: image to write - * @buf: return buffer start here + * @buf: (transfer full): return buffer start here * @len: return buffer length here * - * Writes @in to memory as a simple, unformatted array. + * Writes @in to memory as a simple, unformatted C-style array. * * The caller is responsible for freeing memory. * @@ -2381,7 +2390,7 @@ vips_image_decode( VipsImage *in, VipsImage **out ) * @bands: predict bands here * @format: predict format here * - * We often need to know what an image will decode to without actuaklly + * We often need to know what an image will decode to without actually * decoding it, for example, in arg checking. * * See also: vips_image_decode(). @@ -2514,7 +2523,7 @@ vips_image_ispartial( VipsImage *image ) * * Normally this function is called for you by vips_image_generate() or * vips_image_write_line(). You will need to call it yourself if you plan to - * write directly to the ->data member of a "t" image. + * write directly to the ->data member of a memory image. * * Returns: 0 on success, or -1 on error. */ diff --git a/libvips/iofuncs/init.c b/libvips/iofuncs/init.c index c2419795..bb6e8fe8 100644 --- a/libvips/iofuncs/init.c +++ b/libvips/iofuncs/init.c @@ -811,7 +811,7 @@ guess_prefix( const char *argv0, const char *name ) * * See also: vips_guess_libdir(). * - * Returns: the install prefix as a static string, do not free. + * Returns: (transfer none): the install prefix as a static string, do not free. */ const char * vips_guess_prefix( const char *argv0, const char *env_name ) @@ -876,7 +876,7 @@ vips_guess_prefix( const char *argv0, const char *env_name ) * * See also: vips_guess_prefix(). * - * Returns: the libdir as a static string, do not free. + * Returns: (transfer none): the libdir as a static string, do not free. */ const char * vips_guess_libdir( const char *argv0, const char *env_name ) 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/sink.c b/libvips/iofuncs/sink.c index ca9bca14..e950ffdf 100644 --- a/libvips/iofuncs/sink.c +++ b/libvips/iofuncs/sink.c @@ -335,8 +335,9 @@ vips_sink_base_progress( void *a ) * @a: user data * @b: user data * - * Loops over an image. @generate is called for every pixel in the image, with - * the @reg argument being a region of pixels for processing. + * Loops over an image. @generate_fn is called for every + * pixel in the image, with + * the @reg argument being a region of calculated pixels. * * Each set of pixels is @tile_width by @tile_height pixels (less at the * image edges). This is handy for things like writing a tiled TIFF image, @@ -398,9 +399,10 @@ vips_sink_tile( VipsImage *im, * @a: user data * @b: user data * - * Loops over an image. @generate is called for every pixel in the image, with - * the @reg argument being a region of pixels for processing. vips_sink() is - * used to implement operations like #VipsAvg which have no image output. + * Loops over an image. @generate_fn is called for every pixel in + * the image, with + * the @reg argument being a region of calculated pixels. vips_sink() is + * used to implement operations like vips_avg() which have no image output. * * Each set of pixels is sized according to the requirements of the image * pipeline that generated @im. diff --git a/libvips/iofuncs/sinkdisc.c b/libvips/iofuncs/sinkdisc.c index 443b7128..8c1fd067 100644 --- a/libvips/iofuncs/sinkdisc.c +++ b/libvips/iofuncs/sinkdisc.c @@ -451,7 +451,7 @@ write_free( Write *write ) * @a: client data * * The function should write the pixels in @area from @region. @a is the - * value passed into vips_discsink(). + * value passed into vips_sink_disc(). * * See also: vips_sink_disc(). * @@ -472,7 +472,8 @@ write_free( Write *write ) * sections in top-to-bottom order, and there are never any gaps. * * This operation is handy for making image sinks which output to things like - * disc files. + * disc files. Things like vips_jpegsave(), for example, use this to write + * images to files in JPEG format. * * See also: vips_concurrency_set(). * diff --git a/libvips/iofuncs/sinkmemory.c b/libvips/iofuncs/sinkmemory.c index fca55963..97bf815c 100644 --- a/libvips/iofuncs/sinkmemory.c +++ b/libvips/iofuncs/sinkmemory.c @@ -313,10 +313,10 @@ sink_memory_init( SinkMemory *memory, VipsImage *image ) * vips_sink_memory: * @im: generate this image to memory * - * Loops over an image, generating it to a memory buffer attached to the - * image. + * Loops over @im, generating it to a memory buffer attached to @im. It is + * used by vips to implement writing to a memory buffer. * - * See also: vips_sink(), vips_get_tile_size(). + * See also: vips_sink(), vips_get_tile_size(), vips_image_new_memory(). * * Returns: 0 on success, or -1 on error. */ diff --git a/libvips/iofuncs/sinkscreen.c b/libvips/iofuncs/sinkscreen.c index 1c49efd9..29e4c512 100644 --- a/libvips/iofuncs/sinkscreen.c +++ b/libvips/iofuncs/sinkscreen.c @@ -1047,11 +1047,11 @@ mask_fill( VipsRegion *out, void *seq, void *a, void *b, gboolean *stop ) * @tile_height: tile height * @max_tiles: maximum tiles to cache * @priority: rendering priority - * @notify: pixels are ready notification callback + * @notify_fn: pixels are ready notification callback * @a: client data for callback * * This operation renders @in in the background, making pixels available on - * @out as they are calculated. The @notify callback is run every time a new + * @out as they are calculated. The @notify_fn callback is run every time a new * set of pixels are available. Calculated pixels are kept in a cache with * tiles sized @tile_width by @tile_height pixels and with at most @max_tiles * tiles. @@ -1071,15 +1071,15 @@ mask_fill( VipsRegion *out, void *seq, void *a, void *b, gboolean *stop ) * currently in cache for that #VipsRect (check @mask to see which parts of the * #VipsRect are valid). Any pixels in the #VipsRect which are not in * cache are added - * to a queue, and the @notify callback will trigger when those pixels are + * to a queue, and the @notify_fn callback will trigger when those pixels are * ready. * - * The @notify callback is run from one of the background threads. In the + * The @notify_fn callback is run from one of the background threads. In the * callback * you need to somehow send a message to the main thread that the pixels are * ready. In a glib-based application, this is easily done with g_idle_add(). * - * If @notify is %NULL then vips_sink_screen() runs synchronously. + * If @notify_fn is %NULL then vips_sink_screen() runs synchronously. * vips_region_prepare() on @out will always block until the pixels have been * calculated. * @@ -1093,7 +1093,7 @@ vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask, int tile_width, int tile_height, int max_tiles, int priority, - VipsSinkNotify notify, void *a ) + VipsSinkNotify notify_fn, void *a ) { Render *render; @@ -1125,7 +1125,7 @@ vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask, } if( !(render = render_new( in, out, mask, - tile_width, tile_height, max_tiles, priority, notify, a )) ) + tile_width, tile_height, max_tiles, priority, notify_fn, a )) ) return( -1 ); VIPS_DEBUG_MSG( "vips_sink_screen: max = %d, %p\n", max_tiles, render ); diff --git a/libvips/iofuncs/type.c b/libvips/iofuncs/type.c index 1e9c6f34..8206dd71 100644 --- a/libvips/iofuncs/type.c +++ b/libvips/iofuncs/type.c @@ -59,10 +59,10 @@ * SECTION: type * @short_description: basic types * @stability: Stable - * @see_also: operation + * @see_also: header * @include: vips/vips.h * - * A selection of GType defintions used by VIPS. + * A selection of %GType defintions used by VIPS. */ /* A very simple boxed type for testing. Just an int. @@ -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(). * diff --git a/libvips/iofuncs/vips.c b/libvips/iofuncs/vips.c index ed80b20f..6502f0d6 100644 --- a/libvips/iofuncs/vips.c +++ b/libvips/iofuncs/vips.c @@ -92,7 +92,7 @@ * SECTION: vips * @short_description: startup, shutdown, version * @stability: Stable - * @see_also: operation + * @see_also: VipsOperation * @include: vips/vips.h * * Start VIPS up, shut VIPS down, get version information, relocation.