GRAPHICS(2) GRAPHICS(2)
NAME
Point, Rectangle, Bitmap, Cursor, binit, bclose, berror,
bscreenrect, bneed, bflush, bwrite, bexit, clipr,
cursorswitch, cursorset, rdfontfile, ffree, charwidth,
Pconv, Rconv - bitmap graphics
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <libg.h>
void binit(void (*errfun)(char *), char *font, char *label)
void bclose(void)
void bexit(void)
void berror(char *msg)
Rectangle bscreenrect(Rectangle *clipr)
uchar* bneed(int n)
void bflush(void)
int bwrite(void)
int clipr(Bitmap *b, Rectangle cr)
void cursorswitch(Cursor *curs)
void cursorset(Point p)
Font* rdfontfile(char *name, int ldepth)
void ffree(Font *f)
int charwidth(Font *f, Rune r)
int Pconv(void *arg, Fconv*)
int Rconv(void *arg, Fconv*)
extern Bitmap screen
extern Font *font
DESCRIPTION
A Point is a location in a bitmap (see below), such as the
screen, and is defined as:
Page 1 Plan 9 (printed 12/22/24)
GRAPHICS(2) GRAPHICS(2)
typedef
struct Point {
int x;
int y;
} Point;
The coordinate system has x increasing to the right and y
increasing down.
A Rectangle is a rectangular area in a bitmap.
typedef
struct Rectangle {
Point min; /* upper left */
Point max; /* lower right */
} Rectangle;
By definition, min.x≤max.x and min.y≤max.y. By convention,
the right (maximum x) and bottom (maximum y) edges are
excluded from the represented rectangle, so abutting rectan-
gles have no points in common. Thus, max contains the coor-
dinates of the first point beyond the rectangle.
A Bitmap holds a rectangular image.
typedef
struct Bitmap {
Rectangle r; /* rect. in data area, local coords */
Rectangle clipr; /* clipping region */
int ldepth; /* log base 2 of #bits per pixel */
int id; /* id as known in /dev/bitblt */
Bitmap* cache; /* zero; tells bitmap from layer */
} Bitmap;
R.min is the location in the bitmap of the upper-leftmost
point in the image. There are 2^ldepth contiguous bits for
each pixel of the image; the bits form a binary number giv-
ing the pixel value. `Clipr' is the clipping rectangle;
typically it is the same as r except in a window, where it
is inset by the width of the border. Graphical operations
on the Bitmap will be confined to the clipping rectangle.
The subroutine clipr sets the clipping rectangle of b to the
intersection of cr and b->r. If cr does not intersect b->r
it does nothing. Clipr returns 1 if the clipping region was
set, 0 if it was not.
A Font is a set of character images, indexed by runes (see
utf(6)). The images are organized into Subfonts, each con-
taining the images for a small, contiguous set of runes.
The detailed format of these data structures, which are
described in detail in cachechars(2), is immaterial for most
applications. Font and Subfont structures contain two
Page 2 Plan 9 (printed 12/22/24)
GRAPHICS(2) GRAPHICS(2)
interrelated fields: `ascent', the distance from the top of
the highest character (actually the top of the bitmap hold-
ing all the characters) to the baseline, and `height', the
distance from the top of the highest character to the bottom
of the lowest character (and hence, the interline spacing).
The width of any particular character `r' in a font is
returned by charwidth. The width is defined as the amount to
add to the horizontal position after drawing the character.
Charwidth calls the graphics error function if r is zero
(NUL) because string (see bitblt(2)) cannot draw a NUL. The
other fields are used internally by the text-drawing func-
tions; see cachechars(2) for the details.
Rdfontfile reads the font description in file name and
returns a pointer that can by used by string (see bitblt(2))
to draw characters from the font. The ldepth argument spec-
ifies how characters will be cached; it should usually be
the ldepth of the bitmap that will most often be the target
of string. Ffree frees a font. The convention for naming
font files is:
/lib/font/bit/name/range.size.font
where size is approximately the height in pixels of the
lower case letters (without ascenders or descenders). Range
gives some indication of which characters will be available:
for example ascii, latin1, euro, or unicode. Euro includes
most European languages, punctuation marks, the Interna-
tional Phonetic Alphabet, etc., but no Oriental languages.
Unicode includes every character for which images exist on
the system.
A Cursor is defined:
typedef struct
Cursor {
Point offset;
uchar clr[2*16];
uchar set[2*16];
} Cursor;
The arrays are arranged in rows, two bytes per row, left to
right in big-endian order to give 16 rows of 16 bits each.
A cursor is displayed on the screen by adding offset to the
current mouse position, using clr as a mask to zero the pix-
els where clr is 1, and then setting pixels to ones where
set is one.
The function binit must be called before using any graphics
operations. The errfun argument is a function to be called
with an error message argument when the graphics functions
detect a fatal error; such an error function must not
Page 3 Plan 9 (printed 12/22/24)
GRAPHICS(2) GRAPHICS(2)
return. A zero for the errfun specifies the default berror,
which prints the message and exits. If label is non-null,
it will be written to /dev/label, so that it can be used to
identify the window when hidden (see 8½(1)). Binit sets up
the global screen to be a bitmap describing the area of the
screen that the program can use. This will be either the
whole screen, or some portion of it if the program is run-
ning under a window system such as 8½(1). Binit also estab-
lishes a font by reading the named font file. If font is
null, binit reads the file named in the environment variable
$font; if $font is not set, it imports the default (usually
minimal) font from the operating system. The global font
will be set to point to the resulting Font structure.
Another effect of binit is that it installs print(2) formats
Pconv and Rconv as `%P' and `%R' for printing Points and
Rectangles.
Bclose closes the file descriptor connecting the application
to the graphics server, typically for use by a child process
that needs to disconnect from the graphics server. It does
not automatically flush pending output (see bflush, below).
Bclose is not needed by most programs. Bexit completes any
pending graphics. It is called automatically by exits(2).
The screen.r field is not maintained across `reshape'
events; use bscreenrect to discover the current size (see
event(2)); a non-null clipr will be filled in with the
screen's clip rectangle.
The mouse cursor is always displayed. The initial cursor is
an arrow. Cursorswitch causes the argument cursor to be
displayed instead. A zero argument causes a switch back to
the arrow cursor. Cursorset moves the mouse cursor to posi-
tion p, provided (if in a window) that the requesting pro-
gram is executing in the current window and the mouse is
within the window boundaries; otherwise cursorset is a no-
op.
The graphics functions described in bitblt(2), balloc(2),
cachechars(2), and subfalloc(2) are implemented by writing
commands to /dev/bitblt (see bit(3)); the writes are buf-
fered, so the functions may not take effect immediately.
Bflush flushes the buffer, doing all pending graphics opera-
tions. Binit arranges that bflush will be called on exit,
and the following functions all cause a flush: balloc,
bfree, bscreenrect, cursorset, cursorswitch, ecankbd,
ecanmouse, ekbd, emouse, event, rdfontfile, subfalloc,
ffree, rdbitmap, and wrbitmap.
The rare program that needs to implement the /dev/bitblt
protocol directly can use bneed and bwrite. Bneed returns a
pointer to a place in the write buffer, allocating space for
Page 4 Plan 9 (printed 12/22/24)
GRAPHICS(2) GRAPHICS(2)
n bytes. The buffer will be flushed first if n is zero, or
the buffer is too full. After filling in bytes allocated
with bneed, bwrite can be used to write everything in the
buffer and reset the buffer pointer. Unlike bflush, bwrite
does not call the registered error function and so can be
used when an error is possible and the error function is
inappropriate.
FILES
/lib/font/bit directory of bitmap fonts
SOURCE
/sys/src/libg
SEE ALSO
add(2), balloc(2), cachechars(2), subfalloc(2), bitblt(2),
event(2), frame(2), print(2), bit(3), layer(2), bitmap(6),
font(6)
DIAGNOSTICS
An error function may call errstr(2) for further diagnos-
tics.
Page 5 Plan 9 (printed 12/22/24)