ALLOCIMAGE(2) ALLOCIMAGE(2)
NAME
allocimage, allocimagemix, freeimage, nameimage, namedimage,
setalpha, loadimage, cloadimage, unloadimage, readimage,
writeimage, bytesperline, wordsperline - allocating,
freeing, reading, writing images
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <draw.h>
Image *allocimage(Display *d, Rectangle r,
ulong chan, int repl, ulong col)
Image *allocimagemix(Display *d, ulong one, ulong three)
int freeimage(Image *i)
int nameimage(Image *i, char *name, int in)
Image *namedimage(Display *d, char *name)
ulong setalpha(ulong color, uchar alpha)
int loadimage(Image *i, Rectangle r, uchar *data, int ndata)
int cloadimage(Image *i, Rectangle r, uchar *data, int ndata)
int unloadimage(Image *i, Rectangle r, uchar *data, int ndata)
Image *readimage(Display *d, int fd, int dolock)
int writeimage(int fd, Image *i, int dolock)
int bytesperline(Rectangle r, int d)
int wordsperline(Rectangle r, int d)
enum
{
DOpaque = 0xFFFFFFFF,
DTransparent = 0x00000000,
DBlack = 0x000000FF,
DWhite = 0xFFFFFFFF,
DRed = 0xFF0000FF,
DGreen = 0x00FF00FF,
DBlue = 0x0000FFFF,
DCyan = 0x00FFFFFF,
DMagenta = 0xFF00FFFF,
DYellow = 0xFFFF00FF,
Page 1 Plan 9 (printed 11/23/24)
ALLOCIMAGE(2) ALLOCIMAGE(2)
DPaleyellow = 0xFFFFAAFF,
DDarkyellow = 0xEEEE9EFF,
DDarkgreen = 0x448844FF,
DPalegreen = 0xAAFFAAFF,
DMedgreen = 0x88CC88FF,
DDarkblue = 0x000055FF,
DPalebluegreen = 0xAAFFFFFF,
DPaleblue = 0x0000BBFF,
DBluegreen = 0x008888FF,
DGreygreen = 0x55AAAAFF,
DPalegreygreen = 0x9EEEEEFF,
DYellowgreen = 0x99994CFF,
DMedblue = 0x000099FF,
DGreyblue = 0x005DBBFF,
DPalegreyblue = 0x4993DDFF,
DPurpleblue = 0x8888CCFF,
DNotacolor = 0xFFFFFF00,
DNofill = DNotacolor,
};
DESCRIPTION
A new Image on Display d is allocated with allocimage; it
will have the rectangle, pixel channel format, replication
flag, and initial fill color given by its arguments. Conve-
nient pixel channels like GREY1, GREY2, CMAP8, RGB16, RGB24,
and RGBA32 are predefined. All the new image's pixels will
have initial value col. If col is DNofill, no initialization
is done. Representative useful values of color are prede-
fined: DBlack, DWhite, DRed, and so on. Colors are speci-
fied by 32-bit numbers comprising, from most to least sig-
nificant byte, 8-bit values for red, green, blue, and alpha.
The values correspond to illumination, so 0 is black and 255
is white. Similarly, for alpha 0 is transparent and 255 is
opaque. The id field will have been set to the identifying
number used by /dev/draw (see draw(3)), and the cache field
will be zero. If repl is true, the clip rectangle is set to
a very large region; if false, it is set to r. The depth
field will be set to the number of bits per pixel specified
by the channel descriptor (see image(6)). Allocimage returns
0 if the server has run out of image memory.
Allocimagemix is used to allocate background colors. On 8-
bit color-mapped displays, it returns a 2×2 replicated image
with one pixel colored the color one and the other three
with three. (This simulates a wider range of tones than can
be represented by a single pixel value on a color-mapped
display.) On true color displays, it returns a 1×1 repli-
cated image whose pixel is the result of mixing the two col-
ors in a one to three ratio.
Page 2 Plan 9 (printed 11/23/24)
ALLOCIMAGE(2) ALLOCIMAGE(2)
Freeimage frees the resources used by its argument image.
Nameimage publishes in the server the image i under the
given name. If in is non-zero, the image is published; oth-
erwise i must be already named name and it is withdrawn from
publication. Namedimage returns a reference to the image
published under the given name on Display d. These routines
permit unrelated applications sharing a display to share an
image; for example they provide the mechanism behind
getwindow (see graphics(2)).
The RGB values in a color are premultiplied by the alpha
value; for example, a 50% red is 0x7F00007F not 0xFF00007F.
The function setalpha performs the alpha computation on a
given color, ignoring its initial alpha value, multiplying
the components by the supplied alpha. For example, to make
a 50% red color value, one could execute setalpha(DRed,
0x7F).
The remaining functions deal with moving groups of pixel
values between image and user space or external files.
There is a fixed format for the exchange and storage of
image data (see image(6)).
Unloadimage reads a rectangle of pixels from image i into
data, whose length is specified by ndata. It is an error if
ndata is too small to accommodate the pixels.
Loadimage replaces the specified rectangle in image i with
the ndata bytes of data.
The pixels are presented one horizontal line at a time,
starting with the top-left pixel of r. In the data processed
by these routines, each scan line starts with a new byte in
the array, leaving the last byte of the previous line par-
tially empty, if necessary. Pixels are packed as tightly as
possible within data, regardless of the rectangle being
extracted. Bytes are filled from most to least significant
bit order, as the x coordinate increases, aligned so x=0
would appear as the leftmost pixel of its byte. Thus, for
depth 1, the pixel at x offset 165 within the rectangle will
be in a data byte at bit-position 0x04 regardless of the
overall rectangle: 165 mod 8 equals 5, and 0x80 >> 5 equals
0x04.
Cloadimage does the same as loadimage, but for ndata bytes
of compressed image data (see image(6)). On each call to
cloadimage, the data must be at the beginning of a com-
pressed data block, in particular, it should start with the
y coordinate and data length for the block.
Loadimage, cloadimage, and unloadimage return the number of
Page 3 Plan 9 (printed 11/23/24)
ALLOCIMAGE(2) ALLOCIMAGE(2)
bytes copied.
Readimage creates an image from data contained in an exter-
nal file (see image(6) for the file format); fd is a file
descriptor obtained by opening such a file for reading. The
returned image is allocated using allocimage. The dolock
flag specifies whether the Display should be synchronized
for multithreaded access; single-threaded programs can leave
it zero.
Writeimage writes image i onto file descriptor fd, which
should be open for writing. The format is as described for
readimage.
Readimage and writeimage do not close fd.
Bytesperline and wordsperline return the number of bytes or
words occupied in memory by one scan line of rectangle r in
an image with d bits per pixel.
EXAMPLE
To allocate a single-pixel replicated image that may be used
to paint a region red,
red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);
SOURCE
/sys/src/libdraw
SEE ALSO
graphics(2), draw(2), draw(3), image(6)
DIAGNOSTICS
These functions return pointer 0 or integer -1 on failure,
usually due to insufficient memory.
May set errstr.
BUGS
Depth must be a divisor or multiple of 8.
Page 4 Plan 9 (printed 11/23/24)