MEMDRAW(3)                                             MEMDRAW(3)

     NAME
          Memimage, Memdata, Memdrawparam, memimageinit, wordaddr,
          byteaddr, memimagemove, allocmemimage, allocmemimaged,
          readmemimage, creadmemimage, writememimage, freememimage,
          memsetchan, loadmemimage, cloadmemimage, unloadmemimage,
          memfillcolor, memarc, mempoly, memellipse, memfillpoly,
          memimageline, memimagedraw, drawclip, memlinebbox,
          memlineendsize, allocmemsubfont, openmemsubfont,
          freememsubfont, memsubfontwidth, getmemdefont,
          memimagestring, iprint, hwdraw - drawing routines for
          memory-resident images

     SYNOPSIS
          #include <u.h>
          #include <u.h>
          #include <libc.h>
          #include <draw.h>
          #include <memdraw.h>

          typedef struct Memdata
          {
               ulong     *base;    /* allocated data pointer */
               uchar     *bdata;   /* first byte of actual data; word-aligned */
               int       ref;      /* number of Memimages using this data */
               void*     imref;    /* last image that pointed at this */
               int       allocd;   /* is this malloc'd? */
          } Memdata;

          enum {
               Frepl     = 1<<0,   /* is replicated */
               Fsimple   = 1<<1,   /* is 1x1 */
               Fgrey     = 1<<2,   /* is grey */
               Falpha    = 1<<3,   /* has explicit alpha */
               Fcmap     = 1<<4,   /* has cmap channel */
               Fbytes    = 1<<5,   /* has only 8-bit channels */
          };

          typedef struct Memimage
          {
               Rectangle r;        /* rectangle in data area, local coords */
               Rectangle clipr;    /* clipping region */
               int       depth;    /* number of bits of storage per pixel */
               int       nchan;    /* number of channels */
               ulong     chan;     /* channel descriptions */

               Memdata   *data;    /* pointer to data */
               int       zero;     /* data->bdata+zero==&byte containing (0,0) */
               ulong     width;    /* width in words of a single scan line */
               Memlayer  *layer;   /* nil if not a layer*/
               ulong     flags;

     MEMDRAW(3)                                             MEMDRAW(3)

               ...
          } Memimage;

          typedef struct Memdrawparam
          {
               Memimage  *dst;
               Rectangle r;
               Memimage  *src;
               Rectangle sr;
               Memimage  *mask;
               Rectangle mr;
               ...
          } Memdrawparam;

          int         drawdebug;

          void        memimageinit(void)
          ulong*      wordaddr(Memimage *i, Point p)
          uchar*      byteaddr(Memimage *i, Point p)
          void        memimagemove(void *from, void *to)

          Memimage*   allocmemimage(Rectangle r, ulong chan)
          Memimage*   allocmemimaged(Rectangle r, ulong chan, Memdata *data)
          Memimage*   readmemimage(int fd)
          Memimage*   creadmemimage(int fd)
          int         writememimage(int fd, Memimage *i)
          void        freememimage(Memimage *i)
          int         memsetchan(Memimage*, ulong)

          int         loadmemimage(Memimage *i, Rectangle r,
                         uchar *buf, int nbuf)
          int         cloadmemimage(Memimage *i, Rectangle r,
                         uchar *buf, int nbuf)
          int         unloadmemimage(Memimage *i, Rectangle r,
                         uchar *buf, int nbuf)
          void        memfillcolor(Memimage *i, ulong color)

          void        memarc(Memimage *dst, Point c, int a, int b, int thick,
                         Memimage *src, Point sp, int alpha, int phi, Drawop op)
          void        mempoly(Memimage *dst, Point *p, int np, int end0,
                         int end1, int radius, Memimage *src, Point sp, Drawop op)
          void        memellipse(Memimage *dst, Point c, int a, int b,
                         int thick, Memimage *src, Point sp, Drawop op)
          void        memfillpoly(Memimage *dst, Point *p, int np, int wind,
                         Memimage *src, Point sp, Drawop op)
          void        memimageline(Memimage *dst, Point p0, Point p1, int end0,
                         int end1, int radius, Memimage *src, Point sp, Drawop op)
          void        memimagedraw(Memimage *dst, Rectangle r, Memimage *src,
                         Point sp, Memimage *mask, Point mp, Drawop op)

          int         drawclip(Memimage *dst, Rectangle *dr, Memimage *src,
                         Point *sp, Memimage *mask, Point *mp,

     MEMDRAW(3)                                             MEMDRAW(3)

                         Rectangle *sr, Rectangle *mr)
          Rectangle   memlinebbox(Point p0, Point p1, int end0, int end1,
                         int radius)
          int         memlineendsize(int end)

          Memsubfont* allocmemsubfont(char *name, int n, int height,
                         int ascent, Fontchar *info, Memimage *i)
          Memsubfont* openmemsubfont(char *name)
          void        freememsubfont(Memsubfont *f)
          Point       memsubfontwidth(Memsubfont *f, char *s)
          Memsubfont* getmemdefont(void)
          Point       memimagestring(Memimage *dst, Point p, Memimage *color,
                          Point cp, Memsubfont *f, char *cs, Drawop op)

          int         iprint(char *fmt, ...)
          int         hwdraw(Memdrawparam *param)

     DESCRIPTION
          The Memimage type defines memory-resident rectangular pic-
          tures and the methods to draw upon them; Memimages differ
          from Images (see draw(3)) in that they are manipulated
          directly in user memory rather than by RPCs to the /dev/draw
          hierarchy.  The library is the basis for the kernel draw(3)
          driver and also used by a number of programs that must
          manipulate images without a display.

          The r, clipr, depth, nchan, and chan structure elements are
          identical to the ones of the same name in the Image struc-
          ture.

          The flags element of the Memimage structure holds a number
          of bits of information about the image.  In particular, it
          subsumes the purpose of the repl element of Image struc-
          tures.

          Memimageinit initializes various static data that the
          library depends on, as well as the replicated solid color
          images memopaque, memtransparent, memblack, and memwhite.
          It should be called before referring to any of these images
          and before calling any of the other library functions.

          Each Memimage points at a Memdata structure that in turn
          points at the actual pixel data for the image.  This allows
          multiple images to be associated with the same Memdata.  The
          first word of the data pointed at by the base element of
          Memdata points back at the Memdata structure, so that in the
          Plan 9 kernel, the memory allocator (see Plan 9's pool(3))
          can compact image memory using memimagemove.

          Because images can have different coordinate systems, the
          zero element of the Memimage structure contains the offset
          that must be added to the bdata element of the corresponding

     MEMDRAW(3)                                             MEMDRAW(3)

          Memdata structure in order to yield a pointer to the data
          for the pixel (0,0).  Adding width machine words to this
          pointer moves it down one scan line.  The depth element can
          be used to determine how to move the pointer horizontally.
          Note that this method works even for images whose rectangles
          do not include the origin, although one should only derefer-
          ence pointers corresponding to pixels within the image rect-
          angle.  Wordaddr and byteaddr perform these calculations,
          returning pointers to the word and byte, respectively, that
          contain the beginning of the data for a given pixel.

          Allocmemimage allocages images with a given rectangle and
          channel descriptor (see strtochan in graphics(3)), creating
          a fresh Memdata structure and associated storage.
          Allocmemimaged is similar but uses the supplied Memdata
          structure rather than a new one.  The readmemimage function
          reads an uncompressed bitmap from the given file descriptor,
          while creadmemimage reads a compressed bitmap.
          Writememimage writes a compressed representation of i to
          file descriptor fd. For more on bitmap formats, see
          image(7). Freememimage frees images returned by any of these
          routines.  The Memimage structure contains some tables that
          are used to store precomputed values depending on the chan-
          nel descriptor.  Memsetchan updates the chan element of the
          structure as well as these tables, returning -1 if passed a
          bad channel descriptor.

          Loadmemimage and cloadmemimage replace the pixel data for a
          given rectangle of an image with the given buffer of uncom-
          pressed or compressed data, respectively.  When calling
          cloadmemimage, the buffer must contain an integral number of
          compressed chunks of data that exactly cover the rectangle.
          Unloadmemimage retrieves the uncompressed pixel data for a
          given rectangle of an image.  All three return the number of
          bytes consumed on success, and -1 in case of an error.

          Memfillcolor fills an image with the given color, a 32-bit
          number as described in color(3).

          Memarc, mempoly, memellipse, memfillpoly, memimageline, and
          memimagedraw are identical to the arc, poly, ellipse,
          fillpoly, line, and gendraw, routines described in draw(3),
          except that they operate on Memimages rather than Images.
          Similarly, allocmemsubfont, openmemsubfont, freememsubfont,
          memsubfontwidth, getmemdefont, and memimagestring are the
          Memimage analogues of allocsubfont, openfont, freesubfont,
          strsubfontwidth, getdefont, and string (see subfont(3) and
          graphics(3)), except that they operate only on Memsubfonts
          rather than Fonts.

          Drawclip takes the images involved in a draw operation,
          together with the destination rectangle dr and source and

     MEMDRAW(3)                                             MEMDRAW(3)

          mask alignment points sp and mp, and clips them according to
          the clipping rectangles of the images involved.  It also
          fills in the rectangles sr and mr with rectangles congruent
          to the returned destination rectangle but translated so the
          upper left corners are the returned sp and mp.  Drawclip
          returns zero when the clipped rectangle is empty.
          Memlinebbox returns a conservative bounding box containing a
          line between two points with given end styles and radius.
          Memlineendsize calculates the extra length added to a line
          by attaching an end of a given style.

          The hwdraw and iprint functions are no-op stubs that may be
          overridden by clients of the library.  Hwdraw is called at
          each call to memimagedraw with the current request's parame-
          ters.  If it can satisfy the request, it should do so and
          return 1.  If it cannot satisfy the request, it should
          return 0.  This allows (for instance) the kernel to take
          advantage of hardware acceleration.  Iprint should format
          and print its arguments; it is given much debugging output
          when the global integer variable drawdebug is non-zero.  In
          the kernel, iprint prints to a serial line rather than the
          screen, for obvious reasons.

     SOURCE
          /src/libmemdraw

     SEE ALSO
          addpt(3), color(3), draw(3), graphics(3), memlayer(3),
          stringsize(3), subfont(3), color(7), utf(7)

     BUGS
          Memimagestring is unusual in using a subfont rather than a
          font, and in having no parameter to align the source.