draw: libvips Reference Manual

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

libvips operations are all functional: they take zero or more existing input images and generate zero or more new output images. Images are never altered, you always create new images. This means libvips can cache and thread very agressively.

The downside is that creating entirely fresh images each time can be very slow. libvips has a range of tricks to avoid these problems, but there are still times when you really have to be able to modify an image. An example might be drawing a curved line from a set of straight line segments: if you need to draw 1,000 straight lines, a 1,000 operation-deep pipeline is going to be a slow way to do it. This is where the draw operations come in.

To use these operations, use `vips_copy()` to make a copy of the image you want to modify to ensure that no one else is using it, then call a series of draw operations. Once you are done drawing, return to normal use of vips operations. Any time you want to start drawing again, you'll need to copy again.

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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

[method]

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