VipsRegion

VipsRegion — small, rectangular parts of images

Stability Level

Stable, unless otherwise indicated

Types and Values

Object Hierarchy

    GObject
    ╰── VipsObject
        ╰── VipsRegion

Includes

#include <vips/vips.h>

Description

A VipsRegion is a small part of an image. 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.

Functions

vips_region_new ()

VipsRegion *
vips_region_new (VipsImage *image);

Create a region. VipsRegion s start out empty, you need to call vips_region_prepare() to fill them with pixels.

See also: vips_region_prepare().

[constructor]

Parameters

image

image to create this region on

 

vips_region_buffer ()

int
vips_region_buffer (VipsRegion *reg,
                    const VipsRect *r);

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

Parameters

reg

region to operate upon

 

r

VipsRect of pixels you need to be able to address

 

Returns

0 on success, or -1 for error.


vips_region_image ()

int
vips_region_image (VipsRegion *reg,
                   const VipsRect *r);

The region is transformed so that at least r pixels are available to be read 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.

Parameters

reg

region to operate upon

 

r

VipsRect of pixels you need to be able to address

 

Returns

0 on success, or -1 for error.


vips_region_region ()

int
vips_region_region (VipsRegion *reg,
                    VipsRegion *dest,
                    const VipsRect *r,
                    int x,
                    int y);

Make VIPS_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 moved or destroyed, 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 ).

Parameters

reg

region to operate upon

 

dest

region to connect to

 

r

VipsRect 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.


vips_region_equalsregion ()

int
vips_region_equalsregion (VipsRegion *reg1,
                          VipsRegion *reg2);

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

1
2
3
VIPS_REGION_ADDR( reg1, x, y ) == VIPS_REGION_ADDR( reg2, x, y ) &&
*VIPS_REGION_ADDR( reg1, x, y ) == 
	*VIPS_REGION_ADDR( reg2, x, y ) for all x, y, reg1, reg2.

Parameters

reg1

region to test

 

reg2

region to test

 

Returns

non-zero on equality.


vips_region_position ()

