GRAPHICS(2) System Calls Manual GRAPHICS(2)
NAME
Point, Rectangle, Bitmap, Cursor, binit, bclose, berror, bscreenrect, bneed, bflush, bwrite, bexit, clipr, cursorswitch, cursorset, rdfont-
file, 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:
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 rep-
resented rectangle, so abutting rectangles have no points in common. Thus, max contains the coordinates of the first point beyond the rec-
tangle.
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 giving the pixel value. 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 subrou-
tine 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 containing 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 immate-
rial for most applications. Font and Subfont structures contain two interrelated fields: the distance from the top of the highest charac-
ter (actually the top of the bitmap holding all the characters) to the baseline, and 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 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-draw-
ing functions; 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 specifies 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 International 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 dis-
played on the screen by adding offset to the current mouse position, using clr as a mask to zero the pixels where clr is 1, and then set-
ting 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 mes-
sage argument when the graphics functions detect a fatal error; such an error function must not 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 81/2(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 running under a window system such as
81/2(1). Binit also establishes 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 and 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 position p, provided (if in a window) that the
requesting program 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/bit-
blt (see bit(3)); the writes are buffered, so the functions may not take effect immediately. Bflush flushes the buffer, doing all pending
graphics operations. 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 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 diagnostics.
GRAPHICS(2)