region-operations(3)

NAME

im_region_local, im_region_image, im_region_region, im_re

gion_position, im_region_equalsregion - attach data to region

SYNOPSIS

#include <vips/vips.h>
#include <vips/region.h>
int im_region_local( 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_local(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_pre

pare_copy(3) and the VIPS Library Programmers' Guide.

im_region_local(3) clips Rect r against the size of the

image upon which reg is defined, then allocates enough local mem

ory for the region to be able to hold all of the pels still in

side r.

Memory that has been allocated to a region is freed only

when the region is destroyed, or when a later call to im_re

gion_local(3) asks for more pels than can be fitted into the ini

tial piece. So ... malloc(3) is not called often.

im_region_local(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 or MMAPINRW --

ie., the type make by im_incheck(3).

im_region_region(3) redirects reg to treg. treg can be de

fined on another image. r is clipped against the size of reg's

image, and against treg->valid. treg has to have pel data asso

ciated 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 them

selves! 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 appli

cations.

RETURN VALUE

All int-valued functions return zero on success and non

zero on error.

COPYRIGHT

National Gallery, 1993

SEE ALSO

`VIPS Library Programmers' Guide,' in accompanying docu

mentation.

AUTHOR

J. Cupitt - 23/7/93

11 April 1990 REGION

OPERATIONS(3)