1REGION-OPERATIONS(3)       Library Functions Manual       REGION-OPERATIONS(3)
2
3
4

NAME

6       im_region_local, im_region_image, im_region_region, im_region_position,
7       im_region_equalsregion - attach data to region
8

SYNOPSIS

10       #include <vips/vips.h>
11       #include <vips/region.h>
12
13       int im_region_local( reg, r )
14       REGION *reg;
15       Rect *r;
16
17       int im_region_image( reg, r )
18       REGION *reg;
19       Rect *r;
20
21       int im_region_region( reg, treg, r, x, y )
22       REGION *reg, treg;
23       Rect *r;
24       int x, y;
25
26       int im_region_position( reg, x, y )
27       REGION *reg;
28       int x, y;
29
30       int im_region_equalsregion( REGION *reg1, REGION *reg2 )
31
32

DESCRIPTION

34       These functions are used to say where exactly input from or output to a
35       region  goes.  Briefly, im_region_local(3) gives a region its own piece
36       of local storage, im_region_image(3) links the region to an image,  and
37       im_region_region(3) links the region to another region.
38
39       im_region_region(3)  is  the most powerful of the three --- you can use
40       it  to  avoid  copy  operations.  See  the  source  for  im_extract(3),
41       im_insert(3),  im_copy(3),  im_embed(3), and im_lrmerge(3) for examples
42       of its use, and see also im_prepare_copy(3) and the VIPS  Library  Pro‐
43       grammers' Guide.
44
45       im_region_local(3)  clips  Rect  r  against  the size of the image upon
46       which reg is defined, then allocates enough local memory for the region
47       to be able to hold all of the pels still inside r.
48
49       Memory  that  has  been  allocated  to  a region is freed only when the
50       region is destroyed, or when a later call  to  im_region_local(3)  asks
51       for  more  pels  than can be fitted into the initial piece. So ... mal‐
52       loc(3) is not called often.
53
54       im_region_local(3) is called by im_prepare(3) just before it calls  the
55       user generate function.
56
57       im_region_image(3)  attaches  reg to the image on which it was defined.
58       The image has to be SETBUF, MMAPIN or MMAPINRW --- ie., the  type  make
59       by im_incheck(3).
60
61       im_region_region(3)  redirects  reg  to  treg.  treg  can be defined on
62       another image. r is clipped  against  the  size  of  reg's  image,  and
63       against treg->valid.  treg has to have pel data associated with it (ie.
64       memory local to treg, memory that is part of the image on which treg is
65       defined,  or  even memory from a third region), and the pel data has to
66       be in a form which is compatible with reg, ie. BandFmt and  Bands  must
67       be the same.
68
69       r  becomes the valid field in reg, (x,y) is the top left-hand corner of
70       the area in treg to which valid is mapped.
71
72       im_region_position(3) changes reg->valid, so that reg->valid.left ==  x
73       and  reg->valid.top == y. width and height are clipped against the size
74       of the image. If x < 0 or y < 0 or the clipped rect has zero  width  or
75       height, the call fails.
76
77       This   function  affects  the  way  that  pels  are  addressed  by  the
78       IM_REGION_ADDR(3) macro. It does not affect the pels themselves! It has
79       the effect of moving the area of pels a region represents. This call is
80       used by im_extract(3).
81
82       im_region_equalsregion(3) tests for reg1 and reg2 are identical, ie.:
83
84          IM_REGION_ADDR( reg1, x, y ) ==
85            IM_REGION_ADDR( reg2, x, y ) &&
86          *IM_REGION_ADDR( reg1, x, y ) ==
87            *IM_REGION_ADDR( reg2, x, y )
88
89       It is used internally by VIPS, but may be useful to applications.
90
91

RETURN VALUE

93       All int-valued functions return zero on success and non-zero on error.
94

96       National Gallery, 1993
97

SEE ALSO

99       `VIPS Library Programmers' Guide,' in accompanying documentation.
100

AUTHOR

102       J. Cupitt - 23/7/93
103
104
105
106                                 11 April 1990            REGION-OPERATIONS(3)
Impressum