stuff
This commit is contained in:
John Cupitt
parent
74c0ee0ba8
commit
19c9cccbfc
6
TODO
6
TODO
|
|
@ -16,12 +16,6 @@
|
|||
|
||||
is there a problem
|
||||
|
||||
- update docs, add pages for new cbs
|
||||
|
||||
part of im_malloc.3
|
||||
|
||||
update nip2 for the new system ... seems to just be imageinfo_progress_add()
|
||||
|
||||
- test ppm writer
|
||||
|
||||
- missing libstdc++ in link? what if we configure with no openexr?
|
||||
|
|
|
|||
|
|
@ -120,7 +120,7 @@ typedef struct {
|
|||
/* Derived fields that may be read by the user.
|
||||
*/
|
||||
char *filename; /* File name */
|
||||
struct time_info *time;/* Timing for eval callback */
|
||||
im_time_t *time; /* Timing for eval callback */
|
||||
int kill; /* Set to non-zero to block eval */
|
||||
|
||||
... and lots of other private fields used by VIPS for
|
||||
|
|
@ -592,13 +592,12 @@ descriptor. The base memory allocation function is \verb+im_malloc()+. It
|
|||
has type:
|
||||
|
||||
\begin{verbatim}
|
||||
void *im_malloc( IMAGE *im,
|
||||
size_t size )
|
||||
void *im_malloc( IMAGE *, size_t )
|
||||
\end{verbatim}
|
||||
|
||||
It operates exactly as the standard \verb+malloc()+ C library function,
|
||||
except that the area of memory it allocates is local to image descriptor
|
||||
\verb+im+. If \verb+im_malloc()+ is unable to allocate memory, it returns
|
||||
except that the area of memory it allocates is local to an image.
|
||||
If \verb+im_malloc()+ is unable to allocate memory, it returns
|
||||
\verb+NULL+. If you pass \verb+NULL+ instead of a valid image descriptor,
|
||||
then \verb+im_malloc()+ allocates memory globally and you must free it
|
||||
yourself at some stage.
|
||||
|
|
@ -606,7 +605,7 @@ yourself at some stage.
|
|||
To free memory explicitly, use \verb+im_free()+:
|
||||
|
||||
\begin{verbatim}
|
||||
int im_free( void *mem )
|
||||
int im_free( void * )
|
||||
\end{verbatim}
|
||||
|
||||
\noindent
|
||||
|
|
@ -618,7 +617,7 @@ a new object. You give it a descriptor and a type, and it returns a pointer
|
|||
to enough space to hold an object of that type. It has type:
|
||||
|
||||
\begin{verbatim}
|
||||
type-name *IM_NEW( IMAGE *im, type-name )
|
||||
type-name *IM_NEW( IMAGE *, type-name )
|
||||
\end{verbatim}
|
||||
|
||||
The second macro, \verb+IM_ARRAY()+, is very similar, but allocates
|
||||
|
|
@ -626,8 +625,7 @@ space for an array of objects. Note that, unlike the usual \verb+calloc()+
|
|||
C library function, it does not initialise the array to zero. It has type:
|
||||
|
||||
\begin{verbatim}
|
||||
type-name *IM_ARRAY( IMAGE *im,
|
||||
int n, type-name )
|
||||
type-name *IM_ARRAY( IMAGE *, int, type-name )
|
||||
\end{verbatim}
|
||||
|
||||
Finally, \verb+IM_NUMBER()+ returns the number of elements in an array of
|
||||
|
|
|
|||
|
|
@ -797,8 +797,7 @@ full details.
|
|||
\label{sec:callback}
|
||||
|
||||
VIPS lets you attach callbacks to image descriptors. These are functions
|
||||
you provide that VIPS will call when certain events occur. This release
|
||||
of VIPS supports three callbacks:
|
||||
you provide that VIPS will call when certain events occur.
|
||||
|
||||
\subsubsection{Close callbacks}
|
||||
|
||||
|
|
@ -806,44 +805,35 @@ These callbacks are invoked just before an image is closed. They are useful
|
|||
for freeing objects which are associated with the image. All callbacks are
|
||||
triggered in the reverse order to the order in which they were attached. This
|
||||
is sometimes important when freeing objects which contain pointers to
|
||||
other objects.
|
||||
other objects. Close callbacks are guaranteed to be called, and to be called
|
||||
exactly once.
|
||||
|
||||
Use \verb+im_add_close_callback()+ to add a close callback:
|
||||
|
||||
\begin{verbatim}
|
||||
int
|
||||
im_add_close_callback( IMAGE *im,
|
||||
int (*callback)(),
|
||||
void *a, void *b )
|
||||
typedef int (*im_callback)( void *, void * )
|
||||
int im_add_close_callback( IMAGE *,
|
||||
im_callback_fn,
|
||||
void *, void * )
|
||||
\end{verbatim}
|
||||
|
||||
\noindent
|
||||
where \verb+callback()+ is a function supplied by you which has type:
|
||||
|
||||
\begin{verbatim}
|
||||
int callback( void *a, void *b )
|
||||
\end{verbatim}
|
||||
|
||||
\noindent
|
||||
and which returns 0 on success, and -1 on error, setting
|
||||
\verb+im_error()+. As with \verb+im_generate()+, the values \verb+a+
|
||||
and \verb+b+ are carried around for you by VIPS, and may be used as your
|
||||
As with \verb+im_generate()+, the two \verb+void *+ pointers
|
||||
are carried around for you by VIPS and may be used as your
|
||||
function sees fit.
|
||||
|
||||
\subsubsection{Preclose callbacks}
|
||||
|
||||
Preclose callbacks are called before any shutdown has occured. Everything is
|
||||
still alive and your callback can do anything to the image. Preclose callbacks
|
||||
are guaranteed to be called, and to be called exactly once. See the manual
|
||||
page for \verb+im_add_preclose_callback()+ for full details.
|
||||
|
||||
\subsubsection{Eval callbacks}
|
||||
|
||||
These are callbacks which are invoked by VIPS during evaluation. They
|
||||
are called each time a region is filled with data (for PIO functions), or
|
||||
each time \verb+im_writeline()+ is called (for WIO functions). The callback
|
||||
has access to a large struct containing information about the progress of
|
||||
evaluation, useful for user-interfaces built on top of VIPS. See the manual
|
||||
page for \verb+im_add_eval_callback()+ for full details.
|
||||
|
||||
\subsubsection{Evalend callbacks}
|
||||
|
||||
These are triggered after completion of evaluation of an image, just after all
|
||||
stop functions have been called. Evalend callbacks are useful for summarising
|
||||
the results of a computation, see the example in the section below.
|
||||
These are callbacks which are invoked periodically by VIPS during evaluation.
|
||||
The callback has access to a struct containing information about the progress
|
||||
of evaluation, useful for user-interfaces built on top of VIPS. See the
|
||||
manual page for \verb+im_add_eval_callback()+ for full details.
|
||||
|
||||
\subsection{Memory allocation revisited}
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,9 @@ man_MANS = \
|
|||
im_abs.3 \
|
||||
im_acostra.3 \
|
||||
im_add.3 \
|
||||
im_add_preclose_callback.3 \
|
||||
im_add_close_callback.3 \
|
||||
im_add_evalstart_callback.3 \
|
||||
im_add_eval_callback.3 \
|
||||
im_add_evalend_callback.3 \
|
||||
im_addgnoise.3 \
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
.so man3/im_malloc.3
|
||||
|
|
@ -0,0 +1 @@
|
|||
.so man3/im_malloc.3
|
||||
|
|
@ -1,51 +1,25 @@
|
|||
.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
|
||||
im_add_evalend_callback, im_add_evalstart_callback, im_add_preclose_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;
|
||||
typedef int (*im_callback_fn)( void *, void * );
|
||||
|
||||
int im_add_evalend_callback( im, fn, a, b )
|
||||
.br
|
||||
IMAGE *im;
|
||||
.br
|
||||
int (*fn)();
|
||||
.br
|
||||
void *a, *b;
|
||||
int im_add_close_callback( IMAGE *, im_callback_fn, void *, void * );
|
||||
|
||||
where
|
||||
int im_add_preclose_callback( IMAGE *, im_callback_fn, void *, void * );
|
||||
|
||||
int fn( a, b )
|
||||
.br
|
||||
void *a, *b;
|
||||
int im_add_evalstart_callback( IMAGE *, im_callback_fn, void *, void * );
|
||||
|
||||
char *im_malloc( IMAGE *im, int size );
|
||||
int im_add_eval_callback( IMAGE *, im_callback_fn, void *, void * );
|
||||
|
||||
int im_free( void *s );
|
||||
int im_add_evalend_callback( IMAGE *, im_callback_fn, void *, void * );
|
||||
|
||||
.B #include <vips/vips.h>
|
||||
void *im_malloc( IMAGE *, size_t );
|
||||
|
||||
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;
|
||||
int im_free( void * );
|
||||
|
||||
.SH DESCRIPTION
|
||||
These functions attach callbacks to images. Callbacks are functions, with
|
||||
|
|
@ -62,7 +36,8 @@ is closed by
|
|||
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.
|
||||
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).
|
||||
|
|
@ -93,16 +68,27 @@ 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_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 initalize 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 recieve notification instead.
|
||||
|
||||
.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.
|
||||
the image is evaluated.
|
||||
|
||||
When the callback is triggered, the time field of the descriptor will point to
|
||||
a
|
||||
|
|
@ -111,12 +97,13 @@ structure, see vips.h
|
|||
|
||||
typedef struct {
|
||||
IMAGE *im; /* Image we are part of */
|
||||
GTimer *start; /* Start time */
|
||||
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
|
||||
|
|
@ -140,9 +127,15 @@ be used to provide a `cancel' feature in your user-interface.
|
|||
if( im_add_eval_callback( out, eval_cb, out, NULL ) )
|
||||
return( -1 );
|
||||
|
||||
... now as we write to out, we will get %complete
|
||||
... 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.
|
||||
|
||||
.SH RETURN VALUE
|
||||
All functions return 0 on success and non-zero on error.
|
||||
.SH SEE ALSO
|
||||
|
|
|
|||
Loading…
Reference in New Issue