.TH LAYER 2X
.SH NAME
lalloc, lfree, ltofront, ltoback, lcstring \- graphics layers
.SH SYNOPSIS
.nf
.B
#include <u.h>
.B
#include <libc.h>
.B
#include <libg.h>
.B
#include <layer.h>
.PP
.B
Layer*	lalloc(Cover *c, Rectangle r)
.PP
.B
void   lfree(Layer *l)
.PP
.B
void   ltofront(Layer *l)
.PP
.B
void   ltoback(Layer *l)
.PP
.B
void   lcstring(Bitmap *b, int height, uchar *widths, uchar *msg, int n)
.SH DESCRIPTION
The layer library extends the functionality of the bitmap graphics library
(see
.IR graphics (2))
to overlapping independent rectangular windows, or
.I layers,
on a single bitmap, typically the screen.
The entry points
.BR bitblt ,
.BR point ,
.BR segment ,
.BR string ,
.BR subfontstring ,
and
.BR texture
are overloaded in the layer library to apply these routines equally
to bitmaps and layers.
Other than
.I lcstring,
which is rarely needed,
there are no special entry points for drawing on layers.
.PP
The data structures associated with the main type,
.BR Layer ,
are defined in
.BR <layer.h> :
.IP
.EX
.ta 6n +\w'Bitmap 'u +\w'*ground;   'u
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. from which this is derived */
	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 */
};
.EE
.PP
.B Layers
and
.B Bitmaps
are distinguished by the
.B cache
element of their structures:
.B cache
is non-zero in a
.BR Layer .
The layer library's versions of the graphics routines listed above use
.B cache
to decide how to implement their operations.
These functions operate on type
.BR Bitmap*
but
because
.B Bitmap
is included in
.BR Layer ,
the C compiler will permit passing a
.B Layer
to these routines.
The routines promote the type to
.B Layer*
if they see
.B cache
is non-zero.
(Note that these actions apply only in the layer library; although
.B cache
is defined in
.BR Bitmaps ,
the standard graphics library does not support layers.)
.PP
.I Lalloc
allocates a new
.B Layer
to occupy
.B Rectangle
.I r
in a
.BR Bitmap .
The argument
.B Cover
.I c
connects the set of
.B Layers
to a
.I covering
.BR Bitmap .
Before the first call to
.I lalloc,
.I c
should be allocated and initialized so
.IB c ->cover
is the
.B Bitmap
on which the
.B Layers
will be drawn,
.IB c ->front
is zero,
.IB c ->ground
is a background texture to fill the interstices between
.BR Layers ,
and
.IB c ->cover
is textured with
.IB c ->ground .
It is legal for
.IB c ->cover
itself to be a
.B Layer
for recursive layering.
The rectangle
.I r
may have arbitrary overlap, including none,
with the
.IB c ->cover->r .
After calling
.I lalloc,
the new
.B Layer
is fully visible (as far as geometry permits) on the covering
.B Bitmap
and is cleared to all zeros.
.PP
.I Lfree
frees the
.B Layer
.I l
and restores the contents of its covering
.BR Bitmap .
.PP
.I Ltofront
makes
.I l
fully visible within its covering
.BR Bitmap .
.I Ltoback
pushes
.I l
behind any other
.B Layers
on the same covering
.BR Bitmap .
Neither function changes the x-y location of the
.BR Layer .
.PP
.I Lcstring
is peculiar to programs, such as
.IR 8½ (1),
that multiplex client access to the display.
It acts as a feed-through for the
.B 's'
message generated by
.B string
(see
.IR bit (3)).
.I B
is the bitmap (or layer) 
and
.I height
is the height of the font in which the string is to be drawn.
.I Widths
is an array of
character widths, indexed by font cache position.
.I Msg
is a pointer to the
.B string
message; it contains the header and
.I n
cache indices.
.SH SEE ALSO
.IR graphics (2),
.IR bitblt (2),
.IR cachechars (2),
.IR bit (3)