term% cat index.txt 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 repre‐
sented 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 Bit‐
map 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 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 character
(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 func‐
tion 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 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 let‐
ters (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. Uni‐
code 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 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 er‐
ror function must not return. A zero for the errfun specifies the de‐
fault 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 iden‐
tify 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 pro‐
gram 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 8½(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 re‐
sulting Font structure. Another effect of binit is that it installs
print(2) formats Pconv and Rconv as and for printing Points and Rectan‐
gles.
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 pro‐
grams. Bexit completes any pending graphics. It is called automati‐
cally 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/bitblt (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 di‐
rectly 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)