memlayer.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)