Table of Contents

## Name

im_generate, im_start_one, im_stop_one, im_allocate_input_array, im_start_many, im_stop_many - close an image descriptor

## Synopsis

#include <vips/vips.h>
#include <vips/region.h>

void *im_start_one( out, in )
IMAGE *out, *in;

int im_stop_one( reg )
REGION *reg;

IMAGE **im_allocate_input_array( IMAGE *out, ... )

void *im_start_many( out, in )
IMAGE *out, **in;

int im_stop_many( REGION **out )
REGION **out;

int im_generate( im, start_fn, gen_fn, stop_fn, void *a, void *b )
IMAGE *im;
void *(*start_fn)();
int (*gen_fn)();
int (*stop_fn)();
void *a, void *b;

where, typically,

void *start_fn( im, a, b )
IMAGE *im;
void *a, *b;

int gen_fn( or, seq, a, b )
REGION *or;
void *seq;
void *a, *b;

int stop_fn( seq, a, b )
void *seq;
void *a, *b;

## Description

im_generate(3) , with its supporting convenience functions, is used for PIO image output. See `VIPS Library Programmers' Guide,' in the accompanying documentation, for an introduction to this function. See also im_wrapone(3) for an easy alternative to im_generate(3) for simple image processing operations.

im_start_one(3) and im_stop_one(3) are convenience functions, useful for simple one-image-in, one-image-out operations. 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.

im_stop_one(3) assumes the sequence value is a REGION pointer, and frees it.

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.

im_start_many(3) and im_stop_many(3) work exactly as im_start_one and im_stop_one, but with NULL-terminated arrays of IMAGEs and REGIONs. They are useful for many-images-in, one-image-out operations. 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.

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 im_add(3) for an example of this pair of functions in action.

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 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(3) operation, and work starts on the next set of lines.

Any other image type is an error. 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 im_invert(3) , im_exptra(3) , and, if you are brave, im_conv(3) or im_add(3) .

On machines with SVR4 threads and several CPUs, im_generate(3) and im_iterate(3) automatically parallelise programs. You can set the desired concurrency level with the environment variable IM_CONCURRENCY,

for example

example% setenv 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.

## Copyright

National Gallery, 1993

## See Also

im_wrapone(3) , im_add_eval_callback(3) , im_iterate(3) , im_piocheck(3) , `VIPS Library Programmers' Guide,' in accompanying documentation.

## Author

J. Cupitt - 23/7/93

Table of Contents

- Name
- Synopsis
- Description
- Copyright
- See Also
- Author