term% ls -F
term% cat index.txt
LAYER(2)                      System Calls Manual                     LAYER(2)

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

       #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)

       The  layer library extends the functionality of the bitmap graphics li‐
       brary (see graphics(2)) to overlapping independent rectangular windows,
       or  layers, on a single bitmap, typically the screen.  The entry points
       bitblt, point, segment, string, subfontstring, and  texture  are  over‐
       loaded  in the layer library to apply these routines equally to bitmaps
       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 {

              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 */

              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 imple‐
       ment their operations.  These functions operate on type Bitmap* but be‐
       cause 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.  Be‐
       fore 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 per‐
       mits) on the covering Bitmap and is cleared to all zeros.

       Lfree  frees the Layer l and restores the contents of its covering Bit‐

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

       Lcstring is peculiar to programs, such as 8½(1), that multiplex 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 position.
       Msg  is  a  pointer to the string message; it contains the header and n
       cache indices.


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