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