plan9fox/sys/man/2/allocimage

.TH ALLOCIMAGE 2
.SH NAME
allocimage, 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
.B
Image	*allocimage(Display *d, Rectangle r,
.br
.B
	ulong chan, int repl, ulong col)
.PP
.B
Image	*allocimagemix(Display *d, ulong one, ulong three)
.PP
.B
int	freeimage(Image *i)
.PP
.B
int	nameimage(Image *i, char *name, int in)
.PP
.B
Image	*namedimage(Display *d, char *name)
.PP
.B
ulong	setalpha(ulong color, uchar alpha)
.PP
.B
int	loadimage(Image *i, Rectangle r, uchar *data, int ndata)
.PP
.B
int	cloadimage(Image *i, Rectangle r, uchar *data, int ndata)
.PP
.B
int	unloadimage(Image *i, Rectangle r, uchar *data, int ndata)
.PP
.B
Image	*readimage(Display *d, int fd, int dolock)
.PP
.B
int	writeimage(int fd, Image *i, int dolock)
.PP
.B
int	bytesperline(Rectangle r, int d)
.PP
.B
int	wordsperline(Rectangle r, int d)
.PP
.nf
.B
enum
.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 DESCRIPTION
A new
.B Image
on
.B Display
.B d
is allocated with
.BR allocimage ;
it will have the rectangle, pixel channel format,
replication flag,
and initial fill color
given 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 col
is 
.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 id
field will have been set to the identifying number used by
.B /dev/draw
(see
.IR draw (3)),
and the
.I cache
field will be zero.
If
.I repl
is true, the clip rectangle is set to a very large region; if false, it is set to
.IR r .
The 
.I depth
field will be set to the number of bits per pixel specified
by the channel descriptor
(see
.IR image (6)).
.I Allocimage
returns 0 if the server has run out of image memory.
.PP
.I 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
.I one
and the other three with
.IR 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.
.PP
.I Freeimage
frees the resources used by its argument image.
.PP
.I Nameimage
publishes in the server the image
.I i
under the given
.IR name .
If
.I in
is non-zero, the image is published; otherwise
.I i
must be already named
.I name
and it is withdrawn from publication.
.I Namedimage
returns a reference to the image published under the given
.I name
on
.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)).
.PP
The RGB values in a color are
.I premultiplied
by the alpha value; for example, a 50% red is
.B 0x7F00007F
not
.BR 0xFF00007F .
The function
.I setalpha
performs 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) .
.PP
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
.IR image (6)).
.PP
.I Unloadimage
reads a rectangle of pixels from image
.I i
into
.IR data ,
whose length is specified by
.IR ndata .
It is an error if
.I ndata
is too small to accommodate the pixels.
.PP
.I Loadimage
replaces the specified rectangle in image
.I i
with the
.I ndata
bytes of
.IR data .
.PP
The 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 x
coordinate increases, aligned so
.IR x =0
would appear as the leftmost pixel of its byte.
Thus, for
.B depth
1, the pixel at
.I x
offset 165 within the rectangle will be in a
.I data
byte at bit-position
.B 0x04
regardless of the overall
rectangle: 165 mod 8 equals 5, and
.B "0x80\ >>\ 5"
equals
.BR 0x04 .
.PP
.B Cloadimage
does the same as
.IR loadimage ,
but for
.I ndata
bytes of compressed image
.I data
(see
.IR image (6)).
On each call to
.IR cloadimage,
the
.I data
must be at the beginning of a compressed data block, in particular,
it should start with the
.B y
coordinate and data length for the block. 
.PP
.IR Loadimage ,
.IR cloadimage ,
and
.I unloadimage
return the number of bytes copied.
.PP
.I Readimage
creates an image from data contained in an external file (see
.IR image (6)
for the file format);
.I fd
is a file descriptor obtained by opening such a file for reading.
The returned image is allocated using
.IR allocimage .
The
.I dolock
flag specifies whether the
.B Display
should be synchronized for multithreaded access; single-threaded
programs can leave it zero.
.PP
.I Writeimage
writes image
.I i
onto file descriptor
.IR fd ,
which should be open for writing.
The format is as described for
.IR readimage .
.PP
.I Readimage
and
.I writeimage
do not close
.IR fd .
.PP
.I Bytesperline
and
.I wordsperline
return the number of bytes or words occupied in memory by one scan line of rectangle
.I r
in an image with
.I d
bits per pixel.
.SH EXAMPLE
To 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 DIAGNOSTICS
These functions return pointer 0 or integer \-1 on failure, usually due to insufficient
memory.
.PP
May set
.IR errstr .
.SH BUGS
.B Depth
must be a divisor or multiple of 8.