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