.TH ALLOCIMAGE 2.SH NAMEallocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline \- allocating, freeing, reading, writing images.SH SYNOPSIS.nf.PP.B#include <u.h>.B#include <libc.h>.B#include <draw.h>.PP.ta \w'\fLImage 'u.BImage	*allocimage(Display *d, Rectangle r, .br.B	ulong chan, int repl, int col).PP.BImage	*allocimagemix(Display *d, ulong one, ulong three).PP.Bvoid	freeimage(Image *i).PP.Bint	nameimage(Image *i, char *name, int in).PP.BImage	*namedimage(Display *d, char *name).PP.Bulong	setalpha(ulong color, uchar alpha).PP.Bint	loadimage(Image *i, Rectangle r, uchar *data, int ndata).PP.Bint	cloadimage(Image *i, Rectangle r, uchar *data, int ndata).PP.Bint	unloadimage(Image *i, Rectangle r, uchar *data, int ndata).PP.BImage	*readimage(Display *d, int fd, int dolock).PP.Bint	writeimage(int fd, Image *i, int dolock).PP.Bint	bytesperline(Rectangle r, int d).PP.Bint	wordsperline(Rectangle r, int d).PP.nf.Benum.nf.ft L.ta +4n +20{	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,	};.fi.SH DESCRIPTIONA new.B Imageon.B Display.B dis allocated with.BR allocimage ;it will have the rectangle, pixel channel format,and replication flaggiven by its arguments.Convenient pixel channels like.BR GREY1 ,.BR GREY2 ,.BR CMAP8 ,.BR RGB16 ,.BR RGB24 ,and.BR RGBA32 are predefined.All the new image's pixels will have initial value.IR col .If.I colis .BR DNofill ,no initialization is done.Representative useful values of color are predefined:.BR DBlack ,.BR DWhite ,.BR 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 illumination, so 0 is black and 255 is white.Similarly, for alpha 0 is transparent and 255 is opaque.The.I idfield will have been set to the identifying number used by.B /dev/draw(see.IR draw (3)),and the.I cachefield will be zero.If.I replis true, the clip rectangle is set to a very large region; if false, it is set to.IR r .The .I depthfield will be set to the number of bits per pixel specifiedby the channel descriptor(see.IR image (6))..I Allocimagereturns 0 if the server has run out of image memory..PP.I Allocimagemixis used to allocate background colors.On 8-bit color-mapped displays, itreturns a 2×2 replicated image with one pixel colored the color.I oneand the other three with.IR three .(This simulates a wider range of tones than can be represented by a single pixelvalue 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..PP.I Freeimagefrees the resources used by its argument image..PP.I Nameimagepublishes in the server the image.I iunder the given.IR name .If.I inis non-zero, the image is published; otherwise.I imust be already named.I nameand it is withdrawn from publication..I Namedimagereturns a reference to the image published under the given.I nameon.B Display.IR d .These routines permit unrelated applications sharing a display to share an image;for example they provide the mechanism behind.B getwindow(see.IR graphics (2))..PPThe RGB values in a color are.I premultipliedby the alpha value; for example, a 50% red is.B 0x7F00007Fnot.BR 0xFF00007F .The function.I setalphaperforms the alpha computation on a given.BR color ,ignoring its initial alpha value, multiplying the components by the supplied.BR alpha .For example, to make a 50% red color value, one could execute.B setalpha(DRed,.BR 0x7F) ..PPThe remaining functions deal with moving groups of pixelvalues between image and user space or external files.There is a fixed format for the exchange and storage ofimage data(see.IR image (6))..PP.I Unloadimagereads a rectangle of pixels from image.I iinto.IR data ,whose length is specified by.IR ndata .It is an error if.I ndatais too small to accommodate the pixels..PP.I Loadimagereplaces the specified rectangle in image.I iwith the.I ndatabytes of.IR data ..PPThe pixels are presented one horizontal line at a time,starting with the top-left pixel of.IR 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.IR data ,regardless of the rectangle being extracted.Bytes are filled from most to least significant bit order,as the.I xcoordinate increases, aligned so.IR x =0would appear as the leftmost pixel of its byte.Thus, for.B depth1, the pixel at.I xoffset 165 within the rectangle will be in a.I databyte at bit-position.B 0x04regardless of the overallrectangle: 165 mod 8 equals 5, and.B "0x80\ >>\ 5"equals.BR 0x04 ..PP.B Cloadimagedoes the same as.IR loadimage ,but for.I ndatabytes of compressed image.I data(see.IR image (6)).On each call to.IR cloadimage,the.I datamust be at the beginning of a compressed data block, in particular,it should start with the.B ycoordinate and data length for the block. .PP.IR Loadimage ,.IR cloadimage ,and.I unloadimagereturn the number of bytes copied..PP.I Readimagecreates an image from data contained in an external file (see.IR image (6)for the file format);.I fdis a file descriptor obtained by opening such a file for reading.The returned image is allocated using.IR allocimage .The.I dolockflag specifies whether the.B Displayshould be synchronized for multithreaded access; single-threadedprograms can leave it zero..PP.I Writeimagewrites image.I ionto file descriptor.IR fd ,which should be open for writing.The format is as described for.IR readimage ..PP.I Readimageand.I writeimagedo not close.IR fd ..PP.I Bytesperlineand.I wordsperlinereturn the number of bytes or words occupied in memory by one scan line of rectangle.I rin an image with.I dbits per pixel..SH EXAMPLETo allocate a single-pixel replicated image that may be used to paint a region red,.EX	red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);.EE.SH SOURCE.B /sys/src/libdraw.SH "SEE ALSO".IR graphics (2),.IR draw (2),.IR draw (3),.IR image (6).SH DIAGNOSTICSThese functions return pointer 0 or integer \-1 on failure, usually due to insufficientmemory..PPMay set.IR errstr ..SH BUGS.B Depthmust be a divisor or multiple of 8.