| .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 |
