sergiotarxz
/
libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

add callback gtkdoc

This commit is contained in:
John Cupitt 2009-10-02 10:22:16 +00:00
parent af9ea39b6e
commit b6cb3cbcbd
9 changed files with 210 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
ChangeLog
View File

@ -53,6 +53,7 @@
- gtk-doc comments for meta
- gtk-doc comments for header
- im_printlines(), im_debugim() deprecated (use im_vips2csv() instead)
- callback gtkdocs
25/3/09 started 7.18.0
- revised version numbers

1
doc/reference/libvips-docs.sgml.in
View File

@ -19,6 +19,7 @@
<title>Core VIPS API</title>
<xi:include href="xml/image.xml"/>
<xi:include href="xml/header.xml"/>
<xi:include href="xml/callback.xml"/>
<xi:include href="xml/meta.xml"/>
<xi:include href="xml/buf.xml"/>
</chapter>

1
libvips/include/vips/Makefile.am
View File

@ -7,6 +7,7 @@ pkginclude_HEADERS = \
dispatch.h \
format.h \
header.h \
callback.h \
fmask.h \
mosaic.h \
interpolate.h \

56
libvips/include/vips/callback.h Normal file
View File

@ -0,0 +1,56 @@
/* Various callbacks.
*/
/*
Copyright (C) 1991-2005 The National Gallery
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
/*
These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
*/
#ifndef IM_CALLBACK_H
#define IM_CALLBACK_H
#ifdef __cplusplus
extern "C" {
#endif /*__cplusplus*/
/* Also used for eg. im_local() and friends.
*/
typedef int (*im_callback_fn)( void *a, void *b );
int im_add_close_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
int im_add_preclose_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
int im_add_evalstart_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
int im_add_eval_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
int im_add_evalend_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
int im_add_invalidate_callback( IMAGE *im,
im_callback_fn fn, void *a, void *b );
#ifdef __cplusplus
}
#endif /*__cplusplus*/
#endif /*!IM_CALLBACK_H*/

7
libvips/include/vips/proto.h
View File

@ -146,13 +146,6 @@ int im_existsf( const char *name, ... )
__attribute__((format(printf, 1, 2)));
int im_isvips( const char * );
int im_add_close_callback( IMAGE *, im_callback_fn, void *, void * );
int im_add_preclose_callback( IMAGE *, im_callback_fn, void *, void * );
int im_add_evalstart_callback( IMAGE *, im_callback_fn, void *, void * );
int im_add_eval_callback( IMAGE *, im_callback_fn, void *, void * );
int im_add_evalend_callback( IMAGE *, im_callback_fn, void *, void * );
int im_add_invalidate_callback( IMAGE *, im_callback_fn, void *, void * );
void error_exit( const char *, ... )
__attribute__((noreturn, format(printf, 1, 2)));
const char *im_error_buffer( void );

1
libvips/include/vips/util.h
View File

