Subversion Repositories planix.SVN

.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, int col)

.PP

.B

Image	*allocimagemix(Display *d, ulong one, ulong three)

.PP

.B

void	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,

and replication flag

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.