## inplace

inplace — in-place paintbox operations: flood, paste, line, circle

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    int                 im_draw_rect                        (VipsImage *image,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             int fill,
                                                             VipsPel *ink);
    int                 im_draw_circle                      (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             int radius,
                                                             gboolean fill,
                                                             VipsPel *ink);
    int                 im_draw_image                       (VipsImage *image,
                                                             VipsImage *sub,
                                                             int x,
                                                             int y);
    int                 (*VipsPlotFn)                       (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             void *a,
                                                             void *b,
                                                             void *c);
    int                 im_draw_line_user                   (VipsImage *image,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2,
                                                             VipsPlotFn plot,
                                                             void *a,
                                                             void *b,
                                                             void *c);
    int                 im_draw_line                        (VipsImage *image,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2,
                                                             VipsPel *ink);
    int                 im_lineset                          (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsImage *mask,
                                                             VipsImage *ink,
                                                             int n,
                                                             int *x1v,
                                                             int *y1v,
                                                             int *x2v,
                                                             int *y2v);
    int                 im_draw_flood                       (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink,
                                                             VipsRect *dout);
    int                 im_draw_flood_blob                  (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink,
                                                             VipsRect *dout);
    int                 im_draw_flood_other                 (VipsImage *image,
                                                             VipsImage *test,
                                                             int x,
                                                             int y,
                                                             int serial,
                                                             VipsRect *dout);
    int                 im_draw_mask                        (VipsImage *image,
                                                             VipsImage *mask_im,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink);
    int                 im_draw_point                       (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink);
    int                 im_read_point                       (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink);
    int                 im_draw_smudge                      (VipsImage *image,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height);

## Description

These operations directly modify the image. They do not thread, on 32-bit machines they will be limited to 2GB images, and a little care needs to be taken if you use them as part of an image pipeline.

They are mostly supposed to be useful for paintbox-style programs.

## Details

### im_draw_rect ()

    int                 im_draw_rect                        (VipsImage *image,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             int fill,
                                                             VipsPel *ink);

Paint pixels within `left`, `top`, `width`, `height` in `image` with `ink`. If `fill` is zero, just paint a 1-pixel-wide outline.

See also: `im_draw_circle()`.

`image` : | image to draw on
`left` : | area to paint
`top` : | area to paint
`width` : | area to paint
`height` : | area to paint
`fill` : | fill the rect
`ink` : | paint with this colour
Returns : | 0 on success, or -1 on error.

### im_draw_circle ()

    int                 im_draw_circle                      (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             int radius,
                                                             gboolean fill,
                                                             VipsPel *ink);

Draws a circle on `image`. If `fill` is `TRUE` then the circle is filled, otherwise a 1-pixel-wide perimeter is drawn.

`ink` is an array of bytes containing a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( `image` ) bytes.

See also: `im_draw_line()`.

`image` : | image to draw on
`x` : | centre of circle
`y` : | centre of circle
`radius` : | circle radius
`fill` : | fill the circle
`ink` : | value to draw
Returns : | 0 on success, or -1 on error.

### im_draw_image ()

    int                 im_draw_image                       (VipsImage *image,
                                                             VipsImage *sub,
                                                             int x,
                                                             int y);

Draw `sub` on top of `image` at position `x`, `y`. The two images must have the same Coding. If `sub` has 1 band, the bands will be duplicated to match the number of bands in `image`. `sub` will be converted to `image`'s format, see `im_clip2fmt()`.

See also: `im_insert()`.

`image` : | image to draw on
`sub` : | image to draw
`x` : | position to insert
`y` : | position to insert
Returns : | 0 on success, or -1 on error.

### VipsPlotFn ()

    int                 (*VipsPlotFn)                       (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             void *a,
                                                             void *b,
                                                             void *c);

A plot function, as used by `im_draw_line_user()` to draw on an image.

`image` : | image to draw on
`x` : | position to draw at
`y` : | position to draw at
`a` : | user data
`b` : | user data
`c` : | user data

### im_draw_line_user ()

    int                 im_draw_line_user                   (VipsImage *image,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2,
                                                             VipsPlotFn plot,
                                                             void *a,
                                                             void *b,
                                                             void *c);

Calls `plot` for every point on the line connecting `x1`, `y1` and `x2`, `y2`. If you pass `im_draw_mask()` as the plot operation, you can draw wide lines or lines with various brushes.

See also: `im_draw_mask()`, `im_draw_line()`, `im_draw_circle()`.

`image` : | image to draw on
`x1` : | start point
`y1` : | start point
`x2` : | end point
`y2` : | end point
`plot` : | draw operation
`a` : | draw operation parameter
`b` : | draw operation parameter
`c` : | draw operation parameter
Returns : | 0 on success, or -1 on error.

### im_draw_line ()

    int                 im_draw_line                        (VipsImage *image,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2,
                                                             VipsPel *ink);

