1IM_AND(3) Library Functions Manual IM_AND(3)
2
6 im_add_close_callback, im_add_eval_callback, im_malloc, im_free,
7 im_add_evalend_callback - add image callbacks
8
10 #include <vips/vips.h>
11 int im_add_close_callback( im, fn, a, b )
13 IMAGE *im;
14 int (*fn)();
15 void *a, *b;
16 int im_add_evalend_callback( im, fn, a, b )
18 IMAGE *im;
19 int (*fn)();
20 void *a, *b;
21 where
23 int fn( a, b )
25 void *a, *b;
26 char *im_malloc( IMAGE *im, int size );
28 int im_free( void *s );
30 #include <vips/vips.h>
32 #include <vips/time.h>
33 int im_add_eval_callback( im, fn, a, b )
35 IMAGE *im;
36 int (*fn)();
37 void *a, *b;
38 where
40 int fn( a, b )
42 void *a, *b;
43
46 These functions attach callbacks to images. Callbacks are functions,
47 with optional extra arguments a and b, which are remembered by the
48 IMAGE they are attached to. These functions are triggered at some later
49 stage in reponse to some event. You can attach as many callbacks as you
50 like; all will be remembered, and will be called when the event occurs.
51 The most recently added callback is called first --- this can be impor‐
52 tant for close callbacks.
53 im_add_close_callback(3) adds a callback which will be triggered when
55 the image is closed by im_close(3). The callback is expected to return
56 0 for success and non-zero for failure. If the function fails, then the
57 whole im_close(3) fails.
58 This function is used by VIPS to implement im_malloc(3). This allo‐
60 cates memory exactly as the standard malloc(3) function, but memory
61 allocated is local to a descriptor. When the descriptor is closed, the
62 memory allocated is automatically freed for you. If you pass NULL for
63 the descriptor, then im_malloc(3) acts as malloc(3). On error, im_mal‐
64 loc(3) returns NULL, setting an error message. See the man pages for
65 IM_NEW(3) and im_open_local(3) for further examples.
66 Free memory with im_free(3).
68 You may use close callbacks to trigger other im_close(3) operations,
70 and there may even be circularity in your im_close(3) lists.
71 im_add_evalend_callback(3) adds a callback which will be triggered when
73 VIPS has finished writing to the descriptor. If you want to output some
74 diagnostics from your function (an overflow count, for example), this
75 is the callback to use.
76 im_add_eval_callback(3) adds a callback which will be triggered repeat‐
78 edly as the image is written to. This works for both PIO and WIO
79 images, although it is rather more successful with PIO image output.
80 When the callback is triggered, the time field of the descriptor will
82 point to a time_info structure, as defined in <vips/time.h>
83 #include <sys/timeb.h>
85 struct time_info {
87 IMAGE *im; /* Image we are part of */
88 time_t start; /* Start time, in seconds */
89 int run; /* Time we have been running */
90 int eta; /* Seconds of computation left */
91 int ttiles; /* Tiles we expect to calculate */
92 int ntiles; /* Tiles calculated so far */
93 int percent; /* Percent complete */
94 };
95 These fields are not exact! They should only be used to give approxi‐
97 mate feedback to the user. It is possible to have
98 percent > 100
100 ntiles > ttiles
101 eta == 0
102 so be careful. Again, the eval callback should return 0 for success and
104 non-zero for failure. If the callback fails, evaluation is abandoned.
105 This may be used to provide a `cancel' feature in your user-interface.
106 int
108 eval_cb( IMAGE *im )
109 {
110 printf( "%d%% complete ...\n", im->time->percent );
111 return( 0 );
112 }
113 if( im_add_eval_callback( out, eval_cb, out, NULL ) )
115 return( -1 );
116 ... now as we write to out, we will get %complete
118 ... messages on stdout.
119
122 All functions return 0 on success and non-zero on error.
123
125 IM_NEW(3), im_open_local(3), `VIPS Library Programmers' Guide,' in
126 accompanying documentation.
127
129 National Gallery, 1993
130
132 J. Cupitt - 23/7/93
133 30 October 1992 IM_AND(3)