MEMLAYER(2)                                           MEMLAYER(2)

     NAME
          memdraw, memlalloc, memldelete, memlexpose, memlfree,
          memlhide, memline, memlnorefresh, memload, memunload,
          memlorigin, memlsetrefresh, memltofront, memltofrontn,
          memltorear, memltorearn - windows of memory-resident images

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

          typedef struct Memscreen Memscreen;
          typedef struct Memlayer Memlayer;
          typedef void (*Refreshfn)(Memimage*, Rectangle, void*);

          struct Memscreen
          {
              Memimage  *frontmost; /* frontmost layer on screen */
              Memimage  *rearmost;  /* rearmost layer on screen */
              Memimage  *image;     /* upon which all layers are drawn */
              Memimage  *fill;      /* if non-zero, picture to use when repainting */
          };

          struct Memlayer
          {
              Rectangle screenr;    /* true position of layer on screen */
              Point     delta;      /* add delta to go from image coords to screen */
              Memscreen *screen;    /* screen this layer belongs to */
              Memimage  *front;     /* window in front of this one */
              Memimage  *rear;      /* window behind this one*/
              int       clear;      /* layer is fully visible */
              Memimage  *save;      /* save area for obscured parts */
              Refreshfn refreshfn;  /* fn to refresh obscured parts if save==nil */
              void      *refreshptr;/* argument to refreshfn */
          };

          Memimage* memlalloc(Memscreen *s, Rectangle r, Refreshfn fn, void *arg, ulong col)

          void      memlnorefresh(Memimage *i, Rectangle r, void *arg)

          int       memlsetrefresh(Memimage *i, Refreshfn fn, void *arg)

          int       memldelete(Memimage *i)

          int       memlfree(Memimage *i)

          int       memlexpose(Memimage *i, Rectangle r)

     Page 1                       Plan 9             (printed 3/28/24)

     MEMLAYER(2)                                           MEMLAYER(2)

          int       memlhide(Memimage *i, Rectangle r)

          void      memltofront(Memimage *i)

          void      memltofrontn(Memimage**ia, int n)

          void      memltorear(Memimage *i)

          void      memltorearn(Memimage **ia , int n)

          int       memlorigin(Memimage *i, Point log, Point phys)

          void      memdraw(Image *dst, Rectangle r,
                       Image *src, Point sp, Image *mask, Point mp)
          int       memload(Memimage *i, Rectangle r,
                    uchar *buf, int n, int iscompressed)

          int       memunload(Memimage *i, Rectangle r,
                    uchar *buf, int n)

     DESCRIPTION
          These functions build upon the memdraw(2) interface to main-
          tain overlapping graphical windows on in-memory images.
          They are used by the kernel to implement the windows inter-
          face presented by draw(3) and window(2) and probably have
          little use outside of the kernel.

          The basic function is to extend the definition of a Memimage
          (see memdraw(2)) to include overlapping windows defined by
          the Memlayer type.  The first fields of the Memlayer struc-
          ture are identical to those in Memimage, permitting a func-
          tion that expects a Memimage to be passed a Memlayer, and
          vice versa.  Both structures have a save field, which is nil
          in a Memimage and points to `backing store' in a Memlayer.
          The layer routines accept Memimages or Memlayers; if the
          image is a Memimage the underlying Memimage routine is
          called; otherwise the layer routines recursively subdivide
          the geometry, reducing the operation into a smaller compo-
          nent that ultimately can be performed on a Memimage, either
          the display on which the window appears, or the backing
          store.

          Memlayers are associated with a Memscreen that holds the
          data structures to maintain the windows and connects them to
          the associated image.  The fill color is used to paint the
          background when a window is deleted.  There is no function
          to establish a Memscreen; to create one, allocate the mem-
          ory, zero frontmost and rearmost, set fill to a valid fill
          color or image, and set image to the Memimage (or Memlayer)
          on which the windows will be displayed.

          Memlalloc allocates a Memlayer of size r on Memscreen s. If

     Page 2                       Plan 9             (printed 3/28/24)

     MEMLAYER(2)                                           MEMLAYER(2)

          col is not DNofill, the new window will be initialized by
          painting it that color.

          The refresh function fn and associated argument arg will be
          called by routines in the library to restore portions of the
          window uncovered due to another window being deleted or this
          window being pulled to the front of the stack.  The func-
          tion, when called, receives a pointer to the image (window)
          being refreshed, the rectangle that has been uncovered, and
          the arg recorded when the window was created.  A couple of
          predefined functions provide built-in management methods:
          memlnorefresh does no backup at all, useful for making effi-
          cient temporary windows; while a nil function specifies that
          the backing store (Memlayer.save) will be used to keep the
          obscured data.  Other functions may be provided by the
          client.  Memlsetrefresh allows one to change the function
          associated with the window.

          Memldelete deletes the window i, restoring the underlying
          display.  Memlfree frees the data structures without unlink-
          ing the window from the associated Memscreen or doing any
          graphics.

          Memlexpose restores rectangle r within the window, using the
          backing store or appropriate refresh method.  Memlhide goes
          the other way, backing up r so that that portion of the
          screen may be modified without losing the data in this win-
          dow.

          Memltofront pulls i to the front of the stack of windows,
          making it fully visible.  Memltofrontn pulls the n windows
          in the array ia to the front as a group, leaving their
          internal order unaffected.  Memltorear and memltorearn push
          the windows to the rear.

          Memlorigin changes the coordinate systems associated with
          the window i. The points log and phys represent the upper
          left corner (min) of the window's internal coordinate system
          and its physical location on the screen.  Changing log
          changes the interpretation of coordinates within the window;
          for example, setting it to (0, 0) makes the upper left cor-
          ner of the window appear to be the origin of the coordinate
          system, regardless of its position on the screen.  Changing
          phys changes the physical location of the window on the
          screen.  When a window is created, its logical and physical
          coordinates are the same, so
                    memlorigin(i, i->r.min, i->r.min)
          would be a no-op.

          Memdraw and memline are implemented in the layer library but
          provide the main entry points for drawing on memory-resident
          windows.  They have the signatures of memimagedraw and

     Page 3                       Plan 9             (printed 3/28/24)

     MEMLAYER(2)                                           MEMLAYER(2)

          memimageline (see memdraw(2)) but accept Memlayer or
          Memimage arguments both.

          Memload and memunload are similarly layer-savvy versions of
          loadmemimage and unloadmemimage. The iscompressed flag to
          memload specifies whether the n bytes of data in buf are in
          compressed image format (see image(6)).

     SOURCE
          /sys/src/libmemlayer

     SEE ALSO
          graphics(2), memdraw(2), stringsize(2), window(2), draw(3)

     Page 4                       Plan 9             (printed 3/28/24)