90 lines
2.1 KiB
Groff
90 lines
2.1 KiB
Groff
.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
|