term% cat index.txt BIT(3) Library Functions Manual BIT(3)
NAME
bit - screen graphics, mouse
SYNOPSIS
bind -a #b /dev
/dev/bitblt
/dev/mouse
/dev/mousectl
/dev/screen
#include <u.h>
#include <libg.h>
ushort BGSHORT(uchar *p)
ulong BGLONG(uchar *p)
void BPSHORT(uchar *p, ushort v)
void BPLONG(uchar *p, ulong v)
DESCRIPTION
The bit device provides the files bitblt, mouse, mousectl, and screen
on machines with a bitmapped screen and a mouse. The device is exclu‐
sive use.
The bit device provides, through the bitblt file, access to bitmaps,
fonts, and subfonts in its private storage, as described in graph‐
ics(2). Each object is identified by a short, its id. The bitmap with
id zero is special: it represents the visible display. The subfont
with id zero is also special: it is initialized to a default subfont
that is always available. There is no default font. There is also a
cursor associated with the screen; it is always displayed at the cur‐
rent mouse position. A process can write messages to bitblt to allo‐
cate and free bitmaps, fonts, and subfonts, read or write portions of
the bitmaps, and draw line segments, textures, and character strings in
the bitmaps. All graphics requests are clipped to their bitmaps. Some
messages return a response to be recovered by reading bitblt.
The format of messages written to bitblt is a single lower case letter
followed by binary parameters; multibyte integers are transmitted with
the low order byte first. The BPSHORT and BPLONG macros place cor‐
rectly formatted two- and four-byte integers into a character buffer.
Some messages return a response formatted the same way; it usually
starts with the upper case version of the request character. BGSHORT
and BGLONG retrieve values from a character buffer. Points are two
four-byte numbers: x, y. Rectangles are four four-byte numbers: min x,
min y, max x, and max y.
The following requests are accepted by the bitblt file. The numbers in
brackets give the length in bytes of the parameters.
a ldepth[1] rect[16]
Allocate a bitmap. Ldepth is the log base 2 of the number of bits
per pixel. Rect is a Rectangle giving the extent of the bitmap.
The bitmap is cleared to all zeros. The id of the allocated bit‐
map is returned on a subsequent read from bitblt, returning the
three bytes: followed by the id.
b dstid[2] dstpt[8] srcid[2] srcrect[16] code[2]
Bit-block transfer (bitblt) from a rectangle in the bitmap identi‐
fied by srcid to a congruent rectangle at Point dstpt in the bit‐
map identified by dstid. The rectangle is clipped against both
source and destination bitmaps. See bitblt(2).
c [ pt[8] clr[32] set[32] ]
Switch mouse cursor. See the description of Cursors in graph‐
ics(2) for the meaning of the pt (the offset), set, and clr argu‐
ments. If only is provided — that is, if the message is one byte
long — the cursor changes to the default, typically an arrow.
e id[2] pt[8] value[1] code[2] n[2] pts[n*2]
Join the n+1 points pt and pts with n segments, exactly as for the
l operator. The pts are specified by pairs of signed bytes hold‐
ing offsets from the previous point in the list.
f id[2]
Free the resources associated with the allocated bitmap identified
by id.
g id[2]
Free the resources associated with the allocated subfont identi‐
fied by id, including its bitmap. If the subfont is cached, the
associated data may be recoverable even after it has been freed;
see below.
h id[2]
Free the resources associated with the allocated font identified
by id.
i
Initialize the device. The next operation on bitblt should be a
read(2). A read of length 34 returns information about the dis‐
play:
I ldepth[1] rect[16] cliprect[16].
If the read count is large enough, the above information is fol‐
lowed by the header and character information of the default Sub‐
font, in the format expected by rdsubfontfile (see subfalloc(2)
and font(6)). `Large enough' is 36 + 6n, where n is the number of
characters in the subfont. The ids of the screen bitmap and de‐
fault subfont are both zero.
j q0[4] q1[4]
Check to see whether a subfont with tags q0 and q1 is in the
cache. If it is not, the write of the j message will draw an er‐
ror. If it is, the next read of bitblt will return
J id[2]
followed by the subfont information in the same format as returned
by an init message; the subfont will then be available for use.
k n[2] height[1] ascent[1] bitmapid[2] q0[4] q1[4] info[6*(n+1)]
Allocate subfont. The parameters are as described in subfal‐
loc(2), with info in external subfont file format. Bitmapid iden‐
tifies a previously allocated bitmap containing the character im‐
ages. Q0 and q1 are used as labels for the subfont in the cache;
if all ones, the subfont will not be cached and hence shared with
other applications. The id of the allocated subfont is recovered
by reading from bitblt the three bytes: followed by the id.
Henceforth, the bitmap with id bitmapid is unavailable to the ap‐
plication; in effect, it has been freed.
l id[2] pt1[8] pt2[8] value[1] code[2]
Draw a line segment from Point pt1 to Point pt2, using code for
the drawing function, and value as the source pixel. See segment
in bitblt(2). Id identifies the destination bitmap.
m id[2]
Read the colormap associated with the bitmap with the specified
id. The next read of bitblt will return 12*2^n bytes of colormap
data where n is the number of bits per pixel in the bitmap.
n height[1] ascent[1] ldepth[2] ncache[2]
Allocate a font with the given height, ascent, and ldepth. The id
of the allocated font is recovered by reading from bitblt the
three bytes: followed by the id. The initial cache associated
with the font will have ncache character entries of zero width.
p id[2] pt[8] value[1] code[2]
Change the pixel at Point pt using code for the drawing function,
and value as the source pixel. See point in bitblt(2).
q id[2] rect[16]
Set the clipping rectangle for the bitmap with specified id to the
given rectangle, which will itself be clipped to the bitmap's im‐
age rectangle.
r id[2] miny[4] maxy[4]
Read rows ymin, ymin+1, ... ymax-1 of the bitmap with the given
bitmap id. See the description of rdbitmap in balloc(2). A sub‐
sequent read of bitblt will return the requested rows of pixels.
Note: in this case, the response does not begin with an to sim‐
plify the reading of large bitmaps. Also, the reply may be too
large to fit in a single 9P message (see read(5)), so multiple
reads may be necessary; each read will return only complete rows.
s id[2] pt[8] fontid[2] code[2] n[2] indices[2*n]
Draw using code code in the bitmap identified by id the text
string specified by the n cache indices in font fontid, starting
with the upper left corner at pt.
t dstid[2] rect[16] srcid[2] code[2]
Texture the given rectangle in the bitmap identified by dstid by
overlaying a tiling of the bitmap identified by srcid (aligning
(0,0) in the two bitmaps), and using code as a drawing code for
bitblt; see texture in bitblt(2).
v id[2] ncache[2] width[2]
Reset, resize, and clear the cache for font id; the maximum width
of the ncache characters the cache may hold is set to width. Must
be done before the first load of a cache slot. If the cache can‐
not be resized, the write of this message will fail but the cache
will be unaffected.
w id[2] miny[4] maxy[4] data[n]
Replace rows ymin, ymin+1, ... ymax-1 of the bitmap with the
given bitmap id with the values in data. See the description of
wrbitmap in balloc(2).
x x[4] y[4]
Move the cursor so its origin is at (x,y).
y id[2] cacheindex[2] subfontid[2] subfontindex[2]
Load the description and image of character subfontindex in sub‐
font subfontid into slot cacheindex of font id.
z id[2] map[m]
Replace the colormap associated with bitmap id with map, which
contains m=12*2^n bytes of colormap data (see rgbpix(2) for the
format).
A read of the mouse file returns the mouse status: its position and
button state. The read blocks until the state has changed since the
last read. The read returns 14 bytes:
m buttons[1] x[4] y[4] msec[4]
where x and y are the mouse coordinates in the screen bitmap, msec is a
time stamp, in units of milliseconds, and buttons has set the 1, 2, and
4 bits when the mouse's left, middle, and right buttons, respectively,
are down.
Writing to the mousectl file configures and controls the mouse. The
messages are:
serial n sets serial port n to be the mouse port.
ps2 sets the PS2 port to be the mouse port.
accelerated turns on mouse acceleration.
linear turns off mouse acceleration
res n sets mouse resolution to a setting between 0 and 3 inclu‐
sive.
swap swaps the left and right buttons on the mouse.
Which messages are implemented is machine-dependent.
The screen file contains the screen bitmap in the format described in
bitmap(6).
SOURCE
/sys/src/9/port/devbit.c
DIAGNOSTICS
Most messages to bitblt can return errors; these can be detected by a
system call error on the write(see read(2)) of the data containing the
erroneous message. The most common error is a failure to allocate be‐
cause of insufficient free resources. Most other errors occur only
when the protocol is mishandled by the application. Errstr(2) will re‐
port details.
BUGS
Because each message must fit in a single 9P message, subfonts are lim‐
ited to about 1300 characters.
Can only change the color map of bitmap 0.
BIT(3)