118 lines
3.2 KiB
Groff
118 lines
3.2 KiB
Groff
.TH REGION-OPERATIONS 3 "11 April 1990"
|
|
.SH NAME
|
|
im_region_buffer, im_region_image, im_region_region, im_region_position,
|
|
im_region_equalsregion \-
|
|
attach data to region
|
|
.SH SYNOPSIS
|
|
.B #include <vips/vips.h>
|
|
|
|
int im_region_buffer( reg, r )
|
|
.br
|
|
REGION *reg;
|
|
.br
|
|
Rect *r;
|
|
|
|
int im_region_image( reg, r )
|
|
.br
|
|
REGION *reg;
|
|
.br
|
|
Rect *r;
|
|
|
|
int im_region_region( reg, treg, r, x, y )
|
|
.br
|
|
REGION *reg, treg;
|
|
.br
|
|
Rect *r;
|
|
.br
|
|
int x, y;
|
|
|
|
int im_region_position( reg, x, y )
|
|
.br
|
|
REGION *reg;
|
|
.br
|
|
int x, y;
|
|
|
|
int im_region_equalsregion( REGION *reg1, REGION *reg2 )
|
|
|
|
.SH DESCRIPTION
|
|
These functions are used to say where exactly input from or output to a
|
|
region goes. Briefly,
|
|
.B im_region_buffer(3)
|
|
gives a region its own piece of local storage,
|
|
.B im_region_image(3)
|
|
links the region to an image, and
|
|
.B im_region_region(3)
|
|
links the region to another region.
|
|
|
|
.B im_region_region(3)
|
|
is the most powerful of the three --- you can use it to
|
|
avoid copy operations. See the source for
|
|
.B im_extract(3),
|
|
.B im_insert(3),
|
|
.B im_copy(3),
|
|
.B im_embed(3),
|
|
and
|
|
.B im_lrmerge(3)
|
|
for examples of its use, and see also
|
|
.B im_prepare_copy(3).
|
|
|
|
.B im_region_buffer(3)
|
|
clips Rect r against the size of the image upon which reg is
|
|
defined, then searches for any calculated pixels which enclose that area. If
|
|
there are any suitable pixels already, the region is set to point to them.
|
|
Otherwise, a fresh buffer is allocated.
|
|
|
|
If region->buffer->done is set, then the region is already calculated.
|
|
Otherwise, the pixels need to be calculated.
|
|
|
|
.B im_region_buffer(3)
|
|
is called by
|
|
.B im_prepare(3)
|
|
just before it calls the user generate function.
|
|
|
|
.B im_region_image(3)
|
|
attaches reg to the image on which it was defined. The image
|
|
has to be SETBUF, MMAPIN, MMAPINRW, or OPENIN --- ie., the types passed by
|
|
.B im_incheck(3).
|
|
|
|
.B im_region_region(3)
|
|
redirects reg to treg. treg can be defined on another
|
|
image. r is clipped against the size of reg's image, and against treg->valid.
|
|
treg has to have pel data associated with it (ie. memory local to treg, memory
|
|
that is part of the image on which treg is defined, or even memory from a
|
|
third region), and the pel data has to be in a form which is compatible with
|
|
reg, ie. BandFmt and Bands must be the same.
|
|
|
|
r becomes the valid field in reg, (x,y) is the top left-hand corner of the
|
|
area in treg to which valid is mapped.
|
|
|
|
|
|
.B im_region_position(3)
|
|
changes reg->valid, so that reg->valid.left == x and
|
|
reg->valid.top == y. width and height are clipped against the size of the
|
|
image. If x < 0 or y < 0 or the clipped rect has zero width or height, the
|
|
call fails.
|
|
|
|
This function affects the way that pels are addressed by the
|
|
.B IM_REGION_ADDR(3)
|
|
macro. It does not affect the pels themselves! It has the effect of moving
|
|
the area of pels a region represents. This call is used by
|
|
.B im_extract(3).
|
|
|
|
.B im_region_equalsregion(3)
|
|
tests for reg1 and reg2 are identical, ie.:
|
|
|
|
IM_REGION_ADDR( reg1, x, y ) ==
|
|
IM_REGION_ADDR( reg2, x, y ) &&
|
|
*IM_REGION_ADDR( reg1, x, y ) ==
|
|
*IM_REGION_ADDR( reg2, x, y )
|
|
|
|
It is used internally by VIPS, but may be useful to applications.
|
|
|
|
.SH RETURN VALUE
|
|
All int-valued functions return zero on success and non-zero on error.
|
|
.SH COPYRIGHT
|
|
National Gallery, 1993
|
|
.SH AUTHOR
|
|
J. Cupitt \- 23/7/93
|