MEMDRAW(3)

🌸 NAME 🌸

okay so gather round bestie, because this page is a whole squad of functions — we're talking 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, and hwdraw 💅

and what do they all do? drawing routines for memory-resident images ✨ periodt.

---

✨ SYNOPSIS ✨

ok so before literally anything else, you need these headers in your life 🫶

#include <u.h>
#include <u.h>
#include <libc.h>
#include <draw.h>
#include <memdraw.h>

(yes bestie, <u.h> shows up twice in the original — that's not a typo, that's just how it is, don't @ me 💀)

then the structs and the whole function roster:

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;

void        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)

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)

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)
Point       memimagestring(Memimage *dst, Point p, Memimage *color,
                 Point cp, Memsubfont *f, char *cs, Drawop op)

int         iprint(char *fmt, ...)
int         hwdraw(Memdrawparam *param)

---

💖 DESCRIPTION 💖

okay so the Memimage type is literally the blueprint for memory-resident rectangular pictures, plus all the methods to draw upon them 🎨 and here's the tea: Memimages are different from Images (peep draw(3)) because they get manipulated directly in user memory instead of by RPCs to the /dev/draw hierarchy. no cap. this library is the actual basis for the kernel draw(3) driver, and it's also used by a bunch of programs that gotta manipulate images with no display at all 👑

the r, clipr, depth, nchan and chan structure elements? identical to the ones of the same name in the Image structure. slay, consistency 💅

the flags element of the Memimage structure holds a bunch of bits of info about the image — and in particular, it subsumes the purpose of the repl element of Image structures. iconic behavior honestly.

memimageinit initializes various static data that the library depends on, plus the replicated solid color images memopaque, memtransparent, memblack and memwhite. 🎀 so like — call it before you refer to any of those images, and before calling any of the other library functions. it's the vibe check you do first, fr fr.

every Memimage points at a Memdata structure, which in turn points at the actual pixel data for the image — which is what lets multiple images 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 in the Plan 9 kernel, the memory allocator (see Plan 9's pool(3)) can compact image memory using memimagemove 🧚

and 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 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, and the depth element tells you how to move the pointer horizontally. and the cute part? this method works even for images whose rectangles do not include the origin — although bestie, you should only dereference pointers corresponding to pixels within the image rectangle 🙈. wordaddr and byteaddr do these calculations for you, returning pointers to the word and the 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(3)), creating a fresh Memdata structure and associated storage. allocmemimaged is basically the same but uses the supplied Memdata structure instead of a new one. readmemimage 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. want more on bitmap formats? see image(7) 🌈. freememimage frees images returned by any of these routines. also the Memimage structure contains some tables used to store precomputed values depending on the channel descriptor — memsetchan updates the chan element of the structure as well as these tables, and returns -1 if you pass it 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 you call cloadmemimage, the buffer must contain an integral number of compressed chunks of data that exactly cover the rectangle — no partial vibes allowed. 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(3) 🎨

memarc, mempoly, memellipse, memfillpoly, memimageline and memimagedraw are identical to the arc, poly, ellipse, fillpoly, line and gendraw routines described in draw(3) — except they operate on Memimages rather than Images. same energy for allocmemsubfont, openmemsubfont, freememsubfont, memsubfontwidth and memimagestring, which are the Memimage analogues of allocsubfont, openfont, freesubfont, strsubfontwidth and string (see subfont(3) and graphics(3)) — except they operate only on Memsubfonts rather than Fonts, iykyk 💜

drawclip takes the images involved in a draw operation, together with the destination rectangle dr and the 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. drawclip returns zero when the clipped rectangle is empty. memlinebbox returns a conservative 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 📏

and finally the stubs 🫶 hwdraw and iprint are no-op stubs that may be overridden by clients of the library. hwdraw gets 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 lets (for instance) the kernel take advantage of hardware acceleration ⚡. iprint should format and print its arguments — it's given much debugging output when the global integer variable drawdebug is non-zero 👀. and in the kernel, iprint prints to a serial line rather than the screen, for obvious reasons 😭

---

🦋 SOURCE 🦋

/src/libmemdraw

---

🎀 SEE ALSO 🎀

• addpt(3)
• color(3)
• draw(3)
• graphics(3)
• memlayer(3)
• stringsize(3)
• subfont(3)
• color(7)
• utf(7)

---

💀 BUGS 💀

memimagestring is lowkey unusual — it uses a subfont rather than a font, and it has no parameter to align the source 🙈 that's just how it is bestie, we don't make the rules.

---

okay that's the whole page, no notes 💅 it's MEMDRAW(3) out of the Library Functions Manual — no date stamped on this one ngl, but it's living happily in the source tree at /src/libmemdraw 🌟 bye bestie, go draw something iconic 💖✨🎀