memdraw

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