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 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 .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 void    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 Rectangle       memlinebbox(Point p0, Point p1, int end0, int end1,
 143            int radius)
 144 int     memlineendsize(int end)
 145 .PP
 146 .ft L
 147 .nf
 148 Memsubfont*     allocmemsubfont(char *name, int n, int height,
 149            int ascent, Fontchar *info, Memimage *i)
 150 Memsubfont*     openmemsubfont(char *name)
 151 void    freememsubfont(Memsubfont *f)
 152 Point   memsubfontwidth(Memsubfont *f, char *s)
 153 Memsubfont*     getmemdefont(void)
 154 Point   memimagestring(Memimage *dst, Point p, Memimage *color,
 155             Point cp, Memsubfont *f, char *cs)
 156 .PP
 157 .ft L
 158 .nf
 159 int     iprint(char *fmt, ...)
 160 int     hwdraw(Memdrawparam *param)
 161 .ft R
 162 .SH DESCRIPTION
 163 The
 164 .B Memimage
 165 type defines memory-resident rectangular pictures and the methods to draw upon them;
 166 .BR Memimage s
 167 differ from
 168 .BR Image s
 169 (see
 170 .IR draw (2))
 171 in that they are manipulated directly in user memory rather than by
 172 RPCs to the
 173 .B /dev/draw
 174 hierarchy.
 175 The
 176 .B memdraw
 177 library is the basis for the kernel
 178 .IR draw (3)
 179 driver and also used by a number of programs that must manipulate
 180 images without a display.
 181 .PP
 182 The
 183 .BR r,
 184 .BR clipr ,
 185 .BR depth ,
 186 .BR nchan ,
 187 and
 188 .BR chan
 189 structure elements are identical to
 190 the ones of the same name
 191 in the
 192 .B Image
 193 structure.
 194 .PP
 195 The
 196 .B flags
 197 element of the
 198 .B Memimage
 199 structure holds a number of bits of information about the image.
 200 In particular, it subsumes the
 201 purpose of the
 202 .B repl
 203 element of
 204 .B Image
 205 structures.
 206 .PP
 207 .I Memimageinit
 208 initializes various static data that the library depends on,
 209 as well as the replicated solid color images
 210 .BR memopaque ,
 211 .BR memtransparent ,
 212 .BR memblack ,
 213 and
 214 .BR memwhite .
 215 It should be called before referring to any of these images
 216 and before calling any of the other library functions.
 217 .PP
 218 Each
 219 .B Memimage
 220 points at a
 221 .B Memdata
 222 structure that in turn points at the actual pixel data for the image.
 223 This allows multiple images to be associated with the same
 224 .BR Memdata .
 225 The first word of the data pointed at by
 226 the
 227 .B base
 228 element of
 229 .B Memdata
 230 points back at the
 231 .B Memdata
 232 structure, so that the
 233 memory allocator (see
 234 .IR pool (2))
 235 can compact image memory
 236 using
 237 .IR memimagemove .
 238 .PP
 239 Because images can have different coordinate systems,
 240 the
 241 .B zero
 242 element of the
 243 .B Memimage
 244 structure contains the offset that must be added
 245 to the
 246 .B bdata
 247 element of the corresponding
 248 .B Memdata
 249 structure in order to yield a pointer to the data for the pixel (0,0).
 250 Adding
 251 .BR width
 252 machine words
 253 to this pointer moves it down one scan line.
 254 The
 255 .B depth
 256 element can be used to determine how to move the
 257 pointer horizontally.
 258 Note that this method works even for images whose rectangles
 259 do not include the origin, although one should only dereference
 260 pointers corresponding to pixels within the image rectangle.
 261 .I Wordaddr
 262 and
 263 .IR byteaddr
 264 perform these calculations,
 265 returning pointers to the word and byte, respectively,
 266 that contain the beginning of the data for a given pixel.
 267 .PP
 268 .I Allocmemimage
 269 allocages
 270 images with a given rectangle and channel descriptor
 271 (see
 272 .B strtochan
 273 in
 274 .IR graphics (2)),
 275 creating a fresh
 276 .B Memdata
 277 structure and associated storage.
 278 .I Allocmemimaged
 279 is similar but uses the supplied
 280 .I Memdata
 281 structure rather than a new one.
 282 The
 283 .I readmemimage
 284 function reads an uncompressed bitmap
 285 from the given file descriptor,
 286 while
 287 .I creadmemimage
 288 reads a compressed bitmap.
 289 .I Writememimage
 290 writes a compressed representation of
 291 .I i
 292 to file descriptor
 293 .IR fd .
 294 For more on bitmap formats, see
 295 .IR image (6).
 296 .I Freememimage
 297 frees images returned by any of these routines.
 298 The
 299 .B Memimage
 300 structure contains some tables that are used
 301 to store precomputed values depending on the channel descriptor.
 302 .I Memsetchan
 303 updates the
 304 .B chan
 305 element of the structure as well as these tables,
 306 returning \-1 if passed a bad channel descriptor.
 307 .PP
 308 .I Loadmemimage
 309 and
 310 .I cloadmemimage
 311 replace the pixel data for a given rectangle of an image
 312 with the given buffer of uncompressed or compressed
 313 data, respectively.
 314 When calling
 315 .IR cloadmemimage ,
 316 the buffer must contain an
 317 integral number of
 318 compressed chunks of data that exactly cover the rectangle.
 319 .I Unloadmemimage
 320 retrieves the uncompressed pixel data for a given rectangle of an image.
 321 All three return the number of bytes consumed on success,
 322 and \-1 in case of an error.
 323 .PP
 324 .I Memfillcolor
 325 fills an image with the given color, a 32-bit number as
 326 described in
 327 .IR color (2).
 328 .PP
 329 .IR Memarc ,
 330 .IR mempoly ,
 331 .IR memellipse ,
 332 .IR memfillpoly ,
 333 .IR memimageline ,
 334 and
 335 .I memimagedraw
 336 are identical to the
 337 .IR arc ,
 338 .IR poly ,
 339 .IR ellipse ,
 340 .IR fillpoly ,
 341 .IR line ,
 342 and
 343 .IR gendraw ,
 344 routines described in
 345 .IR draw (2),
 346 except that they operate on
 347 .BR Memimage s
 348 rather than
 349 .BR Image s.
 350 Similarly,
 351 .IR allocmemsubfont ,
 352 .IR openmemsubfont ,
 353 .IR freememsubfont ,
 354 .IR memsubfontwidth ,
 355 .IR getmemdefont ,
 356 and
 357 .I memimagestring
 358 are the
 359 .B Memimage
 360 analogues of
 361 .IR allocsubfont ,
 362 .IR openfont ,
 363 .IR freesubfont ,
 364 .IR strsubfontwidth ,
 365 .IR getdefont ,
 366 and
 367 .B string
 368 (see
 369 .IR subfont (2)
 370 and
 371 .IR graphics (2)),
 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 /sys/src/libmemdraw
 435 .SH SEE ALSO
 436 .IR addpt (2),
 437 .IR color (2),
 438 .IR draw (2),
 439 .IR graphics (2),
 440 .IR memlayer (2),
 441 .IR stringsize (2),
 442 .IR subfont (2),
 443 .IR color (6),
 444 .IR utf (6)
 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.