Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

graphics(2) [plan9 man page]

GRAPHICS(2)							System Calls Manual						       GRAPHICS(2)

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)
Man Page