graphics 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651
  1. .TH GRAPHICS 2
  2. .SH NAME
  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
  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. Font* getdefont(Display *d)
  42. .PP
  43. .B
  44. int flushimage(Display *d, int vis)
  45. .PP
  46. .B
  47. int bufimage(Display *d, int n)
  48. .PP
  49. .B
  50. void lockdisplay(Display *d)
  51. .PP
  52. .B
  53. void unlockdisplay(Display *d)
  54. .PP
  55. .B
  56. int getwindow(Display *d, int ref)
  57. .PP
  58. .B
  59. int gengetwindow(Display *d, char *winname,
  60. .br
  61. .B
  62. Image **ip, Screen **sp, int ref)
  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. .IR 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. .IR draw (2)),
  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. .IR draw (2).
  188. .PP
  189. A
  190. .B Font
  191. is a set of character images, indexed by runes (see
  192. .IR utf (6)).
  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. .IR cachechars (2),
  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. .IR cachechars (2)
  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. .IR draw (2))
  225. to draw characters from the font.
  226. .I Openfont
  227. does the same, but reads the description
  228. from the named file.
  229. .I Freefont
  230. frees a font.
  231. The convention for naming font files is:
  232. .IP
  233. .B /lib/font/bit/\fIname\fP/\fIrange\fP.\fIsize\fP.font
  234. .PD
  235. .PP
  236. where
  237. .I size
  238. is approximately the height in pixels of the lower case letters
  239. (without ascenders or descenders).
  240. .I Range
  241. gives some indication of which characters will be available: for example
  242. .BR ascii ,
  243. .BR latin1 ,
  244. .BR euro ,
  245. or
  246. .BR unicode .
  247. .B Euro
  248. includes most European languages, punctuation marks, the International Phonetic
  249. Alphabet, etc., but no Oriental languages.
  250. .B Unicode
  251. includes every character for which appropriate-sized images exist on the system.
  252. .PP
  253. A
  254. .I Cursor
  255. is defined:
  256. .IP
  257. .EX
  258. .ta 6n +\w'Point 'u
  259. typedef struct
  260. Cursor {
  261. Point offset;
  262. uchar clr[2*16];
  263. uchar set[2*16];
  264. } Cursor;
  265. .EE
  266. .PP
  267. The arrays are arranged in rows, two bytes per row, left to
  268. right in big-endian order to give 16 rows
  269. of 16 bits each.
  270. A cursor is displayed on the screen by adding
  271. .B offset
  272. to the current mouse position, using
  273. .B clr
  274. as a mask to draw white at the pixels where
  275. .B clr
  276. is one, and then drawing black at the pixels where
  277. .B set
  278. is one.
  279. .PP
  280. The routine
  281. .I initdraw
  282. connects to the display; it returns \-1 if it fails and sets the error string.
  283. .I Initdraw
  284. sets up the global variables
  285. .B display
  286. (the
  287. .B Display
  288. structure representing the connection),
  289. .B screen
  290. (an
  291. .B Image
  292. representing the display memory itself or, if
  293. .IR rio (1)
  294. is running, the client's window),
  295. and
  296. .B font
  297. (the default font for text).
  298. The arguments to
  299. .I initdraw
  300. include a
  301. .IR label ,
  302. which is written to
  303. .B /dev/label
  304. if non-nil
  305. so that it can be used to identify the window when hidden (see
  306. .IR rio (1)).
  307. The font is created by reading the named
  308. .I font
  309. file. If
  310. .B font
  311. is null,
  312. .I initdraw
  313. reads the file named in the environment variable
  314. .BR $font ;
  315. if
  316. .B $font
  317. is not set, it imports the default (usually minimal)
  318. font from the operating system.
  319. The global
  320. .I font
  321. will be set to point to the resulting
  322. .B Font
  323. structure.
  324. The
  325. .I errfun
  326. argument is a
  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.
  331. If
  332. .I errfun
  333. is nil, the library provides a default, called
  334. .IR drawerror .
  335. Another effect of
  336. .I initdraw
  337. is that it installs
  338. .IR print (2)
  339. formats
  340. .I Pfmt
  341. and
  342. .I Rfmt
  343. as
  344. .L %P
  345. and
  346. .L %R
  347. for printing
  348. .B Points
  349. and
  350. .BR Rectangles .
  351. .PP
  352. The
  353. .I geninitdraw
  354. function provides a less automated way to establish a connection, for programs
  355. that wish to connect to multiple displays.
  356. .I Devdir
  357. is the name of the directory containing the device files for the display
  358. (if nil, default
  359. .BR /dev );
  360. .IR errfun ,
  361. .IR font ,
  362. and
  363. .I label
  364. are as in
  365. .IR initdraw ;
  366. .I mousedir
  367. and
  368. .I windir
  369. are the directories holding the
  370. .B mouse
  371. and
  372. .B winname
  373. files; and
  374. .I ref
  375. specifies the refresh function to be used to create the window, if running under
  376. .IR rio (1)
  377. (see
  378. .IR window (2)).
  379. .PP
  380. The function
  381. .I newwindow
  382. may be called before
  383. .I initdraw
  384. or
  385. .IR geninitdraw
  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.
  388. The
  389. .I str
  390. argument, if non-null, is concatenated to the string \f5\&"new\ "\fP
  391. that is used to create the window (see
  392. .IR rio (4)).
  393. For example,
  394. .B newwindow("-hide -dy 100")
  395. will cause the program to run in a newly created, hidden window
  396. 100 pixels high.
  397. .PP
  398. .I Initdisplay
  399. is part of
  400. .IR geninitdraw ;
  401. it sets up the display structures but does not allocate any fonts or call
  402. .IR getwindow .
  403. The arguments are similar to those of
  404. .IR initdraw ;
  405. .I win
  406. names the directory, default
  407. .BR /dev ,
  408. in which the files associated with the window reside.
  409. .I Closedisplay
  410. disconnects the display and frees the associated data structures.
  411. .I Getdefont
  412. builds a
  413. .B Font
  414. structure from in-core data describing a default font.
  415. None of these routines is needed by most programs, since
  416. .I initdraw
  417. calls them as needed.
  418. .PP
  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
  422. .B display->locking
  423. to
  424. .BR 1 ,
  425. to notify the library to use a locking protocol for its own accesses,
  426. and call
  427. .I lockdisplay
  428. and
  429. .I unlockdisplay
  430. around any calls to the graphics library that will cause messages to be sent to the display device.
  431. .I Initdraw
  432. and
  433. .I geninitdraw
  434. initialize the display to the locked state.
  435. .PP
  436. .I Getwindow
  437. returns a pointer to the window associated with the application; it is called
  438. automatically by
  439. .I initdraw
  440. to establish the
  441. .B screen
  442. pointer but must be called after each resizing of the window to restore
  443. the library's connection to the window.
  444. If
  445. .B rio
  446. is not running, it returns
  447. .BR display->image ;
  448. otherwise it negotiates with
  449. .B rio
  450. by looking in
  451. .B /dev/winname
  452. to find the name of the window and opening it using
  453. .B namedimage
  454. (see
  455. .IR allocimage (2)).
  456. The resulting window will be created using the refresh method
  457. .I ref
  458. (see
  459. .IR window (2));
  460. this should almost always be
  461. .B Refnone
  462. because
  463. .B rio
  464. provides backing store for the window.
  465. .PP
  466. .I Getwindow
  467. overwrites the global variables
  468. .BR screen ,
  469. a pointer to the
  470. .B Image
  471. defining the window (or the overall display, if no window system is running); and
  472. .BR _screen ,
  473. a pointer to the
  474. .B Screen
  475. representing the root of the window's hierarchy. (See
  476. .IR window (2).
  477. The overloading of the
  478. .B screen
  479. word is an unfortunate historical accident.)
  480. .I Getwindow
  481. arranges that
  482. .B screen
  483. point to the portion of the window inside the border;
  484. sophisticated clients may use
  485. .B _screen
  486. to make further subwindows.
  487. Programs desiring multiple independent windows
  488. may use the mechanisms of
  489. .IR rio (4)
  490. to create more windows (usually by a fresh mount of the window sytem
  491. in a directory other than
  492. .BR /dev ),
  493. then use
  494. .I gengetwindow
  495. to connect to them.
  496. .IR Gengetwindow 's
  497. extra arguments are the full path of the window's
  498. .B winname
  499. file and pointers to be overwritten with the values of the `global'
  500. .B Image
  501. and
  502. .B Screen
  503. variables for the new window.
  504. .PP
  505. The mouse cursor is always displayed.
  506. The initial cursor is an arrow.
  507. .I Cursorswitch
  508. causes the argument cursor to be displayed instead.
  509. A zero argument causes a switch back to the arrow cursor.
  510. .I Cursorset
  511. moves the mouse cursor to position
  512. .IR p ,
  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
  516. .I cursorset
  517. is a no-op.
  518. .PP
  519. The graphics functions described in
  520. .IR draw (2),
  521. .IR allocimage (2),
  522. .IR cachechars (2),
  523. and
  524. .IR subfont (2)
  525. are implemented by writing commands to files under
  526. .B /dev/draw
  527. (see
  528. .IR draw (3));
  529. the writes are buffered, so the functions may not take effect immediately.
  530. .I Flushimage
  531. flushes the buffer, doing all pending graphics operations.
  532. If
  533. .I vis
  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
  537. package (see
  538. .IR event (2));
  539. most programs do not need to call
  540. .IR flushimage .
  541. It returns \-1 on error.
  542. .PP
  543. .I Bufimage
  544. is used to allocate space for
  545. .I n
  546. bytes in the display buffer.
  547. It is used by all the graphics routines to send messages to the display.
  548. .PP
  549. The functions
  550. .I strtochan
  551. and
  552. .I chantostr
  553. convert between the channel descriptor strings
  554. used by
  555. .IR image (6)
  556. and the internal
  557. .B ulong
  558. representation
  559. used by the graphics protocol
  560. (see
  561. .IR draw (3)'s
  562. .B b
  563. message).
  564. .B Chantostr
  565. writes at most nine bytes into the buffer pointed at by
  566. .I s
  567. and returns
  568. .I s
  569. on success,
  570. 0
  571. on failure.
  572. .B Chantodepth
  573. returns the number of bits per pixel used by the
  574. format specified by
  575. .IR chan .
  576. Both
  577. .B chantodepth
  578. and
  579. .B strtochan
  580. return 0 when presented
  581. with bad input.
  582. .SH EXAMPLES
  583. To reconnect to the window after a resize event,
  584. .IP
  585. .EX
  586. if(getwindow(display, Refnone) < 0)
  587. sysfatal("resize failed: %r");
  588. .EE
  589. .PP
  590. To create and set up a new
  591. .IR rio (1)
  592. window,
  593. .IP
  594. .EX
  595. Image *screen2;
  596. Screen *_screen2;
  597. srvwsys = getenv("wsys");
  598. if(srvwsys == nil)
  599. sysfatal("can't find $wsys: %r");
  600. rfork(RFNAMEG); /* keep mount of rio private */
  601. fd = open(srvwsys, ORDWR);
  602. if(fd < 0)
  603. sysfatal("can't open $wsys: %r");
  604. /* mount creates window; see \f2rio\fP(4) */
  605. if(mount(fd, -1, "/tmp", MREPL, "new -dx 300-dy 200") < 0)
  606. sysfatal("can't mount new window: %r");
  607. if(gengetwindow(display, "/tmp/winname",
  608. &screen2, &_screen2, Refnone) < 0)
  609. sysfatal("resize failed: %r");
  610. /* now open /tmp/cons, /tmp/mouse */
  611. \&...
  612. .EE
  613. .SH FILES
  614. .BR /lib/font/bit " directory of fonts
  615. .SH SOURCE
  616. .B /sys/src/libdraw
  617. .SH "SEE ALSO"
  618. .IR rio (1),
  619. .IR addpt (2),
  620. .IR allocimage (2),
  621. .IR cachechars (2),
  622. .IR subfont (2),
  623. .IR draw (2),
  624. .IR event (2),
  625. .IR frame (2),
  626. .IR print (2),
  627. .IR window (2),
  628. .IR draw (3),
  629. .IR rio (4),
  630. .IR image (6),
  631. .IR font (6)
  632. .SH DIAGNOSTICS
  633. An error function may call
  634. .IR errstr (2)
  635. for further diagnostics.
  636. .SH BUGS
  637. The names
  638. .B clr
  639. and
  640. .B set
  641. in the
  642. .B Cursor
  643. structure are reminders of an archaic color map
  644. and might be more appropriately called
  645. .B white
  646. and
  647. .BR black .