1
0

allocimage 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348
  1. .TH ALLOCIMAGE 2
  2. .SH NAME
  3. allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline \- allocating, freeing, reading, writing images
  4. .SH SYNOPSIS
  5. .nf
  6. .PP
  7. .B
  8. #include <u.h>
  9. .B
  10. #include <libc.h>
  11. .B
  12. #include <draw.h>
  13. .PP
  14. .ta \w'\fLImage 'u
  15. .B
  16. Image *allocimage(Display *d, Rectangle r,
  17. .br
  18. .B
  19. ulong chan, int repl, int col)
  20. .PP
  21. .B
  22. Image *allocimagemix(Display *d, ulong one, ulong three)
  23. .PP
  24. .B
  25. void freeimage(Image *i)
  26. .PP
  27. .B
  28. int nameimage(Image *i, char *name, int in)
  29. .PP
  30. .B
  31. Image *namedimage(Display *d, char *name)
  32. .PP
  33. .B
  34. ulong setalpha(ulong color, uchar alpha)
  35. .PP
  36. .B
  37. int loadimage(Image *i, Rectangle r, uchar *data, int ndata)
  38. .PP
  39. .B
  40. int cloadimage(Image *i, Rectangle r, uchar *data, int ndata)
  41. .PP
  42. .B
  43. int unloadimage(Image *i, Rectangle r, uchar *data, int ndata)
  44. .PP
  45. .B
  46. Image *readimage(Display *d, int fd, int dolock)
  47. .PP
  48. .B
  49. int writeimage(int fd, Image *i, int dolock)
  50. .PP
  51. .B
  52. int bytesperline(Rectangle r, int d)
  53. .PP
  54. .B
  55. int wordsperline(Rectangle r, int d)
  56. .PP
  57. .nf
  58. .B
  59. enum
  60. .nf
  61. .ft L
  62. .ta +4n +20
  63. {
  64. DOpaque = 0xFFFFFFFF,
  65. DTransparent = 0x00000000,
  66. DBlack = 0x000000FF,
  67. DWhite = 0xFFFFFFFF,
  68. DRed = 0xFF0000FF,
  69. DGreen = 0x00FF00FF,
  70. DBlue = 0x0000FFFF,
  71. DCyan = 0x00FFFFFF,
  72. DMagenta = 0xFF00FFFF,
  73. DYellow = 0xFFFF00FF,
  74. DPaleyellow = 0xFFFFAAFF,
  75. DDarkyellow = 0xEEEE9EFF,
  76. DDarkgreen = 0x448844FF,
  77. DPalegreen = 0xAAFFAAFF,
  78. DMedgreen = 0x88CC88FF,
  79. DDarkblue = 0x000055FF,
  80. DPalebluegreen = 0xAAFFFFFF,
  81. DPaleblue = 0x0000BBFF,
  82. DBluegreen = 0x008888FF,
  83. DGreygreen = 0x55AAAAFF,
  84. DPalegreygreen = 0x9EEEEEFF,
  85. DYellowgreen = 0x99994CFF,
  86. DMedblue = 0x000099FF,
  87. DGreyblue = 0x005DBBFF,
  88. DPalegreyblue = 0x4993DDFF,
  89. DPurpleblue = 0x8888CCFF,
  90. DNotacolor = 0xFFFFFF00,
  91. DNofill = DNotacolor,
  92. };
  93. .fi
  94. .SH DESCRIPTION
  95. A new
  96. .B Image
  97. on
  98. .B Display
  99. .B d
  100. is allocated with
  101. .BR allocimage ;
  102. it will have the rectangle, pixel channel format,
  103. and replication flag
  104. given by its arguments.
  105. Convenient pixel channels like
  106. .BR GREY1 ,
  107. .BR GREY2 ,
  108. .BR CMAP8 ,
  109. .BR RGB16 ,
  110. .BR RGB24 ,
  111. and
  112. .BR RGBA32
  113. are predefined.
  114. All the new image's pixels will have initial value
  115. .IR col .
  116. If
  117. .I col
  118. is
  119. .BR DNofill ,
  120. no initialization is done.
  121. Representative useful values of color are predefined:
  122. .BR DBlack ,
  123. .BR DWhite ,
  124. .BR DRed ,
  125. and so on.
  126. Colors are specified by 32-bit numbers comprising,
  127. from most to least significant byte,
  128. 8-bit values for red, green, blue, and alpha.
  129. The values correspond to illumination, so 0 is black and 255 is white.
  130. Similarly, for alpha 0 is transparent and 255 is opaque.
  131. The
  132. .I id
  133. field will have been set to the identifying number used by
  134. .B /dev/draw
  135. (see
  136. .IR draw (3)),
  137. and the
  138. .I cache
  139. field will be zero.
  140. If
  141. .I repl
  142. is true, the clip rectangle is set to a very large region; if false, it is set to
  143. .IR r .
  144. The
  145. .I depth
  146. field will be set to the number of bits per pixel specified
  147. by the channel descriptor
  148. (see
  149. .IR image (6)).
  150. .I Allocimage
  151. returns 0 if the server has run out of image memory.
  152. .PP
  153. .I Allocimagemix
  154. is used to allocate background colors.
  155. On 8-bit color-mapped displays, it
  156. returns a 2×2 replicated image with one pixel colored
  157. the color
  158. .I one
  159. and the other three with
  160. .IR three .
  161. (This simulates a wider range of tones than can be represented by a single pixel
  162. value on a color-mapped display.)
  163. On true color displays, it returns a 1×1 replicated image
  164. whose pixel is the result of mixing the two colors in
  165. a one to three ratio.
  166. .PP
  167. .I Freeimage
  168. frees the resources used by its argument image.
  169. .PP
  170. .I Nameimage
  171. publishes in the server the image
  172. .I i
  173. under the given
  174. .IR name .
  175. If
  176. .I in
  177. is non-zero, the image is published; otherwise
  178. .I i
  179. must be already named
  180. .I name
  181. and it is withdrawn from publication.
  182. .I Namedimage
  183. returns a reference to the image published under the given
  184. .I name
  185. on
  186. .B Display
  187. .IR d .
  188. These routines permit unrelated applications sharing a display to share an image;
  189. for example they provide the mechanism behind
  190. .B getwindow
  191. (see
  192. .IR graphics (2)).
  193. .PP
  194. The RGB values in a color are
  195. .I premultiplied
  196. by the alpha value; for example, a 50% red is
  197. .B 0x7F00007F
  198. not
  199. .BR 0xFF00007F .
  200. The function
  201. .I setalpha
  202. performs the alpha computation on a given
  203. .BR color ,
  204. ignoring its initial alpha value, multiplying the components by the supplied
  205. .BR alpha .
  206. For example, to make a 50% red color value, one could execute
  207. .B setalpha(DRed,
  208. .BR 0x7F) .
  209. .PP
  210. The remaining functions deal with moving groups of pixel
  211. values between image and user space or external files.
  212. There is a fixed format for the exchange and storage of
  213. image data
  214. (see
  215. .IR image (6)).
  216. .PP
  217. .I Unloadimage
  218. reads a rectangle of pixels from image
  219. .I i
  220. into
  221. .IR data ,
  222. whose length is specified by
  223. .IR ndata .
  224. It is an error if
  225. .I ndata
  226. is too small to accommodate the pixels.
  227. .PP
  228. .I Loadimage
  229. replaces the specified rectangle in image
  230. .I i
  231. with the
  232. .I ndata
  233. bytes of
  234. .IR data .
  235. .PP
  236. The pixels are presented one horizontal line at a time,
  237. starting with the top-left pixel of
  238. .IR r .
  239. In the data processed by these routines, each scan line starts with a new byte in the array,
  240. leaving the last byte of the previous line partially empty, if necessary.
  241. Pixels are packed as tightly as possible within
  242. .IR data ,
  243. regardless of the rectangle being extracted.
  244. Bytes are filled from most to least significant bit order,
  245. as the
  246. .I x
  247. coordinate increases, aligned so
  248. .IR x =0
  249. would appear as the leftmost pixel of its byte.
  250. Thus, for
  251. .B depth
  252. 1, the pixel at
  253. .I x
  254. offset 165 within the rectangle will be in a
  255. .I data
  256. byte at bit-position
  257. .B 0x04
  258. regardless of the overall
  259. rectangle: 165 mod 8 equals 5, and
  260. .B "0x80\ >>\ 5"
  261. equals
  262. .BR 0x04 .
  263. .PP
  264. .B Cloadimage
  265. does the same as
  266. .IR loadimage ,
  267. but for
  268. .I ndata
  269. bytes of compressed image
  270. .I data
  271. (see
  272. .IR image (6)).
  273. On each call to
  274. .IR cloadimage,
  275. the
  276. .I data
  277. must be at the beginning of a compressed data block, in particular,
  278. it should start with the
  279. .B y
  280. coordinate and data length for the block.
  281. .PP
  282. .IR Loadimage ,
  283. .IR cloadimage ,
  284. and
  285. .I unloadimage
  286. return the number of bytes copied.
  287. .PP
  288. .I Readimage
  289. creates an image from data contained in an external file (see
  290. .IR image (6)
  291. for the file format);
  292. .I fd
  293. is a file descriptor obtained by opening such a file for reading.
  294. The returned image is allocated using
  295. .IR allocimage .
  296. The
  297. .I dolock
  298. flag specifies whether the
  299. .B Display
  300. should be synchronized for multithreaded access; single-threaded
  301. programs can leave it zero.
  302. .PP
  303. .I Writeimage
  304. writes image
  305. .I i
  306. onto file descriptor
  307. .IR fd ,
  308. which should be open for writing.
  309. The format is as described for
  310. .IR readimage .
  311. .PP
  312. .I Readimage
  313. and
  314. .I writeimage
  315. do not close
  316. .IR fd .
  317. .PP
  318. .I Bytesperline
  319. and
  320. .I wordsperline
  321. return the number of bytes or words occupied in memory by one scan line of rectangle
  322. .I r
  323. in an image with
  324. .I d
  325. bits per pixel.
  326. .SH EXAMPLE
  327. To allocate a single-pixel replicated image that may be used to paint a region red,
  328. .EX
  329. red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);
  330. .EE
  331. .SH SOURCE
  332. .B /sys/src/libdraw
  333. .SH "SEE ALSO"
  334. .IR graphics (2),
  335. .IR draw (2),
  336. .IR draw (3),
  337. .IR image (6)
  338. .SH DIAGNOSTICS
  339. These functions return pointer 0 or integer \-1 on failure, usually due to insufficient
  340. memory.
  341. .PP
  342. May set
  343. .IR errstr .
  344. .SH BUGS
  345. .B Depth
  346. must be a divisor or multiple of 8.