graphics(3g) · carta

NAME

Point, Rectangle, Bitmap, Cursor, xtbinit, bclose, berror, bscreenrect, bflush, clipr, cursorswitch, cursorset, rdfontfile, ffree, charwidth, getsubfont, mkfont, scrollfwdbut - graphics

SYNOPSIS

#include <libc.h> #include <libg.h>

void xtbinit(void (*errfun)(char *), char *class, int *pargc, char **argv, char **fallbacks)

void bclose(void)

void berror(char *msg)

Rectangle bscreenrect(Rectangle *clipr)

void bflush(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)

Subfont *getsubfont(char *name)

Font *mkfont(Subfont *subfont);

int scrollfwdbut(void);

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 represented rectangle, so abutting rectangles have no points in common. Thus, max contains the coordinates of the first point beyond the rectangle.

A Bitmap holds a rectangular image.

typedef
struct Bitmap {
	Rectangle	r;	/* rectangle in data area, local coords */
	Rectangle	clipr;	/* clipping region */
	int	ldepth;	/* log base 2 of number of bits per pixel */
	int	id;	/* id as known in the X server */
	Bitmap*	cache;	/* zero; distinguishes bitmap from layer */
	int	flag;	/* flag used by X implementation of libg */
} 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 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(5g)). The images are organized into Subfonts, each containing the images for a small, contiguous set of runes. Font and Subfont structures contain two related 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 function if r is zero (NUL) because string (see bitblt(3g)) cannot draw a NUL. The other fields are used internally by the text-drawing functions. See cachechars(3g) for a detailed description.

Rdfontfile reads the font description in file name and returns a pointer that can by used by string (see bitblt(3g)) 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. [ ldepth is unused in the X implementation of libg.] Ffree frees a font. The convention for naming font files is:

: fontdir/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 font is selected by notifying the X server of the location of the subfonts and then specifying the desired font file. The directory containing the subfonts must be added to the server's font search path using the xset command. For example,

xset +fp /usr/local/p9snf

adds the directory /usr/local/p9snf to the font search path. The p9font resource contains the full path name of the desired font file; it is usually specified in the .Xdefaults or .xrdb startup file. For example, the entry:

*p9font: /n/pyxis/usr/local/p9fonts/pelm.unicode.9.font

selects the 9-point Pellucida Modern unicode font.

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 pixels where clr is 1, and then setting pixels to ones where set is one.

The function xtbinit should be called before using any graphics operations. The errfun argument is a function that will be called with an error message argument when the graphics functions detect an error; such an error function should not return. A zero for the errfun argument means use berror, which prints the message and exits. The class argument is the name of the class of X application, or zero to use the capitalized version of the program name. The pargc and argv arguments should be a pointer to the main program's argc and argv; any standard toolkit options in the argument list will be used to initialize the window's options, and after xtbinit returns, those options will have been removed from the argument list. The fallbacks argument, when non-null, specifies a list of fallback resources for the application. Xtbinit sets up the global screen to be a bitmap describing the area of the screen that the program can use. Xtbinit also initializes the global default font. By default, xtbinit does not install the standard Plan 9 colourmap, see rgbpix(3g).

Bclose releases the resources allocated by xtbinit and the other graphics functions. It usually isn't necessary, since the resources will be released on program exit. [ Bclose is currently unimplemented.]

The screen.r field is not guaranteed to be always accurate; the bscreenrect function returns the current size (see event(3g) to see how to get reshape notification).

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(3g) and balloc(3g) are implemented by writing commands to the X server; the writes are buffered, so the functions may not take effect immediately. Bflush flushes the buffer, doing all pending graphics operations. Xtbinit arranges that bflush will be called on exit, and the following graphics functions all cause a flush: balloc, bfree, bscreenrect, cursorset, cursorswitch, ecankbd, ecanmouse, ekbd, emouse, event, rdbitmap, and wrbitmap.

Getsubfont attempts to load the font given by name; it returns a pointer to a Subfont struct if it succeeds, zero otherwise, see font(5g). The subfont returned by getsubfont may be passed to mkfont to generate a Font suitable for use in string.

Scrollfwdbut returns 3 or 1 depending on which buttons is to be used as the forward scrolling button on the mouse. The default is to return 3.

X DEFAULTS

LibXg understands all of the core X Toolkit resource names and classes as well as:

p9font (class P9font): Specifies the path name of a font file. If the file does not exist or is not a properly formatted font file, the default X11 font directory is searched for an X11 font of the same name.

composeMod (class ComposeMod): Specifies the modifier key to be used in composing characters. The integers 1 to 5 correspond to using modifier keys 1 to 5. When this resource is non-zero it is only necessary to press the compose modifier once before beginning a compose sequence, i.e., it need not be held down for any of the characters in the sequence. A zero for composeMod means use modifier key 1 and this key must be held down in conjuction with the first key of the sequence.

scrollForwardR (class ScrollForwardR): The value true for this resource reverses the value returned by scrollfwdbut, i.e., it returns 3 instead of 1. This reverses the scroll direction selected by clicks of the left or right mouse buttons in the scrollbar.

DIAGNOSTICS

An error function may call errstr(3g) for further diagnostics.

NAME

SYNOPSIS

DESCRIPTION

X DEFAULTS

SEE ALSO

DIAGNOSTICS