3 Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth \- interactive graphics
15 int initdraw(void (*errfun)(Display*, char*), char *font,
20 int geninitdraw(char *devdir, void(*errfun)(Display*, char*),
23 char *font, char *label, char *mousedir, char *windir,
28 int newwindow(char *str)
31 void drawerror(Display *d, char *msg)
34 Display* initdisplay(char *devdir, char *win, void(*errfun)(Display*, char*))
37 void closedisplay(Display *d)
40 Subfont* getdefont(Display *d)
43 int flushimage(Display *d, int vis)
46 uchar* bufimage(Display *d, int n)
49 void lockdisplay(Display *d)
52 void unlockdisplay(Display *d)
55 int getwindow(Display *d, int ref)
58 int gengetwindow(Display *d, char *winname,
61 Image **ip, Screen **sp, int ref)
64 Font* openfont(Display *d, char *name)
67 Font* buildfont(Display *d, char *desc, char *name)
70 void freefont(Font *f)
79 ulong strtochan(char *s)
82 char* chantostr(char *s, ulong chan)
85 int chantodepth(ulong chan)
88 extern Display *display
94 extern Screen *_screen
102 structure represents a connection to the graphics device,
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:
114 void (*error)(Display*, char*);
122 Subfont *defaultsubfont;
129 is a location in an Image
132 such as the display, and is defined as:
143 The coordinate system has
145 increasing to the right and
151 is a rectangular area in an image.
157 Point min; /* upper left */
158 Point max; /* lower right */
166 By convention, the right (maximum
171 excluded from the represented rectangle, so abutting rectangles have no
175 contains the coordinates of the first point beyond the rectangle.
179 data structure is defined in
184 is a set of character images, indexed by runes (see
186 The images are organized into
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
192 is immaterial for most applications.
196 structures contain two interrelated fields:
198 the distance from the top of the highest character
199 (actually the top of the image holding all the characters)
203 the distance from the top of the highest character to the bottom of
204 the lowest character (and hence, the interline spacing).
210 parses the font description in the buffer
214 pointer that can be used by
218 to draw characters from the font.
220 does the same, but reads the description
224 The convention for naming font files is:
226 .B /lib/font/bit/\fIname\fP/\fIrange\fP.\fIsize\fP.font
231 is approximately the height in pixels of the lower case letters
232 (without ascenders or descenders).
234 gives some indication of which characters will be available: for example
241 includes most European languages, punctuation marks, the International Phonetic
242 Alphabet, etc., but no Oriental languages.
244 includes every character for which appropriate-sized images exist on the system.
260 The arrays are arranged in rows, two bytes per row, left to
261 right in big-endian order to give 16 rows
263 A cursor is displayed on the screen by adding
265 to the current mouse position, using
267 as a mask to draw white at the pixels where
269 is one, and then drawing black at the pixels where
283 change the cursor image and its location on the screen.
287 connects to the display; it returns \-1 if it fails and sets the error string.
289 sets up the global variables
293 structure representing the connection),
297 representing the display memory itself or, if
299 is running, the client's window),
302 (the default font for text).
310 so that it can be used to identify the window when hidden (see
312 The font is created by reading the named
318 reads the file named in the environment variable
322 is not set, it imports the default (usually minimal)
323 font from the operating system.
326 will be set to point to the resulting
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.
338 is nil, the library provides a default, called
359 function provides a less automated way to establish a connection, for programs
360 that wish to connect to multiple displays.
362 is the name of the directory containing the device files for the display
374 are the directories holding the
380 specifies the refresh function to be used to create the window, if running under
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.
395 argument, if non-null, is concatenated to the string \f5\&"new\ "\fP
396 that is used to create the window (see
399 .B newwindow("-hide -dy 100")
400 will cause the program to run in a newly created, hidden window
406 it sets up the display structures but does not allocate any fonts or call
408 The arguments are similar to those of
411 names the directory, default
413 in which the files associated with the window reside.
415 disconnects the display and frees the associated data structures.
419 structure from in-core data describing a default subfont.
420 None of these routines is needed by most programs, since
422 calls them as needed.
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
430 to notify the library to use a locking protocol for its own accesses,
435 around any calls to the graphics library that will cause messages to be sent to the display device.
439 initialize the display to the locked state.
442 returns a pointer to the window associated with the application; it is called
447 pointer but must be called after each resizing of the window to restore
448 the library's connection to the window.
451 is not running, it returns
453 otherwise it negotiates with
457 to find the name of the window and opening it using
461 The resulting window will be created using the refresh method
465 this should almost always be
469 provides backing store for the window.
472 overwrites the global variables
476 defining the window (or the overall display, if no window system is running); and
480 representing the root of the window's hierarchy. (See
482 The overloading of the
484 word is an unfortunate historical accident.)
488 point to the portion of the window inside the border;
489 sophisticated clients may use
491 to make further subwindows.
492 Programs desiring multiple independent windows
493 may use the mechanisms of
495 to create more windows (usually by a fresh mount of the window sytem
496 in a directory other than
502 extra arguments are the full path of the window's
504 file and pointers to be overwritten with the values of the `global'
508 variables for the new window.
510 The graphics functions described in
516 are implemented by writing commands to files under
520 the writes are buffered, so the functions may not take effect immediately.
522 flushes the buffer, doing all pending graphics operations.
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
530 most programs do not need to call
532 It returns \-1 on error.
535 is used to allocate space for
537 bytes in the display buffer.
538 It is used by all the graphics routines to send messages to the display.
544 convert between the channel descriptor strings
550 used by the graphics protocol
556 writes at most nine bytes into the buffer pointed at by
564 returns the number of bits per pixel used by the
571 return 0 when presented
574 To reconnect to the window after a resize event,
577 if(getwindow(display, Refnone) < 0)
578 sysfatal("resize failed: %r");
581 To create and set up a new
589 srvwsys = getenv("wsys");
591 sysfatal("can't find $wsys: %r");
592 rfork(RFNAMEG); /* keep mount of rio private */
594 fd = open(srvwsys, ORDWR);
596 sysfatal("can't open $wsys: %r");
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");
605 /* now open /tmp/cons, /tmp/mouse */
609 .BR /lib/font/bit " directory of fonts
628 An error function may call
630 for further diagnostics.
638 structure are reminders of an archaic color map
639 and might be more appropriately called