graphics

GRAPHICS(3G)                                                        GRAPHICS(3G)



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.

SEE ALSO
       add(3g), balloc(3g), cachechars(3g), bitblt(3g), event(3g), frame(3g),
       rgbpix(3g), bitmap(5g), font(5g).

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



                                                                    GRAPHICS(3G)