MEMDRAW(2) MEMDRAW(2)
NAME
Memimage, Memdata, Memdrawparam, memimageinit, wordaddr,
byteaddr, memimagemove, allocmemimage, allocmemimaged,
readmemimage, creadmemimage, writememimage, freememimage,
memsetchan, loadmemimage, cloadmemimage, unloadmemimage,
memfillcolor, memarc, mempoly, memellipse, memfillpoly,
memimageline, memimagedraw, memaffinewarp,
allocmemimagekernel, memimagecorrelate, drawclip,
drawclipnorepl, memlinebbox, memlineendsize,
allocmemsubfont, openmemsubfont, freememsubfont,
memsubfontwidth, getmemdefont, memimagestring, hwdraw -
drawing routines for memory-resident images
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <draw.h>
#include <memdraw.h>
typedef struct Memdata
{
ulong *base; /* allocated data pointer */
uchar *bdata; /* first byte of actual data; word-aligned */
int ref; /* number of Memimages using this data */
void* imref; /* last image that pointed at this */
int allocd; /* is this malloc'd? */
} Memdata;
enum {
Frepl = 1<<0, /* is replicated */
Fsimple = 1<<1, /* is 1x1 */
Fgrey = 1<<2, /* is grey */
Falpha = 1<<3, /* has explicit alpha */
Fcmap = 1<<4, /* has cmap channel */
Fbytes = 1<<5, /* has only 8-bit channels */
};
typedef struct Memimage
{
Rectangle r; /* rectangle in data area, local coords */
Rectangle clipr; /* clipping region */
int depth; /* number of bits of storage per pixel */
int nchan; /* number of channels */
ulong chan; /* channel descriptions */
Memdata *data; /* pointer to data */
int zero; /* data->bdata+zero==&byte containing (0,0) */
ulong width; /* width in words of a single scan line */
Memlayer *layer; /* nil if not a layer*/
ulong flags;
...
} Memimage;
typedef struct Memdrawparam
{
Memimage *dst;
Rectangle r;
Memimage *src;
Rectangle sr;
Memimage *mask;
Rectangle mr;
...
} Memdrawparam;
int drawdebug;
int memimageinit(void)
ulong* wordaddr(Memimage *i, Point p)
uchar* byteaddr(Memimage *i, Point p)
void memimagemove(void *from, void *to)
Memimage* allocmemimage(Rectangle r, ulong chan)
Memimage* allocmemimaged(Rectangle r, ulong chan, Memdata *data)
Memimage* readmemimage(int fd)
Memimage* creadmemimage(int fd)
int writememimage(int fd, Memimage *i)
void freememimage(Memimage *i)
int memsetchan(Memimage*, ulong)
int loadmemimage(Memimage *i, Rectangle r,
uchar *buf, int nbuf)
int cloadmemimage(Memimage *i, Rectangle r,
uchar *buf, int nbuf)
int unloadmemimage(Memimage *i, Rectangle r,
uchar *buf, int nbuf)
void memfillcolor(Memimage *i, ulong color)
void memarc(Memimage *dst, Point c, int a, int b, int thick,
Memimage *src, Point sp, int alpha, int phi, Drawop op)
void mempoly(Memimage *dst, Point *p, int np, int end0,
int end1, int radius, Memimage *src, Point sp, Drawop op)
void memellipse(Memimage *dst, Point c, int a, int b,
int thick, Memimage *src, Point sp, Drawop op)
void memfillpoly(Memimage *dst, Point *p, int np, int wind,
Memimage *src, Point sp, Drawop op)
void memimageline(Memimage *dst, Point p0, Point p1, int end0,
int end1, int radius, Memimage *src, Point sp, Drawop op)
void memimagedraw(Memimage *dst, Rectangle r, Memimage *src,
Point sp, Memimage *mask, Point mp, Drawop op)
void memaffinewarp(Memimage *dst, Rectangle r, Memimage *src,
Point sp, Warp *w, int smooth)
Memimage* allocmemimagekernel(double *k, int dx, int dy,
double denom)
int memimagecorrelate(Memimage *dst, Rectangle r, Memimage *src,
Point sp, Memimage *k)
int drawclip(Memimage *dst, Rectangle *dr, Memimage *src,
Point *sp, Memimage *mask, Point *mp,
Rectangle *sr, Rectangle *mr)
int drawclipnorepl(Memimage *dst, Rectangle *dr, Memimage *src,
Point *sp, Memimage *mask, Point *mp,
Rectangle *sr, Rectangle *mr)
Rectangle memlinebbox(Point p0, Point p1, int end0, int end1,
int radius)
int memlineendsize(int end)
Memsubfont* allocmemsubfont(char *name, int n, int height,
int ascent, Fontchar *info, Memimage *i)
Memsubfont* openmemsubfont(char *name, Rune min)
void freememsubfont(Memsubfont *f)
Point memsubfontwidth(Memsubfont *f, char *s)
Memsubfont* getmemdefont(void)
Point memimagestring(Memimage *dst, Point p, Memimage *color,
Point cp, Memsubfont *f, char *cs)
int hwdraw(Memdrawparam *param)
DESCRIPTION
The Memimage type defines memory-resident rectangular pic-
tures and the methods to draw upon them; Memimages differ
from Images (see draw(2)) in that they are manipulated
directly in user memory rather than by RPCs to the /dev/draw
hierarchy. The memdraw library is the basis for the kernel
draw(3) driver and also used by a number of programs that
must manipulate images without a display.
The r, clipr, depth, nchan, and chan structure elements are
identical to the ones of the same name in the Image struc-
ture.
The flags element of the Memimage structure holds a number
of bits of information about the image. In particular, it
subsumes the purpose of the repl element of Image struc-
tures.
Memimageinit initializes various static data that the
library depends on, as well as the replicated solid color
images memopaque, memtransparent, memblack, and memwhite.
It should be called before referring to any of these images
and before calling any of the other library functions. It
returns non-zero on error.
Each Memimage points at a Memdata structure that in turn
points at the actual pixel data for the image. This allows
multiple images to be associated with the same Memdata. The
first word of the data pointed at by the base element of
Memdata points back at the Memdata structure, so that the
memory allocator (see pool(2)) can compact image memory
using memimagemove.
Because images can have different coordinate systems, the
zero element of the Memimage structure contains the offset
that must be added to the bdata element of the corresponding
Memdata structure in order to yield a pointer to the data
for the pixel (0,0). Adding width machine words to this
pointer moves it down one scan line. The depth element can
be used to determine how to move the pointer horizontally.
Note that this method works even for images whose rectangles
do not include the origin, although one should only derefer-
ence pointers corresponding to pixels within the image rec-
tangle. Wordaddr and byteaddr perform these calculations,
returning pointers to the word and byte, respectively, that
contain the beginning of the data for a given pixel.
Allocmemimage allocates images with a given rectangle and
channel descriptor (see strtochan in graphics(2)), creating
a fresh Memdata structure and associated storage.
Allocmemimaged is similar but uses the supplied Memdata
structure rather than a new one. The readmemimage function
reads an uncompressed bitmap from the given file descriptor,
while creadmemimage reads a compressed bitmap.
Writememimage writes a compressed representation of i to
file descriptor fd. For more on bitmap formats, see
image(6). Freememimage frees images returned by any of these
routines. The Memimage structure contains some tables that
are used to store precomputed values depending on the chan-
nel descriptor. Memsetchan updates the chan element of the
structure as well as these tables, returning -1 if passed a
bad channel descriptor.
Loadmemimage and cloadmemimage replace the pixel data for a
given rectangle of an image with the given buffer of
uncompressed or compressed data, respectively. When calling
cloadmemimage, the buffer must contain an integral number of
compressed chunks of data that exactly cover the rectangle.
Unloadmemimage retrieves the uncompressed pixel data for a
given rectangle of an image. All three return the number of
bytes consumed on success, and -1 in case of an error.
Memfillcolor fills an image with the given color, a 32-bit
number as described in color(2).
Memarc, mempoly, memellipse, memfillpoly, memimageline,
memaffinewarp, and memimagedraw are identical to the arc,
poly, ellipse, fillpoly, line, affinewarp, and gendraw, rou-
tines described in draw(2), except that they operate on
Memimages rather than Images. Similarly, allocmemsubfont,
openmemsubfont, freememsubfont, memsubfontwidth,
getmemdefont, and memimagestring are the Memimage analogues
of allocsubfont, openfont, freesubfont, strsubfontwidth,
getdefont, and string (see subfont(2) and graphics(2)),
except that they operate only on Memsubfonts rather than
Fonts.
Allocmemimagekernel takes k as a matrix with dx columns and
dy rows, and turns it into a 32-bit depth Memimage with each
pixel representing an element of the matrix as a fixed-point
number—as required by memimagecorrelate. Each of the ele-
ments will be divided by denom except when it's zero, where
a sum of coefficients (Σkᵢ) will be precalculated and used
instead.
Memimagecorrelate correlates image src with the filter k,
and stores the result in the region of dst defined by r. It
also follows the conventions of draw(2) regarding clipping
and source image replication. The result is not normalized,
but the same can be accomplished by normalizing the kernel
(k/Σkᵢ) before calling this routine.
Drawclip takes the images involved in a draw operation,
together with the destination rectangle dr and source and
mask alignment points sp and mp, and clips them according to
the clipping rectangles of the images involved. It also
fills in the rectangles sr and mr with rectangles congruent
to the returned destination rectangle but translated so the
upper left corners are the returned sp and mp.
Drawclipnorepl does the same as drawclip but avoids clamping
sp and mr within the image rectangle of source and mask when
replicated. Drawclip and drawclipnorepl return zero when
the clipped rectangle is empty. Memlinebbox returns a con-
servative bounding box containing a line between two points
with given end styles and radius. Memlineendsize calculates
the extra length added to a line by attaching an end of a
given style.
The hwdraw function is a no-op stub that may be overridden
by clients of the library. Hwdraw is called at each call to
memimagedraw with the current request's parameters. If it
can satisfy the request, it should do so and return 1. If
it cannot satisfy the request, it should return 0. This
allows (for instance) the kernel to take advantage of
hardware acceleration.
SOURCE
/sys/src/libmemdraw
SEE ALSO
addpt(2), color(2), draw(2), graphics(2), memlayer(2),
stringsize(2), subfont(2), color(6), utf(6)
BUGS
Memimagestring is unusual in using a subfont rather than a
font, and in having no parameter to align the source.
Writememimage won't write compressed images if the
compressed block size of the resulting image is greater than
8000 bytes, in order to avoid exceeding the iounit when
loading it into a draw(3) device.
MEMLAYER(2) MEMLAYER(2)
NAME
memdraw, memlalloc, memldelete, memlexpose, memlfree,
memlhide, memline, memlnorefresh, memload, memunload,
memlorigin, memlsetrefresh, memltofront, memltofrontn,
memltorear, memltorearn - windows of memory-resident images
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <draw.h>
#include <memdraw.h>
#include <memlayer.h>
typedef struct Memscreen Memscreen;
typedef struct Memlayer Memlayer;
typedef void (*Refreshfn)(Memimage*, Rectangle, void*);
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 */
};
Memimage* memlalloc(Memscreen *s, Rectangle r, Refreshfn fn, void *arg, ulong col)
void memlnorefresh(Memimage *i, Rectangle r, void *arg)
int memlsetrefresh(Memimage *i, Refreshfn fn, void *arg)
void memldelete(Memimage *i)
void memlfree(Memimage *i)
void memlexpose(Memimage *i, Rectangle r)
void memlhide(Memimage *i, Rectangle r)
void memltofront(Memimage *i)
void memltofrontn(Memimage**ia, int n)
void memltorear(Memimage *i)
void memltorearn(Memimage **ia , int n)
int memlorigin(Memimage *i, Point log, Point phys)
void memdraw(Memimage *dst, Rectangle r,
Memimage *src, Point sp, Memimage *mask, Point mp, Drawop op)
int memload(Memimage *i, Rectangle r,
uchar *buf, int n, int iscompressed)
int memunload(Memimage *i, Rectangle r,
uchar *buf, int n)
void memlaffinewarp(Memimage *dst, Rectangle r,
Memimage *src, Point sp, Warp w, int smooth)
DESCRIPTION
These functions build upon the memdraw(2) interface to main-
tain overlapping graphical windows on in-memory images.
They are used by the kernel to implement the windows inter-
face presented by draw(3) and window(2) and probably have
little use outside of the kernel.
The basic function is to extend the definition of a Memimage
(see memdraw(2)) to include overlapping windows defined by
the Memlayer type. The first fields of the Memlayer struc-
ture are identical to those in Memimage, permitting a func-
tion that expects a Memimage to be passed a Memlayer, and
vice versa. Both structures have a save field, which is nil
in a Memimage and points to `backing store' in a Memlayer.
The layer routines accept Memimages or Memlayers; if the
image is a Memimage the underlying Memimage routine is
called; otherwise the layer routines recursively subdivide
the geometry, reducing the operation into a smaller com-
ponent that ultimately can be performed on a Memimage,
either the display on which the window appears, or the back-
ing store.
Memlayers are associated with a Memscreen that holds the
data structures to maintain the windows and connects them to
the associated image. The fill color is used to paint the
background when a window is deleted. There is no function
to establish a Memscreen; to create one, allocate the
memory, zero frontmost and rearmost, set fill to a valid
fill color or image, and set image to the Memimage (or
Memlayer) on which the windows will be displayed.
Memlalloc allocates a Memlayer of size r on Memscreen s. If
col is not DNofill, the new window will be initialized by
painting it that color.
The refresh function fn and associated argument 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 func-
tion, when called, receives a pointer to the image (window)
being refreshed, the rectangle that has been uncovered, and
the arg recorded when the window was created. A couple of
predefined functions provide built-in management methods:
memlnorefresh does no backup at all, useful for making effi-
cient temporary windows; while a nil function specifies that
the backing store (Memlayer.save) will be used to keep the
obscured data. Other functions may be provided by the
client. Memlsetrefresh allows one to change the function
associated with the window.
Memldelete deletes the window i, restoring the underlying
display. Memlfree frees the data structures without unlink-
ing the window from the associated Memscreen or doing any
graphics.
Memlexpose restores rectangle r within the window, using the
backing store or appropriate refresh method. Memlhide goes
the other way, backing up r so that portion of the screen
may be modified without losing the data in this window.
Memltofront pulls i to the front of the stack of windows,
making it fully visible. Memltofrontn pulls the n windows
in the array ia to the front as a group, leaving their
internal order unaffected. Memltorear and memltorearn push
the windows to the rear.
Memlorigin changes the coordinate systems associated with
the window i. The points log and phys represent the upper
left corner (min) of the window's internal coordinate system
and its physical location on the screen. Changing 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 coordi-
nate system, regardless of its position on the screen.
Changing phys changes the physical location of the window on
the screen. When a window is created, its logical and phy-
sical coordinates are the same, so
memlorigin(i, i->r.min, i->r.min)
would be a no-op.
Memdraw, memline and memlaffinewarp are implemented in the
layer library but provide the main entry points for drawing
on memory-resident windows. They have the signatures of
memimagedraw, memimageline and memaffinewarp (see
memdraw(2)) but accept Memlayer or Memimage arguments both.
Memload and memunload are similarly layer-savvy versions of
loadmemimage and unloadmemimage. The iscompressed flag to
memload specifies whether the n bytes of data in buf are in
compressed image format (see image(6)).
SOURCE
/sys/src/libmemlayer
SEE ALSO
graphics(2), memdraw(2), stringsize(2), window(2), draw(3)
/plan9/man/2/