<!-- manual page source format generated by PolyglotMan v3.2, --> <!-- available at http://polyglotman.sourceforge.net/ --> <html> <head> <title>IM_GENERATE(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_generate, im_start_one, im_stop_one, im_allocate_input_array, im_start_many, im_stop_many - generate image pixels <h2><a name='sect1' href='#toc1'>Synopsis</a></h2> <b>#include <vips/vips.h></b> <p> void *im_start_one( out, in ) <br> IMAGE *out, *in; <p> int im_stop_one( reg ) <br> REGION *reg; <p> IMAGE **im_allocate_input_array( IMAGE *out, ... ) <p> void *im_start_many( out, in ) <br> IMAGE *out, **in; <p> int im_stop_many( REGION **out ) <br> REGION **out; <p> int im_generate( im, start_fn, gen_fn, stop_fn, void *a, void *b )<br> <br> IMAGE *im; <br> void *(*start_fn)(); <br> int (*gen_fn)(); <br> int (*stop_fn)(); <br> void *a, void *b; <p> where, typically, <p> void *start_fn( im, a, b ) <br> IMAGE *im; <br> void *a, *b; <p> int gen_fn( or, seq, a, b ) <br> REGION *or; <br> void *seq; <br> void *a, *b; <p> int stop_fn( seq, a, b ) <br> void *seq; <br> void *a, *b; <h2><a name='sect2' href='#toc2'>Description</a></h2> <a href='im_generate.3.html'><b>im_generate(3)</a> , </b> with its supporting convenience functions, is used for PIO image output. See also <a href='im_wrapone.3.html'><b>im_wrapone(3)</a> </b> for an easy alternative to <a href='im_generate.3.html'><b>im_generate(3)</a> </b> for simple image processing operations. <p> <a href='im_start_one.3.html'><b>im_start_one(3)</a> </b> and <a href='im_stop_one.3.html'><b>im_stop_one(3)</a> </b> are convenience functions, useful for simple one-image-in, one-image-out operations. <a href='im_start_one.3.html'><b>im_start_one(3)</a> </b> assumes the first of the two user arguments (a, above) is the input image. It creates a REGION on this image and returns a pointer to the region as a sequence value. <p> <a href='im_stop_one.3.html'><b>im_stop_one(3)</a> </b> assumes the sequence value is a REGION pointer, and frees it. <p> <a href='im_allocate_input_array.3.html'><b>im_allocate_input_array(3)</a> </b> takes as arguments the output image and a list of input images, terminated with a NULL. It allocates a NULL-terminated array to hold the images, and attaches a close callback to the output image to free that array. Example: <p> IMAGE *in, *in2, *in3, *in4;<br> IMAGE **arry;<br> <p> if( !(arry = im_allocate_input_array( out, <br> in1, in2, in3, in4, NULL )) )<br> return( -1 );<br> <p> builds the structure <p> IMAGE *arry[] = { in1, in2, in3, in4, NULL };<br> <p> and makes sure it will be freed. <p> <a href='im_start_many.3.html'><b>im_start_many(3)</a> </b> and <a href='im_stop_many.3.html'><b>im_stop_many(3)</a> </b> work exactly as <a href='im_start_one.3.html'><b>im_start_one(3)</a> </b> and <a href='im_stop_one.3.html'><b>im_stop_one(3)</a> , </b> but with NULL-terminated arrays of IMAGEs and REGIONs. They are useful for many-images-in, one-image-out operations. <a href='im_start_many.3.html'><b>im_start_many(3)</a> </b> assumes that the first of the two user arguments is a pointer to a NULL-terminates array of IMAGEs. It builds and returns as the sequence value a NULL-terminated array of REGIONs. <p> <a href='im_stop_many.3.html'><b>im_stop_many(3)</a> </b> assumes the sequence value is a pointer to a NULL-terminated array of REGIONs. It frees all the regions in turn. See <a href='im_add.3.html'><b>im_add(3)</a> </b> for an example of this pair of functions in action. <p> <a href='im_generate.3.html'><b>im_generate(3)</a> </b> looks at the type of im and acts accordingly: <p> IM_PARTIAL: the start, process and stop functions are attached to the <br> region, and im_generate returns immediately. See <a href='im_prepare.3.html'><b>im_prepare(3)</a> .</b> <p> IM_SETBUF: memory for the output image is created and sequences<br> started to fill it. It is an error to write to the same buffer twice. <p> IM_MMAPINRW: sequences are started, and asked to fill the image in patches.<br> <p> IM_OPENOUT: The output file is created and a header written to disc. A <br> buffer large enough to hold GENERATE_TILE_HEIGHT complete horizontal lines is created, and sequences started to fill this buffer. When the buffer has been filled, the whole set of lines are flushed to disc in a single <a href='write.2.html'>write(2)</a> operation, and work starts on the next set of lines. <p> Any other image type is an error. <a href='im_generate.3.html'><b>im_generate(3)</a> </b> returns 0 for complete success, and non-zero on failure. <p> static int<br> wombat_gen( or, ir, in )<br> REGION *or, *ir;<br> IMAGE *in;<br> {<br> ... process!<br> <p> return( 0 );<br> }<br> <p> int<br> im_wombat( in, out )<br> IMAGE *in, *out;<br> {<br> if( im_iocheck( in, out ) )<br> return( -1 );<br> <p> ... check parametersm check image descriptors <br> ... for type-compatibility, etc. etc.<br> <p> if( im_cp_desc( out, in ) )<br> return( -1 );<br> <p> ... set fields in out for the type of image you<br> ... wish to write<br> <p> if( im_generate( out,<br> im_start_one, wombat_gen, im_stop_one, <br> in, NULL ) )<br> return( -1 );<br> <p> return( 0 );<br> }<br> <p> See also the source to <a href='im_invert.3.html'><b>im_invert(3)</a> , </b> <a href='im_exptra.3.html'><b>im_exptra(3)</a> , </b> and, if you are brave, <a href='im_conv.3.html'><b>im_conv(3)</a> </b> or <a href='im_add.3.html'><b>im_add(3)</a> .</b> <p> On machines with several CPUs, <a href='im_generate.3.html'><b>im_generate(3)</a> </b> and <a href='im_iterate.3.html'><b>im_iterate(3)</a> </b> automatically parallelise programs. You can set the desired concurrency level with the environment variable IM_CONCURRENCY, <p>for example <p> example% export IM_CONCURRENCY=2<br> example% lintra 2.0 fred.v 0.0 fred2.v<br> <p> will run lintra with enough concurrency to keep 2 CPUs fully occupied. If IM_CONCURRENCY is not set, then it defaults to 1. See also <a href='im_concurrency_set.3.html'>im_concurrency_set(3)</a> . <p> Most programs which use VIPS will also let you use the command-line argument --vips-concurrency to set parallelisation, see <a href='im_get_option_group.3.html'>im_get_option_group(3)</a> . <p> <h2><a name='sect3' href='#toc3'>Copyright</a></h2> National Gallery, 1993 <h2><a name='sect4' href='#toc4'>See Also</a></h2> <a href='im_wrapone.3.html'>im_wrapone(3)</a> , <a href='im_add_eval_callback.3.html'>im_add_eval_callback(3)</a> , <a href='im_iterate.3.html'>im_iterate(3)</a> , <a href='im_piocheck.3.html'>im_piocheck(3)</a> , <a href='im_concurrency_set.3.html'>im_concurrency_set(3)</a> , <a href='im_get_option_group.3.html'>im_get_option_group(3)</a> , ‘VIPS manual,’ in accompanying documentation. <h2><a name='sect5' href='#toc5'>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'>Copyright</a></li> <li><a name='toc4' href='#sect4'>See Also</a></li> <li><a name='toc5' href='#sect5'>Author</a></li> </ul> </body> </html>