term% cat index.txt ALLOCIMAGE(2) System Calls Manual ALLOCIMAGE(2)
NAME
allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha,
loadimage, cloadimage, unloadimage, readimage, writeimage, bytesper‐
line, 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,
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. Convenient pixel channels like GREY1,
GREY2, CMAP8, RGB16, RGB24, and RGBA32 are predefined. All the new im‐
age's pixels will have initial value col. If col is DNofill, no ini‐
tialization is done. Representative useful values of color are prede‐
fined: 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 correspond to illumina‐
tion, so 0 is black and 255 is white. Similarly, for alpha 0 is trans‐
parent and 255 is opaque. The id field will have been set to the iden‐
tifying 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 col‐
ored 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
replicated image whose pixel is the result of mixing the two colors in
a one to three ratio.
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; otherwise 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 ex‐
ample, 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 ex‐
ample, 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 partially empty, if necessary. Pixels are packed as
tightly as possible within data, regardless of the rectangle being ex‐
tracted. 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 com‐
pressed image data (see image(6)). On each call to cloadimage, the
data must be at the beginning of a compressed data block, in particu‐
lar, it should start with the y coordinate and data length for the
block.
Loadimage, cloadimage, and unloadimage return the number of bytes
copied.
Readimage creates an image from data contained in an external 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 occu‐
pied 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.
ALLOCIMAGE(2)