--- name: "graphics" section: "3g" platform: "linux" package: "libxg-dev" version: "4.3-14" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/graphics" --- # graphics(3g) graphics ## NAME Point, Rectangle, Bitmap, Cursor, xtbinit, bclose, berror, bscreenrect, bflush, clipr, cursorswitch, cursorset, rdfontfile, ffree, charwidth, getsubfont, mkfont, scrollfwdbut - graphics ## SYNOPSIS ``` ``` **#include \** **#include \** **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)](/utf/5g.md)). The images are organized into **Subfont**s, 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)](/bitblt/3g.md)) cannot draw a NUL. The other fields are used internally by the text-drawing functions. See [*cachechars*(3g)](/cachechars/3g.md) 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)](/bitblt/3g.md)) 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)](/rgbpix/3g.md). *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)](/event/3g.md) 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)](/bitblt/3g.md) and [*balloc*(3g)](/balloc/3g.md) 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)](/font/5g.md). 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. ## SEE ALSO [*add*(3g)](/add/3g.md), [*balloc*(3g)](/balloc/3g.md), [*cachechars*(3g)](/cachechars/3g.md), [*bitblt*(3g)](/bitblt/3g.md), [*event*(3g)](/event/3g.md), [*frame*(3g)](/frame/3g.md), [*rgbpix*(3g)](/rgbpix/3g.md), *bitmap*(5g), [*font*(5g)](/font/5g.md). ## DIAGNOSTICS An error function may call *errstr*(3g) for further diagnostics.