3 Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth \- interactive graphics
16 int initdraw(void (*errfun)(Display*, char*), char *font,
21 int geninitdraw(char *devdir, void(*errfun)(Display*, char*),
24 char *font, char *label, char *mousedir, char *windir,
29 int newwindow(char *str)
32 void drawerror(Display *d, char *msg)
35 Display* initdisplay(char *devdir, char *win, void(*errfun)(Display*, char*))
38 void closedisplay(Display *d)
41 Font* getdefont(Display *d)
44 int flushimage(Display *d, int vis)
47 int bufimage(Display *d, int n)
50 int lockdisplay(Display *d)
53 int unlockdisplay(Display *d)
56 int getwindow(Display *d, int ref)
59 int gengetwindow(Display *d, char *winname,
62 Image **ip, Screen **sp, int ref)
65 void cursorswitch(Cursor *curs)
68 void cursorset(Point p)
71 Font* openfont(Display *d, char *name)
74 Font* buildfont(Display *d, char *desc, char *name)
77 void freefont(Font *f)
86 ulong strtochan(char *s)
89 char* chantostr(char *s, ulong chan)
92 int chantodepth(ulong chan)
95 extern Display *display
101 extern Screen *_screen
109 structure represents a connection to the graphics device,
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:
121 void (*error)(Display*, char*);
129 Subfont *defaultsubfont;
136 is a location in an Image
139 such as the display, and is defined as:
150 The coordinate system has
152 increasing to the right and
158 is a rectangular area in an image.
164 Point min; /* upper left */
165 Point max; /* lower right */
173 By convention, the right (maximum
178 excluded from the represented rectangle, so abutting rectangles have no
182 contains the coordinates of the first point beyond the rectangle.
186 data structure is defined in
191 is a set of character images, indexed by runes (see
193 The images are organized into
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
199 is immaterial for most applications.
203 structures contain two interrelated fields:
205 the distance from the top of the highest character
206 (actually the top of the image holding all the characters)
210 the distance from the top of the highest character to the bottom of
211 the lowest character (and hence, the interline spacing).
217 parses the font description in the buffer
221 pointer that can be used by
225 to draw characters from the font.
227 does the same, but reads the description
231 The convention for naming font files is:
233 .B /lib/font/bit/\fIname\fP/\fIrange\fP.\fIsize\fP.font
238 is approximately the height in pixels of the lower case letters
239 (without ascenders or descenders).
241 gives some indication of which characters will be available: for example
248 includes most European languages, punctuation marks, the International Phonetic
249 Alphabet, etc., but no Oriental languages.
251 includes every character for which appropriate-sized images exist on the system.
267 The arrays are arranged in rows, two bytes per row, left to
268 right in big-endian order to give 16 rows
270 A cursor is displayed on the screen by adding
272 to the current mouse position, using
274 as a mask to draw white at the pixels where
276 is one, and then drawing black at the pixels where
282 connects to the display; it returns \-1 if it fails and sets the error string.
284 sets up the global variables
288 structure representing the connection),
292 representing the display memory itself or, if
294 is running, the client's window),
297 (the default font for text).
305 so that it can be used to identify the window when hidden (see
307 The font is created by reading the named
313 reads the file named in the environment variable
317 is not set, it imports the default (usually minimal)
318 font from the operating system.
321 will be set to point to the resulting
327 .I graphics error function
328 to call in the event of a fatal error in the library; it must never return.
329 Its arguments are the
330 display pointer and an error string.
333 is nil, the library provides a default, called
354 function provides a less automated way to establish a connection, for programs
355 that wish to connect to multiple displays.
357 is the name of the directory containing the device files for the display
369 are the directories holding the
375 specifies the refresh function to be used to create the window, if running under
382 .\" may be called before
386 .\" to cause the program to occupy a newly created window rather than take over the one in
387 .\" which it is running when it starts.
390 .\" argument, if non-null, is concatenated to the string \f5\&"new\ "\fP
391 .\" that is used to create the window (see
394 .\" .B newwindow("-hide -dy 100")
395 .\" will cause the program to run in a newly created, hidden window
401 it sets up the display structures but does not allocate any fonts or call
403 The arguments are similar to those of
406 names the directory, default
408 in which the files associated with the window reside.
410 disconnects the display and frees the associated data structures.
414 structure from in-core data describing a default font.
415 None of these routines is needed by most programs, since
417 calls them as needed.
419 The data structures associated with the display must be protected in a multi-process program,
420 because they assume only one process will be using them at a time.
421 Multi-process programs should set
425 to notify the library to use a locking protocol for its own accesses,
430 around any calls to the graphics library that will cause messages to be sent to the display device.
434 initialize the display to the locked state.
437 returns a pointer to the window associated with the application; it is called
442 pointer but must be called after each resizing of the window to restore
443 the library's connection to the window.
446 is not running, it returns
448 otherwise it negotiates with
452 to find the name of the window and opening it using
456 The resulting window will be created using the refresh method
460 this should almost always be
464 provides backing store for the window.
467 overwrites the global variables
471 defining the window (or the overall display, if no window system is running); and
475 representing the root of the window's hierarchy. (See
477 The overloading of the
479 word is an unfortunate historical accident.)
483 point to the portion of the window inside the border;
484 sophisticated clients may use
486 to make further subwindows.
487 .\" Programs desiring multiple independent windows
488 .\" may use the mechanisms of
490 .\" to create more windows (usually by a fresh mount of the window sytem
491 .\" in a directory other than
495 .\" to connect to them.
497 extra arguments are the full path of the window's
499 file and pointers to be overwritten with the values of the `global'
503 variables for the new window.
505 The mouse cursor is always displayed.
506 The initial cursor is an arrow.
508 causes the argument cursor to be displayed instead.
509 A zero argument causes a switch back to the arrow cursor.
511 moves the mouse cursor to position
513 provided (if in a window) that the requesting program is
514 executing in the current window and the mouse is within
515 the window boundaries; otherwise
519 The graphics functions described in
525 are implemented by writing commands to files under
529 the writes are buffered, so the functions may not take effect immediately.
531 flushes the buffer, doing all pending graphics operations.
534 is non-zero, any changes are also copied from the `soft screen' (if any) in the
535 driver to the visible frame buffer.
536 The various allocation routines in the library flush automatically, as does the event
539 most programs do not need to call
541 It returns \-1 on error.
544 is used to allocate space for
546 bytes in the display buffer.
547 It is used by all the graphics routines to send messages to the display.
553 convert between the channel descriptor strings
559 used by the graphics protocol
565 writes at most nine bytes into the buffer pointed at by
573 returns the number of bits per pixel used by the
580 return 0 when presented
583 To reconnect to the window after a resize event,
586 if(getwindow(display, Refnone) < 0)
587 sysfatal("resize failed: %r");
590 To create and set up a new
598 srvwsys = getenv("wsys");
600 sysfatal("can't find $wsys: %r");
601 rfork(RFNAMEG); /* keep mount of rio private */
603 fd = open(srvwsys, ORDWR);
605 sysfatal("can't open $wsys: %r");
607 /* mount creates window; see \f2rio\fP(4) */
608 if(mount(fd, -1, "/tmp", MREPL, "new -dx 300-dy 200") < 0)
609 sysfatal("can't mount new window: %r");
610 if(gengetwindow(display, "/tmp/winname",
611 &screen2, &_screen2, Refnone) < 0)
612 sysfatal("resize failed: %r");
614 /* now open /tmp/cons, /tmp/mouse */
618 .BR \*9/font/bit " directory of fonts
637 An error function may call
639 for further diagnostics.
647 structure are reminders of an archaic color map
648 and might be more appropriately called
653 These manual pages contain many references to
