IM_PREPARE(3)

NAME
im_prepare, im_prepare_to - fill region with data

SYNOPSIS
#include <vips/vips.h>
#include <vips/region.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;

DESCRIPTION
im_prepare(3) fills region reg with pels covering the area inside r. See `VIPS Library Programmers' Guide,' in the accompanying documentation for an introduction to this call. 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_local(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.

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

SEE ALSO
im_generate(3), im_open(3). `VIPS Library Programmers' Guide,' in accompanying documentation.

COPYRIGHT
National Gallery

AUTHOR
J. Cupitt - 23/7/93