tdraw.3 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
tdraw.3 (19735B)
---
1 .TH DRAW 3
2 .SH NAME
3 Image, draw, drawop, gendraw, gendrawop, drawreplxy, drawrepl,
4 replclipr, line, lineop, poly, polyop, fillpoly, fillpolyop, bezier, bezierop,
5 bezspline, bezsplineop, bezsplinepts, fillbezier, fillbezierop,
6 fillbezspline, fillbezsplineop, ellipse, ellipseop,
7 fillellipse, fillellipseop, arc, arcop, fillarc, fillarcop,
8 icossin, icossin2, border, borderop, string, stringop, stringn, stringnop,
9 runestring, runestringop, runestringn, runestringnop, stringbg,
10 stringbgop, stringnbg, stringnbgop, runestringbg, runestringbgop,
11 runestringnbg, runestringnbgop, _string, ARROW, drawsetdebug \- graphics functions
12 .de PB
13 .PP
14 .ft L
15 .nf
16 ..
17 .SH SYNOPSIS
18 .de PB
19 .PP
20 .ft L
21 .nf
22 ..
23 .PB
24 #include <u.h>
25 #include <libc.h>
26 #include <draw.h>
27 .PB
28 typedef
29 struct Image
30 {
31 Display *display; /* display holding data */
32 int id; /* id of system-held Image */
33 Rectangle r; /* rectangle in data area, local coords */
34 Rectangle clipr; /* clipping region */
35 ulong chan; /* pixel channel format descriptor */
36 int depth; /* number of bits per pixel */
37 int repl; /* flag: data replicates to tile clipr */
38 Screen *screen; /* 0 if not a window */
39 Image *next; /* next in list of windows */
40 } Image;
41 .PB
42 typedef enum
43 {
44 /* Porter-Duff compositing operators */
45 Clear = 0,
46 .sp 0.1
47 SinD = 8,
48 DinS = 4,
49 SoutD = 2,
50 DoutS = 1,
51 .sp 0.1
52 S = SinD|SoutD,
53 SoverD = SinD|SoutD|DoutS,
54 SatopD = SinD|DoutS,
55 SxorD = SoutD|DoutS,
56 .sp 0.1
57 D = DinS|DoutS,
58 DoverS = DinS|DoutS|SoutD,
59 DatopS = DinS|SoutD,
60 DxorS = DoutS|SoutD, /* == SxorD */
61 .sp 0.1
62 Ncomp = 12,
63 } Drawop;
64 .PB
65 .PD 0
66 .ta +\w'\fL 'u +\w'\fL 'u +6n +4n
67 void draw(Image *dst, Rectangle r, Image *src,
68 Image *mask, Point p)
69 .PB
70 void drawop(Image *dst, Rectangle r, Image *src,
71 Image *mask, Point p, Drawop op)
72 .PB
73 void gendraw(Image *dst, Rectangle r, Image *src, Point sp,
74 Image *mask, Point mp)
75 .PB
76 void gendrawop(Image *dst, Rectangle r, Image *src, Point sp,
77 Image *mask, Point mp, Drawop op)
78 .PB
79 int drawreplxy(int min, int max, int x)
80 .PB
81 Point drawrepl(Rectangle r, Point p)
82 .PB
83 void replclipr(Image *i, int repl, Rectangle clipr)
84 .PB
85 void line(Image *dst, Point p0, Point p1, int end0, int end1,
86 int radius, Image *src, Point sp)
87 .PB
88 void lineop(Image *dst, Point p0, Point p1, int end0, int end1,
89 int radius, Image *src, Point sp, Drawop op)
90 .PB
91 void poly(Image *dst, Point *p, int np, int end0, int end1,
92 int radius, Image *src, Point sp)
93 .PB
94 void polyop(Image *dst, Point *p, int np, int end0, int end1,
95 int radius, Image *src, Point sp, Drawop op)
96 .PB
97 void fillpoly(Image *dst, Point *p, int np, int wind,
98 Image *src, Point sp)
99 .PB
100 void fillpolyop(Image *dst, Point *p, int np, int wind,
101 Image *src, Point sp, Drawop op)
102 .PB
103 int bezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
104 int end0, int end1, int radius, Image *src, Point sp)
105 .PB
106 int bezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
107 int end0, int end1, int radius, Image *src, Point sp,
108 Drawop op)
109 .PB
110 int bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
111 int radius, Image *src, Point sp)
112 .PB
113 int bezsplineop(Image *dst, Point *pt, int npt, int end0, int end1,
114 int radius, Image *src, Point sp, Drawop op)
115 .PB
116 int bezsplinepts(Point *pt, int npt, Point **pp)
117 .PB
118 int fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
119 int w, Image *src, Point sp)
120 .PB
121 int fillbezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
122 int w, Image *src, Point sp, Drawop op)
123 .PB
124 int fillbezspline(Image *dst, Point *pt, int npt, int w,
125 Image *src, Point sp)
126 .PB
127 int fillbezsplineop(Image *dst, Point *pt, int npt, int w,
128 Image *src, Point sp, Drawop op)
129 .PB
130 void ellipse(Image *dst, Point c, int a, int b, int thick,
131 Image *src, Point sp)
132 .PB
133 void ellipseop(Image *dst, Point c, int a, int b, int thick,
134 Image *src, Point sp, Drawop op)
135 .PB
136 void fillellipse(Image *dst, Point c, int a, int b,
137 Image *src, Point sp)
138 .PB
139 void fillellipseop(Image *dst, Point c, int a, int b,
140 Image *src, Point sp, Drawop op)
141 .PB
142 void arc(Image *dst, Point c, int a, int b, int thick,
143 Image *src, Point sp, int alpha, int phi)
144 .PB
145 void arcop(Image *dst, Point c, int a, int b, int thick,
146 Image *src, Point sp, int alpha, int phi, Drawop op)
147 .PB
148 void fillarc(Image *dst, Point c, int a, int b, Image *src,
149 Point sp, int alpha, int phi)
150 .PB
151 void fillarcop(Image *dst, Point c, int a, int b, Image *src,
152 Point sp, int alpha, int phi, Drawop op)
153 .PB
154 int icossin(int deg, int *cosp, int *sinp)
155 .PB
156 int icossin2(int x, int y, int *cosp, int *sinp)
157 .PB
158 void border(Image *dst, Rectangle r, int i, Image *color, Point sp)
159 .PB
160 void borderop(Image *im, Rectangle r, int i, Image *color, Point sp,
161 Drawop op)
162 .br
163 .PB
164 Point string(Image *dst, Point p, Image *src, Point sp,
165 Font *f, char *s)
166 .PB
167 Point stringop(Image *dst, Point p, Image *src, Point sp,
168 Font *f, char *s, Drawop op)
169 .PB
170 Point stringn(Image *dst, Point p, Image *src, Point sp,
171 Font *f, char *s, int len)
172 .PB
173 Point stringnop(Image *dst, Point p, Image *src, Point sp,
174 Font *f, char *s, int len, Drawop op)
175 .PB
176 Point runestring(Image *dst, Point p, Image *src, Point sp,
177 Font *f, Rune *r)
178 .PB
179 Point runestringop(Image *dst, Point p, Image *src, Point sp,
180 Font *f, Rune *r, Drawop op)
181 .PB
182 Point runestringn(Image *dst, Point p, Image *src, Point sp,
183 Font *f, Rune *r, int len)
184 .PB
185 Point runestringnop(Image *dst, Point p, Image *src, Point sp,
186 Font *f, Rune *r, int len, Drawop op)
187 .PB
188 Point stringbg(Image *dst, Point p, Image *src, Point sp,
189 Font *f, char *s, Image *bg, Point bgp)
190 .PB
191 Point stringbgop(Image *dst, Point p, Image *src, Point sp,
192 Font *f, char *s, Image *bg, Point bgp, Drawop op)
193 .PB
194 Point stringnbg(Image *dst, Point p, Image *src, Point sp,
195 Font *f, char *s, int len, Image *bg, Point bgp)
196 .PB
197 Point stringnbgop(Image *dst, Point p, Image *src, Point sp,
198 Font *f, char *s, int len, Image *bg, Point bgp, Drawop op)
199 .PB
200 Point runestringbg(Image *dst, Point p, Image *src, Point sp,
201 Font *f, Rune *r, Image *bg, Point bgp)
202 .PB
203 Point runestringbgop(Image *dst, Point p, Image *src, Point sp,
204 Font *f, Rune *r, Image *bg, Point bgp, Drawop op)
205 .PB
206 Point runestringnbg(Image *dst, Point p, Image *src, Point sp,
207 Font *f, Rune *r, int len, Image *bg, Point bgp)
208 .PB
209 Point runestringnbgop(Image *dst, Point p, Image *src, Point sp,
210 Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op)
211 .PB
212 Point _string(Image *dst, Point p, Image *src,
213 Point sp, Font *f, char *s, Rune *r, int len,
214 Rectangle clipr, Image *bg, Point bgp, Drawop op)
215 .PB
216 void drawsetdebug(int on)
217 .PD
218 .PB
219 enum
220 {
221 /* line ends */
222 Endsquare = 0,
223 Enddisc = 1,
224 Endarrow = 2,
225 Endmask = 0x1F
226 };
227 .PB
228 #define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23))
229 .SH DESCRIPTION
230 The
231 .B Image
232 type defines rectangular pictures and the methods to draw upon them;
233 it is also the building block for higher level objects such as
234 windows and fonts.
235 In particular, a window is represented as an
236 .BR Image ;
237 no special operators are needed to draw on a window.
238 .PP
239 .TP 10
240 .B r
241 The coordinates of the rectangle in the plane for which the
242 .B Image
243 has defined pixel values.
244 It should not be modified after the image is created.
245 .TP
246 .B clipr
247 The clipping rectangle: operations that read or write
248 the image will not access pixels outside
249 .BR clipr .
250 Frequently,
251 .B clipr
252 is the same as
253 .BR r ,
254 but it may differ; see in particular the discussion of
255 .BR repl .
256 The clipping region may be modified dynamically using
257 .I replclipr
258 .RI ( q.v. ).
259 .TP
260 .B chan
261 The pixel channel format descriptor, as described in
262 .MR image (7) .
263 The value should not be modified after the image is created.
264 .TP
265 .B depth
266 The
267 number of bits per pixel in the picture;
268 it is identically
269 .B chantodepth(chan)
270 (see
271 .MR graphics (3) )
272 and is provided as a convenience.
273 The value should not be modified after the image is created.
274 .TP
275 .B repl
276 A boolean value specifying whether the image is tiled to cover
277 the plane when used as a source for a drawing operation.
278 If
279 .B repl
280 is zero, operations are restricted to the intersection of
281 .B r
282 and
283 .BR clipr .
284 If
285 .B repl
286 is set,
287 .B r
288 defines the tile to be replicated and
289 .B clipr
290 defines the portion of the plane covered by the tiling, in other words,
291 .B r
292 is replicated to cover
293 .BR clipr ;
294 in such cases
295 .B r
296 and
297 .B clipr
298 are independent.
299 .IP
300 For example, a replicated image with
301 .B r
302 set to ((0,\ 0),\ (1,\ 1)) and
303 .B clipr
304 set to ((0,\ 0),\ (100,\ 100)),
305 with the single pixel of
306 .B r
307 set to blue,
308 behaves identically to an image with
309 .B r
310 and
311 .B clipr
312 both set to ((0,\ 0),\ (100,\ 100)) and all pixels set to blue.
313 However,
314 the first image requires far less memory.
315 The replication flag may be modified dynamically using
316 .I replclipr
317 .RI ( q.v. ).
318 .PP
319 Most of the drawing functions come in two forms:
320 a basic form, and an extended form that takes an extra
321 .B Drawop
322 to specify a Porter-Duff compositing operator to use.
323 The basic forms assume the operator is
324 .BR SoverD ,
325 which suffices for the vast majority of applications.
326 The extended forms are named by adding an
327 .RB - op
328 suffix to the basic form.
329 Only the basic forms are listed below.
330 .TP
331 .BI draw( dst\fP,\fP\ r\fP,\fP\ src\fP,\fP\ mask\fP,\fP\ p )
332 .I Draw
333 is the standard drawing function.
334 Only those pixels within the intersection of
335 .IB dst ->r
336 and
337 .IB dst ->clipr
338 will be affected;
339 .I draw
340 ignores
341 .IB dst ->repl\fR.
342 The operation proceeds as follows
343 (this is a description of the behavior, not the implementation):
344 .RS
345 .IP 1.
346 If
347 .B repl
348 is set in
349 .I src
350 or
351 .IR mask ,
352 replicate their contents to fill
353 their clip rectangles.
354 .IP 2.
355 Translate
356 .I src
357 and
358 .I mask
359 so
360 .I p
361 is aligned with
362 .IB r .min\fR.
363 .IP 3.
364 Set
365 .I r
366 to the intersection of
367 .I r
368 and
369 .IB dst ->r\fR.
370 .IP 4.
371 Intersect
372 .I r
373 with
374 .IB src ->clipr\fR.
375 If
376 .IB src ->repl
377 is false, also intersect
378 .I r
379 with
380 .IB src ->r\fR.
381 .IP 5.
382 Intersect
383 .I r
384 with
385 .IB mask ->clipr\fR.
386 If
387 .IB mask ->repl
388 is false, also intersect
389 .I r
390 with
391 .IB mask ->r\fR.
392 .IP 6.
393 For each location in
394 .IR r ,
395 combine the
396 .I dst
397 pixel with the
398 .I src
399 pixel using the alpha value
400 corresponding to the
401 .I mask
402 pixel.
403 If the
404 .I mask
405 has an explicit alpha channel, the alpha value
406 corresponding to the
407 .I mask
408 pixel is simply that pixel's alpha channel.
409 Otherwise, the alpha value is the NTSC greyscale equivalent
410 of the color value, with white meaning opaque and black transparent.
411 In terms of the Porter-Duff compositing algebra,
412 .I draw
413 replaces the
414 .I dst
415 pixels with
416 .RI ( src
417 in
418 .IR mask )
419 over
420 .IR dst .
421 (In the extended form,
422 ``over'' is replaced by
423 .IR op ).
424 .RE
425 .IP
426 The various
427 pixel channel formats
428 involved need not be identical.
429 If the channels involved are smaller than 8-bits, they will
430 be promoted before the calculation by replicating the extant bits;
431 after the calculation, they will be truncated to their proper sizes.
432 .TP
433 \f5gendraw(\f2dst\fP, \f2r\fP, \f2src\fP, \f2p0\fP, \f2mask\fP, \f2p1\f5)\fP
434 Similar to
435 .I draw
436 except that
437 .I gendraw
438 aligns the source and mask differently:
439 .I src
440 is aligned so
441 .I p0
442 corresponds to
443 .IB r .min
444 and
445 .I mask
446 is aligned so
447 .I p1
448 corresponds to
449 .IB r .min .
450 For most purposes with simple masks and source images,
451 .B draw
452 is sufficient, but
453 .B gendraw
454 is the general operator and the one all other drawing primitives are built upon.
455 .TP
456 .BI drawreplxy( min , max , x\f5)
457 Clips
458 .I x
459 to be in the half-open interval [\fImin\fP, \fImax\fP) by adding
460 or subtracting a multiple of \fImax-min\fP.
461 .TP
462 .BI drawrepl( r , p )
463 Clips the point \fIp\fP to be within the rectangle \fIr\fP
464 by translating the point horizontally by an integer multiple of rectangle width
465 and vertically by the height.
466 .TP
467 .BI replclipr( i , repl , clipr\f5)
468 Because the image data is stored on the server, local modifications to the
469 .B Image
470 data structure itself will have no effect.
471 .I Repclipr
472 modifies the local
473 .B Image
474 data structure's
475 .B repl
476 and
477 .B clipr
478 fields, and notifies the server of their modification.
479 .TP
480 \f5line(\f2dst\fP, \f2p0\fP, \f2p1\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
481 Line
482 draws in
483 .I dst
484 a line of width
485 .RI 1+2* thick
486 pixels joining points
487 .I p0
488 and
489 .IR p1 .
490 The line is drawn using pixels from the
491 .I src
492 image aligned so
493 .I sp
494 in the source corresponds to
495 .I p0
496 in the destination.
497 The line touches both
498 .I p0
499 and
500 .IR p1 ,
501 and
502 .I end0
503 and
504 .I end1
505 specify how the ends of the line are drawn.
506 .B Endsquare
507 terminates the line perpendicularly to the direction of the line; a thick line with
508 .B Endsquare
509 on both ends will be a rectangle.
510 .B Enddisc
511 terminates the line by drawing a disc of diameter
512 .RI 1+2* thick
513 centered on the end point.
514 .B Endarrow
515 terminates the line with an arrowhead whose tip touches the endpoint.
516 .IP
517 The macro
518 .B ARROW
519 permits explicit control of the shape of the arrow.
520 If all three parameters are zero, it produces the default arrowhead,
521 otherwise,
522 .I a
523 sets the distance along line from end of the regular line to tip,
524 .I b
525 sets the distance along line from the barb to the tip,
526 and
527 .I c
528 sets the distance perpendicular to the line from edge of line to the tip of the barb,
529 all in pixels.
530 .IP
531 .I Line
532 and the other geometrical operators are equivalent to calls to
533 .I gendraw
534 using a mask produced by the geometric procedure.
535 .TP
536 \f5poly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
537 .I Poly
538 draws a general polygon; it
539 is conceptually equivalent to a series of calls to
540 .I line
541 joining adjacent points in the
542 array of
543 .B Points
544 .IR p ,
545 which has
546 .I np
547 elements.
548 The ends of the polygon are specified as in
549 .IR line ;
550 interior lines are terminated with
551 .B Enddisc
552 to make smooth joins.
553 The source is aligned so
554 .I sp
555 corresponds to
556 .IB p [0]\f1.
557 .TP
558 \f5fillpoly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
559 .I Fillpoly
560 is like
561 .I poly
562 but fills in the resulting polygon rather than outlining it.
563 The source is aligned so
564 .I sp
565 corresponds to
566 .IB p [0]\f1.
567 The winding rule parameter
568 .I wind
569 resolves ambiguities about what to fill if the polygon is self-intersecting.
570 If
571 .I wind
572 is
573 .BR ~0 ,
574 a pixel is inside the polygon if the polygon's winding number about the point
575 is non-zero.
576 If
577 .I wind
578 is
579 .BR 1 ,
580 a pixel is inside if the winding number is odd.
581 Complementary values (0 or ~1) cause outside pixels to be filled.
582 The meaning of other values is undefined.
583 The polygon is closed with a line if necessary.
584 .TP
585 \f5bezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
586 .I Bezier
587 draws the
588 cubic Bezier curve defined by
589 .B Points
590 .IR a ,
591 .IR b ,
592 .IR c ,
593 and
594 .IR d .
595 The end styles are determined by
596 .I end0
597 and
598 .IR end1 ;
599 the thickness of the curve is
600 .RI 1+2* thick .
601 The source is aligned so
602 .I sp
603 in
604 .I src
605 corresponds to
606 .I a
607 in
608 .IR dst .
609 .TP
610 \f5bezspline(\f2dst\fP, \f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
611 .I Bezspline
612 takes the same arguments as
613 .I poly
614 but draws a quadratic B-spline (despite its name) rather than a polygon.
615 If the first and last points in
616 .I p
617 are equal, the spline has periodic end conditions.
618 .TP
619 \f5bezsplinepts(\f2pt\fP, \f2npt\fP, \f2pp\fP)
620 .I Bezsplinepts
621 returns in
622 .I pp
623 a list of points making up the open polygon that
624 .I bezspline
625 would draw.
626 The caller is responsible for freeing
627 .IR *pp .
628 .TP
629 \f5fillbezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
630 .I Fillbezier
631 is to
632 .I bezier
633 as
634 .I fillpoly
635 is to
636 .IR poly .
637 .TP
638 \f5fillbezspline(\f2dst\fP, \f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
639 .I Fillbezspline
640 is like
641 .I fillpoly
642 but fills the quadratic B-spline rather than the polygon outlined by
643 .IR p .
644 The spline is closed with a line if necessary.
645 .TP
646 \f5ellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
647 .I Ellipse
648 draws in
649 .I dst
650 an ellipse centered on
651 .I c
652 with horizontal and vertical semiaxes
653 .I a
654 and
655 .IR b .
656 The source is aligned so
657 .I sp
658 in
659 .I src
660 corresponds to
661 .I c
662 in
663 .IR dst .
664 The ellipse is drawn with thickness
665 .RI 1+2* thick .
666 .TP
667 \f5fillellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP)
668 .I Fillellipse
669 is like
670 .I ellipse
671 but fills the ellipse rather than outlining it.
672 .TP
673 \f5arc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP)
674 .I Arc
675 is like
676 .IR ellipse ,
677 but draws only that portion of the ellipse starting at angle
678 .I alpha
679 and extending through an angle of
680 .IR phi .
681 The angles are measured in degrees counterclockwise from the positive
682 .I x
683 axis.
684 .TP
685 \f5fillarc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP)
686 .I Fillarc
687 is like
688 .IR arc ,
689 but fills the sector with the source color.
690 .TP
691 \f5icossin(\f2deg\fP, \f2cosp\fP, \f2sinp\fP)
692 .I Icossin
693 stores in
694 .BI * cosp
695 and
696 .BI * sinp
697 scaled integers representing the cosine and sine of the angle
698 .IR deg ,
699 measured in integer degrees.
700 The values are scaled so cos(0) is 1024.
701 .TP
702 \f5icossin2(\f2x\fP, \f2y\fP, \f2cosp\fP, \f2sinp\fP)
703 .I Icossin2
704 is analogous to
705 .IR icossin,
706 with the angle represented not in degrees but implicitly by the point
707 .RI ( x , y ).
708 It is to
709 .I icossin
710 what
711 .B atan2
712 is to
713 .B atan
714 (see
715 .MR sin (3) ).
716 .TP
717 .BI border( dst\fP,\fP\ r\fP,\fP\ i\fP,\fP\ color\fP,\fP\ sp\fP)
718 .I Border
719 draws an outline of rectangle
720 .I r
721 in the specified
722 .IR color .
723 The outline has width
724 .IR i ;
725 if positive, the border goes inside the rectangle; negative, outside.
726 The source is aligned so
727 .I sp
728 corresponds to
729 .IB r .min .
730 .TP
731 .BI string( dst\fP,\fP\ p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ s )
732 .I String
733 draws in
734 .I dst
735 characters specified by the string
736 .I s
737 and
738 .IR font ;
739 it is equivalent to a series of calls to
740 .I gendraw
741 using source
742 .I src
743 and masks determined by the character shapes.
744 The text is positioned with the left of the first character at
745 .IB p .x
746 and the top of the line of text at
747 .IB p .y\f1.
748 The source is positioned so
749 .I sp
750 in
751 .I src
752 corresponds to
753 .I p
754 in
755 .IR dst .
756 .I String
757 returns a
758 .B Point
759 that is the position of the next character that would be drawn if the string were longer.
760 .IP
761 For characters with undefined
762 or zero-width images in the font, the character at font position 0 (NUL) is drawn.
763 .IP
764 The other string routines are variants of this basic form, and
765 have names that encode their variant behavior.
766 Routines whose names contain
767 .B rune
768 accept a string of Runes rather than
769 .SM UTF\c
770 -encoded bytes.
771 Routines ending in
772 .B n
773 accept an argument,
774 .IR n ,
775 that defines the number of characters to draw rather than accepting a NUL-terminated
776 string.
777 Routines containing
778 .B bg
779 draw the background behind the characters in the specified color
780 .RI ( bg )
781 and
782 alignment
783 .RI ( bgp );
784 normally the text is drawn leaving the background intact.
785 .IP
786 The routine
787 .I _string
788 captures all this behavior into a single operator. Whether it draws a
789 .SM UTF
790 string
791 or Rune string depends on whether
792 .I s
793 or
794 .I r
795 is null (the string length is always determined by
796 .IR len ).
797 If
798 .I bg
799 is non-null, it is used as a background color.
800 The
801 .I clipr
802 argument allows further management of clipping when drawing the string;
803 it is intersected with the usual clipping rectangles to further limit the extent of the text.
804 .TP
805 .BI drawsetdebug( on )
806 Turns on or off debugging output (usually
807 to a serial line) according to whether
808 .I on
809 is non-zero.
810 .SH SOURCE
811 .B \*9/src/libdraw
812 .SH SEE ALSO
813 .MR graphics (3) ,
814 .MR stringsize (3) ,
815 .MR color (7) ,
816 .MR utf (7) ,
817 .MR addpt (3)
818 .PP
819 T. Porter, T. Duff.
820 ``Compositing Digital Images'',
821 .I "Computer Graphics
822 (Proc. SIGGRAPH), 18:3, pp. 253-259, 1984.
823 .SH DIAGNOSTICS
824 These routines call the graphics error function on fatal errors.
825 .SH BUGS
826 Anti-aliased characters can be drawn by defining a font
827 with multiple bits per pixel, but there are
828 no anti-aliasing geometric primitives.