154 lines
5.0 KiB
Groff
154 lines
5.0 KiB
Groff
.TH IM_AND 3 "30 October 1992"
|
|
.SH 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
|
|
.SH SYNOPSIS
|
|
.B #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 * );
|
|
|
|
.SH 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.
|
|
|
|
.B im_add_close_callback(3)
|
|
adds a callback which will be triggered when the image
|
|
is closed by
|
|
.B im_close(3).
|
|
The callback is expected to return 0 for success and
|
|
non-zero for failure. If the function fails, then the whole
|
|
.B 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
|
|
.B im_malloc(3).
|
|
This allocates memory
|
|
exactly as the standard
|
|
.B 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
|
|
.B im_malloc(3)
|
|
acts as
|
|
.B malloc(3).
|
|
On error,
|
|
.B im_malloc(3)
|
|
returns NULL, setting an
|
|
error message. See the man pages for
|
|
.B IM_NEW(3) and
|
|
.B im_open_local(3)
|
|
for further examples.
|
|
|
|
Free memory with
|
|
.B im_free(3).
|
|
|
|
You may use close callbacks to trigger other
|
|
.B im_close(3)
|
|
operations, and there
|
|
may even be circularity in your
|
|
.B im_close(3)
|
|
lists.
|
|
|
|
.B 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.
|
|
|
|
.B 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.
|
|
|
|
.B 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
|
|
.B 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.
|
|
|
|
.B 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.
|
|
|
|
.B 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.
|
|
|
|
.SH RETURN VALUE
|
|
All functions return 0 on success and non-zero on error.
|
|
.SH SEE ALSO
|
|
IM_NEW(3), im_open_local(3).
|
|
.SH COPYRIGHT
|
|
National Gallery, 1993
|
|
.SH AUTHOR
|
|
J. Cupitt \- 23/7/93
|