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.  Clipr 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(4)).
       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: ascent, the distance from the top of the highest
       character (actually the top of the bitmap holding all the characters)
       to the baseline, and 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 r 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(3)) cannot draw a NUL.  The other fields are used internally by
       the text-drawing functions.  See cachechars(3) for a detailed
       description.

       Rdfontfile reads the font description in file name and returns a
       pointer that can by used by string (see bitblt(3)) 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(3).

       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(3) 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(3) and balloc(3) 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(4).  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(3), balloc(3), cachechars(3), bitblt(3), event(3), frame(3),
       rgbpix(3), bitmap(4), font(4).

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



                                                                  GRAPHICS(3G)