DRAW(2) DRAW(2)
NAME
Image, draw, gendraw, drawreplxy, drawrepl, replclipr, line,
poly, fillpoly, bezier, bezspline, fillbezier,
fillbezspline, ellipse, fillellipse, arc, fillarc, icossin,
icossin2, border, string, stringn, runestring, runestringn,
stringbg, stringnbg, runestringbg, runestringnbg, _string,
ARROW, drawsetdebug - graphics functions
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <draw.h>
typedef
struct Image
{
Display *display; /* display holding data */
int id; /* id of system-held Image */
Rectangle r; /* rectangle in data area, local coords */
Rectangle clipr; /* clipping region */
ulong chan; /* pixel channel format descriptor */
int depth; /* number of bits per pixel */
int repl; /* flag: data replicates to tile clipr */
Screen *screen; /* 0 if not a window */
Image *next; /* next in list of windows */
} Image;
void draw(Image *dst, Rectangle r,
Image *src, Image *mask, Point p)
void gendraw(Image *dst, Rectangle r,
Image *src, Point sp, Image *mask, Point mp)
int drawreplxy(int min, int max, int x)
Point drawrepl(Rectangle r, Point p)
void replclipr(Image *i, int repl, Rectangle clipr)
void line(Image *dst, Point p0, Point p1, int end0, int end1,
int radius, Image *src, Point sp)
void poly(Image *dst, Point *p, int np, int end0, int end1,
int radius, Image *src, Point sp)
void fillpoly(Image *dst, Point *p, int np, int wind,
Image *src, Point sp)
int bezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
int end0, int end1, int radius, Image *src, Point sp)
Page 1 Plan 9 (printed 4/26/24)
DRAW(2) DRAW(2)
int bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
int radius, Image *src, Point sp)
int fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
int w, Image *src, Point sp)
int fillbezspline(Image *dst, Point *pt, int npt, int w,
Image *src, Point sp)
void ellipse(Image *dst, Point c, int a, int b, int thick,
Image *src, Point sp)
void fillellipse(Image *dst, Point c, int a, int b,
Image *src, Point sp)
void arc(Image *dst, Point c, int a, int b, int thick,
Image *src, Point sp, int alpha, int phi)
void fillarc(Image *dst, Point c, int a, int b, Image *src,
Point sp, int alpha, int phi)
int icossin(int deg, int *cosp, int *sinp)
int icossin2(int x, int y, int *cosp, int *sinp)
void border(Image *dst, Rectangle r, int i, Image *color, Point sp)
Point string(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s)
Point stringn(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, int len)
Point runestring(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r)
Point runestringn(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, int len)
Point stringbg(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, Image *bg, Point bgp)
Point stringnbg(Image *dst, Point p, Image *src, Point sp,
Font *f, char *s, int len, Image *bg, Point bgp)
Point runestringbg(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, Image *bg, Point bgp)
Point runestringnbg(Image *dst, Point p, Image *src, Point sp,
Font *f, Rune *r, int len, Image *bg, Point bgp)
Point _string(Image *dst, Point p, Image *src,
Page 2 Plan 9 (printed 4/26/24)
DRAW(2) DRAW(2)
Point sp, Font *f, char *s, Rune *r, int len,
Rectangle clipr, Image *bg, Point bgp)
void drawsetdebug(int on)
enum
{
/* line ends */
Endsquare= 0,
Enddisc= 1,
Endarrow= 2,
Endmask= 0x1F
};
#define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23))
DESCRIPTION
The Image type defines rectangular pictures and the methods
to draw upon them; it is also the building block for higher
level objects such as windows and fonts. In particular, a
window is represented as an Image; no special operators are
needed to draw on a window.
r The coordinates of the rectangle in the plane for
which the Image has defined pixel values. It
should not be modified after the image is created.
clipr The clipping rectangle: operations that read or
write the image will not access pixels outside
clipr. Frequently, clipr is the same as r, but it
may differ; see in particular the discussion of
repl. The clipping region may be modified dynami-
cally using replclipr (q.v.).
chan The pixel channel format descriptor, as described
in image(6). The value should not be modified
after the image is created.
depth The number of bits per pixel in the picture; it is
identically chantodepth(chan) (see graphics(2))
and is provided as a convenience. The value
should not be modified after the image is created.
repl A boolean value specifying whether the image is
tiled to cover the plane when used as a source for
a drawing operation. If repl is zero, operations
are restricted to the intersection of r and clipr.
If repl is set, r defines the tile to be repli-
cated and clipr defines the portion of the plane
covered by the tiling, in other words, r is repli-
cated to cover clipr; in such cases r and clipr
are independent.
Page 3 Plan 9 (printed 4/26/24)
DRAW(2) DRAW(2)
For example, a replicated image with r set to
((0, 0), (1, 1)) and clipr set to
((0, 0), (100, 100)), with the single pixel of r
set to blue, behaves identically to an image with
r and clipr both set to ((0, 0), (100, 100)) and
all pixels set to blue. However, the first image
requires far less memory. The replication flag
may be modified dynamically using replclipr
(q.v.).
draw(dst, r, src, mask, p)
Draw is the standard drawing function. Only those
pixels within the intersection of dst->r and
dst->clipr will be affected; draw ignores
dst->repl. The operation proceeds as follows
(this is a description of the behavior, not the
implementation):
1. If repl is set in src or mask, replicate
their contents to fill their clip rectangles.
2. Translate src and mask so p is aligned with
r.min.
3. Set r to the intersection of r and dst->r.
4. Intersect r with src->clipr. If src->repl is
false, also intersect r with src->r.
5. Intersect r with mask->clipr. If mask->repl
is false, also intersect r with mask->r.
6. For each location in r, combine the dst pixel
with the src pixel using the alpha value cor-
responding to the mask pixel. If the mask
has an explicit alpha channel, the alpha
value corresponding to the mask pixel is sim-
ply that pixel's alpha channel. Otherwise,
the alpha value is the NTSC greyscale equiva-
lent of the color value, with white meaning
opaque and black transparent. In terms of
the Porter-Duff compositing algebra, draw
replaces the dst pixels with (src in mask)
over dst.
The various pixel channel formats involved need
not be identical. If the channels involved are
smaller than 8-bits, they will be promoted before
the calculation by replicating the extant bits;
after the calculation, they will be truncated to
their proper sizes.
Page 4 Plan 9 (printed 4/26/24)
DRAW(2) DRAW(2)
gendraw(dst, r, src, p0, mask, p1)
Similar to draw except that gendraw aligns the
source and mask differently: src is aligned so p0
corresponds to r.min and mask is aligned so p1
corresponds to r.min. For most purposes with sim-
ple masks and source images, draw is sufficient,
but gendraw is the general operator and the one
all other drawing primitives are built upon.
drawreplxy(min,max,x)
Clips x to be in the half-open interval [min, max)
by adding or subtracting a multiple of max-min.
drawrepl(r,p)
Clips the point p to be within the rectangle r by
translating the point horizontally by an integer
multiple of rectangle width and vertically by the
height.
replclipr(i,repl,clipr)
Because the image data is stored on the server,
local modifications to the Image data structure
itself will have no effect. Repclipr modifies the
local Image data structure's repl and clipr
fields, and notifies the server of their modifica-
tion.
line(dst, p0, p1, end0, end1, thick, src, sp)
Line draws in dst a line of width 1+2*thick pixels
joining points p0 and p1. The line is drawn using
pixels from the src image aligned so sp in the
source corresponds to p0 in the destination. The
line touches both p0 and p1, and end0 and end1
specify how the ends of the line are drawn.
Endsquare terminates the line perpendicularly to
the direction of the line; a thick line with
Endsquare on both ends will be a rectangle.
Enddisc terminates the line by drawing a disc of
diameter 1+2*thick centered on the end point.
Endarrow terminates the line with an arrowhead
whose tip touches the endpoint.
The macro ARROW permits explicit control of the
shape of the arrow. If all three parameters are
zero, it produces the default arrowhead, other-
wise, a sets the distance along line from end of
the regular line to tip, b sets the distance along
line from the barb to the tip, and c sets the dis-
tance perpendicular to the line from edge of line
to the tip of the barb, all in pixels.
Line and the other geometrical operators are
Page 5 Plan 9 (printed 4/26/24)
DRAW(2) DRAW(2)
equivalent to calls to gendraw using a mask pro-
duced by the geometric procedure.
poly(dst, p, np, end0, end1, thick, src, sp)
Poly draws a general polygon; it is conceptually
equivalent to a series of calls to line joining
adjacent points in the array of Points p, which
has np elements. The ends of the polygon are
specified as in line; interior lines are termi-
nated with Enddisc to make smooth joins. The
source is aligned so sp corresponds to p[0].
fillpoly(dst, p, np, wind, src, sp)
Fillpoly is like poly but fills in the resulting
polygon rather than outlining it. The source is
aligned so sp corresponds to p[0]. The winding
rule parameter wind resolves ambiguities about
what to fill if the polygon is self-intersecting.
If wind is ~0, a pixel is inside the polygon if
the polygon's winding number about the point is
non-zero. If wind is 1, a pixel is inside if the
winding number is odd. Complementary values (0 or
~1) cause outside pixels to be filled. The mean-
ing of other values is undefined. The polygon is
closed with a line if necessary.
bezier(dst, a, b, c, d, end0, end1, thick, src, sp)
Bezier draws the cubic Bezier curve defined by
Points a, b, c, and d. The end styles are deter-
mined by end0 and end1; the thickness of the curve
is 1+2*thick. The source is aligned so sp in src
corresponds to a in dst.
bezspline(dst, p, end0, end1, thick, src, sp)
Bezspline takes the same arguments as poly but
draws a quadratic B-spline (despite its name)
rather than a polygon. If the first and last
points in p are equal, the spline has periodic end
conditions.
fillbezier(dst, a, b, c, d, wind, src, sp)
Fillbezier is to bezier as fillpoly is to poly.
fillbezspline(dst, p, wind, src, sp)
Fillbezspline is like fillpoly but fills the qua-
dratic B-spline rather than the polygon outlined
by p. The spline is closed with a line if neces-
sary.
ellipse(dst, c, a, b, thick, src, sp)
Ellipse draws in dst an ellipse centered on c with
horizontal and vertical semiaxes a and b. The
Page 6 Plan 9 (printed 4/26/24)
DRAW(2) DRAW(2)
source is aligned so sp in src corresponds to c in
dst. The ellipse is drawn with thickness
1+2*thick.
fillellipse(dst, c, a, b, src, sp)
Fillellipse is like ellipse but fills the ellipse
rather than outlining it.
arc(dst, c, a, b, thick, src, sp, alpha, phi)
Arc is like ellipse, but draws only that portion
of the ellipse starting at angle alpha and extend-
ing through an angle of phi. The angles are mea-
sured in degrees counterclockwise from the posi-
tive x axis.
fillarc(dst, c, a, b, src, sp, alpha, phi)
Fillarc is like arc, but fills the sector with the
source color.
icossin(deg, cosp, sinp)
Icossin stores in *cosp and *sinp scaled integers
representing the cosine and sine of the angle deg,
measured in integer degrees. The values are
scaled so cos(0) is 1024.
icossin2(x, y, cosp, sinp)
Icossin2 is analogous to icossin, with the angle
represented not in degrees but implicitly by the
point (x,y). It is to icossin what atan2 is to
atan (see sin(2)).
border(dst, r, i, color, sp)
Border draws an outline of rectangle r in the
specified color. The outline has width i; if posi-
tive, the border goes inside the rectangle; nega-
tive, outside. The source is aligned so sp corre-
sponds to r.min.
string(dst, p, src, sp, font, s)
String draws in dst characters specified by the
string s and font; it is equivalent to a series of
calls to gendraw using source src and masks deter-
mined by the character shapes. The text is posi-
tioned with the left of the first character at p.x
and the top of the line of text at p.y. The
source is positioned so sp in src corresponds to p
in dst. String returns a Point that is the posi-
tion of the next character that would be drawn if
the string were longer.
For characters with undefined or zero-width images
in the font, the character at font position 0
Page 7 Plan 9 (printed 4/26/24)
DRAW(2) DRAW(2)
(NUL) is drawn.
The other string routines are variants of this
basic form, and have names that encode their vari-
ant behavior. Routines whose names contain rune
accept a string of Runes rather than UTF-encoded
bytes. Routines ending in n accept an argument,
n, that defines the number of characters to draw
rather than accepting a NUL-terminated string.
Routines containing bg draw the background behind
the characters in the specified color (bg) and
alignment (bgp); normally the text is drawn leav-
ing the background intact.
The routine _string captures all this behavior
into a single operator. Whether it draws a UTF
string or Rune string depends on whether s or r is
null (the string length is always determined by
len). If bg is non-null, it is used as a back-
ground color. The clipr argument allows further
management of clipping when drawing the string; it
is intersected with the usual clipping rectangles
to further limit the extent of the text.
drawsetdebug(on)
Turns on or off debugging output (usually to a
serial line) according to whether on is non-zero.
SOURCE
/sys/src/libdraw
SEE ALSO
graphics(2), stringsize(2), color(6), utf(6), addpt(2)
T. Porter, T. Duff. ``Compositing Digital Images'',
Computer Graphics (Proc. SIGGRAPH), 18:3, pp. 253-259, 1984.
DIAGNOSTICS
These routines call the graphics error function on fatal
errors.
BUGS
Anti-aliased characters can be drawn by defining a font with
multiple bits per pixel, but there are no anti-aliasing geo-
metric primitives.
Page 8 Plan 9 (printed 4/26/24)