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