diff --git a/ChangeLog b/ChangeLog
index 6267298b..786a6bb9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -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
diff --git a/doc/reference/libvips-docs.sgml.in b/doc/reference/libvips-docs.sgml.in
index 74fe29b4..b14df8c6 100644
--- a/doc/reference/libvips-docs.sgml.in
+++ b/doc/reference/libvips-docs.sgml.in
@@ -19,6 +19,7 @@
Core VIPS API
+
diff --git a/libvips/include/vips/Makefile.am b/libvips/include/vips/Makefile.am
index 84111558..21d59ae7 100644
--- a/libvips/include/vips/Makefile.am
+++ b/libvips/include/vips/Makefile.am
@@ -7,6 +7,7 @@ pkginclude_HEADERS = \
dispatch.h \
format.h \
header.h \
+ callback.h \
fmask.h \
mosaic.h \
interpolate.h \
diff --git a/libvips/include/vips/callback.h b/libvips/include/vips/callback.h
new file mode 100644
index 00000000..e130e2d8
--- /dev/null
+++ b/libvips/include/vips/callback.h
@@ -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*/
diff --git a/libvips/include/vips/proto.h b/libvips/include/vips/proto.h
index 1a03fb67..eb9ca278 100644
--- a/libvips/include/vips/proto.h
+++ b/libvips/include/vips/proto.h
@@ -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 );
diff --git a/libvips/include/vips/util.h b/libvips/include/vips/util.h
index b54da355..b711b1db 100644
--- a/libvips/include/vips/util.h
+++ b/libvips/include/vips/util.h
@@ -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.
diff --git a/libvips/include/vips/vips.h b/libvips/include/vips/vips.h
index 315e9bfb..5d29b93a 100644
--- a/libvips/include/vips/vips.h
+++ b/libvips/include/vips/vips.h
@@ -124,6 +124,7 @@ typedef struct im__DOUBLEMASK {
#include
#include
+#include
#include
#include
/* #include */
diff --git a/libvips/iofuncs/callback.c b/libvips/iofuncs/callback.c
index 365118fa..2808fe19 100644
--- a/libvips/iofuncs/callback.c
+++ b/libvips/iofuncs/callback.c
@@ -54,13 +54,28 @@
#include
#endif /*WITH_DMALLOC*/
+/**
+ * SECTION: callback
+ * @short_description: image callbacks
+ * @stability: Stable
+ * @see_also: image
+ * @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 ) );
}
diff --git a/libvips/iofuncs/meta.c b/libvips/iofuncs/meta.c
index fd308275..fc3b6f6f 100644
--- a/libvips/iofuncs/meta.c
+++ b/libvips/iofuncs/meta.c
@@ -86,7 +86,7 @@
* SECTION: meta
* @short_description: get and set image metadata
* @stability: Stable
- * @see_also: header
+ * @see_also: header
* @include: vips/vips.h
*
* You can attach arbitrary metadata to images. Metadata is copied as images