1
0

memdraw 9.9 KB

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