Lots of man pages.
This commit is contained in:
rsc
parent
08df2a433e
commit
cfa37a7b11
152 changed files with 25407 additions and 148 deletions
348
man/man3/allocimage.3
Normal file
348
man/man3/allocimage.3
Normal file
|
|
@ -0,0 +1,348 @@
|
|||
.TH ALLOCIMAGE 3
|
||||
.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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue