215 lines
5.0 KiB
Groff
215 lines
5.0 KiB
Groff
.TH IM_GENERATE 3 "11 April 1993"
|
|
.SH NAME
|
|
im_generate, im_start_one, im_stop_one, im_allocate_input_array,
|
|
im_start_many, im_stop_many \- generate image pixels
|
|
.SH SYNOPSIS
|
|
.B #include <vips/vips.h>
|
|
|
|
void *im_start_one( out, in )
|
|
.br
|
|
IMAGE *out, *in;
|
|
|
|
int im_stop_one( reg )
|
|
.br
|
|
REGION *reg;
|
|
|
|
IMAGE **im_allocate_input_array( IMAGE *out, ... )
|
|
|
|
void *im_start_many( out, in )
|
|
.br
|
|
IMAGE *out, **in;
|
|
|
|
int im_stop_many( REGION **out )
|
|
.br
|
|
REGION **out;
|
|
|
|
int im_generate( im,
|
|
start_fn, gen_fn, stop_fn, void *a, void *b )
|
|
.br
|
|
IMAGE *im;
|
|
.br
|
|
void *(*start_fn)();
|
|
.br
|
|
int (*gen_fn)();
|
|
.br
|
|
int (*stop_fn)();
|
|
.br
|
|
void *a, void *b;
|
|
|
|
where, typically,
|
|
|
|
void *start_fn( im, a, b )
|
|
.br
|
|
IMAGE *im;
|
|
.br
|
|
void *a, *b;
|
|
|
|
int gen_fn( or, seq, a, b )
|
|
.br
|
|
REGION *or;
|
|
.br
|
|
void *seq;
|
|
.br
|
|
void *a, *b;
|
|
|
|
int stop_fn( seq, a, b )
|
|
.br
|
|
void *seq;
|
|
.br
|
|
void *a, *b;
|
|
.SH DESCRIPTION
|
|
.B im_generate(3),
|
|
with its supporting convenience functions, is used for
|
|
PIO image output. See also
|
|
.B im_wrapone(3)
|
|
for an easy alternative to
|
|
.B im_generate(3)
|
|
for simple image
|
|
processing operations.
|
|
|
|
.B im_start_one(3)
|
|
and
|
|
.B im_stop_one(3)
|
|
are convenience functions, useful for
|
|
simple one-image-in, one-image-out operations.
|
|
.B im_start_one(3)
|
|
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.
|
|
|
|
.B im_stop_one(3)
|
|
assumes the sequence value is a REGION pointer, and frees it.
|
|
|
|
.B im_allocate_input_array(3)
|
|
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:
|
|
|
|
IMAGE *in, *in2, *in3, *in4;
|
|
IMAGE **arry;
|
|
|
|
if( !(arry = im_allocate_input_array( out,
|
|
in1, in2, in3, in4, NULL )) )
|
|
return( -1 );
|
|
|
|
builds the structure
|
|
|
|
IMAGE *arry[] = { in1, in2, in3, in4, NULL };
|
|
|
|
and makes sure it will be freed.
|
|
|
|
.B im_start_many(3)
|
|
and
|
|
.B im_stop_many(3)
|
|
work exactly as
|
|
.B im_start_one(3)
|
|
and
|
|
.B im_stop_one(3),
|
|
but with NULL-terminated arrays of IMAGEs and REGIONs.
|
|
They are useful for many-images-in, one-image-out operations.
|
|
.B im_start_many(3)
|
|
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.
|
|
|
|
.B im_stop_many(3)
|
|
assumes the sequence value is a pointer to a NULL-terminated
|
|
array of REGIONs. It frees all the regions in turn. See
|
|
.B im_add(3)
|
|
for an
|
|
example of this pair of functions in action.
|
|
|
|
.B im_generate(3)
|
|
looks at the type of im and acts accordingly:
|
|
|
|
IM_PARTIAL: the start, process and stop functions are attached to the
|
|
region, and im_generate returns immediately. See
|
|
.B im_prepare(3).
|
|
|
|
IM_SETBUF: memory for the output image is created and sequences
|
|
started to fill it. It is an error to write to the same buffer twice.
|
|
|
|
IM_MMAPINRW: sequences are started, and asked to fill the image in patches.
|
|
|
|
IM_OPENOUT: The output file is created and a header written to disc. A
|
|
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 write(2)
|
|
operation, and work starts on the next set of lines.
|
|
|
|
Any other image type is an error.
|
|
.B im_generate(3)
|
|
returns 0 for complete
|
|
success, and non-zero on failure.
|
|
|
|
static int
|
|
wombat_gen( or, ir, in )
|
|
REGION *or, *ir;
|
|
IMAGE *in;
|
|
{
|
|
... process!
|
|
|
|
return( 0 );
|
|
}
|
|
|
|
int
|
|
im_wombat( in, out )
|
|
IMAGE *in, *out;
|
|
{
|
|
if( im_iocheck( in, out ) )
|
|
return( -1 );
|
|
|
|
... check parametersm check image descriptors
|
|
... for type-compatibility, etc. etc.
|
|
|
|
if( im_cp_desc( out, in ) )
|
|
return( -1 );
|
|
|
|
... set fields in out for the type of image you
|
|
... wish to write
|
|
|
|
if( im_generate( out,
|
|
im_start_one, wombat_gen, im_stop_one,
|
|
in, NULL ) )
|
|
return( -1 );
|
|
|
|
return( 0 );
|
|
}
|
|
|
|
See also the source to
|
|
.B im_invert(3),
|
|
.B im_exptra(3),
|
|
and, if you are brave,
|
|
.B im_conv(3)
|
|
or
|
|
.B im_add(3).
|
|
|
|
On machines with several CPUs,
|
|
.B im_generate(3)
|
|
and
|
|
.B im_iterate(3)
|
|
automatically parallelise programs. You can set the desired
|
|
concurrency level with the environment variable IM_CONCURRENCY, for example
|
|
|
|
example% export IM_CONCURRENCY=2
|
|
example% lintra 2.0 fred.v 0.0 fred2.v
|
|
|
|
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
|
|
im_concurrency_set(3).
|
|
|
|
Most programs which use VIPS will also let you use the command-line argument
|
|
--vips-concurrency to set parallelisation, see im_get_option_group(3).
|
|
|
|
.SH COPYRIGHT
|
|
National Gallery, 1993
|
|
.SH SEE ALSO
|
|
im_wrapone(3), im_add_eval_callback(3), im_iterate(3), im_piocheck(3),
|
|
im_concurrency_set(3),
|
|
im_get_option_group(3),
|
|
`VIPS manual,' in accompanying documentation.
|
|
.SH AUTHOR
|
|
J. Cupitt \- 23/7/93
|