156 lines
3.8 KiB
Groff
156 lines
3.8 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 \- add image callbacks
|
||
|
.SH SYNOPSIS
|
||
|
.B #include <vips/vips.h>
|
||
|
|
||
|
int im_add_close_callback( im, fn, a, b )
|
||
|
.br
|
||
|
IMAGE *im;
|
||
|
.br
|
||
|
int (*fn)();
|
||
|
.br
|
||
|
void *a, *b;
|
||
|
|
||
|
int im_add_evalend_callback( im, fn, a, b )
|
||
|
.br
|
||
|
IMAGE *im;
|
||
|
.br
|
||
|
int (*fn)();
|
||
|
.br
|
||
|
void *a, *b;
|
||
|
|
||
|
where
|
||
|
|
||
|
int fn( a, b )
|
||
|
.br
|
||
|
void *a, *b;
|
||
|
|
||
|
char *im_malloc( IMAGE *im, int size );
|
||
|
|
||
|
int im_free( void *s );
|
||
|
|
||
|
.B #include <vips/vips.h>
|
||
|
.br
|
||
|
.B #include <vips/time.h>
|
||
|
|
||
|
int im_add_eval_callback( im, fn, a, b )
|
||
|
.br
|
||
|
IMAGE *im;
|
||
|
.br
|
||
|
int (*fn)();
|
||
|
.br
|
||
|
void *a, *b;
|
||
|
|
||
|
where
|
||
|
|
||
|
int fn( a, b )
|
||
|
.br
|
||
|
void *a, *b;
|
||
|
|
||
|
.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.
|
||
|
|
||
|
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_evalend_callback(3)
|
||
|
adds a callback which will be triggered when VIPS
|
||
|
has finished writing to the descriptor. If you want to output some diagnostics
|
||
|
from your function (an overflow count, for example), this is the callback to
|
||
|
use.
|
||
|
|
||
|
.B im_add_eval_callback(3)
|
||
|
adds a callback which will be triggered repeatedly as
|
||
|
the image is written to. This works for both PIO and WIO images,
|
||
|
although it is rather more successful with PIO image output.
|
||
|
|
||
|
When the callback is triggered, the time field of the descriptor will point to
|
||
|
a time_info structure, as defined in <vips/time.h>
|
||
|
|
||
|
#include <sys/timeb.h>
|
||
|
|
||
|
struct time_info {
|
||
|
IMAGE *im; /* Image we are part of */
|
||
|
time_t start; /* Start time, in seconds */
|
||
|
int run; /* Time we have been running */
|
||
|
int eta; /* Seconds of computation left */
|
||
|
int ttiles; /* Tiles we expect to calculate */
|
||
|
int ntiles; /* Tiles calculated so far */
|
||
|
int percent; /* Percent complete */
|
||
|
};
|
||
|
|
||
|
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 we write to out, we will get %complete
|
||
|
... messages on stdout.
|
||
|
|
||
|
.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
|