sys/man/2/graphics

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