VipsRegion: libvips Reference Manual

## VipsRegion VipsRegion — small, rectangular parts of images |

## Stability Level

Stable, unless otherwise indicated

## Functions

VipsRegion * | vips_region_new ()
int | vips_region_buffer ()
int | vips_region_image ()
int | vips_region_region ()
int | vips_region_equalsregion ()
int | vips_region_position ()
void | vips_region_paint ()
void | vips_region_paint_pel ()
void | vips_region_black ()
void | vips_region_copy ()
int | vips_region_shrink_method ()
int | vips_region_shrink ()
int | vips_region_prepare ()
int | vips_region_prepare_to ()
VipsPel * | vips_region_fetch ()
int | vips_region_width ()
int | vips_region_height ()
void | vips_region_invalidate ()
#define | VIPS_COUNT_PIXELS()
#define | VIPS_REGION_LSKIP()
#define | VIPS_REGION_N_ELEMENTS()
#define | VIPS_REGION_SIZEOF_ELEMENT()
#define | VIPS_REGION_SIZEOF_PEL()
#define | VIPS_REGION_SIZEOF_LINE()
#define | VIPS_REGION_ADDR()
#define | VIPS_REGION_ADDR_TOPLEFT()

## Types and Values

enum | VipsRegionShrink

## Object Hierarchy

        GEnum
        ╰── VipsRegionShrink
        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 | position of `r` in `dest` |
y | position 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 | position of `r` in `dest` |
y | position 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 | position of `r` in `dest` |
y | position 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

<link linkend="VipsImage">image</link>, <link linkend="libvips-generate">generate</link>