1
0

graphics 12 KB

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