glenda.party
term% ls -F
term% cat index.txt
MEMDRAW(2)                    System Calls Manual                   MEMDRAW(2)



NAME
       Memimage,  Memdata,  Memdrawparam,  memimageinit,  wordaddr,  byteaddr,
       memimagemove, allocmemimage, allocmemimaged, readmemimage,  creadmemim‐
       age, writememimage, freememimage, memsetchan, loadmemimage, cloadmemim‐
       age, unloadmemimage, memfillcolor, memarc,  mempoly,  memellipse,  mem‐
       fillpoly,  memimageline,  memimagedraw,  drawclip,  memlinebbox, memli‐
       neendsize,  allocmemsubfont,  openmemsubfont,  freememsubfont,  memsub‐
       fontwidth,  getmemdefont, memimagestring, iprint, hwdraw - drawing rou‐
       tines for memory-resident images

SYNOPSIS
       #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;
            ...
       } 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,
                      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)

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

DESCRIPTION
       The Memimage type defines memory-resident rectangular pictures and  the
       methods  to  draw upon them; Memimages differ from Images (see draw(2))
       in that they are manipulated directly in user  memory  rather  than  by
       RPCs  to the /dev/draw hierarchy.  The memdraw 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 structure.

       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 structures.

       Memimageinit initializes various static data that the  library  depends
       on,  as  well as the replicated solid color images memopaque, memtrans‐
       parent, 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 the memory allocator (see pool(2))  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 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 ori‐
       gin, although one should only  dereference  pointers  corresponding  to
       pixels within the image rectangle.  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(2)),  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 bit‐
       map formats, see image(6).  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 channel  descrip‐
       tor.   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  rec‐
       tangle  of an image with the given buffer of uncompressed or compressed
       data, respectively.  When calling cloadmemimage, the buffer  must  con‐
       tain 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(2).

       Memarc,  mempoly,  memellipse, memfillpoly, memimageline, and memimage‐
       draw are identical to the arc, poly, ellipse, fillpoly, line, and  gen‐
       draw, routines described in draw(2), except that they operate on Memim‐
       ages rather than Images.  Similarly,  allocmemsubfont,  openmemsubfont,
       freememsubfont,  memsubfontwidth,  getmemdefont, and memimagestring are
       the Memimage analogues of allocsubfont, openfont, freesubfont,  strsub‐
       fontwidth,  getdefont,  and  string  (see  subfont(2) and graphics(2)),
       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 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 rec‐
       tangles 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  con‐
       servative  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  memimage‐
       draw  with  the  current  request's  parameters.  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
       /sys/src/libmemdraw

SEE ALSO
       addpt(2),  color(2),  draw(2), graphics(2), memlayer(2), stringsize(2),
       subfont(2), color(6), utf(6)

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



                                                                    MEMDRAW(2)