NAME
im_prepare, im_prepare_to - fill region with data
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.
SEE ALSO
im_generate(3), im_open(3).
COPYRIGHT
National Gallery
AUTHOR
J. Cupitt - 23/7/93
11 April 1990 IM_PREPARE(3)