154 lines
3.8 KiB
Groff
154 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>
|
|
|
|
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
|
|
.B im_time_t
|
|
structure, see vips.h
|
|
|
|
typedef struct {
|
|
IMAGE *im; /* Image we are part of */
|
|
GTimer *start; /* Start time */
|
|
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 */
|
|
} 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 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
|