1
0

memdraw 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448
  1. .TH MEMDRAW 2
  2. .SH NAME
  3. Memimage,
  4. Memdata,
  5. Memdrawparam,
  6. memimageinit,
  7. wordaddr,
  8. byteaddr,
  9. memimagemove,
  10. allocmemimage,
  11. allocmemimaged,
  12. readmemimage,
  13. creadmemimage,
  14. writememimage,
  15. freememimage,
  16. memsetchan,
  17. loadmemimage,
  18. cloadmemimage,
  19. unloadmemimage,
  20. memfillcolor,
  21. memarc,
  22. mempoly,
  23. memellipse,
  24. memfillpoly,
  25. memimageline,
  26. memimagedraw,
  27. drawclip,
  28. memlinebbox,
  29. memlineendsize,
  30. allocmemsubfont,
  31. openmemsubfont,
  32. freememsubfont,
  33. memsubfontwidth,
  34. getmemdefont,
  35. memimagestring,
  36. iprint,
  37. hwdraw \- drawing routines for memory-resident images
  38. .SH SYNOPSIS
  39. .nf
  40. .B #include <u.h>
  41. .B #include <libc.h>
  42. .B #include <draw.h>
  43. .B #include <memdraw.h>
  44. .PP
  45. .ft L
  46. typedef struct Memdata
  47. {
  48. ulong *base; /* allocated data pointer */
  49. uchar *bdata; /* first byte of actual data; word-aligned */
  50. int ref; /* number of Memimages using this data */
  51. void* imref; /* last image that pointed at this */
  52. int allocd; /* is this malloc'd? */
  53. } Memdata;
  54. enum {
  55. Frepl = 1<<0, /* is replicated */
  56. Fsimple = 1<<1, /* is 1x1 */
  57. Fgrey = 1<<2, /* is grey */
  58. Falpha = 1<<3, /* has explicit alpha */
  59. Fcmap = 1<<4, /* has cmap channel */
  60. Fbytes = 1<<5, /* has only 8-bit channels */
  61. };
  62. typedef struct Memimage
  63. {
  64. Rectangle r; /* rectangle in data area, local coords */
  65. Rectangle clipr; /* clipping region */
  66. int depth; /* number of bits of storage per pixel */
  67. int nchan; /* number of channels */
  68. ulong chan; /* channel descriptions */
  69. Memdata *data; /* pointer to data */
  70. int zero; /* data->bdata+zero==&byte containing (0,0) */
  71. ulong width; /* width in words of a single scan line */
  72. Memlayer *layer; /* nil if not a layer*/
  73. ulong flags;
  74. \fI...\fP
  75. } Memimage;
  76. typedef struct Memdrawparam
  77. {
  78. Memimage *dst;
  79. Rectangle r;
  80. Memimage *src;
  81. Rectangle sr;
  82. Memimage *mask;
  83. Rectangle mr;
  84. \fI...\fP
  85. } Memdrawparam;
  86. .ta \w'\fLMemsubfont* 'u
  87. int drawdebug;
  88. .ft
  89. .PP
  90. .ft L
  91. .nf
  92. void memimageinit(void)
  93. ulong* wordaddr(Memimage *i, Point p)
  94. uchar* byteaddr(Memimage *i, Point p)
  95. void memimagemove(void *from, void *to)
  96. .PP
  97. .ft L
  98. .nf
  99. Memimage* allocmemimage(Rectangle r, ulong chan)
  100. Memimage* allocmemimaged(Rectangle r, ulong chan, Memdata *data)
  101. Memimage* readmemimage(int fd)
  102. Memimage* creadmemimage(int fd)
  103. int writememimage(int fd, Memimage *i)
  104. void freememimage(Memimage *i)
  105. int memsetchan(Memimage*, ulong)
  106. .PP
  107. .ft L
  108. .nf
  109. int loadmemimage(Memimage *i, Rectangle r,
  110. uchar *buf, int nbuf)
  111. int cloadmemimage(Memimage *i, Rectangle r,
  112. uchar *buf, int nbuf)
  113. int unloadmemimage(Memimage *i, Rectangle r,
  114. uchar *buf, int nbuf)
  115. void memfillcolor(Memimage *i, ulong color)
  116. .PP
  117. .ft L
  118. .nf
  119. void memarc(Memimage *dst, Point c, int a, int b, int thick,
  120. Memimage *src, Point sp, int alpha, int phi, Drawop op)
  121. void mempoly(Memimage *dst, Point *p, int np, int end0,
  122. int end1, int radius, Memimage *src, Point sp, Drawop op)
  123. void memellipse(Memimage *dst, Point c, int a, int b,
  124. int thick, Memimage *src, Point sp, Drawop op)
  125. void memfillpoly(Memimage *dst, Point *p, int np, int wind,
  126. Memimage *src, Point sp, Drawop op)
  127. void memimageline(Memimage *dst, Point p0, Point p1, int end0,
  128. int end1, int radius, Memimage *src, Point sp, Drawop op)
  129. void memimagedraw(Memimage *dst, Rectangle r, Memimage *src,
  130. Point sp, Memimage *mask, Point mp, Drawop op)
  131. .PP
  132. .ft L
  133. .nf
  134. int drawclip(Memimage *dst, Rectangle *dr, Memimage *src,
  135. Point *sp, Memimage *mask, Point *mp,
  136. Rectangle *sr, Rectangle *mr)
  137. Rectangle memlinebbox(Point p0, Point p1, int end0, int end1,
  138. int radius)
  139. int memlineendsize(int end)
  140. .PP
  141. .ft L
  142. .nf
  143. Memsubfont* allocmemsubfont(char *name, int n, int height,
  144. int ascent, Fontchar *info, Memimage *i)
  145. Memsubfont* openmemsubfont(char *name)
  146. void freememsubfont(Memsubfont *f)
  147. Point memsubfontwidth(Memsubfont *f, char *s)
  148. Memsubfont* getmemdefont(void)
  149. Point memimagestring(Memimage *dst, Point p, Memimage *color,
  150. Point cp, Memsubfont *f, char *cs)
  151. .PP
  152. .ft L
  153. .nf
  154. int iprint(char *fmt, ...)
  155. int hwdraw(Memdrawparam *param)
  156. .ft R
  157. .SH DESCRIPTION
  158. The
  159. .B Memimage
  160. type defines memory-resident rectangular pictures and the methods to draw upon them;
  161. .BR Memimage s
  162. differ from
  163. .BR Image s
  164. (see
  165. .IR draw (2))
  166. in that they are manipulated directly in user memory rather than by
  167. RPCs to the
  168. .B /dev/draw
  169. hierarchy.
  170. The
  171. .B memdraw
  172. library is the basis for the kernel
  173. .IR draw (3)
  174. driver and also used by a number of programs that must manipulate
  175. images without a display.
  176. .PP
  177. The
  178. .BR r,
  179. .BR clipr ,
  180. .BR depth ,
  181. .BR nchan ,
  182. and
  183. .BR chan
  184. structure elements are identical to
  185. the ones of the same name
  186. in the
  187. .B Image
  188. structure.
  189. .PP
  190. The
  191. .B flags
  192. element of the
  193. .B Memimage
  194. structure holds a number of bits of information about the image.
  195. In particular, it subsumes the
  196. purpose of the
  197. .B repl
  198. element of
  199. .B Image
  200. structures.
  201. .PP
  202. .I Memimageinit
  203. initializes various static data that the library depends on,
  204. as well as the replicated solid color images
  205. .BR memopaque ,
  206. .BR memtransparent ,
  207. .BR memblack ,
  208. and
  209. .BR memwhite .
  210. It should be called before referring to any of these images
  211. and before calling any of the other library functions.
  212. .PP
  213. Each
  214. .B Memimage
  215. points at a
  216. .B Memdata
  217. structure that in turn points at the actual pixel data for the image.
  218. This allows multiple images to be associated with the same
  219. .BR Memdata .
  220. The first word of the data pointed at by
  221. the
  222. .B base
  223. element of
  224. .B Memdata
  225. points back at the
  226. .B Memdata
  227. structure, so that the
  228. memory allocator (see
  229. .IR pool (2))
  230. can compact image memory
  231. using
  232. .IR memimagemove .
  233. .PP
  234. Because images can have different coordinate systems,
  235. the
  236. .B zero
  237. element of the
  238. .B Memimage
  239. structure contains the offset that must be added
  240. to the
  241. .B bdata
  242. element of the corresponding
  243. .B Memdata
  244. structure in order to yield a pointer to the data for the pixel (0,0).
  245. Adding
  246. .BR width
  247. machine words
  248. to this pointer moves it down one scan line.
  249. The
  250. .B depth
  251. element can be used to determine how to move the
  252. pointer horizontally.
  253. Note that this method works even for images whose rectangles
  254. do not include the origin, although one should only dereference
  255. pointers corresponding to pixels within the image rectangle.
  256. .I Wordaddr
  257. and
  258. .IR byteaddr
  259. perform these calculations,
  260. returning pointers to the word and byte, respectively,
  261. that contain the beginning of the data for a given pixel.
  262. .PP
  263. .I Allocmemimage
  264. allocages
  265. images with a given rectangle and channel descriptor
  266. (see
  267. .B strtochan
  268. in
  269. .IR graphics (2)),
  270. creating a fresh
  271. .B Memdata
  272. structure and associated storage.
  273. .I Allocmemimaged
  274. is similar but uses the supplied
  275. .I Memdata
  276. structure rather than a new one.
  277. The
  278. .I readmemimage
  279. function reads an uncompressed bitmap
  280. from the given file descriptor,
  281. while
  282. .I creadmemimage
  283. reads a compressed bitmap.
  284. .I Writememimage
  285. writes a compressed representation of
  286. .I i
  287. to file descriptor
  288. .IR fd .
  289. For more on bitmap formats, see
  290. .IR image (6).
  291. .I Freememimage
  292. frees images returned by any of these routines.
  293. The
  294. .B Memimage
  295. structure contains some tables that are used
  296. to store precomputed values depending on the channel descriptor.
  297. .I Memsetchan
  298. updates the
  299. .B chan
  300. element of the structure as well as these tables,
  301. returning \-1 if passed a bad channel descriptor.
  302. .PP
  303. .I Loadmemimage
  304. and
  305. .I cloadmemimage
  306. replace the pixel data for a given rectangle of an image
  307. with the given buffer of uncompressed or compressed
  308. data, respectively.
  309. When calling
  310. .IR cloadmemimage ,
  311. the buffer must contain an
  312. integral number of
  313. compressed chunks of data that exactly cover the rectangle.
  314. .I Unloadmemimage
  315. retrieves the uncompressed pixel data for a given rectangle of an image.
  316. All three return the number of bytes consumed on success,
  317. and \-1 in case of an error.
  318. .PP
  319. .I Memfillcolor
  320. fills an image with the given color, a 32-bit number as
  321. described in
  322. .IR color (2).
  323. .PP
  324. .IR Memarc ,
  325. .IR mempoly ,
  326. .IR memellipse ,
  327. .IR memfillpoly ,
  328. .IR memimageline ,
  329. and
  330. .I memimagedraw
  331. are identical to the
  332. .IR arc ,
  333. .IR poly ,
  334. .IR ellipse ,
  335. .IR fillpoly ,
  336. .IR line ,
  337. and
  338. .IR gendraw ,
  339. routines described in
  340. .IR draw (2),
  341. except that they operate on
  342. .BR Memimage s
  343. rather than
  344. .BR Image s.
  345. Similarly,
  346. .IR allocmemsubfont ,
  347. .IR openmemsubfont ,
  348. .IR freememsubfont ,
  349. .IR memsubfontwidth ,
  350. .IR getmemdefont ,
  351. and
  352. .I memimagestring
  353. are the
  354. .B Memimage
  355. analogues of
  356. .IR allocsubfont ,
  357. .IR openfont ,
  358. .IR freesubfont ,
  359. .IR strsubfontwidth ,
  360. .IR getdefont ,
  361. and
  362. .B string
  363. (see
  364. .IR subfont (2)
  365. and
  366. .IR graphics (2)),
  367. except that they operate
  368. only on
  369. .BR Memsubfont s
  370. rather than
  371. .BR Font s.
  372. .PP
  373. .I Drawclip
  374. takes the images involved in a draw operation,
  375. together with the destination rectangle
  376. .B dr
  377. and source
  378. and mask alignment points
  379. .B sp
  380. and
  381. .BR mp ,
  382. and
  383. clips them according to the clipping rectangles of the images involved.
  384. It also fills in the rectangles
  385. .B sr
  386. and
  387. .B mr
  388. with rectangles congruent to the returned destination rectangle
  389. but translated so the upper left corners are the returned
  390. .B sp
  391. and
  392. .BR mp .
  393. .I Drawclip
  394. returns zero when the clipped rectangle is empty.
  395. .I Memlinebbox
  396. returns a conservative bounding box containing a line between
  397. two points
  398. with given end styles
  399. and radius.
  400. .I Memlineendsize
  401. calculates the extra length added to a line by attaching
  402. an end of a given style.
  403. .PP
  404. The
  405. .I hwdraw
  406. and
  407. .I iprint
  408. functions are no-op stubs that may be overridden by clients
  409. of the library.
  410. .I Hwdraw
  411. is called at each call to
  412. .I memimagedraw
  413. with the current request's parameters.
  414. If it can satisfy the request, it should do so
  415. and return 1.
  416. If it cannot satisfy the request, it should return 0.
  417. This allows (for instance) the kernel to take advantage
  418. of hardware acceleration.
  419. .I Iprint
  420. should format and print its arguments;
  421. it is given much debugging output when
  422. the global integer variable
  423. .B drawdebug
  424. is non-zero.
  425. In the kernel,
  426. .I iprint
  427. prints to a serial line rather than the screen, for obvious reasons.
  428. .SH SOURCE
  429. .B /sys/src/libmemdraw
  430. .SH SEE ALSO
  431. .IR addpt (2),
  432. .IR color (2),
  433. .IR draw (2),
  434. .IR graphics (2),
  435. .IR memlayer (2),
  436. .IR stringsize (2),
  437. .IR subfont (2),
  438. .IR color (6),
  439. .IR utf (6)
  440. .SH BUGS
  441. .I Memimagestring
  442. is unusual in using a subfont rather than a font,
  443. and in having no parameter to align the source.