<!-- manual page source format generated by PolyglotMan v3.2, -->
<!-- available at http://polyglotman.sourceforge.net/ -->
<html>
<head>
<title>IM_AND(3) manual page</title>
</head>
<body bgcolor='white'>
<a href='#toc'>Table of Contents</a><p>
<h2><a name='sect0' href='#toc0'>Name</a></h2>
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
<h2><a name='sect1' href='#toc1'>Synopsis</a></h2>
<b>#include <vips/vips.h></b>
<p> typedef int (*im_callback_fn)(
void *, void * );
<p> int im_add_close_callback( IMAGE *, im_callback_fn,
void *, void * );
<p> int im_add_preclose_callback( IMAGE *, im_callback_fn,
void *, void * );
<p> int im_add_evalstart_callback( IMAGE *, im_callback_fn,
void *, void * );
<p> int im_add_eval_callback( IMAGE *, im_callback_fn, void
*, void * );
<p> int im_add_evalend_callback( IMAGE *, im_callback_fn, void
*, void * );
<p> int im_add_invalidate_callback( IMAGE *, im_callback_fn,
void *, void * );
<p> void *im_malloc( IMAGE *, size_t );
<p> int im_free( void
* );
<p>
<h2><a name='sect2' href='#toc2'>Description</a></h2>
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.
<p> <a href='im_add_close_callback.3.html'><b>im_add_close_callback(3)</a>
</b> adds a callback which will
be triggered when the image is closed by <a href='im_close.3.html'><b>im_close(3)</a>
. </b> The callback is
expected to return 0 for success and non-zero for failure. If the function
fails, then the whole <a href='im_close.3.html'><b>im_close(3)</a>
</b> fails. Close callbacks are guaranteed
to be called exactly once, so they are a good place to release resources.
<p> This function is used by VIPS to implement <a href='im_malloc.3.html'><b>im_malloc(3)</a>
. </b> This allocates
memory exactly as the standard <a href='malloc.3.html'><b>malloc(3)</a>
</b> 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
<a href='im_malloc.3.html'><b>im_malloc(3)</a>
</b> acts as <a href='malloc.3.html'><b>malloc(3)</a>
. </b> On error, <a href='im_malloc.3.html'><b>im_malloc(3)</a>
</b> returns NULL,
setting an error message. See the man pages for <a href='IM_NEW.3.html'><b>IM_NEW(3)</a>
and </b> <a href='im_open_local.3.html'><b>im_open_local(3)</b></a>
for further examples.
<p> Free memory with <a href='im_free.3.html'><b>im_free(3)</a>
.</b>
<p> You may use close
callbacks to trigger other <a href='im_close.3.html'><b>im_close(3)</a>
</b> operations, and there may even
be circularity in your <a href='im_close.3.html'><b>im_close(3)</a>
</b> lists.
<p> <a href='im_add_preclose_callback.3.html'><b>im_add_preclose_callback(3)</a>
</b> 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.
<p> <a href='im_add_evalstart_callback.3.html'><b>im_add_evalstart_callback(3)</a>
</b> 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.
<p> 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.
<p> If a later image adds eval callbacks, then the inheritance
is broken, and that image will recieve notification instead.
<p> <a href='im_add_eval_callback.3.html'><b>im_add_eval_callback(3)</a>
</b> adds a callback which will be triggered repeatedly as the image is evaluated.
<p> When the callback is triggered, the time field of the descriptor will
point to a <b>im_time_t </b> structure, see vips.h
<p> typedef struct {<br>
IMAGE *im; /* Image we are part of */<br>
time_t unused; /* For compatibility */<br>
int run; /* Time we have been running (secs) */<br>
int eta; /* Estimated seconds of computation left */<br>
gint64 tpels; /* Number of pels we expect to calculate */<br>
gint64 npels; /* Number of pels calculated so far */<br>
int percent; /* Percent complete */<br>
GTimer *start; /* Start time */<br>
} im_time_t;<br>
<p> These fields are not exact! They should only be used to give approximate
feedback to the user. It is possible to have
<p> percent > 100<br>
ntiles > ttiles<br>
eta == 0<br>
<p> 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.
<p> int<br>
eval_cb( IMAGE *im )<br>
{<br>
printf( "%d%% complete ...\n", im->time->percent );<br>
return( 0 );<br>
}<br>
<p> if( im_add_eval_callback( out, eval_cb, out, NULL ) )<br>
return( -1 );<br>
<p> ... now as out is evaluated, we will get %complete <br>
... messages on stdout.<br>
<p> <a href='im_add_evalend_callback.3.html'><b>im_add_evalend_callback(3)</a>
</b> 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.
<p> <a href='im_add_invalidate_callback.3.html'><b>im_add_invalidate_callback(3)</a>
</b> 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.
<p>
<h2><a name='sect3' href='#toc3'>Return Value</a></h2>
All functions return 0 on success and non-zero on error.
<h2><a name='sect4' href='#toc4'>See Also</a></h2>
<a href='IM_NEW.3.html'>IM_NEW(3)</a>
, <a href='im_open_local.3.html'>im_open_local(3)</a>
.
<h2><a name='sect5' href='#toc5'>Copyright</a></h2>
National Gallery, 1993
<h2><a name='sect6' href='#toc6'>Author</a></h2>
J.
Cupitt - 23/7/93 <p>
<hr><p>
<a name='toc'><b>Table of Contents</b></a><p>
<ul>
<li><a name='toc0' href='#sect0'>Name</a></li>
<li><a name='toc1' href='#sect1'>Synopsis</a></li>
<li><a name='toc2' href='#sect2'>Description</a></li>
<li><a name='toc3' href='#sect3'>Return Value</a></li>
<li><a name='toc4' href='#sect4'>See Also</a></li>
<li><a name='toc5' href='#sect5'>Copyright</a></li>
<li><a name='toc6' href='#sect6'>Author</a></li>
</ul>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
c109337651527e96d7bb9adc83c5b18a
>
files
>
119
