sys/man/2/draw

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