---
name: "im_region_local"
section: "3"
platform: "linux"
package: "libvips10-dev"
version: "7.10.21-1"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/im_region_local"
---

# im\_region\_local(3)

attach data to region

## NAME

im\_region\_local, im\_region\_image, im\_region\_region, im\_region\_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)](/im_region_local/3.md) gives a region its own piece of local storage, [im\_region\_image(3)](/im_region_image/3.md) links the region to an image, and [im\_region\_region(3)](/im_region_region/3.md) links the region to another region.

[im\_region\_region(3)](/im_region_region/3.md) is the most powerful of the three --- you can use it to avoid copy operations. See the source for [im\_extract(3)](/im_extract/3.md), [im\_insert(3)](/im_insert/3.md), [im\_copy(3)](/im_copy/3.md), [im\_embed(3)](/im_embed/3.md), and [im\_lrmerge(3)](/im_lrmerge/3.md) for examples of its use, and see also im\_prepare\_copy(3) and the VIPS Library Programmers' Guide.

[im\_region\_local(3)](/im_region_local/3.md) clips Rect r against the size of the image upon which reg is defined, then allocates enough local memory for the region to be able to hold all of the pels still inside r.

Memory that has been allocated to a region is freed only when the region is destroyed, or when a later call to [im\_region\_local(3)](/im_region_local/3.md) asks for more pels than can be fitted into the initial piece. So ... [malloc(3)](/malloc/3.md) is not called often.

[im\_region\_local(3)](/im_region_local/3.md) is called by [im\_prepare(3)](/im_prepare/3.md) just before it calls the user generate function.

[im\_region\_image(3)](/im_region_image/3.md) 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_incheck/3.md).

[im\_region\_region(3)](/im_region_region/3.md) 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)](/im_region_position/3.md) 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)](/IM_REGION_ADDR/3.md) 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_extract/3.md).

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

## SEE ALSO

\`VIPS Library Programmers' Guide,' in accompanying documentation.

## AUTHOR

J. Cupitt - 23/7/93