aboutsummaryrefslogtreecommitdiff
path: root/man/man3/memdraw.3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3/memdraw.3')
-rw-r--r--man/man3/memdraw.3450
1 files changed, 450 insertions, 0 deletions
diff --git a/man/man3/memdraw.3 b/man/man3/memdraw.3
new file mode 100644
index 00000000..2d94742f
--- /dev/null
+++ b/man/man3/memdraw.3
@@ -0,0 +1,450 @@
+.TH MEMDRAW 3
+.SH 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,
+drawclip,
+memlinebbox,
+memlineendsize,
+allocmemsubfont,
+openmemsubfont,
+freememsubfont,
+memsubfontwidth,
+getmemdefont,
+memimagestring,
+iprint,
+hwdraw \- drawing routines for memory-resident images
+.SH SYNOPSIS
+.nf
+.B #include <u.h>
+.nf
+.B #include <u.h>
+.B #include <libc.h>
+.B #include <draw.h>
+.B #include <memdraw.h>
+.PP
+.ft L
+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;
+ \fI...\fP
+} Memimage;
+
+typedef struct Memdrawparam
+{
+ Memimage *dst;
+ Rectangle r;
+ Memimage *src;
+ Rectangle sr;
+ Memimage *mask;
+ Rectangle mr;
+ \fI...\fP
+} Memdrawparam;
+
+.ta \w'\fLMemsubfont* 'u
+int drawdebug;
+.ft
+.PP
+.ft L
+.nf
+void memimageinit(void)
+ulong* wordaddr(Memimage *i, Point p)
+uchar* byteaddr(Memimage *i, Point p)
+void memimagemove(void *from, void *to)
+.PP
+.ft L
+.nf
+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)
+.PP
+.ft L
+.nf
+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)
+.PP
+.ft L
+.nf
+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)
+.PP
+.ft L
+.nf
+int drawclip(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)
+.PP
+.ft L
+.nf
+Memsubfont* allocmemsubfont(char *name, int n, int height,
+ int ascent, Fontchar *info, Memimage *i)
+Memsubfont* openmemsubfont(char *name)
+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, Drawop op)
+.PP
+.ft L
+.nf
+int iprint(char *fmt, ...)
+int hwdraw(Memdrawparam *param)
+.ft R
+.SH DESCRIPTION
+The
+.B Memimage
+type defines memory-resident rectangular pictures and the methods to draw upon them;
+.BR Memimage s
+differ from
+.BR Image s
+(see
+.IR draw (2))
+in that they are manipulated directly in user memory rather than by
+RPCs to the
+.B /dev/draw
+hierarchy.
+The
+.Bmemdraw
+library is the basis for the kernel
+.IR draw (3)
+driver and also used by a number of programs that must manipulate
+images without a display.
+.PP
+The
+.BR r,
+.BR clipr ,
+.BR depth ,
+.BR nchan ,
+and
+.BR chan
+structure elements are identical to
+the ones of the same name
+in the
+.B Image
+structure.
+.PP
+The
+.B flags
+element of the
+.B Memimage
+structure holds a number of bits of information about the image.
+In particular, it subsumes the
+purpose of the
+.B repl
+element of
+.B Image
+structures.
+.PP
+.I Memimageinit
+initializes various static data that the library depends on,
+as well as the replicated solid color images
+.BR memopaque ,
+.BR memtransparent ,
+.BR memblack ,
+and
+.BR memwhite .
+It should be called before referring to any of these images
+and before calling any of the other library functions.
+.PP
+Each
+.B Memimage
+points at a
+.B Memdata
+structure that in turn points at the actual pixel data for the image.
+This allows multiple images to be associated with the same
+.BR Memdata .
+The first word of the data pointed at by
+the
+.B base
+element of
+.B Memdata
+points back at the
+.B Memdata
+structure, so that the
+memory allocator (see
+.IR pool (2))
+can compact image memory
+using
+.IR memimagemove .
+.PP
+Because images can have different coordinate systems,
+the
+.B zero
+element of the
+.B Memimage
+structure contains the offset that must be added
+to the
+.B bdata
+element of the corresponding
+.B Memdata
+structure in order to yield a pointer to the data for the pixel (0,0).
+Adding
+.BR width
+machine words
+to this pointer moves it down one scan line.
+The
+.B 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 dereference
+pointers corresponding to pixels within the image rectangle.
+.I Wordaddr
+and
+.IR byteaddr
+perform these calculations,
+returning pointers to the word and byte, respectively,
+that contain the beginning of the data for a given pixel.
+.PP
+.I Allocmemimage
+allocages
+images with a given rectangle and channel descriptor
+(see
+.B strtochan
+in
+.IR graphics (2)),
+creating a fresh
+.B Memdata
+structure and associated storage.
+.I Allocmemimaged
+is similar but uses the supplied
+.I Memdata
+structure rather than a new one.
+The
+.I readmemimage
+function reads an uncompressed bitmap
+from the given file descriptor,
+while
+.I creadmemimage
+reads a compressed bitmap.
+.I Writememimage
+writes a compressed representation of
+.I i
+to file descriptor
+.IR fd .
+For more on bitmap formats, see
+.IR image (6).
+.I Freememimage
+frees images returned by any of these routines.
+The
+.B Memimage
+structure contains some tables that are used
+to store precomputed values depending on the channel descriptor.
+.I Memsetchan
+updates the
+.B chan
+element of the structure as well as these tables,
+returning \-1 if passed a bad channel descriptor.
+.PP
+.I Loadmemimage
+and
+.I cloadmemimage
+replace the pixel data for a given rectangle of an image
+with the given buffer of uncompressed or compressed
+data, respectively.
+When calling
+.IR cloadmemimage ,
+the buffer must contain an
+integral number of
+compressed chunks of data that exactly cover the rectangle.
+.I 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.
+.PP
+.I Memfillcolor
+fills an image with the given color, a 32-bit number as
+described in
+.IR color (2).
+.PP
+.IR Memarc ,
+.IR mempoly ,
+.IR memellipse ,
+.IR memfillpoly ,
+.IR memimageline ,
+and
+.I memimagedraw
+are identical to the
+.IR arc ,
+.IR poly ,
+.IR ellipse ,
+.IR fillpoly ,
+.IR line ,
+and
+.IR gendraw ,
+routines described in
+.IR draw (2),
+except that they operate on
+.BR Memimage s
+rather than
+.BR Image s.
+Similarly,
+.IR allocmemsubfont ,
+.IR openmemsubfont ,
+.IR freememsubfont ,
+.IR memsubfontwidth ,
+.IR getmemdefont ,
+and
+.I memimagestring
+are the
+.B Memimage
+analogues of
+.IR allocsubfont ,
+.IR openfont ,
+.IR freesubfont ,
+.IR strsubfontwidth ,
+.IR getdefont ,
+and
+.B string
+(see
+.IR subfont (2)
+and
+.IR graphics (2)),
+except that they operate
+only on
+.BR Memsubfont s
+rather than
+.BR Font s.
+.PP
+.I Drawclip
+takes the images involved in a draw operation,
+together with the destination rectangle
+.B dr
+and source
+and mask alignment points
+.B sp
+and
+.BR mp ,
+and
+clips them according to the clipping rectangles of the images involved.
+It also fills in the rectangles
+.B sr
+and
+.B mr
+with rectangles congruent to the returned destination rectangle
+but translated so the upper left corners are the returned
+.B sp
+and
+.BR mp .
+.I Drawclip
+returns zero when the clipped rectangle is empty.
+.I Memlinebbox
+returns a conservative bounding box containing a line between
+two points
+with given end styles
+and radius.
+.I Memlineendsize
+calculates the extra length added to a line by attaching
+an end of a given style.
+.PP
+The
+.I hwdraw
+and
+.I iprint
+functions are no-op stubs that may be overridden by clients
+of the library.
+.I Hwdraw
+is called at each call to
+.I 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.
+.I Iprint
+should format and print its arguments;
+it is given much debugging output when
+the global integer variable
+.B drawdebug
+is non-zero.
+In the kernel,
+.I iprint
+prints to a serial line rather than the screen, for obvious reasons.
+.SH SOURCE
+.B /sys/src/libmemdraw
+.SH SEE ALSO
+.IR addpt (2),
+.IR color (2),
+.IR draw (2),
+.IR graphics (2),
+.IR memlayer (2),
+.IR stringsize (2),
+.IR subfont (2),
+.IR color (6),
+.IR utf (6)
+.SH BUGS
+.I Memimagestring
+is unusual in using a subfont rather than a font,
+and in having no parameter to align the source.