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_errorstring`. 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: 3.3 Image input with Up: 3. Programming PIO functions Previous: 3.1 Easy PIO with Contents