![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <vips/vips.h> REGION; REGION * im_region_create (IMAGE *im
); void im_region_free (REGION *reg
); int im_region_buffer (REGION *reg
,Rect *r
); int im_region_image (REGION *reg
,Rect *r
); int im_region_region (REGION *reg
,REGION *to
,Rect *r
,int x
,int y
); int im_region_equalsregion (REGION *reg1
,REGION *reg2
); int im_region_position (REGION *reg1
,int x
,int y
); #define IM_REGION_LSKIP (R) #define IM_REGION_N_ELEMENTS (R) #define IM_REGION_SIZEOF_LINE (R) #define IM_REGION_ADDR (B, X, Y) #define IM_REGION_ADDR_TOPLEFT (B)
A REGION is a small part of an image and some pixels. You use regions to read pixels out of images without having to have the whole image in memory at once.
A region can be a memory buffer, part of a memory-mapped file, part of some other image, or part of some other region.
Regions must be created, used and freed all within the same thread, since
they can reference private per-thread caches. VIPS sanity-checks region
ownership in various places, so you are likely to see g_assert()
errors if
you don't follow this rule.
There is API to transfer ownership of regions between threads, but hopefully this is only needed within VIPS, so we don't expose it. Hopefully.
typedef struct { /* Users may read these two fields. */ IMAGE *im; /* Link back to parent image */ Rect valid; /* Area of parent we can see */ /* The rest of REGION is private. */ } REGION;
A small part of an IMAGE. valid
holds the left/top/width/height of the
area of pixels that are available from the region.
See also: IM_REGION_ADDR()
, im_region_create()
, im_prepare()
.
REGION * im_region_create (IMAGE *im
);
Create a region. REGION s start out empty, you need to call im_prepare()
to
fill them with pixels.
See also: im_prepare()
, im_region_free()
.
|
image to create this region on |
void im_region_free (REGION *reg
);
Free a region and any resources it holds.
If im
has previously been closed, then freeing the last REGION on in
can
cause im
to finally be freed as well.
|
REGION to free |
int im_region_buffer (REGION *reg
,Rect *r
);
The region is transformed so that at least r
pixels are available as a
memory buffer.
|
region to operate upon |
|
Rect of pixels you need to be able to address |
Returns : |
0 on success, or -1 for error. |
int im_region_image (REGION *reg
,Rect *r
);
The region is transformed so that at least r
pixels are available directly
from the image. The image needs to be a memory buffer or represent a file
on disc that has been mapped or can be mapped.
|
region to operate upon |
|
Rect of pixels you need to be able to address |
Returns : |
0 on success, or -1 for error. |
int im_region_region (REGION *reg
,REGION *to
,Rect *r
,int x
,int y
);
Make IM_REGION_ADDR()
on reg
go to dest
instead.
r
is the part of reg
which you want to be able to address (this
effectively becomes the valid field), (x
, y
) is the top LH corner of the
corresponding area in dest
.
Performs all clipping necessary to ensure that reg->valid
is indeed
valid.
If the region we attach to is modified, we can be left with dangling pointers! If the region we attach to is on another image, the two images must have the same sizeof( pel ).
|
region to operate upon |
|
region to connect to |
|
Rect of pixels you need to be able to address |
|
postion of r in dest
|
|
postion of r in dest
|
Returns : |
0 on success, or -1 for error. |
int im_region_equalsregion (REGION *reg1
,REGION *reg2
);
Do two regions point to the same piece of image? ie.
1 2 3 |
IM_REGION_ADDR( reg1, x, y ) == IM_REGION_ADDR( reg2, x, y ) && *IM_REGION_ADDR( reg1, x, y ) == *IM_REGION_ADDR( reg2, x, y ) for all x, y, reg1, reg2. |
|
region to test |
|
region to test |
Returns : |
non-zero on equality. |
int im_region_position (REGION *reg1
,int x
,int y
);
Set the position of a region. This only affects reg->valid, ie. the way pixels are addressed, not reg->data, the pixels which are addressed. Clip against the size of the image. Do not allow negative positions, or positions outside the image.
|
region to operate upon |
|
position to move to |
|
position to move to |
Returns : |
0 on success, or -1 for error. |
#define IM_REGION_LSKIP(R)
|
a REGION |
Returns : |
The number of bytes to add to move down a scanline. |
#define IM_REGION_N_ELEMENTS(R)
|
a REGION |
Returns : |
The number of band elements across a region. |
#define IM_REGION_SIZEOF_LINE(R)
|
a REGION |
Returns : |
The number of bytes across a region. |
#define IM_REGION_ADDR(B,X,Y)
This macro returns a pointer to a pixel in a region. The (x, y) coordinates
need to be within the Rect (R->valid
).
If DEBUG is defined, you get a version that checks bounds for you.
|
a REGION |
|
x coordinate |
|
y coordinate |
Returns : |
The address of pixel (x,y) in the region. |