.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