Regions are the next layer of abstraction above image descriptors. A region is a small part of an image, held in memory ready for processing. A region is defined as:
typedef struct { Rect valid; IMAGE *im; ... and some other private fields, ... used by VIPS for housekeeping } REGION;
where valid
holds the sub-area of image im
that this region
represents, and Rect
is defined as:
typedef struct { int left, top; int width, height; } Rect;
two macros are available for Rect
calculations:
int IM_RECT_RIGHT( Rect *r ) int IM_RECT_BOTTOM( Rect *r )
where IM_RECT_RIGHT()
returns left
+ width
, and
IM_RECT_BOTTOM()
returns top
+ height
. A small library
of C functions are also available for Rect
algebra, see the manual
pages for im_rect_intersectrect()
.
Regions are created with im_region_create()
. This has type:
REGION *im_region_create( IMAGE *im )
im_region_create()
returns a pointer to a new region structure,
or NULL
on error. Regions returned by im_region_create()
are blank -- they contain no image data and cannot be read from or written
to. See the next couple of sections for calls to fill regions with data.
Regions are destroyed with im_region_free()
. It has type:
int im_region_free( REGION *reg )
And, as usual, returns 0 on success and non-zero on error, setting
im_error()
. You must free all regions you create. If you close
an image without freeing all the regions defined on that image, the image is
just marked for future closure -- it is not actually closed until the final
region is freed. This behaviour helps to prevent dangling pointers, and it
is not difficult to make sure you free all regions -- see the examples below.