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 windir
 372 is the directory holding the
 373 .B winname
 374 file; and
 375 .I ref
 376 specifies the refresh function to be used to create the window, if running under
 377 .IR rio (1)
 378 (see
 379 .IR window (2)).
 380 .PP
 381 The function
 382 .I newwindow
 383 may be called before
 384 .I initdraw
 385 or
 386 .IR geninitdraw
 387 to cause the program to occupy a newly created window rather than take over the one in
 388 which it is running when it starts.
 389 The
 390 .I str
 391 argument, if non-null, is concatenated to the string \f5\&"new\ "\fP
 392 that is used to create the window (see
 393 .IR rio (4)).
 394 For example,
 395 .B newwindow("-hide -dy 100")
 396 will cause the program to run in a newly created, hidden window
 397 100 pixels high.
 398 .PP
 399 .I Initdisplay
 400 is part of
 401 .IR geninitdraw ;
 402 it sets up the display structures but does not allocate any fonts or call
 403 .IR getwindow .
 404 The arguments are similar to those of
 405 .IR initdraw ;
 406 .I win
 407 names the directory, default
 408 .BR /dev ,
 409 in which the files associated with the window reside.
 410 .I Closedisplay
 411 disconnects the display and frees the associated data structures.
 412 .I Getdefont
 413 builds a
 414 .B Subfont
 415 structure from in-core data describing a default subfont.
 416 None of these routines are needed by most programs, since
 417 .I initdraw
 418 calls them as needed.
 419 .PP
 420 The data structures associated with the display must be protected in a multi-process program,
 421 because they assume only one process will be using them at a time.
 422 Multi-process programs should set
 423 .B display->locking
 424 to
 425 .BR 1 ,
 426 to notify the library to use a locking protocol for its own accesses,
 427 and call
 428 .I lockdisplay
 429 and
 430 .I unlockdisplay
 431 around any calls to the graphics library that will cause messages to be sent to the display device.
 432 .I Initdraw
 433 and
 434 .I geninitdraw
 435 initialize the display to the locked state.
 436 .PP
 437 .I Getwindow
 438 returns a pointer to the window associated with the application; it is called
 439 automatically by
 440 .I initdraw
 441 to establish the
 442 .B screen
 443 pointer but must be called after each resizing of the window to restore
 444 the library's connection to the window.
 445 If
 446 .B rio
 447 is not running, it returns
 448 .BR display->image ;
 449 otherwise it negotiates with
 450 .B rio
 451 by looking in
 452 .B /dev/winname
 453 to find the name of the window and opening it using
 454 .B namedimage
 455 (see
 456 .IR allocimage (2)).
 457 The resulting window will be created using the refresh method
 458 .I ref
 459 (see
 460 .IR window (2));
 461 this should almost always be
 462 .B Refnone
 463 because
 464 .B rio
 465 provides backing store for the window.
 466 .PP
 467 .I Getwindow
 468 overwrites the global variables
 469 .BR screen ,
 470 a pointer to the
 471 .B Image
 472 defining the window (or the overall display, if no window system is running); and
 473 .BR _screen ,
 474 a pointer to the
 475 .B Screen
 476 representing the root of the window's hierarchy. (See
 477 .IR window (2).
 478 The overloading of the
 479 .B screen
 480 word is an unfortunate historical accident.)
 481 .I Getwindow
 482 arranges that
 483 .B screen
 484 point to the portion of the window inside the border;
 485 sophisticated clients may use
 486 .B _screen
 487 to make further subwindows.
 488 Programs desiring multiple independent windows
 489 may use the mechanisms of
 490 .IR rio (4)
 491 to create more windows (usually by a fresh mount of the window system
 492 in a directory other than
 493 .BR /dev ),
 494 then use
 495 .I gengetwindow
 496 to connect to them.
 497 .IR Gengetwindow 's
 498 extra arguments are the full path of the window's
 499 .B winname
 500 file and pointers to be overwritten with the values of the `global'
 501 .B Image
 502 and
 503 .B Screen
 504 variables for the new window.
 505 .PP
 506 The graphics functions described in
 507 .IR draw (2),
 508 .IR allocimage (2),
 509 .IR cachechars (2),
 510 and
 511 .IR subfont (2)
 512 are implemented by writing commands to files under
 513 .B /dev/draw
 514 (see
 515 .IR draw (3));
 516 the writes are buffered, so the functions may not take effect immediately.
 517 .I Flushimage
 518 flushes the buffer, doing all pending graphics operations.
 519 If
 520 .I vis
 521 is non-zero, any changes are also copied from the `soft screen' (if any) in the
 522 driver to the visible frame buffer.
 523 The various allocation routines in the library flush automatically, as does the event
 524 package (see
 525 .IR event (2));
 526 most programs do not need to call
 527 .IR flushimage .
 528 It returns \-1 on error.
 529 .PP
 530 .I Bufimage
 531 is used to allocate space for
 532 .I n
 533 bytes in the display buffer.
 534 It is used by all the graphics routines to send messages to the display.
 535 .PP
 536 The functions
 537 .I strtochan
 538 and
 539 .I chantostr
 540 convert between the channel descriptor strings
 541 used by
 542 .IR image (6)
 543 and the internal
 544 .B ulong
 545 representation
 546 used by the graphics protocol
 547 (see
 548 .IR draw (3)'s
 549 .B b
 550 message).
 551 .B Chantostr
 552 writes at most nine bytes into the buffer pointed at by
 553 .I s
 554 and returns
 555 .I s
 556 on success,
 557 0
 558 on failure.
 559 .B Chantodepth
 560 returns the number of bits per pixel used by the
 561 format specified by
 562 .IR chan .
 563 Both
 564 .B chantodepth
 565 and
 566 .B strtochan
 567 return 0 when presented
 568 with bad input.
 569 .SH EXAMPLES
 570 To reconnect to the window after a resize event,
 571 .IP
 572 .EX
 573 if(getwindow(display, Refnone) < 0)
 574         sysfatal("resize failed: %r");
 575 .EE
 576 .PP
 577 To create and set up a new
 578 .IR rio (1)
 579 window,
 580 .IP
 581 .EX
 582 Image *screen2;
 583 Screen *_screen2;
 584
 585 srvwsys = getenv("wsys");
 586 if(srvwsys == nil)
 587         sysfatal("can't find $wsys: %r");
 588 rfork(RFNAMEG); /* keep mount of rio private */
 589
 590 fd = open(srvwsys, ORDWR);
 591 if(fd < 0)
 592         sysfatal("can't open $wsys: %r");
 593
 594 /* mount creates window; see \f2rio\fP(4) */
 595 if(mount(fd, -1, "/tmp", MREPL, "new -dx 300-dy 200") < 0)
 596         sysfatal("can't mount new window: %r");
 597 if(gengetwindow(display, "/tmp/winname",
 598    &screen2, &_screen2, Refnone) < 0)
 599         sysfatal("resize failed: %r");
 600
 601 /* now open /tmp/cons, /tmp/mouse */
 602 \&...
 603 .EE
 604 .SH FILES
 605 .BR /lib/font/bit "    directory of fonts
 606 .SH SOURCE
 607 .B /sys/src/libdraw
 608 .SH "SEE ALSO"
 609 .IR rio (1),
 610 .IR addpt (2),
 611 .IR allocimage (2),
 612 .IR cachechars (2),
 613 .IR subfont (2),
 614 .IR draw (2),
 615 .IR event (2),
 616 .IR frame (2),
 617 .IR print (2),
 618 .IR window (2),
 619 .IR draw (3),
 620 .IR rio (4),
 621 .IR image (6),
 622 .IR font (6)
 623 .SH DIAGNOSTICS
 624 An error function may call
 625 .IR errstr (2)
 626 for further diagnostics.
 627 .SH BUGS
 628 The names
 629 .B clr
 630 and
 631 .B set
 632 in the
 633 .B Cursor
 634 structure are reminders of an archaic color map
 635 and might be more appropriately called
 636 .B white
 637 and
 638 .BR black .