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