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