NAME
im_region_buffer, im_region_image, im_region_region,
im_region_position, im_region_equalsregion - attach data to region
SYNOPSIS
#include <vips/vips.h>
int im_region_buffer( reg, r )
REGION *reg;
Rect *r;
int im_region_image( reg, r )
REGION *reg;
Rect *r;
int im_region_region( reg, treg, r, x, y )
REGION *reg, treg;
Rect *r;
int x, y;
int im_region_position( reg, x, y )
REGION *reg;
int x, y;
int im_region_equalsregion( REGION *reg1, REGION *reg2 )
DESCRIPTION
These functions are used to say where exactly input from or output to a
region goes. Briefly, im_region_buffer(3) gives a region its own piece
of local storage, im_region_image(3) links the region to an image, and
im_region_region(3) links the region to another region.
im_region_region(3) is the most powerful of the three --- you can use
it to avoid copy operations. See the source for im_extract(3),
im_insert(3), im_copy(3), im_embed(3), and im_lrmerge(3) for examples
of its use, and see also im_prepare_copy(3).
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.
im_region_buffer(3) is called by im_prepare(3) just before it calls the
user generate function.
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 im_incheck(3).
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.
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
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 im_extract(3).
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.
RETURN VALUE
All int-valued functions return zero on success and non-zero on error.
COPYRIGHT
National Gallery, 1993
AUTHOR
J. Cupitt - 23/7/93
11 April 1990 REGION-OPERATIONS(3)