## draw

draw — drawing operations: flood, paste, line, circle

## Stability Level

Stable, unless otherwise indicated

## Functions

int | vips_draw_rect ()
int | vips_draw_rect1 ()
int | vips_draw_point ()
int | vips_draw_point1 ()
int | vips_draw_image ()
int | vips_draw_mask ()
int | vips_draw_mask1 ()
int | vips_draw_line ()
int | vips_draw_line1 ()
int | vips_draw_circle ()
int | vips_draw_circle1 ()
int | vips_draw_flood ()
int | vips_draw_flood1 ()
int | vips_draw_smudge ()

## Types and Values

enum | VipsCombineMode

## Includes

    #include <vips/vips.h>

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

## Functions

### vips_draw_rect ()

    int
    vips_draw_rect (VipsImage *image,
                    double *ink,
                    int n,
                    int left,
                    int top,
                    int width,
                    int height,
                    ...);

Optional arguments:

`fill` : fill the rect

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

See also: `vips_draw_circle()`.

#### Parameters

image | image to draw on |
ink | value to draw. | [array length=n]
n | length of ink array |
left | area to paint |
top | area to paint |
width | area to paint |
height | area to paint |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_rect1 ()

    int
    vips_draw_rect1 (VipsImage *image,
                     double ink,
                     int left,
                     int top,
                     int width,
                     int height,
                     ...);

Optional arguments:

`fill` : fill the rect

As `vips_draw_rect()`, but just take a single double for `ink` .

See also: `vips_draw_rect()`.

#### Parameters

image | image to draw on |
ink | value to draw |
left | area to paint |
top | area to paint |
width | area to paint |
height | area to paint |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_point ()

    int
    vips_draw_point (VipsImage *image,
                     double *ink,
                     int n,
                     int x,
                     int y,
                     ...);

As `vips_draw_rect()`, but draw a single pixel at `x` , `y` .

See also: `vips_draw_rect()`.

#### Parameters

image | image to draw on |
ink | value to draw. | [array length=n]
n | length of ink array |
x | point to paint |
y | point to paint |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_point1 ()

    int
    vips_draw_point1 (VipsImage *image,
                      double ink,
                      int x,
                      int y,
                      ...);

As `vips_draw_point()`, but just take a single double for `ink` .

See also: `vips_draw_point()`.

#### Parameters

image | image to draw on |
ink | value to draw |
x | point to draw |
y | point to draw |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_image ()

    int
    vips_draw_image (VipsImage *image,
                     VipsImage *sub,
                     int x,
                     int y,
                     ...);

Optional arguments:

`mode` : how to combine pixels

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

Use `mode` to set how pixels are combined. If you use VIPS_COMBINE_MODE_ADD, both images muct be uncoded.

See also: `vips_draw_mask()`, `vips_insert()`.

#### Parameters

image | image to draw on |
sub | image to paint |
x | draw `sub` here |
y | draw `sub` here |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_mask ()

    int
    vips_draw_mask (VipsImage *image,
                    double *ink,
                    int n,
                    VipsImage *mask,
                    int x,
                    int y,
                    ...);

Draw `mask` on the image. `mask` 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 `vips_text()` to draw text on an image. Use in a `vips_draw_line()` subclass to draw an object along a line.

`ink` is an array of double containing values to draw.

See also: `vips_text()`, `vips_draw_line()`.

#### Parameters

image | image to draw on |
ink | value to draw. | [array length=n]
n | size of ink array |
mask | mask of 0/255 values showing where to plot |
x | draw mask here |
y | draw mask here |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_mask1 ()

    int
    vips_draw_mask1 (VipsImage *image,
                     double ink,
                     VipsImage *mask,
                     int x,
                     int y,
                     ...);

As `vips_draw_mask()`, but just takes a single double for `ink` .

See also: `vips_draw_mask()`.

#### Parameters

image | image to draw on |
ink | value to draw |
mask | mask of 0/255 values showing where to plot |
x | draw mask here |
y | draw mask here |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_line ()

    int
    vips_draw_line (VipsImage *image,
                    double *ink,
                    int n,
                    int x1,
                    int y1,
                    int x2,
                    int y2,
                    ...);

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

