Lots of man pages.

1 files changed, 305 insertions, 0 deletions

diff --git a/man/man3/memlayer.3 b/man/man3/memlayer.3
new file mode 100644
index 00000000..4acadf53
--- /dev/null
+++ b/man/man3/memlayer.3
@@ -0,0 +1,305 @@
+.TH MEMLAYER 3
+.SH NAME
+memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, memltofront, memltofrontn, memltorear, memltorearn \- windows of memory-resident images
+.SH SYNOPSIS
+.nf
+.B #include <u.h>
+.br
+.B #include <libc.h>
+.br
+.B #include <draw.h>
+.br
+.B #include <memdraw.h>
+.br
+.B #include <memlayer.h>
+.PP
+.ft L
+typedef struct Memscreen Memscreen;
+typedef struct Memlayer Memlayer;
+typedef void (*Refreshfn)(Memimage*, Rectangle, void*);
+.ta 4n +\w'\fLRefreshfn 'u +\w'\fL*frontmost; 'u
+
+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 */
+};
+.ft
+.ta \w'\fLMemimage* 'u
+.PP
+.B
+Memimage*	memlalloc(Memscreen *s, Rectangle r, Refreshfn fn, void *arg, ulong col)
+.PP
+.B void	memlnorefresh(Memimage *i, Rectangle r, void *arg)
+.PP
+.B
+int	memlsetrefresh(Memimage *i, Refreshfn fn, void *arg)
+.PP
+.B
+int	memldelete(Memimage *i)
+.PP
+.B
+int	memlfree(Memimage *i)
+.PP
+.B
+int	memlexpose(Memimage *i, Rectangle r)
+.PP
+.B
+int	memlhide(Memimage *i, Rectangle r)
+.PP
+.B 
+void	memltofront(Memimage *i)
+.PP
+.B
+void	memltofrontn(Memimage**ia, int n)
+.PP
+.B
+void	memltorear(Memimage *i)
+.PP
+.B
+void	memltorearn(Memimage **ia , int n)
+.PP
+.B
+int	memlorigin(Memimage *i, Point log, Point phys)
+.PP
+.B
+void	memdraw(Image *dst, Rectangle r,
+.br
+.B
+		   Image *src, Point sp, Image *mask, Point mp, Drawop op)
+.fi
+.B
+int	memload(Memimage *i, Rectangle r,
+.br
+.B
+		uchar *buf, int n, int iscompressed)
+.PP
+.B
+int	memunload(Memimage *i, Rectangle r,
+.br
+.B
+		uchar *buf, int n)
+.PP
+.SH DESCRIPTION
+These functions build upon the
+.IR memdraw (2)
+interface to maintain overlapping graphical windows on in-memory images.
+They are used by the kernel to implement the windows interface presented by
+.IR draw (3)
+and
+.IR window (2)
+and probably have little use outside of the kernel.
+.PP
+The basic function is to extend the definition of a
+.B Memimage
+(see
+.IR memdraw (2))
+to include overlapping windows defined by the
+.B Memlayer
+type.
+The first fields of the
+.B Memlayer
+structure are identical to those in
+.BR Memimage ,
+permitting a function that expects a
+.B Memimage
+to be passed a
+.BR Memlayer ,
+and vice versa.
+Both structures have a
+.B save
+field, which is nil in a
+.B Memimage
+and points to `backing store' in a
+.BR Memlayer .
+The layer routines accept
+.B Memimages
+or
+.BR Memlayers ;
+if the image is a
+.B Memimage
+the underlying
+.B Memimage
+routine is called; otherwise the layer routines recursively
+subdivide the geometry, reducing the operation into a smaller
+component that ultimately can be performed on a
+.BR Memimage ,
+either the display on which the window appears, or the backing store.
+.PP
+.B Memlayers
+are associated with a
+.B Memscreen
+that holds the data structures to maintain the windows and connects
+them to the associated
+.BR image .
+The
+.B fill
+color is used to paint the background when a window is deleted.
+There is no function to establish a
+.BR Memscreen ;
+to create one, allocate the memory, zero
+.B frontmost
+and
+.BR rearmost ,
+set
+.B fill
+to a valid fill color or image, and set
+.B image
+to the
+.B Memimage
+(or
+.BR Memlayer )
+on which the windows will be displayed.
+.PP
+.I Memlalloc
+allocates a
+.B Memlayer
+of size
+.I r
+on
+.B Memscreen
+.IR s .
+If
+.I col
+is not
+.BR DNofill ,
+the new window will be initialized by painting it that color.
+.PP
+The refresh function
+.I fn
+and associated argument
+.I 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 function, when called,
+receives a pointer to the image (window) being refreshed, the rectangle that has been uncovered,
+and the
+.I arg
+recorded when the window was created.
+A couple of predefined functions provide built-in management methods:
+.I memlnorefresh
+does no backup at all, useful for making efficient temporary windows;
+while a
+.I nil
+function specifies that the backing store
+.RB ( Memlayer.save )
+will be used to keep the obscured data.
+Other functions may be provided by the client.
+.I Memlsetrefresh
+allows one to change the function associated with the window.
+.PP
+.I Memldelete
+deletes the window
+.IR i ,
+restoring the underlying display.
+.I Memlfree
+frees the data structures without unlinking the window from the associated
+.B Memscreen
+or doing any graphics.
+.PP
+.I Memlexpose
+restores rectangle
+.I r
+within the window, using the backing store or appropriate refresh method.
+.I Memlhide
+goes the other way, backing up
+.I r
+so that that portion of the screen may be modified without losing the data in this window.
+.PP
+.I Memltofront
+pulls
+.I i
+to the front of the stack of windows, making it fully visible.
+.I Memltofrontn
+pulls the
+.I n
+windows in the array
+.I ia
+to the front as a group, leaving their internal order unaffected.
+.I Memltorear
+and
+.I memltorearn
+push the windows to the rear.
+.PP
+.I Memlorigin
+changes the coordinate systems associated with the window
+.IR i .
+The points
+.I log
+and
+.I phys
+represent the upper left corner
+.RB ( min )
+of the window's internal coordinate system and its physical location on the screen.
+Changing
+.I log
+changes the interpretation of coordinates within the window; for example, setting it to
+(0,\ 0) makes the upper left corner of the window appear to be the origin of the coordinate
+system, regardless of its position on the screen.
+Changing
+.I 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
+.EX
+	memlorigin(i, i->r.min, i->r.min)
+.EE
+would be a no-op.
+.PP
+.I Memdraw
+and
+.I memline
+are implemented in the layer library but provide the main entry points for drawing on
+memory-resident windows.
+They have the signatures of
+.I memimagedraw
+and
+.I memimageline
+(see
+.IR memdraw (2))
+but accept
+.B Memlayer
+or
+.B Memimage
+arguments both.
+.PP
+.I Memload
+and
+.I memunload
+are similarly layer-savvy versions of
+.I loadmemimage
+and
+.IR unloadmemimage .
+The
+.I iscompressed
+flag to
+.I memload
+specifies whether the
+.I n
+bytes of data in
+.I buf
+are in compressed image format
+(see
+.IR image (6)).
+.SH SOURCE
+.B /sys/src/libmemlayer
+.SH SEE ALSO
+.IR graphics (2),
+.IR memdraw (2),
+.IR stringsize (2),
+.IR window (2),
+.IR draw (3)