1IM_CLOSE(3) Library Functions Manual IM_CLOSE(3)
2
6 im_generate, im_start_one, im_stop_one, im_allocate_input_array,
7 im_start_many, im_stop_many - close an image descriptor
8
10 #include <vips/vips.h>
11 #include <vips/region.h>
12 void *im_start_one( out, in )
14 IMAGE *out, *in;
15 int im_stop_one( reg )
17 REGION *reg;
18 IMAGE **im_allocate_input_array( IMAGE *out, ... )
20 void *im_start_many( out, in )
22 IMAGE *out, **in;
23 int im_stop_many( REGION **out )
25 REGION **out;
26 int im_generate( im,
28 start_fn, gen_fn, stop_fn, void *a, void *b )
29 IMAGE *im;
30 void *(*start_fn)();
31 int (*gen_fn)();
32 int (*stop_fn)();
33 void *a, void *b;
34 where, typically,
36 void *start_fn( im, a, b )
38 IMAGE *im;
39 void *a, *b;
40 int gen_fn( or, seq, a, b )
42 REGION *or;
43 void *seq;
44 void *a, *b;
45 int stop_fn( seq, a, b )
47 void *seq;
48 void *a, *b;
49
51 im_generate(3), with its supporting convenience functions, is used for
52 PIO image output. See `VIPS Library Programmers' Guide,' in the accom‐
53 panying documentation, for an introduction to this function. See also
54 im_wrapone(3) for an easy alternative to im_generate(3) for simple
55 image processing operations.
56 im_start_one(3) and im_stop_one(3) are convenience functions, useful
58 for simple one-image-in, one-image-out operations. im_start_one(3)
59 assumes the first of the two user arguments (a, above) is the input
60 image. It creates a REGION on this image and returns a pointer to the
61 region as a sequence value.
62 im_stop_one(3) assumes the sequence value is a REGION pointer, and
64 frees it.
65 im_allocate_input_array(3) takes as arguments the output image and a
67 list of input images, terminated with a NULL. It allocates a NULL-ter‐
68 minated array to hold the images, and attaches a close callback to the
69 output image to free that array. Example:
70 IMAGE *in, *in2, *in3, *in4;
72 IMAGE **arry;
73 if( !(arry = im_allocate_input_array( out,
75 in1, in2, in3, in4, NULL )) )
76 return( -1 );
77 builds the structure
79 IMAGE *arry[] = { in1, in2, in3, in4, NULL };
81 and makes sure it will be freed.
83 im_start_many(3) and im_stop_many(3) work exactly as im_start_one and
85 im_stop_one, but with NULL-terminated arrays of IMAGEs and REGIONs.
86 They are useful for many-images-in, one-image-out operations.
87 im_start_many(3) assumes that the first of the two user arguments is a
88 pointer to a NULL-terminates array of IMAGEs. It builds and returns as
89 the sequence value a NULL-terminated array of REGIONs.
90 im_stop_many(3) assumes the sequence value is a pointer to a NULL-ter‐
92 minated array of REGIONs. It frees all the regions in turn. See
93 im_add(3) for an example of this pair of functions in action.
94 im_generate(3) looks at the type of im and acts accordingly:
96 IM_PARTIAL: the start, process and stop functions are attached to the
98 region, and im_generate returns immediately. See im_prepare(3).
99 IM_SETBUF: memory for the output image is created and sequences started
101 to fill it. It is an error to write to the same buffer twice.
102 IM_MMAPINRW: sequences are started, and asked to fill the image in
104 patches.
105 IM_OPENOUT: The output file is created and a header written to disc. A
107 buffer large enough to hold GENERATE_TILE_HEIGHT complete horizontal
108 lines is created, and sequences started to fill this buffer. When the
109 buffer has been filled, the whole set of lines are flushed to disc in a
110 single write(3) operation, and work starts on the next set of lines.
111 Any other image type is an error. im_generate(3) returns 0 for complete
113 success, and non-zero on failure.
114 static int
116 wombat_gen( or, ir, in )
117 REGION *or, *ir;
118 IMAGE *in;
119 {
120 ... process!
121 return( 0 );
123 }
124 int
126 im_wombat( in, out )
127 IMAGE *in, *out;
128 {
129 if( im_iocheck( in, out ) )
130 return( -1 );
131 ... check parametersm check image descriptors
133 ... for type-compatibility, etc. etc.
134 if( im_cp_desc( out, in ) )
136 return( -1 );
137 ... set fields in out for the type of image you
139 ... wish to write
140 if( im_generate( out,
142 im_start_one, wombat_gen, im_stop_one,
143 in, NULL ) )
144 return( -1 );
145 return( 0 );
147 }
148 See also the source to im_invert(3), im_exptra(3), and, if you are
150 brave, im_conv(3) or im_add(3).
151 On machines with SVR4 threads and several CPUs, im_generate(3) and
153 im_iterate(3) automatically parallelise programs. You can set the
154 desired concurrency level with the environment variable IM_CONCURRENCY,
155 for example
156 example% setenv IM_CONCURRENCY 2
158 example% lintra 2.0 fred.v 0.0 fred2.v
159 will run lintra with enough concurrency to keep 2 CPUs fully occupied.
161 If IM_CONCURRENCY is not set, then it defaults to 1.
162
165 National Gallery, 1993
166
168 im_wrapone(3), im_add_eval_callback(3), im_iterate(3), im_piocheck(3),
169 `VIPS Library Programmers' Guide,' in accompanying documentation.
170
172 J. Cupitt - 23/7/93
173 11 April 1990 IM_CLOSE(3)