LAYER(2)                                                 LAYER(2)

     NAME
          lalloc, lfree, ltofront, ltoback, lcstring - graphics layers

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <libg.h>
          #include <layer.h>

          Layer* lalloc(Cover *c, Rectangle r)

          void   lfree(Layer *l)

          void   ltofront(Layer *l)

          void   ltoback(Layer *l)

          void   lcstring(Bitmap *b, int height, uchar *widths, uchar *msg,
                          int n)

     DESCRIPTION
          The layer library extends the functionality of the bitmap
          graphics library (see graphics(2)) to overlapping indepen-
          dent rectangular windows, or layers, on a single bitmap,
          typically the screen.  The entry points bitblt, point,
          segment, string, subfontstring, and texture are overloaded
          in the layer library to apply these routines equally to bit-
          maps and layers.  Other than lcstring, which is rarely
          needed, there are no special entry points for drawing on
          layers.

          The data structures associated with the main type, Layer,
          are defined in <layer.h>:

               typedef struct Layer Layer;
               typedef struct Cover Cover;
               typedef enum Lvis {
                     Visible,
                     Obscured,
                     Invisible,
               }Lvis;

               struct Layer {
                     Bitmap;         /* Bitmap.cache!=0 ==> layer */
                     Layer  *next;   /* next layer from front to back */
                     Cover  *cover;  /* layer etc. that derived this one */
                     int    user;    /* a place for the user to stick stuff */
                     Lvis   vis;     /* visibility state */
               };

     LAYER(2)                                                 LAYER(2)

               struct Cover {
                     Layer  *layer;  /* layer on which these are painted */
                     Layer  *front;  /* first sublayer */
                     Bitmap *ground; /* background texture */
               };

          Layers and Bitmaps are distinguished by the cache element of
          their structures: cache is non-zero in a Layer.  The layer
          library's versions of the graphics routines listed above use
          cache to decide how to implement their operations.  These
          functions operate on type Bitmap* but because Bitmap is
          included in Layer, the C compiler will permit passing a
          Layer to these routines.  The routines promote the type to
          Layer* if they see cache is non-zero.  (Note that these
          actions apply only in the layer library; although cache is
          defined in Bitmaps, the standard graphics library does not
          support layers.)

          Lalloc allocates a new Layer to occupy Rectangle r in a
          Bitmap.  The argument Cover c connects the set of Layers to
          a covering Bitmap.  Before the first call to lalloc, c
          should be allocated and initialized so c->layer is the
          Bitmap on which the Layers will be drawn, c->front is zero,
          c->ground is a background texture to fill the interstices
          between Layers, and c->layer is textured with c->ground.  It
          is legal for c->layer itself to be a Layer for recursive
          layering.  The rectangle r may have arbitrary overlap,
          including none, with c->layer->r.  After calling lalloc, the
          new Layer is fully visible (as far as geometry permits) on
          the covering Bitmap and is cleared to all zeros.

          Lfree frees the Layer l and restores the contents of its
          covering Bitmap.

          Ltofront makes l fully visible within its covering Bitmap.
          Ltoback pushes l behind any other Layers on the same cover-
          ing Bitmap.  Neither function changes the x-y location of
          the Layer.

          Lcstring is peculiar to programs, such as 8½(1), that multi-
          plex client access to the display.  It acts as a feed-
          through for the 's' message generated by string (see
          bit(3)). B is the bitmap (or layer) and height is the height
          of the font in which the string is to be drawn.  Widths is
          an array of character widths, indexed by font cache posi-
          tion.  Msg is a pointer to the string message; it contains
          the header and n cache indices.

     SOURCE
          /sys/src/liblayer

     SEE ALSO

     LAYER(2)                                                 LAYER(2)

          graphics(2), bitblt(2), cachechars(2), bit(3)