.de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH GRAPHICS 3G
.SH NAME
Point, Rectangle, Bitmap, Cursor, xtbinit, bclose, berror, bscreenrect, bflush, clipr, cursorswitch, cursorset, rdfontfile, ffree, charwidth, getsubfont, mkfont, scrollfwdbut \- graphics
.SH SYNOPSIS
.nf
.PP
.B
#include <libc.h>
.B
#include <libg.h>
.PP
.ta \w'\fLRectangle 'u
.B
void	xtbinit(void (*errfun)(char *), char *class, int *pargc,
.B
char **argv, char **fallbacks)
.PP
.B
void	bclose(void)
.PP
.B
void	berror(char *msg)
.PP
.B
Rectangle	bscreenrect(Rectangle *clipr)
.PP
.B
void	bflush(void)
.PP
.B
int	clipr(Bitmap *b, Rectangle cr)
.PP
.B
void	cursorswitch(Cursor *curs)
.PP
.B
void	cursorset(Point p)
.PP
.B
Font*	rdfontfile(char *name, int ldepth)
.PP
.B
void	ffree(Font *f)
.PP
.B
int	charwidth(Font *f, Rune r)
.PP
.B
Subfont	*getsubfont(char *name)
.PP
.B
Font	*mkfont(Subfont *subfont);
.PP
.B
int	scrollfwdbut(void);
.PP
.B
extern Bitmap    screen
.PP
.B
extern Font      *font
.fi
.SH DESCRIPTION
A
.B Point
is a location in a bitmap
(see below),
such as the screen, and is defined as:
.IP
.EX
.ta 6n
typedef
struct Point {
	int x;
	int y;
} Point;
.EE
.PP
The coordinate system has
.I x
increasing to the right and
.I y
increasing down.
.PP
A
.B Rectangle
is a rectangular area in a bitmap.
.IP
.EX
.ta 6n
typedef
struct Rectangle {
	Point min;      /* upper left */
	Point max;      /* lower right */
} Rectangle;
.EE
.PP
By definition,
.B min.x <= max.x
and
.BR "min.y <= max.y" .
By convention, the right (maximum
.IR x )
and bottom (maximum
.IR y )
edges are
excluded from the represented rectangle, so abutting rectangles have no
points in common.
Thus,
.B max
contains the coordinates of the first point beyond the rectangle.
.PP
A 
.B Bitmap
holds a rectangular image.
.IP
.EX
.ta 6n +\w'Rectangle 'u +\w'ldepth;  'u
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;
.EE
.PP
.B R.min
is the location in the bitmap
of the upper-leftmost point in the image.
There are
.if t .I 2\u\s8ldepth\s10\d
.if n 2^ldepth
contiguous bits for each pixel of the image;
the bits form a binary number giving the pixel value.
.L Clipr
is the clipping rectangle; typically it is the same as
.B r
except in a window, where it is inset by the width of
the border.
Graphical operations on the
.B Bitmap
will be confined to the clipping rectangle.
The subroutine
.I Clipr
sets the clipping rectangle of
.B b
to the intersection of
.B cr
and
.BR b->r .
If
.I cr
does not intersect
.BR b->r
it does nothing.
.I Clipr
returns 1 if the clipping region was set,
0 if it was not.
.PP
A
.B Font
is a set of character images, indexed by runes (see
.IR utf (4)).
The images are organized into
.BR Subfont s,
each containing the images for a small, contiguous set of runes.
.B Font
and
.B Subfont
structures contain two related fields:
.LR ascent ,
the distance from the top of the highest character
(actually the top of the bitmap holding all the characters)
to the baseline,
and
.LR height ,
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
.L r
in a font is returned by
.IR charwidth.
The width is defined as the amount to add to the horizontal position
after drawing the character.
.I Charwidth
calls the graphics error function if
.B r
is zero (NUL) because
.B string
(see
.IR bitblt (3))
cannot draw a NUL.
The other fields are used internally by the text-drawing functions.
See
.IR cachechars (3)
for a detailed description.
.PP
.I Rdfontfile
reads the font description in file
.I name
and returns a pointer that can by used by
.I string
(see
.IR bitblt (3))
to draw characters from the font.
The
.I 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
.IR string .
[
.I ldepth
is unused in the X implementation of libg.]
.I Ffree
frees a font.
The convention for naming font files is:
.IP
.B \fIfontdir\fP/\fIname\fP.\fIrange\fP.\fIsize\fP.font
.PD
.PP
where
.I size
is approximately the height in pixels of the lower case letters
(without ascenders or descenders).
.I Range
gives some indication of which characters will be available: for example
.BR ascii ,
.BR latin1 ,
.BR euro ,
or
.BR unicode .
.B Euro
includes most European languages, punctuation marks, the International Phonetic
Alphabet, etc., but no Oriental languages.
.B Unicode
includes every character for which images exist on the system.
.PP
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
.B xset
command.  For example,
.PP
.EX
xset +fp /usr/local/p9snf
.EE
.PP
adds the directory
.B /usr/local/p9snf
to the font search path.
The
.B p9font
resource contains the full path name
of the desired font file; it is usually specified in the
.B .Xdefaults
or
.B .xrdb
startup file.  For example,
the entry:
.PP
.EX
*p9font: /n/pyxis/usr/local/p9fonts/pelm.unicode.9.font
.EE
.PP
selects the 9-point Pellucida Modern unicode font.
.PP
A
.I Cursor
is defined:
.IP
.EX
.ta 6n +\w'Point 'u
typedef struct
Cursor {
	Point	offset;
	uchar	clr[2*16];
	uchar	set[2*16];
} Cursor;
.EE
.PP
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
.B offset
to the current mouse position, using
.B clr
as a mask to zero the pixels where
.B clr
is 1, and then setting pixels to ones where
.B set
is one.
.PP
The function
.I xtbinit
should be called before using any graphics operations.
The
.I 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
.I errfun
argument means use
.IR berror ,
which prints the message and exits.
The
.I class
argument is the name of the class of X application, or zero to
use the capitalized version of the program name.
The
.I pargc
and
.I argv
arguments should be a pointer to the main program's
.I argc
and
.IR argv ;
any standard toolkit options in the argument list will be used
to initialize the window's options, and after
.I xtbinit
returns, those options will have been removed from the argument list.
The
.I fallbacks
argument, when non-null, specifies a list of fallback resources
for the application.
.B Xtbinit
sets up the global
.I screen
to be a bitmap describing the area of the screen that the program
can use.
.I Xtbinit
also initializes the global default
.IR font .
By default,
.I xtbinit
does not install the standard Plan 9 colourmap, see
.IR rgbpix (3).
.PP
.I Bclose
releases the resources allocated by
.I xtbinit
and the other graphics functions.
It usually isn't necessary, since the resources will be released
on program exit.  [
.I Bclose
is currently unimplemented.]
.PP
The
.IB screen .r
field is not guaranteed to be always accurate; the
.I bscreenrect
function returns the current size
(see
.IR event (3)
to see how to get reshape notification).
.PP
The mouse cursor is always displayed.
The initial cursor is an arrow.
.I Cursorswitch
causes the argument cursor to be displayed instead.
A zero argument causes a switch back to the arrow cursor.
.I Cursorset
moves the mouse cursor to position
.I 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
.I cursorset
is a no-op.
.PP
The graphics functions described in
.IR bitblt (3)
and
.IR balloc (3)
are implemented by writing commands to the X server;
the writes are buffered, so the functions may not take effect immediately.
.I Bflush
flushes the buffer, doing all pending graphics operations.
.I Xtbinit
arranges that
.I bflush
will be called on exit,
and the following graphics functions all cause a flush:
.IR balloc ,
.IR bfree ,
.IR bscreenrect ,
.IR cursorset ,
.IR cursorswitch ,
.IR ecankbd ,
.IR ecanmouse ,
.IR ekbd ,
.IR emouse ,
.IR event ,
.IR rdbitmap ,
and
.IR wrbitmap .
.PP
.I Getsubfont
attempts to load the font given by
.IR name ;
it returns a pointer to a
.B Subfont
struct if it succeeds, zero otherwise,
see
.IR font (4).
The subfont returned by
.I getsubfont
may be passed to
.I mkfont
to generate a
.B Font
suitable for use in
.IR string .
.PP
.I 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.
.SH "X DEFAULTS"
LibXg understands all of the core X Toolkit resource names and
classes as well as:
.TP 8
.B "p9font (\fPclass\fB 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.
.TP 8
.B "composeMod (\fPclass\fB 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
.B composeMod
means use modifier key 1 and this key must be held down in conjuction
with the first key of the sequence.
.TP 8
.B "scrollForwardR (\fPclass\fB ScrollForwardR)"
The value
.I true
for this resource
reverses the value returned by
.IR 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.
.SH "SEE ALSO"
.IR add (3),
.IR balloc (3),
.IR cachechars (3),
.IR bitblt (3),
.IR event (3),
.IR frame (3),
.IR rgbpix (3),
.IR bitmap (4),
.IR font (4).
.SH DIAGNOSTICS
An error function may call
.IR errstr (2)
for further diagnostics.