| .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 initialize 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 receive 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 |