10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
349 lines
7.1 KiB
Groff
349 lines
7.1 KiB
Groff
.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
|
||
.MR 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
|
||
.MR image 7 ).
|
||
.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
|
||
.MR graphics 3 ).
|
||
.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
|
||
.MR image 7 ).
|
||
.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
|
||
.MR image 7 ).
|
||
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
|
||
.MR image 7
|
||
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 \*9/src/libdraw
|
||
.SH "SEE ALSO"
|
||
.MR graphics 3 ,
|
||
.MR draw 3 ,
|
||
.MR draw 3 ,
|
||
.MR image 7
|
||
.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.
|