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
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 int flushimage(Display *d, int vis)
44 int bufimage(Display *d, int n)
47 int lockdisplay(Display *d)
50 int unlockdisplay(Display *d)
53 int getwindow(Display *d, int ref)
56 int gengetwindow(Display *d, char *winname,
59 Image **ip, Screen **sp, int ref)
62 int scalesize(Display *d, int n)
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 In contrast to Plan 9, font names in Plan 9 from User Space are
232 a small language describing the desired font.
251 The arrays are arranged in rows, two bytes per row, left to
252 right in big-endian order to give 16 rows
254 A cursor is displayed on the screen by adding
256 to the current mouse position, using
258 as a mask to draw white at the pixels where
260 is one, and then drawing black at the pixels where
266 connects to the display; it returns \-1 if it fails and sets the error string.
268 sets up the global variables
272 structure representing the connection),
276 representing the display memory itself or, if
278 is running, the client's window),
281 (the default font for text).
289 so that it can be used to identify the window when hidden (see
291 The font is created by reading the named
297 reads the file named in the environment variable
301 is not set, it imports the default (usually minimal)
302 font from the operating system.
305 for a full discussion of font syntaxes.)
308 will be set to point to the resulting
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.
320 is nil, the library provides a default, called
341 function provides a less automated way to establish a connection, for programs
342 that wish to connect to multiple displays.
344 is the name of the directory containing the device files for the display
356 are the directories holding the
362 specifies the refresh function to be used to create the window, if running under
369 .\" may be called before
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.
377 .\" argument, if non-null, is concatenated to the string \f5\&"new\ "\fP
378 .\" that is used to create the window (see
381 .\" .B newwindow("-hide -dy 100")
382 .\" will cause the program to run in a newly created, hidden window
388 it sets up the display structures but does not allocate any fonts or call
390 The arguments are similar to those of
393 names the directory, default
395 in which the files associated with the window reside.
397 disconnects the display and frees the associated data structures.
398 Neither of these routines is needed by most programs, since
400 calls them as needed.
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
408 to notify the library to use a locking protocol for its own accesses,
413 around any calls to the graphics library that will cause messages to be sent to the display device.
417 initialize the display to the locked state.
420 returns a pointer to the window associated with the application; it is called
425 pointer but must be called after each resizing of the window to restore
426 the library's connection to the window.
429 is not running, it returns
431 otherwise it negotiates with
435 to find the name of the window and opening it using
438 .MR allocimage (3) ).
439 The resulting window will be created using the refresh method
443 this should almost always be
447 provides backing store for the window.
450 overwrites the global variables
454 defining the window (or the overall display, if no window system is running); and
458 representing the root of the window's hierarchy. (See
460 The overloading of the
462 word is an unfortunate historical accident.)
466 point to the portion of the window inside the border;
467 sophisticated clients may use
469 to make further subwindows.
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
482 fields may be updated during the call to
484 Programs should discard any cached information about display or font sizes.
485 .\" Programs desiring multiple independent windows
486 .\" may use the mechanisms of
488 .\" to create more windows (usually by a fresh mount of the window sytem
489 .\" in a directory other than
493 .\" to connect to them.
495 extra arguments are the full path of the window's
497 file and pointers to be overwritten with the values of the `global'
501 variables for the new window.
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.
506 contains the display's actual density if known, or else
510 scales the fixed pixel count
513 .BR display->dpi / DefaultDPI ,
514 rounding appropriately.
516 The mouse cursor is always displayed.
517 The initial cursor is an arrow.
519 causes the argument cursor to be displayed instead.
520 A zero argument causes a switch back to the arrow cursor.
522 moves the mouse cursor to position
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
530 The graphics functions described in
536 are implemented by writing commands to files under
540 the writes are buffered, so the functions may not take effect immediately.
542 flushes the buffer, doing all pending graphics operations.
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
550 most programs do not need to call
552 It returns \-1 on error.
555 is used to allocate space for
557 bytes in the display buffer.
558 It is used by all the graphics routines to send messages to the display.
564 convert between the channel descriptor strings
570 used by the graphics protocol
576 writes at most nine bytes into the buffer pointed at by
584 returns the number of bits per pixel used by the
591 return 0 when presented
594 To reconnect to the window after a resize event,
597 if(getwindow(display, Refnone) < 0)
598 sysfatal("resize failed: %r");
601 To create and set up a new
609 srvwsys = getenv("wsys");
611 sysfatal("can't find $wsys: %r");
612 rfork(RFNAMEG); /* keep mount of rio private */
614 fd = open(srvwsys, ORDWR);
616 sysfatal("can't open $wsys: %r");
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");
625 /* now open /tmp/cons, /tmp/mouse */
629 .BR \*9/font/bit " directory of fonts
648 An error function may call
650 for further diagnostics.
658 structure are reminders of an archaic color map
659 and might be more appropriately called
664 These manual pages contain many references to
