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