graphics.3 (13650B)
1 .TH GRAPHICS 3 2 .SH NAME 3 Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth \- interactive graphics 4 .SH SYNOPSIS 5 .nf 6 .PP 7 .ft L 8 #include <u.h> 9 #include <libc.h> 10 #include <draw.h> 11 #include <cursor.h> 12 .ft P 13 .PP 14 .ta \w'\fLFont* 'u 15 .B 16 int initdraw(void (*errfun)(Display*, char*), char *font, 17 .B 18 char *label) 19 .PP 20 .B 21 int geninitdraw(char *devdir, void(*errfun)(Display*, char*), 22 .PP 23 .B 24 char *font, char *label, char *mousedir, char *windir, 25 .B 26 int ref) 27 .PP 28 .B 29 int newwindow(char *str) 30 .PP 31 .B 32 void drawerror(Display *d, char *msg) 33 .PP 34 .B 35 Display* initdisplay(char *devdir, char *win, void(*errfun)(Display*, char*)) 36 .PP 37 .B 38 void closedisplay(Display *d) 39 .PP 40 .B 41 int flushimage(Display *d, int vis) 42 .PP 43 .B 44 int bufimage(Display *d, int n) 45 .PP 46 .B 47 int lockdisplay(Display *d) 48 .PP 49 .B 50 int unlockdisplay(Display *d) 51 .PP 52 .B 53 int getwindow(Display *d, int ref) 54 .PP 55 .B 56 int gengetwindow(Display *d, char *winname, 57 .br 58 .B 59 Image **ip, Screen **sp, int ref) 60 .PP 61 .B 62 int scalesize(Display *d, int n) 63 .PP 64 .B 65 void cursorswitch(Cursor *curs) 66 .PP 67 .B 68 void cursorset(Point p) 69 .PP 70 .B 71 Font* openfont(Display *d, char *name) 72 .PP 73 .B 74 Font* buildfont(Display *d, char *desc, char *name) 75 .PP 76 .B 77 void freefont(Font *f) 78 .PP 79 .B 80 int Pfmt(Fmt*) 81 .PP 82 .B 83 int Rfmt(Fmt*) 84 .PP 85 .B 86 ulong strtochan(char *s) 87 .PP 88 .B 89 char* chantostr(char *s, ulong chan) 90 .PP 91 .B 92 int chantodepth(ulong chan) 93 .PP 94 .B 95 extern Display *display 96 .PP 97 .B 98 extern Image *screen 99 .PP 100 .B 101 extern Screen *_screen 102 .PP 103 .B 104 extern Font *font 105 .fi 106 .SH DESCRIPTION 107 A 108 .B Display 109 structure represents a connection to the graphics device, 110 .MR draw (3) , 111 holding all graphics resources associated with the connection, 112 including in particular raster image data in use by the client program. 113 The structure is defined (in part) as: 114 .IP 115 .EX 116 .ta 6n +10n 117 typedef 118 struct Display 119 { 120 ... 121 void (*error)(Display*, char*); 122 ... 123 Image *black; 124 Image *white; 125 Image *opaque; 126 Image *transparent; 127 Image *image; 128 Font *defaultfont; 129 Subfont *defaultsubfont; 130 ... 131 }; 132 .EE 133 .PP 134 A 135 .B Point 136 is a location in an Image 137 (see below and 138 .MR draw (3) ), 139 such as the display, and is defined as: 140 .IP 141 .EX 142 .ta 6n 143 typedef 144 struct Point { 145 int x; 146 int y; 147 } Point; 148 .EE 149 .PP 150 The coordinate system has 151 .I x 152 increasing to the right and 153 .I y 154 increasing down. 155 .PP 156 A 157 .B Rectangle 158 is a rectangular area in an image. 159 .IP 160 .EX 161 .ta 6n 162 typedef 163 struct Rectangle { 164 Point min; /* upper left */ 165 Point max; /* lower right */ 166 } Rectangle; 167 .EE 168 .PP 169 By definition, 170 .BR min.x ≤ max.x 171 and 172 .BR min.y ≤ max.y . 173 By convention, the right (maximum 174 .IR x ) 175 and bottom (maximum 176 .IR y ) 177 edges are 178 excluded from the represented rectangle, so abutting rectangles have no 179 points in common. 180 Thus, 181 .B max 182 contains the coordinates of the first point beyond the rectangle. 183 .PP 184 The 185 .B Image 186 data structure is defined in 187 .MR draw (3) . 188 .PP 189 A 190 .B Font 191 is a set of character images, indexed by runes (see 192 .MR utf (7) ). 193 The images are organized into 194 .BR Subfonts , 195 each containing the images for a small, contiguous set of runes. 196 The detailed format of these data structures, 197 which are described in detail in 198 .MR cachechars (3) , 199 is immaterial for most applications. 200 .B Font 201 and 202 .B Subfont 203 structures contain two interrelated fields: 204 .LR ascent , 205 the distance from the top of the highest character 206 (actually the top of the image holding all the characters) 207 to the baseline, 208 and 209 .LR height , 210 the distance from the top of the highest character to the bottom of 211 the lowest character (and hence, the interline spacing). 212 See 213 .MR cachechars (3) 214 for more details. 215 .PP 216 .I Buildfont 217 parses the font description in the buffer 218 .BR desc , 219 returning a 220 .B Font* 221 pointer that can be used by 222 .B string 223 (see 224 .MR draw (3) ) 225 to draw characters from the font. 226 .I Openfont 227 does the same, but reads the description 228 from the named font. 229 .I Freefont 230 frees a font. 231 In contrast to Plan 9, font names in Plan 9 from User Space are 232 a small language describing the desired font. 233 See 234 .MR font (7) 235 for details. 236 .PP 237 A 238 .I Cursor 239 is defined: 240 .IP 241 .EX 242 .ta 6n +\w'Point 'u 243 typedef struct 244 Cursor { 245 Point offset; 246 uchar clr[2*16]; 247 uchar set[2*16]; 248 } Cursor; 249 .EE 250 .PP 251 The arrays are arranged in rows, two bytes per row, left to 252 right in big-endian order to give 16 rows 253 of 16 bits each. 254 A cursor is displayed on the screen by adding 255 .B offset 256 to the current mouse position, using 257 .B clr 258 as a mask to draw white at the pixels where 259 .B clr 260 is one, and then drawing black at the pixels where 261 .B set 262 is one. 263 .PP 264 The routine 265 .I initdraw 266 connects to the display; it returns \-1 if it fails and sets the error string. 267 .I Initdraw 268 sets up the global variables 269 .B display 270 (the 271 .B Display 272 structure representing the connection), 273 .B screen 274 (an 275 .B Image 276 representing the display memory itself or, if 277 .MR rio (1) 278 is running, the client's window), 279 and 280 .B font 281 (the default font for text). 282 The arguments to 283 .I initdraw 284 include a 285 .IR label , 286 which is written to 287 .B /dev/label 288 if non-nil 289 so that it can be used to identify the window when hidden (see 290 .MR rio (1) ). 291 The font is created by reading the named 292 .I font 293 file. If 294 .B font 295 is null, 296 .I initdraw 297 reads the file named in the environment variable 298 .BR $font ; 299 if 300 .B $font 301 is not set, it imports the default (usually minimal) 302 font from the operating system. 303 (See 304 .MR font (7) 305 for a full discussion of font syntaxes.) 306 The global 307 .I font 308 will be set to point to the resulting 309 .B Font 310 structure. 311 The 312 .I errfun 313 argument is a 314 .I graphics error function 315 to call in the event of a fatal error in the library; it must never return. 316 Its arguments are the 317 display pointer and an error string. 318 If 319 .I errfun 320 is nil, the library provides a default, called 321 .IR drawerror . 322 Another effect of 323 .I initdraw 324 is that it installs 325 .MR print (3) 326 formats 327 .I Pfmt 328 and 329 .I Rfmt 330 as 331 .L %P 332 and 333 .L %R 334 for printing 335 .B Points 336 and 337 .BR Rectangles . 338 .PP 339 The 340 .I geninitdraw 341 function provides a less automated way to establish a connection, for programs 342 that wish to connect to multiple displays. 343 .I Devdir 344 is the name of the directory containing the device files for the display 345 (if nil, default 346 .BR /dev ); 347 .IR errfun , 348 .IR font , 349 and 350 .I label 351 are as in 352 .IR initdraw ; 353 .I mousedir 354 and 355 .I windir 356 are the directories holding the 357 .B mouse 358 and 359 .B winname 360 files; and 361 .I ref 362 specifies the refresh function to be used to create the window, if running under 363 .MR rio (1) 364 (see 365 .MR window (3) ). 366 .\" .PP 367 .\" The function 368 .\" .I newwindow 369 .\" may be called before 370 .\" .I initdraw 371 .\" or 372 .\" .IR geninitdraw 373 .\" to cause the program to occupy a newly created window rather than take over the one in 374 .\" which it is running when it starts. 375 .\" The 376 .\" .I str 377 .\" argument, if non-null, is concatenated to the string \f5\&"new\ "\fP 378 .\" that is used to create the window (see 379 .\" .IR rio (4)). 380 .\" For example, 381 .\" .B newwindow("-hide -dy 100") 382 .\" will cause the program to run in a newly created, hidden window 383 .\" 100 pixels high. 384 .PP 385 .I Initdisplay 386 is part of 387 .IR geninitdraw ; 388 it sets up the display structures but does not allocate any fonts or call 389 .IR getwindow . 390 The arguments are similar to those of 391 .IR initdraw ; 392 .I win 393 names the directory, default 394 .BR /dev , 395 in which the files associated with the window reside. 396 .I Closedisplay 397 disconnects the display and frees the associated data structures. 398 Neither of these routines is needed by most programs, since 399 .I initdraw 400 calls them as needed. 401 .PP 402 The data structures associated with the display must be protected in a multi-process program, 403 because they assume only one process will be using them at a time. 404 Multi-process programs should set 405 .B display->locking 406 to 407 .BR 1 , 408 to notify the library to use a locking protocol for its own accesses, 409 and call 410 .I lockdisplay 411 and 412 .I unlockdisplay 413 around any calls to the graphics library that will cause messages to be sent to the display device. 414 .I Initdraw 415 and 416 .I geninitdraw 417 initialize the display to the locked state. 418 .PP 419 .I Getwindow 420 returns a pointer to the window associated with the application; it is called 421 automatically by 422 .I initdraw 423 to establish the 424 .B screen 425 pointer but must be called after each resizing of the window to restore 426 the library's connection to the window. 427 If 428 .B rio 429 is not running, it returns 430 .BR display->image ; 431 otherwise it negotiates with 432 .B rio 433 by looking in 434 .B /dev/winname 435 to find the name of the window and opening it using 436 .B namedimage 437 (see 438 .MR allocimage (3) ). 439 The resulting window will be created using the refresh method 440 .I ref 441 (see 442 .MR window (3) ); 443 this should almost always be 444 .B Refnone 445 because 446 .B rio 447 provides backing store for the window. 448 .PP 449 .I Getwindow 450 overwrites the global variables 451 .BR screen , 452 a pointer to the 453 .B Image 454 defining the window (or the overall display, if no window system is running); and 455 .BR _screen , 456 a pointer to the 457 .B Screen 458 representing the root of the window's hierarchy. (See 459 .MR window (3) . 460 The overloading of the 461 .B screen 462 word is an unfortunate historical accident.) 463 .I Getwindow 464 arranges that 465 .B screen 466 point to the portion of the window inside the border; 467 sophisticated clients may use 468 .B _screen 469 to make further subwindows. 470 If 471 .I getwindow 472 is being called due to a resizing of the window, 473 the resize may be accompanied by a change in screen pixel density (DPI), 474 in which case the value of the 475 .BR Display 's 476 .B dpi 477 field and any open 478 .BR Font 's 479 .B height 480 and 481 .B ascent 482 fields may be updated during the call to 483 .IR getwindow . 484 Programs should discard any cached information about display or font sizes. 485 .\" Programs desiring multiple independent windows 486 .\" may use the mechanisms of 487 .\" .IR rio (4) 488 .\" to create more windows (usually by a fresh mount of the window sytem 489 .\" in a directory other than 490 .\" .BR /dev ), 491 .\" then use 492 .\" .I gengetwindow 493 .\" to connect to them. 494 .IR Gengetwindow 's 495 extra arguments are the full path of the window's 496 .B winname 497 file and pointers to be overwritten with the values of the `global' 498 .B Image 499 and 500 .B Screen 501 variables for the new window. 502 .PP 503 Historically, Plan 9 graphics programs have used fixed-size graphics features that assume a narrow range of display densities, around 100 dpi: pixels (or dots) per inch. 504 The new field 505 .B display->dpi 506 contains the display's actual density if known, or else 507 .B DefaultDPI 508 (100). 509 .I Scalesize 510 scales the fixed pixel count 511 .I n 512 by 513 .BR display->dpi / DefaultDPI , 514 rounding appropriately. 515 .PP 516 The mouse cursor is always displayed. 517 The initial cursor is an arrow. 518 .I Cursorswitch 519 causes the argument cursor to be displayed instead. 520 A zero argument causes a switch back to the arrow cursor. 521 .I Cursorset 522 moves the mouse cursor to position 523 .IR p , 524 provided (if in a window) that the requesting program is 525 executing in the current window and the mouse is within 526 the window boundaries; otherwise 527 .I cursorset 528 is a no-op. 529 .PP 530 The graphics functions described in 531 .MR draw (3) , 532 .MR allocimage (3) , 533 .MR cachechars (3) , 534 and 535 .MR subfont (3) 536 are implemented by writing commands to files under 537 .B /dev/draw 538 (see 539 .MR draw (3) ); 540 the writes are buffered, so the functions may not take effect immediately. 541 .I Flushimage 542 flushes the buffer, doing all pending graphics operations. 543 If 544 .I vis 545 is non-zero, any changes are also copied from the `soft screen' (if any) in the 546 driver to the visible frame buffer. 547 The various allocation routines in the library flush automatically, as does the event 548 package (see 549 .MR event (3) ); 550 most programs do not need to call 551 .IR flushimage . 552 It returns \-1 on error. 553 .PP 554 .I Bufimage 555 is used to allocate space for 556 .I n 557 bytes in the display buffer. 558 It is used by all the graphics routines to send messages to the display. 559 .PP 560 The functions 561 .I strtochan 562 and 563 .I chantostr 564 convert between the channel descriptor strings 565 used by 566 .MR image (7) 567 and the internal 568 .B ulong 569 representation 570 used by the graphics protocol 571 (see 572 .MR draw (3) 's 573 .B b 574 message). 575 .B Chantostr 576 writes at most nine bytes into the buffer pointed at by 577 .I s 578 and returns 579 .I s 580 on success, 581 0 582 on failure. 583 .B Chantodepth 584 returns the number of bits per pixel used by the 585 format specified by 586 .IR chan . 587 Both 588 .B chantodepth 589 and 590 .B strtochan 591 return 0 when presented 592 with bad input. 593 .SH EXAMPLES 594 To reconnect to the window after a resize event, 595 .IP 596 .EX 597 if(getwindow(display, Refnone) < 0) 598 sysfatal("resize failed: %r"); 599 .EE 600 .PP 601 To create and set up a new 602 .MR rio (1) 603 window, 604 .IP 605 .EX 606 Image *screen2; 607 Screen *_screen2; 608 609 srvwsys = getenv("wsys"); 610 if(srvwsys == nil) 611 sysfatal("can't find $wsys: %r"); 612 rfork(RFNAMEG); /* keep mount of rio private */ 613 614 fd = open(srvwsys, ORDWR); 615 if(fd < 0) 616 sysfatal("can't open $wsys: %r"); 617 618 /* mount creates window; see \f2rio\fP(4) */ 619 if(mount(fd, -1, "/tmp", MREPL, "new -dx 300-dy 200") < 0) 620 sysfatal("can't mount new window: %r"); 621 if(gengetwindow(display, "/tmp/winname", 622 &screen2, &_screen2, Refnone) < 0) 623 sysfatal("resize failed: %r"); 624 625 /* now open /tmp/cons, /tmp/mouse */ 626 \&... 627 .EE 628 .SH FILES 629 .BR \*9/font/bit " directory of fonts 630 .SH SOURCE 631 .B \*9/src/libdraw 632 .SH "SEE ALSO" 633 .MR rio (1) , 634 .MR addpt (3) , 635 .MR allocimage (3) , 636 .MR cachechars (3) , 637 .MR subfont (3) , 638 .MR draw (3) , 639 .MR event (3) , 640 .MR frame (3) , 641 .MR print (3) , 642 .MR window (3) , 643 .MR draw (3) , 644 .\" .IR rio (4), 645 .MR image (7) , 646 .MR font (7) 647 .SH DIAGNOSTICS 648 An error function may call 649 .MR errstr (3) 650 for further diagnostics. 651 .SH BUGS 652 The names 653 .B clr 654 and 655 .B set 656 in the 657 .B Cursor 658 structure are reminders of an archaic color map 659 and might be more appropriately called 660 .B white 661 and 662 .BR black . 663 .PP 664 These manual pages contain many references to 665 the now-fictitious 666 .BR /dev/draw .