BIT(3) BIT(3)
NAME
bit - screen graphics, mouse
SYNOPSIS
bind #b /dev
/dev/bitblt
/dev/mouse
/dev/screen
#include <u.h>
#include <libg.h>
ushortBGSHORT(uchar *p)
ulong BGLONG(uchar *p)
void BPSHORT(uchar *p, ushort v)
void BPLONG(uchar *p, ulong v)
DESCRIPTION
The bit device provides the bitblt, mouse, and screen on
machines with a bitmapped screen and a mouse. The device is
exclusive use.
The bit device provides, through the bitblt file, access to
bitmaps, fonts, and subfonts in its private storage, as
described in graphics(2). Each object is identified by a
short, its id. The bitmap with id zero is special: it repre-
sents 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 current mouse position. A process can write messages
to bitblt to allocate and free bitmaps, fonts, and subfonts,
read or write portions of the bitmaps, and draw line seg-
ments, textures, and character strings in the bitmaps. All
graphics requests are clipped to their bitmaps. Some mes-
sages 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 inte-
gers are transmitted with the low order byte first. The
BPSHORT and BPLONG macros place correctly 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
Page 1 Plan 9 (printed 12/22/24)
BIT(3) BIT(3)
numbers in brackets give the length in bytes of the parame-
ters.
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 bitmap is returned on a
subsequent read from bitblt, returning the three bytes:
`A' 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 identified by srcid to a congruent rectangle at
Point dstpt in the bitmap identified by dstid. The
rectangle is clipped against both source and destina-
tion bitmaps. See bitblt(2).
c [ pt[8] clr[32] set[32] ]
Switch mouse cursor. See the description of Cursors in
graphics(2) for the meaning of the pt (the offset),
set, and clr arguments. If only `c' is provided - that
is, if the message is one byte long - the cursor
changes to the default, typically an arrow.
f id[2]
Free the resources associated with the allocated bitmap
identified by id.
g id[2]
Free the resources associated with the allocated sub-
font identified by id, including its bitmap. If the
subfont is cached, the associated data may be recover-
able 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 infor-
mation about the display:
I ldepth[1] rect[16] cliprect[16].
If the read count is large enough, the above informa-
tion is followed by the header and character informa-
tion of the default Subfont, 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 font. The ids of the screen bitmap and default
subfont are both zero.
Page 2 Plan 9 (printed 12/22/24)
BIT(3) BIT(3)
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 error. 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
subfalloc(2), with info in external subfont file for-
mat. Bitmapid identifies a previously allocated bitmap
containing the character images. 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: `K'
followed by the id. Henceforth, the bitmap with id
bitmapid is unavailable to the application; 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 des-
tination 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: `N' 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 speci-
fied id to the given rectangle, which will itself be
Page 3 Plan 9 (printed 12/22/24)
BIT(3) BIT(3)
clipped to the bitmap's image 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 subsequent read of bitblt will return
the requested rows of pixels. Note: in this case, the
response does not begin an `R', to simplify the reading
of large bitmaps.
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 cannot 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 subfont 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 posi-
tion 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]
Page 4 Plan 9 (printed 12/22/24)
BIT(3) BIT(3)
where x and y are the mouse coordinates in the screen bit-
map, 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.
The screen file contains the screen bitmap in the format
described in bitmap(6).
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 because of insufficient free
resources. Most other errors occur only when the protocol
is mishandled by the application.
BUGS
Because each message must fit in a single 9P message, sub-
fonts are limited to about 1300 characters.
Page 5 Plan 9 (printed 12/22/24)