<!-- 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>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
c109337651527e96d7bb9adc83c5b18a
>
files
>
540
