region

region — small, rectangular parts of images

Stability Level

Stable, unless otherwise indicated

Synopsis

#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 *dest,
                                                         Rect *r,
                                                         int x,
                                                         int y);
int                 im_region_equalsregion              (REGION *reg1,
                                                         REGION *reg2);
int                 im_region_position                  (REGION *reg,
                                                         int x,
                                                         int y);
void                im_region_paint                     (REGION *reg,
                                                         Rect *r,
                                                         int value);
void                im_region_black                     (REGION *reg);
void                im_region_copy                      (REGION *reg,
                                                         REGION *dest,
                                                         Rect *r,
                                                         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                      (R,
                                                         X,
                                                         Y)
#define             IM_REGION_ADDR_TOPLEFT              (R)

Description

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.

Details

REGION

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().

IMAGE *im;

the IMAGE that this region is defined on

Rect valid;

the Rect of pixels that this region represents

im_region_create ()

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().

im :

image to create this region on

im_region_free ()

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.

reg :

REGION to free

im_region_buffer ()

int                 im_region_buffer                    (REGION *reg,
                                                         Rect *r);

The region is transformed so that at least r pixels are available as a memory buffer.

reg :

region to operate upon

r :

Rect of pixels you need to be able to address

Returns :

0 on success, or -1 for error.

im_region_image ()

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.

reg :

region to operate upon

r :

Rect of pixels you need to be able to address

Returns :

0 on success, or -1 for error.

im_region_region ()

int                 im_region_region                    (REGION *reg,
                                                         REGION *dest,
                                                         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 ).

reg :

region to operate upon

dest :

region to connect to

r :

Rect of pixels you need to be able to address

x :

postion of r in dest

y :

postion of r in dest

Returns :

0 on success, or -1 for error.

im_region_equalsregion ()

int                 im_region_equalsregion              (REGION *reg1,
                                                         REGION *reg2);

Do two regions point to the same piece of image? ie.

	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.

reg1 :

region to test

reg2 :

region to test

Returns :

non-zero on equality.

im_region_position ()

int                 im_region_position                  (REGION *reg,
                                                         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.

reg :

region to operate upon

x :

position to move to

y :

position to move to

Returns :

0 on success, or -1 for error.

im_region_paint ()

void                im_region_paint                     (REGION *reg,
                                                         Rect *r,
                                                         int value);

Paints value into reg covering rectangle r. value is passed to memset(), so it usually needs to be 0 or 255. r is clipped against reg->valid.

See also: im_region_black().

reg :

region to operate upon

r :

area to paint

value :

value to paint

im_region_black ()

void                im_region_black                     (REGION *reg);

Paints 0 into the valid part of reg.

See also: im_region_paint().

reg :

region to operate upon

im_region_copy ()

void                im_region_copy                      (REGION *reg,
                                                         REGION *dest,
                                                         Rect *r,
                                                         int x,
                                                         int y);

Copy from one region to another. Copy area r from inside reg to dest, positioning the area of pixels at x, y. The two regions must have pixels which are the same size.

See also: im_region_paint().

reg :

source region

dest :

destination region

r :

Rect of pixels you need to copy

x :

postion of r in dest

y :

postion of r in dest

IM_REGION_LSKIP()

#define             IM_REGION_LSKIP(R)

R :

a REGION

Returns :

The number of bytes to add to move down a scanline.

IM_REGION_N_ELEMENTS()

#define             IM_REGION_N_ELEMENTS(R)

R :

a REGION

Returns :

The number of band elements across a region.

IM_REGION_SIZEOF_LINE()

#define             IM_REGION_SIZEOF_LINE(R)

R :

a REGION

Returns :

The number of bytes across a region.

IM_REGION_ADDR()

#define             IM_REGION_ADDR(R,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.

R :

a REGION

X :

x coordinate

Y :

y coordinate

Returns :

The address of pixel (x,y) in the region.

IM_REGION_ADDR_TOPLEFT()

#define IM_REGION_ADDR_TOPLEFT(R)   ( (R)->data )

This macro returns a pointer to the top-left pixel in the REGION, that is, the pixel at (R->valid.left, R->valid.top).

R :

a REGION

Returns :

The address of the top-left pixel in the region.

See Also

image, generate