NAME
im_add_close_callback, im_add_eval_callback, im_malloc, im_free,
im_add_evalend_callback, im_add_evalstart_callback,
im_add_preclose_callback, im_add_invalidate_callback - add image
callbacks
SYNOPSIS
#include <vips/vips.h>
typedef int (*im_callback_fn)( void *, void * );
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 *im_malloc( IMAGE *, size_t );
int im_free( void * );
DESCRIPTION
These functions attach callbacks to images. Callbacks are functions,
with optional extra arguments a and b, which are remembered by the
IMAGE they are attached to. These functions are triggered at some later
stage in reponse to some event. You can attach as many callbacks as you
like; all will be remembered, and will be called when the event occurs.
The most recently added callback is called first --- this can be
important for close callbacks.
im_add_close_callback(3) adds a callback which will be triggered when
the image is closed by im_close(3). The callback is expected to return
0 for success and non-zero for failure. If the function fails, then the
whole im_close(3) fails. Close callbacks are guaranteed to be called
exactly once, so they are a good place to release resources.
This function is used by VIPS to implement im_malloc(3). This
allocates memory exactly as the standard malloc(3) function, but memory
allocated is local to a descriptor. When the descriptor is closed, the
memory allocated is automatically freed for you. If you pass NULL for
the descriptor, then im_malloc(3) acts as malloc(3). On error,
im_malloc(3) returns NULL, setting an error message. See the man pages
for IM_NEW(3) and im_open_local(3) for further examples.
Free memory with im_free(3).
You may use close callbacks to trigger other im_close(3) operations,
and there may even be circularity in your im_close(3) lists.
im_add_preclose_callback(3) adds a callback which will be triggered
when the image is closed, but before any closing has started.
Everything is still alive and you can do anything with the image.
Preclose callbacks are guaranteed to be called exactly once.
im_add_evalstart_callback(3) adds a callback which will be triggered
just before image evaluation starts. It can be called many times. It’s
a good place to initalize data structures. Don’t allocate resources
here.
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.
im_add_eval_callback(3) adds a callback which will be triggered
repeatedly as the image is evaluated.
When the callback is triggered, the time field of the descriptor will
point to a im_time_t structure, see vips.h
typedef struct {
IMAGE *im; /* Image we are part of */
time_t unused; /* For compatibility */
int run; /* Time we have been running (secs) */
int eta; /* Estimated seconds of computation left */
gint64 tpels; /* Number of pels we expect to calculate */
gint64 npels; /* Number of pels calculated so far */
int percent; /* Percent complete */
GTimer *start; /* Start time */
} im_time_t;
These fields are not exact! They should only be used to give
approximate feedback to the user. It is possible to have
percent > 100
ntiles > ttiles
eta == 0
so be careful. Again, the eval callback should return 0 for success and
non-zero for failure. If the callback fails, evaluation is abandoned.
This may be used to provide a ‘cancel’ feature in your user-interface.
int
eval_cb( IMAGE *im )
{
printf( "%d%% complete ...\n", im->time->percent );
return( 0 );
}
if( im_add_eval_callback( out, eval_cb, out, NULL ) )
return( -1 );
... now as out is evaluated, we will get %complete
... messages on stdout.
im_add_evalend_callback(3) adds a callback which will be triggered when
VIPS has finished evaluating the image. If you want to output some
diagnostics from your function (an overflow count, for example), this
is the callback to use. Again, this can be called many times.
im_add_invalidate_callback(3) adds a callback which will be triggered
when VIPS invalidates the cache on an image. This is useful for
removing images from other, higher-level caches.
RETURN VALUE
All functions return 0 on success and non-zero on error.
SEE ALSO
IM_NEW(3), im_open_local(3).
COPYRIGHT
National Gallery, 1993
AUTHOR
J. Cupitt - 23/7/93
30 October 1992 IM_AND(3)