Top |
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 () |
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 |
|
... |
|
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 |
|
... |
|
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 |
|
... |
|
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 |
|
... |
|
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 |
|
y |
draw |
|
... |
|
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 |
|
... |
|
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 |
|
... |
|
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 |
|
... |
|
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 |
|
... |
|
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 |
|
... |
|
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 |
|
... |
|
vips_draw_flood ()
int vips_draw_flood (VipsImage *image
,double *ink
,int n
,int x
,int y
,...
);
Optional arguments:
test
: test this imageequal
: fill while equal to edgeleft
: output left edge of bounding box of modified areatop
: output top edge of bounding box of modified areawidth
: output width of bounding box of modified areaheight
: 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 |
|
... |
|
vips_draw_flood1 ()
int vips_draw_flood1 (VipsImage *image
,double ink
,int x
,int y
,...
);
Optional arguments:
test
: test this imageequal
: fill while equal to edgeleft
: output left edge of bounding box of modified areatop
: output top edge of bounding box of modified areawidth
: output width of bounding box of modified areaheight
: 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 |
|
... |
|
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 |
|
... |
|
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()
.