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