.TH IM_ITERATE 3 "30 October 1992"
.SH NAME
im_iterate \- PIO input from image
.SH SYNOPSIS
.B #include <vips/vips.h>

int im_iterate( im, start_fn, scan_fn, stop_fn, a, b )
.br
IMAGE *im;
.br
void *(*start_fn)();
.br
int (*scan_fn)();
.br
int (*stop_fn)();
.br
void *a, *b;

where, typically, 

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

int scan_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
im_iterate(3) is used for PIO image input. See `VIPS Library Programmers'
guide,' in the accompanying documentation, for an introduction to this
function.

im_iterate(3) makes one or more regions on im, and starts one or more sequences
running over the image. im_iterate(3) guarantees that

   - scan_fn() will see each of the pels in im exactly once
   - start_fn() and stop_fn() are both exclusive

See the guide, the man page for im_generate(3), and the source to im_deviate(3)
for examples.

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% stats fred.v 

will run stats with enough concurrency to keep 2 CPUs fully occupied.
If IM_CONCURRENCY is not set, then it defaults to 1.
.SH RETURN VALUE
All functions return 0 on success and non-zero on error.
.SH SEE ALSO
im_generate(3).
.SH COPYRIGHT
National Gallery, 1993
.SH AUTHOR
J. Cupitt \- 23/7/93