1
0

memlayer 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305
  1. .TH MEMLAYER 2
  2. .SH NAME
  3. memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, memltofront, memltofrontn, memltorear, memltorearn \- windows of memory-resident images
  4. .SH SYNOPSIS
  5. .nf
  6. .B #include <u.h>
  7. .br
  8. .B #include <libc.h>
  9. .br
  10. .B #include <draw.h>
  11. .br
  12. .B #include <memdraw.h>
  13. .br
  14. .B #include <memlayer.h>
  15. .PP
  16. .ft L
  17. typedef struct Memscreen Memscreen;
  18. typedef struct Memlayer Memlayer;
  19. typedef void (*Refreshfn)(Memimage*, Rectangle, void*);
  20. .ta 4n +\w'\fLRefreshfn 'u +\w'\fL*frontmost; 'u
  21. struct Memscreen
  22. {
  23. Memimage *frontmost; /* frontmost layer on screen */
  24. Memimage *rearmost; /* rearmost layer on screen */
  25. Memimage *image; /* upon which all layers are drawn */
  26. Memimage *fill; /* if non-zero, picture to use when repainting */
  27. };
  28. struct Memlayer
  29. {
  30. Rectangle screenr; /* true position of layer on screen */
  31. Point delta; /* add delta to go from image coords to screen */
  32. Memscreen *screen; /* screen this layer belongs to */
  33. Memimage *front; /* window in front of this one */
  34. Memimage *rear; /* window behind this one*/
  35. int clear; /* layer is fully visible */
  36. Memimage *save; /* save area for obscured parts */
  37. Refreshfn refreshfn; /* fn to refresh obscured parts if save==nil */
  38. void *refreshptr; /* argument to refreshfn */
  39. };
  40. .ft
  41. .ta \w'\fLMemimage* 'u
  42. .PP
  43. .B
  44. Memimage* memlalloc(Memscreen *s, Rectangle r, Refreshfn fn, void *arg, ulong col)
  45. .PP
  46. .B void memlnorefresh(Memimage *i, Rectangle r, void *arg)
  47. .PP
  48. .B
  49. int memlsetrefresh(Memimage *i, Refreshfn fn, void *arg)
  50. .PP
  51. .B
  52. int memldelete(Memimage *i)
  53. .PP
  54. .B
  55. int memlfree(Memimage *i)
  56. .PP
  57. .B
  58. int memlexpose(Memimage *i, Rectangle r)
  59. .PP
  60. .B
  61. int memlhide(Memimage *i, Rectangle r)
  62. .PP
  63. .B
  64. void memltofront(Memimage *i)
  65. .PP
  66. .B
  67. void memltofrontn(Memimage**ia, int n)
  68. .PP
  69. .B
  70. void memltorear(Memimage *i)
  71. .PP
  72. .B
  73. void memltorearn(Memimage **ia , int n)
  74. .PP
  75. .B
  76. int memlorigin(Memimage *i, Point log, Point phys)
  77. .PP
  78. .B
  79. void memdraw(Image *dst, Rectangle r,
  80. .br
  81. .B
  82. Image *src, Point sp, Image *mask, Point mp, Drawop op)
  83. .fi
  84. .B
  85. int memload(Memimage *i, Rectangle r,
  86. .br
  87. .B
  88. uchar *buf, int n, int iscompressed)
  89. .PP
  90. .B
  91. int memunload(Memimage *i, Rectangle r,
  92. .br
  93. .B
  94. uchar *buf, int n)
  95. .PP
  96. .SH DESCRIPTION
  97. These functions build upon the
  98. .IR memdraw (2)
  99. interface to maintain overlapping graphical windows on in-memory images.
  100. They are used by the kernel to implement the windows interface presented by
  101. .IR draw (3)
  102. and
  103. .IR window (2)
  104. and probably have little use outside of the kernel.
  105. .PP
  106. The basic function is to extend the definition of a
  107. .B Memimage
  108. (see
  109. .IR memdraw (2))
  110. to include overlapping windows defined by the
  111. .B Memlayer
  112. type.
  113. The first fields of the
  114. .B Memlayer
  115. structure are identical to those in
  116. .BR Memimage ,
  117. permitting a function that expects a
  118. .B Memimage
  119. to be passed a
  120. .BR Memlayer ,
  121. and vice versa.
  122. Both structures have a
  123. .B save
  124. field, which is nil in a
  125. .B Memimage
  126. and points to `backing store' in a
  127. .BR Memlayer .
  128. The layer routines accept
  129. .B Memimages
  130. or
  131. .BR Memlayers ;
  132. if the image is a
  133. .B Memimage
  134. the underlying
  135. .B Memimage
  136. routine is called; otherwise the layer routines recursively
  137. subdivide the geometry, reducing the operation into a smaller
  138. component that ultimately can be performed on a
  139. .BR Memimage ,
  140. either the display on which the window appears, or the backing store.
  141. .PP
  142. .B Memlayers
  143. are associated with a
  144. .B Memscreen
  145. that holds the data structures to maintain the windows and connects
  146. them to the associated
  147. .BR image .
  148. The
  149. .B fill
  150. color is used to paint the background when a window is deleted.
  151. There is no function to establish a
  152. .BR Memscreen ;
  153. to create one, allocate the memory, zero
  154. .B frontmost
  155. and
  156. .BR rearmost ,
  157. set
  158. .B fill
  159. to a valid fill color or image, and set
  160. .B image
  161. to the
  162. .B Memimage
  163. (or
  164. .BR Memlayer )
  165. on which the windows will be displayed.
  166. .PP
  167. .I Memlalloc
  168. allocates a
  169. .B Memlayer
  170. of size
  171. .I r
  172. on
  173. .B Memscreen
  174. .IR s .
  175. If
  176. .I col
  177. is not
  178. .BR DNofill ,
  179. the new window will be initialized by painting it that color.
  180. .PP
  181. The refresh function
  182. .I fn
  183. and associated argument
  184. .I arg
  185. will be called by routines in the library to restore portions of the window
  186. uncovered due to another window being deleted or this window being pulled to the front of the stack.
  187. The function, when called,
  188. receives a pointer to the image (window) being refreshed, the rectangle that has been uncovered,
  189. and the
  190. .I arg
  191. recorded when the window was created.
  192. A couple of predefined functions provide built-in management methods:
  193. .I memlnorefresh
  194. does no backup at all, useful for making efficient temporary windows;
  195. while a
  196. .I nil
  197. function specifies that the backing store
  198. .RB ( Memlayer.save )
  199. will be used to keep the obscured data.
  200. Other functions may be provided by the client.
  201. .I Memlsetrefresh
  202. allows one to change the function associated with the window.
  203. .PP
  204. .I Memldelete
  205. deletes the window
  206. .IR i ,
  207. restoring the underlying display.
  208. .I Memlfree
  209. frees the data structures without unlinking the window from the associated
  210. .B Memscreen
  211. or doing any graphics.
  212. .PP
  213. .I Memlexpose
  214. restores rectangle
  215. .I r
  216. within the window, using the backing store or appropriate refresh method.
  217. .I Memlhide
  218. goes the other way, backing up
  219. .I r
  220. so that that portion of the screen may be modified without losing the data in this window.
  221. .PP
  222. .I Memltofront
  223. pulls
  224. .I i
  225. to the front of the stack of windows, making it fully visible.
  226. .I Memltofrontn
  227. pulls the
  228. .I n
  229. windows in the array
  230. .I ia
  231. to the front as a group, leaving their internal order unaffected.
  232. .I Memltorear
  233. and
  234. .I memltorearn
  235. push the windows to the rear.
  236. .PP
  237. .I Memlorigin
  238. changes the coordinate systems associated with the window
  239. .IR i .
  240. The points
  241. .I log
  242. and
  243. .I phys
  244. represent the upper left corner
  245. .RB ( min )
  246. of the window's internal coordinate system and its physical location on the screen.
  247. Changing
  248. .I log
  249. changes the interpretation of coordinates within the window; for example, setting it to
  250. (0,\ 0) makes the upper left corner of the window appear to be the origin of the coordinate
  251. system, regardless of its position on the screen.
  252. Changing
  253. .I phys
  254. changes the physical location of the window on the screen.
  255. When a window is created, its logical and physical coordinates are the same, so
  256. .EX
  257. memlorigin(i, i->r.min, i->r.min)
  258. .EE
  259. would be a no-op.
  260. .PP
  261. .I Memdraw
  262. and
  263. .I memline
  264. are implemented in the layer library but provide the main entry points for drawing on
  265. memory-resident windows.
  266. They have the signatures of
  267. .I memimagedraw
  268. and
  269. .I memimageline
  270. (see
  271. .IR memdraw (2))
  272. but accept
  273. .B Memlayer
  274. or
  275. .B Memimage
  276. arguments both.
  277. .PP
  278. .I Memload
  279. and
  280. .I memunload
  281. are similarly layer-savvy versions of
  282. .I loadmemimage
  283. and
  284. .IR unloadmemimage .
  285. The
  286. .I iscompressed
  287. flag to
  288. .I memload
  289. specifies whether the
  290. .I n
  291. bytes of data in
  292. .I buf
  293. are in compressed image format
  294. (see
  295. .IR image (6)).
  296. .SH SOURCE
  297. .B /sys/src/libmemlayer
  298. .SH SEE ALSO
  299. .IR graphics (2),
  300. .IR memdraw (2),
  301. .IR stringsize (2),
  302. .IR window (2),
  303. .IR draw (3)