Draws a 1-pixel-wide line on an image.

`ink` is an array of bytes containing a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( `image` ) bytes.

See also: `im_draw_circle()`.

`image` : | image to draw on
`x1` : | start point
`y1` : | start point
`x2` : | end point
`y2` : | end point
`ink` : | value to draw
Returns : | 0 on success, or -1 on error.

### im_lineset ()

    int                 im_lineset                          (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsImage *mask,
                                                             VipsImage *ink,
                                                             int n,
                                                             int *x1v,
                                                             int *y1v,
                                                             int *x2v,
                                                             int *y2v);

### im_draw_flood ()

    int                 im_draw_flood                       (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink,
                                                             VipsRect *dout);

Flood-fill `image` with `ink`, starting at position `x`, `y`. The filled area is bounded by pixels that are equal to the ink colour, in other words, it searches for pixels enclosed by a line of `ink`.

The bounding box of the modified pixels is returned in `dout`. `dout` may be NULL.

See also: `im_draw_flood_blob()`, `im_draw_flood_other()`.

`image` : | image to fill
`x` : | position to start fill
`y` : | position to start fill
`ink` : | colour to fill with
`dout` : | output the bounding box of the filled area
Returns : | 0 on success, or -1 on error.

### im_draw_flood_blob ()

    int                 im_draw_flood_blob                  (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink,
                                                             VipsRect *dout);

Flood-fill `image` with `ink`, starting at position `x`, `y`. The filled area is bounded by pixels that are equal to the start pixel, in other words, it searches for a blob of same-coloured pixels.

The bounding box of the modified pixels is returned in `dout`. `dout` may be NULL.

See also: `im_draw_flood()`, `im_draw_flood_other()`, `im_draw_flood_blob()`.

`image` : | image to fill
`x` : | position to start fill
`y` : | position to start fill
`ink` : | colour to fill with
`dout` : | output the bounding box of the filled area
Returns : | 0 on success, or -1 on error.

### im_draw_flood_other ()

    int                 im_draw_flood_other                 (VipsImage *image,
                                                             VipsImage *test,
                                                             int x,
                                                             int y,
                                                             int serial,
                                                             VipsRect *dout);

Flood-fill `image` with `serial`, starting at position `x`, `y`. The filled area is bounded by pixels in `test` that are equal to the start pixel, in other words, it searches `test` for a blob of same-coloured pixels, marking those pixels in `image` with `serial`.

The bounding box of the modified pixels is returned in `dout`. `dout` may be NULL.

See also: `im_draw_flood()`, `im_label_regions()`, `im_draw_flood_blob()`.

`image` : | image to mark
`test` : | image to test
`x` : | position to start fill
`y` : | position to start fill
`serial` : | mark pixels with this number
`dout` : | output the bounding box of the filled area
Returns : | 0 on success, or -1 on error.

### im_draw_mask ()

    int                 im_draw_mask                        (VipsImage *image,
                                                             VipsImage *mask_im,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink);

Draw a mask on the image. `mask_im` is a monochrome 8-bit image with 0/255 for transparent or `ink` coloured points. Intermediate values blend the ink with the pixel. Use with `im_text()` to draw text on an image.

`ink` is an array of bytes containing a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( `image` ) bytes.

See also: `im_draw_circle()`, `im_text()`, `im_draw_line_user()`.

`image` : | image to draw on
`mask_im` : | mask of 0/255 values showing where to plot
`x` : | draw mask here
`y` : | draw mask here
`ink` : | value to draw
Returns : | 0 on success, or -1 on error.

### im_draw_point ()

    int                 im_draw_point                       (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink);

Draws a single point on an image.

`ink` is an array of bytes containing a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( `im` ) bytes.

See also: `im_draw_line()`.

`image` : | image to draw on
`x` : | position to draw
`y` : | position to draw
`ink` : | value to draw
Returns : | 0 on success, or -1 on error.

### im_read_point ()

    int                 im_read_point                       (VipsImage *image,
                                                             int x,
                                                             int y,
                                                             VipsPel *ink);

Reads a single point on an image.

`ink` is an array of bytes to contain a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( `im` ) bytes.

See also: `im_draw_point()`.

`image` : | image to read from
`x` : | position to read
`y` : | position to read
`ink` : | read value here
Returns : | 0 on success, or -1 on error.

### im_draw_smudge ()

    int                 im_draw_smudge                      (VipsImage *image,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height);

Smudge a section of `image`. Each pixel in the area `left`, `top`, `width`, `height` is replaced by the average of the surrounding 3x3 pixels.

This an inplace operation, so `image` is changed. It does not thread and will not work well as part of a pipeline. On 32-bit machines it will be limited to 2GB images.

See also: `im_draw_line()`.

`image` : | image to smudge
`left` : | area to smudge
`top` : | area to smudge
`width` : | area to smudge
`height` : | area to smudge
Returns : | 0 on success, or -1 on error.