GRAPHICS(2)                                           GRAPHICS(2)

     NAME
          Point, Rectangle, Bitmap, Cursor, binit, bclose, berror,
          bscreenrect, bneed, bflush, bwrite, bexit, clipr,
          cursorswitch, cursorset, rdfontfile, ffree, charwidth,
          Pconv, Rconv - bitmap graphics

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

          void      binit(void (*errfun)(char *), char *font, char *label)

          void      bclose(void)

          void      bexit(void)

          void      berror(char *msg)

          Rectangle bscreenrect(Rectangle *clipr)

          uchar*    bneed(int n)

          void      bflush(void)

          int       bwrite(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)

          int       Pconv(void *arg, Fconv*)

          int       Rconv(void *arg, Fconv*)

          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:

     GRAPHICS(2)                                           GRAPHICS(2)

               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 rectan-
          gles have no points in common.  Thus, max contains the coor-
          dinates of the first point beyond the rectangle.

          A Bitmap holds a rectangular image.

               typedef
               struct Bitmap {
                     Rectangle r;       /* rect. in data area, local coords */
                     Rectangle clipr;   /* clipping region */
                     int       ldepth;  /* log base 2 of #bits per pixel */
                     int       id;      /* id as known in /dev/bitblt */
                     Bitmap*   cache;   /* zero; tells bitmap from layer */
               } 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 giv-
          ing 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(6)). The images are organized into Subfonts, each con-
          taining the images for a small, contiguous set of runes.
          The detailed format of these data structures, which are
          described in detail in cachechars(2), is immaterial for most
          applications.  Font and Subfont structures contain two

     GRAPHICS(2)                                           GRAPHICS(2)

          interrelated fields: `ascent', the distance from the top of
          the highest character (actually the top of the bitmap hold-
          ing 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(2)) cannot draw a NUL.  The
          other fields are used internally by the text-drawing func-
          tions; see cachechars(2) for the details.

          Rdfontfile reads the font description in file name and
          returns a pointer that can by used by string (see bitblt(2))
          to draw characters from the font.  The ldepth argument spec-
          ifies how characters will be cached; it should usually be
          the ldepth of the bitmap that will most often be the target
          of string. Ffree frees a font.  The convention for naming
          font files is:

               /lib/font/bit/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 Interna-
          tional Phonetic Alphabet, etc., but no Oriental languages.
          Unicode includes every character for which images exist on
          the system.

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

          The function binit must be called before using any graphics
          operations.  The errfun argument is a function to be called
          with an error message argument when the graphics functions
          detect a fatal error; such an error function must not

     GRAPHICS(2)                                           GRAPHICS(2)

          return.  A zero for the errfun specifies the default berror,
          which prints the message and exits.  If label is non-null,
          it will be written to /dev/label, so that it can be used to
          identify the window when hidden (see 8½(1)). Binit sets up
          the global screen to be a bitmap describing the area of the
          screen that the program can use.  This will be either the
          whole screen, or some portion of it if the program is run-
          ning under a window system such as 8½(1). Binit also estab-
          lishes a font by reading the named font file.  If font is
          null, binit reads the file named in the environment variable
          $font; if $font is not set, it imports the default (usually
          minimal) font from the operating system.  The global font
          will be set to point to the resulting Font structure.
          Another effect of binit is that it installs print(2) formats
          Pconv and Rconv as `%P' and `%R' for printing Points and
          Rectangles.

          Bclose closes the file descriptor connecting the application
          to the graphics server, typically for use by a child process
          that needs to disconnect from the graphics server.  It does
          not automatically flush pending output (see bflush, below).
          Bclose is not needed by most programs.  Bexit completes any
          pending graphics.  It is called automatically by exits(2).

          The screen.r field is not maintained across `reshape'
          events; use bscreenrect to discover the current size (see
          event(2)); a non-null clipr will be filled in with the
          screen's clip rectangle.

          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 posi-
          tion p, provided (if in a window) that the requesting pro-
          gram 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(2), balloc(2),
          cachechars(2), and subfalloc(2) are implemented by writing
          commands to /dev/bitblt (see bit(3)); the writes are buf-
          fered, so the functions may not take effect immediately.
          Bflush flushes the buffer, doing all pending graphics opera-
          tions.  Binit arranges that bflush will be called on exit,
          and the following functions all cause a flush: balloc,
          bfree, bscreenrect, cursorset, cursorswitch, ecankbd,
          ecanmouse, ekbd, emouse, event, rdfontfile, subfalloc,
          ffree, rdbitmap, and wrbitmap.

          The rare program that needs to implement the /dev/bitblt
          protocol directly can use bneed and bwrite. Bneed returns a
          pointer to a place in the write buffer, allocating space for

     GRAPHICS(2)                                           GRAPHICS(2)

          n bytes.  The buffer will be flushed first if n is zero, or
          the buffer is too full.  After filling in bytes allocated
          with bneed, bwrite can be used to write everything in the
          buffer and reset the buffer pointer.  Unlike bflush, bwrite
          does not call the registered error function and so can be
          used when an error is possible and the error function is
          inappropriate.

     FILES
          /lib/font/bit    directory of bitmap fonts

     SOURCE
          /sys/src/libg

     SEE ALSO
          add(2), balloc(2), cachechars(2), subfalloc(2), bitblt(2),
          event(2), frame(2), print(2), bit(3), layer(2), bitmap(6),
          font(6)

     DIAGNOSTICS
          An error function may call errstr(2) for further diagnos-
          tics.