@ -181,7 +181,6 @@ extern "C" {
/* Basic function types.
*/
typedef int (*im_callback_fn)( void *, void * );
typedef void *(*im_construct_fn)( void *, void *, void * );
/* strtok replacement.

1
libvips/include/vips/vips.h
View File

@ -124,6 +124,7 @@ typedef struct im__DOUBLEMASK {
#include <vips/image.h>
#include <vips/almostdeprecated.h>
#include <vips/callback.h>
#include <vips/util.h>
#include <vips/colour.h>
/* #include <vips/vector.h> */

159
libvips/iofuncs/callback.c
View File

@ -54,13 +54,28 @@
#include <dmalloc.h>
#endif /*WITH_DMALLOC*/
/**
* SECTION: callback
* @short_description: image callbacks
* @stability: Stable
* @see_also: <link linkend="libvips-image">image</link>
* @include: vips/vips.h
*
* Images trigger various callbacks at various points in their lifetime. You
* can register callbacks and be notified of various events, such as
* evaluation progress or close.
*
* Callbacks should return 0 for success, or -1 on error, setting an error
* message with im_error().
*/
/* Callback struct. We attach a list of callbacks to images to be invoked when
* the image is closed. These do things like closing previous elements in a
* chain of operations, freeing client data, etc.
*/
typedef struct {
IMAGE *im; /* IMAGE we are attached to */
int (*fn)(); /* callback function */
im_callback_fn fn; /* callback function */
void *a, *b; /* arguments to callback */
} VCallback;
@ -68,7 +83,7 @@ typedef struct {
* im__close(), or by im_generate(), etc. for evalend callbacks.
*/
static int
add_callback( IMAGE *im, GSList **cblist, int (*fn)(), void *a, void *b )
add_callback( IMAGE *im, GSList **cblist, im_callback_fn fn, void *a, void *b )
{
VCallback *cbs;
@ -84,23 +99,81 @@ add_callback( IMAGE *im, GSList **cblist, int (*fn)(), void *a, void *b )
return( 0 );
}
/**
* im_add_close_callback:
* @im: image to attach callback to
* @fn: callback function
* @a: user data 1
* @b: user data 2
*
* Attaches a close callback @fn to @im.
*
* Close callbacks are triggered exactly once when the image has been closed
* and most resources freed, but just before the memory for @im is released.
*
* Close callbacks are a good place to free memory that was need to generate
* @im, delete temporary files and so on. You can close other images and there
* may even be circularity in your close lists.
*
* See also: im_malloc() (implemented with im_add_close_callback()),
* im_add_preclose_callback() (called earlier in the image close process),
* im_free().
*/
int
im_add_close_callback( IMAGE *im, int (*fn)(), void *a, void *b )
im_add_close_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
{
return( add_callback( im, &im->closefns, fn, a, b ) );
}
/**
* im_add_preclose_callback:
* @im: image to attach callback to
* @fn: callback function
* @a: user data 1
* @b: user data 2
*
* Attaches a pre-close callback @fn to @im.
*
* Pre-close callbacks are triggered exactly once just before an image is
* closed. The image is still valid and you can do anything with it, except
* stop close from happening.
*
* Pre-close callbacks are a good place for languae bindings to break as
* association between the language object and the VIPS image.
*/
int
im_add_preclose_callback( IMAGE *im, int (*fn)(), void *a, void *b )
im_add_preclose_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
{
return( add_callback( im, &im->preclosefns, fn, a, b ) );
}
/* Add an eval callback to an IMAGE. You must call this after opening the
* image but before using it as an argument to an operation.
/**
* im_add_eval_callback:
* @im: image to attach callback to
* @fn: callback function
* @a: user data 1
* @b: user data 2
*
* Attaches an eval callback @fn to @im.
*
* Eval callbacks are called during evaluation and are a good place to give
* the user feedback about computation progress. In the eval callback, you may
* look at the #VipsProgress #time member of #IMAGE to get information about
* the number of
* pels processed, elapsed time, and so on.
*
* Eval callbacks are inherited. That is, any images which use your image
* as input will inherit your eval callbacks. As a result, if you add an
* eval callback to an image, you will be notified if any later image uses
* your image for computation.
*
* If a later image adds eval callbacks, then the inheritance is broken,
* and that image will recieve notification instead.
*
* See also: im_add_evalend_callback(), im_add_evalstart_callback().
*/
int
im_add_eval_callback( IMAGE *im, int (*fn)(), void *a, void *b )
im_add_eval_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
{
/* Mark this image as needing progress feedback. im__link_make()
* propogates this value to our children as we build a pipeline.
@ -111,20 +184,86 @@ im_add_eval_callback( IMAGE *im, int (*fn)(), void *a, void *b )
return( add_callback( im, &im->evalfns, fn, a, b ) );
}
/**
* im_add_evalend_callback:
* @im: image to attach callback to
* @fn: callback function
* @a: user data 1
* @b: user data 2
*
* Attaches an eval end callback @fn to @im.
*
* Eval end callbacks are called at the end of evaluation. They are a good
* place to clean up after progress notification or to display some
* diagnostics about computation (eg. an overflow count). They can be called
* many times. Every evalend call is guaranteed to have a matching evalstart,
* but not necessarily any eval calls.
*
* Eval callbacks are inherited. That is, any images which use your image
* as input will inherit your eval callbacks. As a result, if you add an
* eval callback to an image, you will be notified if any later image uses
* your image for computation.
*
* If a later image adds eval callbacks, then the inheritance is broken,
* and that image will recieve notification instead.
*
* See also: im_add_eval_callback(), im_add_evalstart_callback().
*/
int
im_add_evalend_callback( IMAGE *im, int (*fn)(), void *a, void *b )
im_add_evalend_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
{
return( add_callback( im, &im->evalendfns, fn, a, b ) );
}
/**
* im_add_evalstart_callback:
* @im: image to attach callback to
* @fn: callback function
* @a: user data 1
* @b: user data 2
*
* Attaches an eval start callback @fn to @im.
*
* Eval start callbacks are called at the beginning of evaluation. They are a
* good
* place to get ready to give progress notification.
* They can be called
* many times. Every evalend call is guaranteed to have a matching evalstart,
* but not necessarily any eval calls.
*
* Eval callbacks are inherited. That is, any images which use your image
* as input will inherit your eval callbacks. As a result, if you add an
* eval callback to an image, you will be notified if any later image uses
* your image for computation.
*
* If a later image adds eval callbacks, then the inheritance is broken,
* and that image will recieve notification instead.
*
* See also: im_add_eval_callback(), im_add_evalend_callback().
*/
int
im_add_evalstart_callback( IMAGE *im, int (*fn)(), void *a, void *b )
im_add_evalstart_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
{
return( add_callback( im, &im->evalstartfns, fn, a, b ) );
}
/**
* im_add_invalidate_callback:
* @im: image to attach callback to
* @fn: callback function
* @a: user data 1
* @b: user data 2
*
* Attaches an invalidate callback @fn to @im.
*
* Invalidate callbacks are triggered
* when VIPS invalidates the cache on an image. This is useful for
* removing images from other, higher-level caches.
*
* See also: im_invalidate().
*/
int
im_add_invalidate_callback( IMAGE *im, int (*fn)(), void *a, void *b )
im_add_invalidate_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
{
return( add_callback( im, &im->invalidatefns, fn, a, b ) );
}

2
libvips/iofuncs/meta.c
View File

@ -86,7 +86,7 @@
* SECTION: meta
* @short_description: get and set image metadata
* @stability: Stable
* @see_also: header
* @see_also: <link linkend="libvips-header">header</link>
* @include: vips/vips.h
*
* You can attach arbitrary metadata to images. Metadata is copied as images