LAYER(2)							System Calls Manual							  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 independent rectangular win-
       dows, 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 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 {
		    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 */
	      };

	      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 stan-
       dard 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 covering Bitmap.  Neither
       function changes the x-y location of the Layer.

       Lcstring is peculiar to programs, such as 81/2(1), that multiplex client access to the display.	It acts as a feed-through for the 's' mes-
       sage 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.

SOURCE

       /sys/src/liblayer

SEE ALSO

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

																	  LAYER(2)