.TH IM_PREPARE 3 "11 April 1990"
.SH NAME
im_prepare, im_prepare_to \- fill region with data
.SH SYNOPSIS
.B #include <vips/vips.h>

int im_prepare( reg, r )
.br
REGION *reg;
.br
Rect *r;

int im_prepare_to( reg, dest, r, x, y )
.br
REGION *reg, *dest;
.br
Rect *r;
.br
int x, y;

int im_prepare_many( reg, r )
.br
REGION **reg;
.br
Rect *r;

.SH DESCRIPTION
.B im_prepare(3)
fills region reg with pels covering the area inside r. 

r is expected to lie within the image on which reg was defined; if it does not
it will be clipped against the size of the image. Consequence: if

    im_prepare( reg, r )

succeeds, VIPS guarantees that pels within reg->valid may be read from reg
with
.B IM_REGION_ADDR(3).
It does not guarantee that you may read all of r!

The action taken by im_prepare(3) depends upon the image descriptor on which
reg was defined:

PARTIAL: The area requested is clipped against the edges of the image, local
memory is attached to reg with
.B im_region_buffer(3)
and that area requested
from the image's generate function, see
.B im_generate(3).
If necessary, a new
sequence is started.

SETBUF: MMAPIN: MMAPINRW: The area defined by r is clipped against the edges
of the image, and that area attached to reg.

.B im_prepare_to(3)
is very like
.B im_prepare(3),
but rather than writing pixels to local memory on reg (or attaching reg to
some other piece of memory), it instead writes pixels into the region dest at
position x, y. The parameters dest, r, x, y behave in the same way as the
paramaters to
.B im_region_region(3).

Effectively, it's just like
.B im_prepare(3)
followed by a copy operation. Except that the copy will be skipped when
possible.

This call is used by (among others)
.B im_generate(3)
to make operations output to
disc buffers, and by
.B im_embed(3)
to get images written inside larger images.

.B im_prepare_many(3)
prepares the same Rect on a NULL terminated array of REGION pointers, as
returned by
.BR im_start_many(3) .

.SH RETURN VALUE
The function returns 0 on success and non-zero on error.
.SH SEE ALSO
im_generate(3), im_open(3). 
.SH COPYRIGHT
National Gallery
.SH AUTHOR
J. Cupitt \- 23/7/93