305 lines
6.8 KiB
Text
305 lines
6.8 KiB
Text
.TH MEMLAYER 2
|
|
.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 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)
|