draw 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791
  1. .TH DRAW 3
  2. .SH NAME
  3. draw \- screen graphics
  4. .SH SYNOPSIS
  5. .nf
  6. .B bind -a #i /dev
  7. .B /dev/draw/new
  8. .BI /dev/draw/ n /ctl
  9. .BI /dev/draw/ n /data
  10. .BI /dev/draw/ n /colormap
  11. .BI /dev/draw/ n /refresh
  12. .ft L
  13. #include <u.h>
  14. #include <draw.h>
  15. .ta \w'ushort 'u
  16. ushort BGSHORT(uchar *p)
  17. ulong BGLONG(uchar *p)
  18. void BPSHORT(uchar *p, ushort v)
  19. void BPLONG(uchar *p, ulong v)
  20. .ft P
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. .I draw
  25. device serves a three-level file system
  26. providing an interface to the graphics facilities of the system.
  27. Each client of the device connects by opening
  28. .B /dev/draw/new
  29. and reading 12 strings, each 11 characters wide followed by a blank:
  30. the connection number
  31. .RI ( n ),
  32. the image id
  33. .RI ( q.v. )
  34. of the display image (always zero),
  35. the
  36. channel format
  37. of the image,
  38. the
  39. .BR min.x ,
  40. .BR min.y ,
  41. .BR max.x ,
  42. and
  43. .B max.y
  44. of the display image,
  45. and the
  46. .BR min.x ,
  47. .BR min.y ,
  48. .BR max.x ,
  49. and
  50. .B max.y
  51. of the clipping rectangle.
  52. The channel format string is described in
  53. .IR image (6),
  54. and the other fields are decimal numbers.
  55. .PP
  56. The client can then open the directory
  57. .BI /dev/draw/ n /
  58. to access the
  59. .BR ctl ,
  60. .BR data ,
  61. .BR colormap ,
  62. and
  63. .B refresh
  64. files associated with the connection.
  65. .PP
  66. Via the
  67. .B ctl
  68. and
  69. .B draw
  70. files, the
  71. .I draw
  72. device provides access to
  73. images and font caches
  74. in its private storage,
  75. as described in
  76. .IR graphics (2).
  77. Each image is identified by a 4-byte integer, its
  78. .IR id .
  79. .PP
  80. Reading the
  81. .B ctl
  82. file yields 12 strings formatted as in
  83. .BR /dev/draw/new ,
  84. but for the current image rather
  85. than the display image.
  86. The current image may be set by writing a
  87. binary image id to the
  88. .B ctl
  89. file.
  90. .PP
  91. A process can write messages to
  92. .B data
  93. to allocate and free images, fonts, and subfonts;
  94. read or write portions of the images;
  95. and draw line segments and character
  96. strings in the images.
  97. All graphics requests are clipped to their images.
  98. Some messages return a response to be recovered by
  99. reading the
  100. .B data
  101. file.
  102. .PP
  103. The format of messages written to
  104. .B data
  105. is a single letter
  106. followed by binary parameters;
  107. multibyte integers are transmitted with the low order byte first.
  108. The
  109. .B BPSHORT
  110. and
  111. .B BPLONG
  112. macros place correctly formatted two- and four-byte integers into a character
  113. buffer.
  114. .B BGSHORT
  115. and
  116. .B BGLONG
  117. retrieve values from a character buffer.
  118. Points are two four-byte numbers:
  119. .IR x ,
  120. .IR y .
  121. Rectangles are four four-byte numbers: min
  122. .IR x ,
  123. min
  124. .IR y ,
  125. max
  126. .IR x ,
  127. and max
  128. .IR y .
  129. Images, screens, and fonts have 32-bit identifiers.
  130. In the discussion of the protocol below,
  131. the distinction between identifier and actual image, screen, or font
  132. is not made, so that
  133. ``the object
  134. .IR id ''
  135. should be interpreted as
  136. ``the object with identifier
  137. .IR id ''.
  138. The definitions of constants used in the description below can be found in
  139. .BR draw.h .
  140. .PP
  141. The following requests are accepted by the
  142. .B data
  143. file.
  144. The numbers in brackets give the length in bytes of the parameters.
  145. .HP .5i
  146. .B A
  147. .IR id [4]
  148. .IR imageid [4]
  149. .IR fillid [4]
  150. .IR public [1]
  151. .br
  152. Allocate a new
  153. .B Screen
  154. (see
  155. .IR window (2))
  156. with
  157. screen identifier
  158. .I id
  159. using
  160. backing store image
  161. .IR imageid ,
  162. filling it initially
  163. with data from image
  164. .IR fillid .
  165. If the
  166. .I public
  167. byte is non-zero, the screen can
  168. be accessed from other processes
  169. using the
  170. .B publicscreen
  171. interface.
  172. .HP
  173. .B b
  174. .IR id [4]
  175. .IR screenid [4]
  176. .IR refresh [1]
  177. .IR chan [4]
  178. .IR repl [1]
  179. .IR r [4*4]
  180. .IR clipr [4*4]
  181. .IR color [4]
  182. .br
  183. Allocate an image with a given
  184. .I id
  185. on the
  186. screen named by
  187. .IR screenid .
  188. The image will have rectangle
  189. .I r
  190. and clipping rectangle
  191. .IR clipr .
  192. If
  193. .I repl
  194. is non-zero, the image's replicate
  195. bit will be set (see
  196. .IR draw (2)).
  197. .IP
  198. .I Refresh
  199. specifies the method to be used to draw the window
  200. when it is uncovered.
  201. .B Refbackup
  202. causes the server to maintain a backing store,
  203. .B Refnone
  204. does not refresh the image,
  205. and
  206. .B Refmesg
  207. causes a message to be sent via
  208. the
  209. .B refresh
  210. file
  211. .RI ( q.v. ).
  212. .IP
  213. The image format is described by
  214. .IR chan ,
  215. a binary version of the channel format string.
  216. Specifically, the image format is the catenation of up to four
  217. 8-bit numbers, each describing a particular image channel.
  218. Each of these 8-bit numbers contains a channel type in its
  219. high nibble and a bit count in its low nibble.
  220. The channel type is one of
  221. .BR CRed ,
  222. .BR CGreen ,
  223. .BR CBlue ,
  224. .BR CGrey ,
  225. .BR CAlpha ,
  226. .BR CMap ,
  227. and
  228. .BR CIgnore .
  229. See
  230. .IR image (6).
  231. .IP
  232. .I Color
  233. is the catenation of four 8-bit numbers
  234. specifying the red, green, blue, and alpha
  235. channels of the color that the new image should
  236. be initially filled with.
  237. The red channel is in the highest 8 bits, and
  238. the alpha in the lowest.
  239. Note that color is always in this format, independent of
  240. the image format.
  241. .HP
  242. .B c
  243. .IR dstid [4]
  244. .IR repl [1]
  245. .IR clipr [4*4]
  246. .br
  247. Change the replicate bit and clipping rectangle of the
  248. image
  249. .IR dstid .
  250. This overrides whatever settings were specified in
  251. the allocate message.
  252. .HP
  253. .B d
  254. .IR dstid [4]
  255. .IR srcid [4]
  256. .IR maskid [4]
  257. .IR dstr [4*4]
  258. .IR srcp [2*4]
  259. .IR maskp [2*4]
  260. .br
  261. Use the
  262. .B draw
  263. operator to combine the rectangle
  264. .I dstr
  265. of
  266. image
  267. .I dstid
  268. with a
  269. rectangle of image
  270. .IR srcid ,
  271. using a rectangle of image
  272. .IR maskid
  273. as an alpha mask to further control blending.
  274. The three rectangles are congruent and aligned such that
  275. the upper left corner
  276. .I dstr
  277. in image
  278. .I dstid
  279. corresponds to
  280. the point
  281. .I srcp
  282. in image
  283. .I srcid
  284. and
  285. the point
  286. .I maskp
  287. in image
  288. .IR maskid .
  289. See
  290. .IR draw (2).
  291. .HP
  292. .B D
  293. .IR debugon [1]
  294. .br
  295. If
  296. .I debugon
  297. is non-zero, enable debugging output.
  298. If zero, disable it.
  299. The meaning of ``debugging output'' is implementation dependent.
  300. .HP
  301. .B e
  302. .IR dstid [4]
  303. .IR srcid [4]
  304. .IR c [2*4]
  305. .IR a [4]
  306. .IR b [4]
  307. .IR thick [4]
  308. .IR sp [2*4]
  309. .IR alpha [4]
  310. .IR phi [4]
  311. .br
  312. Draw an ellipse in image
  313. .I dst
  314. centered on the point
  315. .I c
  316. with horizontal and vertical semiaxes
  317. .I a
  318. and
  319. .IR b .
  320. The ellipse is drawn using the image
  321. .IR src ,
  322. with
  323. the point
  324. .I sp
  325. in
  326. .I src
  327. aligned with
  328. .I c
  329. in
  330. .IR dst .
  331. The ellipse is drawn with thickness
  332. .RI 1+2× thick .
  333. .IP
  334. If the high bit of
  335. .I alpha
  336. is set,
  337. only the arc of the ellipse from degree angles
  338. .I alpha
  339. to
  340. .I phi
  341. is drawn.
  342. For the purposes of drawing the arc,
  343. .I alpha
  344. is treated as a signed 31-bit number
  345. by ignoring its high bit.
  346. .HP
  347. .B E
  348. .IR dstid [4]
  349. .IR srcid [4]
  350. .IR center [2*4]
  351. .IR a [4]
  352. .IR b [4]
  353. .IR thick [4]
  354. .IR sp [2*4]
  355. .IR alpha [4]
  356. .IR phi [4]
  357. .br
  358. Draws an ellipse or arc as the
  359. .B e
  360. message, but rather than outlining it, fills
  361. the corresponding sector using the image
  362. .IR srcid .
  363. The
  364. .I thick
  365. field is ignored, but must be non-negative.
  366. .HP
  367. .B f
  368. .IR id [4]
  369. .br
  370. Free the resources associated with the image
  371. .IR id .
  372. .HP
  373. .B F
  374. .IR id [4]
  375. .br
  376. Free the the screen with the specified
  377. .IR id .
  378. Windows on the screen must be freed separately.
  379. .HP
  380. .B i
  381. .IR id [4]
  382. .IR n [4]
  383. .IR ascent [1]
  384. .br
  385. Treat the image
  386. .I id
  387. as a font cache of
  388. .I n
  389. character cells, each with
  390. ascent
  391. .IR ascent .
  392. .HP
  393. .B l
  394. .IR cacheid [4]
  395. .IR srcid [4]
  396. .IR index [2]
  397. .IR r [4*4]
  398. .IR sp [2*4]
  399. .IR left [1]
  400. .IR width [1]
  401. .br
  402. Load a character into the font cache associated with image
  403. .I cacheid
  404. at cache position
  405. .IR index .
  406. The character data is drawn in rectangle
  407. .I r
  408. of the font cache image
  409. and is fetched from
  410. the congruent rectangle in image
  411. .I srcid
  412. with upper left corner
  413. .IR sp .
  414. .I Width
  415. specifies the width of the character\(emthe spacing from this character to the next\(emwhile
  416. .I left
  417. specifies
  418. the horizontal distance from the left side
  419. of the character to the left side of the cache image.
  420. The dimensions of the image of the character are defined by
  421. .IR r .
  422. .HP
  423. .B L
  424. .IR dstid [4]
  425. .IR p0 [2*4]
  426. .IR p1 [2*4]
  427. .IR end0 [4]
  428. .IR end1 [4]
  429. .IR thick [4]
  430. .IR srcid [4]
  431. .IR sp [2*4]
  432. .br
  433. Draw a line of thickness
  434. .RI 1+2× thick
  435. in image
  436. .I dstid
  437. from point
  438. .I p0
  439. to
  440. .IR p1 .
  441. The line is drawn using the image
  442. .IR srcid ,
  443. translated so that point
  444. .I sp
  445. in
  446. .I srcid
  447. aligns with
  448. .I p0
  449. in
  450. .IR dstid .
  451. The
  452. .I end0
  453. and
  454. .I end1
  455. fields specify whether the corresponding
  456. line end should be a square, a disc,
  457. or an arrow head.
  458. See
  459. .I line
  460. in
  461. .IR draw (2)
  462. for more details.
  463. .HP
  464. .B N
  465. .IR id [4]
  466. .IR in [1]
  467. .IR j [1]
  468. .IR name [ j ]
  469. .br
  470. If
  471. .I in
  472. is non-zero, associate the image
  473. .I id
  474. with the string
  475. .IR name .
  476. If
  477. .I in
  478. is zero and
  479. .I name
  480. already corresponds to the
  481. image
  482. .IR id ,
  483. the association is deleted.
  484. .HP
  485. .B n
  486. .IR id [4]
  487. .IR j [1]
  488. .IR name [ j ]
  489. .br
  490. Introduce the identifier
  491. .I id
  492. to correspond to the image named
  493. by the string
  494. .IR name .
  495. .HP
  496. .B o
  497. .IR id [4]
  498. .IR r.min [2*4]
  499. .IR scr [2*4]
  500. .br
  501. Position the window
  502. .I id
  503. so that its upper left corner is at the
  504. point
  505. .I scr
  506. on its screen.
  507. Simultaneously change its internal (logical) coordinate system
  508. so that the point
  509. .I log
  510. corresponds to the upper left corner of the window.
  511. .HP
  512. .B O
  513. .IR op [1]
  514. .br
  515. Set the compositing operator to
  516. .I op
  517. for the next draw operation.
  518. (The default is
  519. .BR SoverD ).
  520. .HP
  521. .B p
  522. .IR dstid [4]
  523. .IR n [2]
  524. .IR end0 [4]
  525. .IR end1 [4]
  526. .IR thick [4]
  527. .IR srcid [4]
  528. .IR sp [2*4]
  529. .IR dp [2*2*(n+1)]
  530. .br
  531. Draw a polygon of thickness
  532. .RI 1+2× thick .
  533. It is conceptually equivalent to a series of
  534. .I n
  535. line-drawing messages (see
  536. .B L
  537. above)
  538. joining adjacent points in the list of points
  539. .IR dp .
  540. The source image
  541. .I srcid
  542. is translated so that the point
  543. .I sp
  544. in
  545. .I srcid
  546. aligns with the first point
  547. in the list
  548. .IR dp .
  549. The polygon need not be closed:
  550. .I end0
  551. and
  552. .I end1
  553. specify the line endings for the first and
  554. last point on the polygon.
  555. All interior lines have rounded ends
  556. to make smooth joins.
  557. .HP
  558. .B P
  559. .IR dstid [4]
  560. .IR n [2]
  561. .IR wind [4]
  562. .IR ignore [2*4]
  563. .IR srcid [4]
  564. .IR sp [2*4]
  565. .IR dp [2*2*(n+1)]
  566. .br
  567. Draw a polygon as the
  568. .B p
  569. message, but
  570. fill it rather than outlining it.
  571. The winding rule parameter
  572. .I wind
  573. resolves ambiguities about what to fill if the polygon is self-intersecting.
  574. If
  575. .I wind
  576. is
  577. .BR ~0 ,
  578. a pixel is inside the polygon if the polygon's winding number about the point
  579. is non-zero.
  580. If
  581. .I wind
  582. is
  583. .BR 1 ,
  584. a pixel is inside if the winding number is odd.
  585. Complementary values (0 or ~1) cause outside pixels to be filled.
  586. The meaning of other values is undefined.
  587. The polygon is closed with a line if necessary.
  588. .HP
  589. .B r
  590. .IR id [4]
  591. .IR r [4*4]
  592. .br
  593. Cause the next read of the
  594. .B data
  595. file to return the image pixel data corresponding to the
  596. rectangle
  597. .I r
  598. in image
  599. .IR id .
  600. .HP
  601. .B s
  602. .IR dstid [4]
  603. .IR srcid [4]
  604. .IR fontid [4]
  605. .IR p [2*4]
  606. .IR clipr [4*4]
  607. .IR sp [2*4]
  608. .IR n [2]
  609. .IR n*(index [2])
  610. .br
  611. Draw in the image
  612. .I dstid
  613. the text string specified by the
  614. .I n
  615. cache
  616. .I indices
  617. into font
  618. .IR fontid ,
  619. starting with the upper left corner at point
  620. .I p
  621. in image
  622. .IR dstid .
  623. The image drawn is taken from image
  624. .IR srcid ,
  625. translated to align
  626. .I sp
  627. in
  628. .I srcid
  629. with
  630. .I dp
  631. in
  632. .IR dstid.
  633. All drawing is confined to the clipping rectangle
  634. .I clipr
  635. in
  636. .IR dstid .
  637. .HP
  638. .B x
  639. .IR dstid [4]
  640. .IR srcid [4]
  641. .IR fontid [4]
  642. .IR dp [2*4]
  643. .IR clipr [4*4]
  644. .IR sp [2*4]
  645. .IR n [2]
  646. .IR bgid [4]
  647. .IR bp [2*4]
  648. .IR n*(index [2])
  649. .br
  650. Like the string drawing
  651. .B s
  652. command, but fill the background of each character
  653. with pixels from image
  654. .IR bgid .
  655. The image
  656. .I bgid
  657. is translated so that the point
  658. .I bp
  659. aligns with the
  660. point
  661. .I dp
  662. in
  663. .IR dstid .
  664. .HP
  665. .B S
  666. .IR id [4]
  667. .IR chan [4]
  668. Attach to the public screen with the specified
  669. .IR id .
  670. It is an error if the screen does not exist, is not public, or does not
  671. have the channel descriptor
  672. .I chan
  673. for its associated image.
  674. .HP
  675. .B t
  676. .IR top [1]
  677. .IR n [2]
  678. .IR n*id [4]
  679. .br
  680. Send
  681. .I n
  682. windows to the top (if
  683. .I t
  684. is non-zero) or bottom (if
  685. .I t
  686. is zero) of the window stack.
  687. The window is specified by the list of
  688. .I n
  689. image
  690. .IR id s
  691. are moved as a group, maintaining their own order within the stack.
  692. .HP
  693. .B v
  694. .br
  695. Flush changes from a soft screen, if any, to the display buffer.
  696. .HP
  697. .B y
  698. .IR id [4]
  699. .IR r [4*4]
  700. .IR buf [x*1]
  701. .br
  702. .ti -0.5i
  703. .B Y
  704. .IR id [4]
  705. .IR r [4*4]
  706. .IR buf [x*1]
  707. .br
  708. Replace the rectangle
  709. .I r
  710. of pixels in image
  711. .I id
  712. with the pixel data in
  713. .IR buf .
  714. The pixel data must be in the format dictated by
  715. .IR id 's
  716. image channel descriptor (see
  717. .IR image (6)).
  718. The
  719. .B y
  720. message uses uncompressed data,
  721. while the
  722. .B Y
  723. message uses compressed data.
  724. In either case,
  725. it is an error to include more data than necessary.
  726. .PP
  727. Reading the
  728. .B colormap
  729. returns the system color map used on 8-bit displays.
  730. Each color map entry consists of a single line containing
  731. four space-separated decimal strings.
  732. The first is an index into the map, and the remaining three are
  733. the red, green, and blue values associated with that index.
  734. The color map can be changed by writing entries in the
  735. above format to
  736. the
  737. .B colormap
  738. file.
  739. Note that changing the system color map
  740. does not change the color map used for
  741. calculations involving
  742. .B m8
  743. images, which is immutable.
  744. .PP
  745. The
  746. .B refresh
  747. file is read-only.
  748. As windows owned by the client are uncovered,
  749. if they cannot be refreshed by the server (such as when they have
  750. refresh functions associated with them), a message is made available
  751. on the
  752. .B refresh
  753. file reporting what needs to be repainted by the client.
  754. The message has five decimal integers formatted as in the
  755. .B ctl
  756. message: the image id of the window and the coordinates of the rectangle
  757. that should be refreshed.
  758. .SH SOURCE
  759. .B /sys/src/9/port/devdraw.c
  760. .br
  761. .B /sys/src/libmemdraw
  762. .SH DIAGNOSTICS
  763. Most messages to
  764. .B draw
  765. can return errors;
  766. these can be detected by a system call error
  767. on the
  768. .IR write (see
  769. .IR read (2))
  770. of the data containing the erroneous message.
  771. The most common error is a failure to allocate
  772. because of insufficient free resources. Most other errors occur
  773. only when the protocol is mishandled by the application.
  774. .IR Errstr (2)
  775. will report details.
  776. .SH BUGS
  777. The
  778. .B Refmesg
  779. refresh method is not fully implemented.
  780. .br
  781. The
  782. .B colormap
  783. files only reference the system color map, and as
  784. such should be called
  785. .B /dev/colormap
  786. rather than
  787. .BI /dev/draw/ n /colormap\f1.