From af84b3097c29bddd10e0e92f5a0a59185e562b99 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Tue, 19 Aug 2014 16:57:37 +0100 Subject: [PATCH] more docs work --- TODO | 3 +- libvips/deprecated/wrapvips7.c | 2 +- libvips/include/vips/generate.h | 3 +- libvips/iofuncs/generate.c | 21 ++-- libvips/iofuncs/header.c | 209 +++++++++++++++++++++----------- libvips/iofuncs/image.c | 67 +++++----- libvips/iofuncs/init.c | 4 +- libvips/iofuncs/sink.c | 12 +- libvips/iofuncs/sinkdisc.c | 5 +- libvips/iofuncs/sinkmemory.c | 6 +- libvips/iofuncs/sinkscreen.c | 14 +-- libvips/iofuncs/type.c | 4 +- libvips/iofuncs/vips.c | 2 +- 13 files changed, 217 insertions(+), 135 deletions(-) diff --git a/TODO b/TODO index 7a36e5b4..f540d142 100644 --- a/TODO +++ b/TODO @@ -2,7 +2,8 @@ - vips_object_unref_outputs() needs docs ... bindings will need it -- vips_init() has a deprecation warning, bizarre +- where should we explain VIPS_IMAGE_ADDR(), VIPS_REGION_ADDR(), + vips_region_region() etc.? 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/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/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/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..af7ff785 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. 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.