`ink` is an array of double containing values to draw.

See also: `vips_draw_line1()`, `vips_draw_circle()`, `vips_draw_mask()`.

#### Parameters

image | image to draw on |
ink | value to draw. | [array length=n]
n | length of ink array |
x1 | start of draw_line |
y1 | start of draw_line |
x2 | end of draw_line |
y2 | end of draw_line |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_line1 ()

    int
    vips_draw_line1 (VipsImage *image,
                     double ink,
                     int x1,
                     int y1,
                     int x2,
                     int y2,
                     ...);

As `vips_draw_line()`, but just take a single double for `ink` .

See also: `vips_draw_line()`.

#### Parameters

image | image to draw on |
ink | value to draw |
x1 | start of draw_line |
y1 | start of draw_line |
x2 | end of draw_line |
y2 | end of draw_line |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_circle ()

    int
    vips_draw_circle (VipsImage *image,
                      double *ink,
                      int n,
                      int cx,
                      int cy,
                      int radius,
                      ...);

Optional arguments:

`fill` : fill the draw_circle

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 double containing values to draw.

See also: `vips_draw_circle1()`, `vips_draw_line()`.

#### Parameters

image | image to draw on |
ink | value to draw. | [array length=n]
n | length of ink array |
cx | centre of draw_circle |
cy | centre of draw_circle |
radius | draw_circle radius |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_circle1 ()

    int
    vips_draw_circle1 (VipsImage *image,
                       double ink,
                       int cx,
                       int cy,
                       int radius,
                       ...);

Optional arguments:

`fill` : fill the draw_circle

As `vips_draw_circle()`, but just takes a single double for `ink` .

See also: `vips_draw_circle()`.

#### Parameters

image | image to draw on |
ink | value to draw |
cx | centre of draw_circle |
cy | centre of draw_circle |
radius | draw_circle radius |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_flood ()

    int
    vips_draw_flood (VipsImage *image,
                     double *ink,
                     int n,
                     int x,
                     int y,
                     ...);

Optional arguments:

`test` : test this image `equal` : fill while equal to edge `left` : output left edge of bounding box of modified area `top` : output top edge of bounding box of modified area `width` : output width of bounding box of modified area `height` : output height of bounding box of modified area

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 an edge of `ink` .

If `equal` is set, it instead searches for pixels which are equal to the start point and fills them with `ink` .

Normally it will test and set pixels in `image` . If `test` is set, it will test pixels in `test` and set pixels in `image` . This lets you search an image (`test` ) for continuous areas of pixels without modifying it.

`left` , `top` , `width` , `height` output the bounding box of the modified pixels.

`ink` is an array of double containing values to draw.

See also: `vips_draw_flood1()`.

#### Parameters

image | image to draw on |
ink | value to draw. | [array length=n]
n | length of ink array |
x | centre of circle |
y | centre of circle |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_flood1 ()

    int
    vips_draw_flood1 (VipsImage *image,
                      double ink,
                      int x,
                      int y,
                      ...);

Optional arguments:

`test` : test this image `equal` : fill while equal to edge `left` : output left edge of bounding box of modified area `top` : output top edge of bounding box of modified area `width` : output width of bounding box of modified area `height` : output height of bounding box of modified area

As `vips_draw_flood()`, but just takes a single double for `ink` .

See also: `vips_draw_flood()`.

#### Parameters

image | image to draw on |
ink | value to draw |
x | centre of circle |
y | centre of circle |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_draw_smudge ()

    int
    vips_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.

See also: `vips_draw_line()`.

#### Parameters

image | image to draw on |
left | point to paint |
top | point to paint |
width | area to paint |
height | area to paint |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

## Types and Values

### enum VipsCombineMode

See `vips_draw_image()` and so on.

Operations like `vips_draw_image()` need to be told how to combine images from two sources.

See also: `vips_join()`.

#### Members

VIPS_COMBINE_MODE_SET | set pixels to the new value |
VIPS_COMBINE_MODE_ADD | add pixels |
VIPS_COMBINE_MODE_LAST |  |