ALLOCIMAGE(3) ALLOCIMAGE(3)
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, int col)
Image *allocimagemix(Display *d, ulong one, ulong three)
void 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 12/22/24)
ALLOCIMAGE(3) ALLOCIMAGE(3)
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, and replica-
tion flag given by its arguments. Convenient pixel channels
like GREY1, GREY2, CMAP8, RGB16, RGB24, and RGBA32 are pre-
defined. All the new image's pixels will have initial value
col. If col is DNofill, no initialization is done. Repre-
sentative useful values of color are predefined: DBlack,
DWhite, DRed, and so on. Colors are specified by 32-bit
numbers comprising, from most to least significant byte, 8-
bit values for red, green, blue, and alpha. The values cor-
respond 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(7)). 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 12/22/24)
ALLOCIMAGE(3) ALLOCIMAGE(3)
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(3)).
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(7)).
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(7)). 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 12/22/24)
ALLOCIMAGE(3) ALLOCIMAGE(3)
bytes copied.
Readimage creates an image from data contained in an exter-
nal file (see image(7) 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
/usr/local/plan9/src/libdraw
SEE ALSO
graphics(3), draw(3), draw(3), image(7)
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 12/22/24)