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 as‐
       sociated 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 de‐
       scriptor (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)), ex‐
       cept 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  im‐
       ages  involved.  It also fills in the rectangles sr and mr with rectan‐
       gles 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 re‐
       quest, 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 ad‐
       vantage 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  se‐
       rial 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)