SYNOPSIS

#include <vips/vips.h>

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

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

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

DESCRIPTION

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 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 im_region_buffer(3) and that area requested from the image's generate function, see 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.

im_prepare_to(3) is very like 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 im_region_region(3).

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

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

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

RETURN VALUE

The function returns 0 on success and non-zero on error.

COPYRIGHT

National Gallery

AUTHOR

J. Cupitt - 23/7/93