int
vips_region_position (VipsRegion *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.

Parameters

reg

region to operate upon

 

x

position to move to

 

y

position to move to

 

Returns

0 on success, or -1 for error.


vips_region_paint ()

void
vips_region_paint (VipsRegion *reg,
                   const VipsRect *r,
                   int value);

Paints value into reg covering rectangle r . r is clipped against reg->valid .

For int images, value is passed to memset(), so it usually needs to be 0 or 255. For float images, value is cast to a float and copied in to each band element.

r is clipped against reg->valid .

See also: vips_region_black().

Parameters

reg

region to operate upon

 

r

area to paint

 

value

value to paint

 

vips_region_paint_pel ()

void
vips_region_paint_pel (VipsRegion *reg,
                       const VipsRect *r,
                       const VipsPel *ink);

Paints ink into reg covering rectangle r . r is clipped against reg->valid .

ink should be a byte array of the same size as an image pixel containing the binary value to write into the pixels.

See also: vips_region_paint().

Parameters

reg

region to operate upon

 

r

area to paint

 

ink

value to paint

 

vips_region_black ()

void
vips_region_black (VipsRegion *reg);

Paints 0 into the valid part of reg .

See also: vips_region_paint().

Parameters

reg

region to operate upon

 

vips_region_copy ()

void
vips_region_copy (VipsRegion *reg,
                  VipsRegion *dest,
                  const VipsRect *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: vips_region_paint().

Parameters

reg

source region

 

dest

destination region.

[inout]

r

VipsRect of pixels you need to copy

 

x

postion of r in dest

 

y

postion of r in dest

 

vips_region_shrink_method ()

int
vips_region_shrink_method (VipsRegion *from,
                           VipsRegion *to,
                           const VipsRect *target,
                           VipsRegionShrink method);

Write the pixels target in to from the x2 larger area in from . Non-complex uncoded images and LABQ only. Images with alpha (see vips_image_hasalpha()) shrink with pixels scaled by alpha to avoid fringing.

method selects the method used to do the 2x2 shrink.

See also: vips_region_copy().

Parameters

from

source region

 

to

destination region.

[inout]

target

VipsRect of pixels you need to copy

 

method

method to use when generating target pixels

 

vips_region_shrink ()

int
vips_region_shrink (VipsRegion *from,
                    VipsRegion *to,
                    const VipsRect *target);

Write the pixels target in to from the x2 larger area in from . Non-complex uncoded images and LABQ only. Images with alpha (see vips_image_hasalpha()) shrink with pixels scaled by alpha to avoid fringing.

This is a compatibility stub that just calls vips_region_shrink_method().

See also: vips_region_shrink_method().

[skip]

Parameters

from

source region

 

to

destination region.

[inout]

target

VipsRect of pixels you need to copy

 

vips_region_prepare ()

int
vips_region_prepare (VipsRegion *reg,
                     const VipsRect *r);

vips_region_prepare() fills reg with pixels. After calling, you can address at least the area r with VIPS_REGION_ADDR() and get valid pixels.

vips_region_prepare() runs in-line, that is, computation is done by the calling thread, no new threads are involved, and computation blocks until the pixels are ready.

Use vips_sink_screen() to calculate an area of pixels in the background.

See also: vips_sink_screen(), vips_region_prepare_to().

Parameters

reg

region to prepare

 

r

VipsRect of pixels you need to be able to address

 

Returns

0 on success, or -1 on error.


vips_region_prepare_to ()

int
vips_region_prepare_to (VipsRegion *reg,
                        VipsRegion *dest,
                        const VipsRect *r,
                        int x,
                        int y);

Like vips_region_prepare(): fill reg with the pixels in area r .

Unlike vips_region_prepare(), rather than writing the result to reg , the pixels are written into dest at offset x , y .

Also unlike vips_region_prepare(), dest is not set up for writing for you with vips_region_buffer(). You can point dest at anything, and pixels really will be written there. This makes vips_region_prepare_to() useful for making the ends of pipelines.

See also: vips_region_prepare(), vips_sink_disc().

Parameters

reg

region to prepare

 

dest

region to write to

 

r

VipsRect 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 on error


vips_region_fetch ()

VipsPel *
vips_region_fetch (VipsRegion *region,
                   int left,
                   int top,
                   int width,
                   int height,
                   size_t *len);

Generate an area of pixels and return a copy. The result must be freed with g_free(). The requested area must be completely inside the image.

This is equivalent to vips_region_prepare(), followed by a memcpy. It is convenient for language bindings.

Parameters

region

region to fetch pixels from

 

left

area of pixels to fetch

 

top

area of pixels to fetch

 

width

area of pixels to fetch

 

height

area of pixels to fetch

 

Returns

A copy of the pixel data.


vips_region_width ()

int
vips_region_width (VipsRegion *region);

Parameters

region

fetch width from this

 

Returns

Width of the pixels held in region.


vips_region_height ()

int
vips_region_height (VipsRegion *region);

Parameters

region

fetch height from this

 

Returns

Height of the pixels held in region.


vips_region_invalidate ()

void
vips_region_invalidate (VipsRegion *reg);

Mark a region as containing invalid pixels. Calling this function means that the next time vips_region_prepare() is called, the region will be recalculated.

This is faster than calling vips_image_invalidate_all(), but obviously only affects a single region.

See also: vips_image_invalidate_all(), vips_region_prepare().

Parameters

reg

region to invalidate

 

VIPS_COUNT_PIXELS()

#define VIPS_COUNT_PIXELS( R, N ) vips__region_count_pixels( R, N )

VIPS_REGION_LSKIP()

#define             VIPS_REGION_LSKIP( R )

Parameters

R

a VipsRegion

 

Returns

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


VIPS_REGION_N_ELEMENTS()

#define             VIPS_REGION_N_ELEMENTS( R )

Parameters

R

a VipsRegion

 

Returns

The number of band elements across a region.


VIPS_REGION_SIZEOF_ELEMENT()

#define             VIPS_REGION_SIZEOF_ELEMENT( R )

VIPS_REGION_SIZEOF_PEL()

#define             VIPS_REGION_SIZEOF_PEL( R )

VIPS_REGION_SIZEOF_LINE()

#define             VIPS_REGION_SIZEOF_LINE( R )

Parameters

R

a VipsRegion

 

Returns

The number of bytes across a region.


VIPS_REGION_ADDR()

#define             VIPS_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 VipsRect (R->valid ).

If DEBUG is defined, you get a version that checks bounds for you.

See also: vips_region_prepare().

Parameters

R

a VipsRegion

 

X

x coordinate

 

Y

y coordinate

 

Returns

The address of pixel (X ,Y ) in R .


VIPS_REGION_ADDR_TOPLEFT()

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

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

See also: vips_region_prepare().

Parameters

R

a VipsRegion

 

Returns

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

Types and Values

enum VipsRegionShrink

How to calculate the output pixels when shrinking a 2x2 region.

Members

VIPS_REGION_SHRINK_MEAN

use the average

 

VIPS_REGION_SHRINK_MEDIAN

use the median

 

VIPS_REGION_SHRINK_MODE

use the mode

 

VIPS_REGION_SHRINK_MAX

use the maximum

 

VIPS_REGION_SHRINK_MIN

use the minimum

 

VIPS_REGION_SHRINK_NEAREST

use the top-left pixel

 

VIPS_REGION_SHRINK_LAST

   

See Also

image, generate