next up previous contents
Next: 3.3 Image input with Up: 3. Programming PIO functions Previous: 3.1 Easy PIO with   Contents

3.2 Region descriptors

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.


next up previous contents
Next: 3.3 Image input with Up: 3. Programming PIO functions Previous: 3.1 Easy PIO with   Contents
John Cupitt 2005-04-11