term% ls -F
term% cat index.txt
GRAPHICS(2)                   System Calls Manual                  GRAPHICS(2)

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

       #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

       A  Point is a location in a bitmap (see below), such as the screen, and
       is defined as:

              struct Point {
                    int x;
                    int y;
              } Point;

       The coordinate system has x increasing to the right  and  y  increasing

       A Rectangle is a rectangular area in a bitmap.

              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  repre‐
       sented  rectangle,  so  abutting  rectangles  have no points in common.
       Thus, max contains the coordinates of the first point beyond  the  rec‐

       A Bitmap holds a rectangular image.

              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 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 Bit‐
       map 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 containing 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  immate‐
       rial  for  most  applications.  Font and Subfont structures contain two
       interrelated 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  func‐
       tion  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 specifies 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:


       where size is approximately the height in pixels of the lower case let‐
       ters (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.  Uni‐
       code 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  dis‐
       played  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 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 er‐
       ror function must not return.  A zero for the errfun specifies the  de‐
       fault  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 iden‐
       tify  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  pro‐
       gram can use.  This will be either the whole screen, or some portion of
       it if the program is running under a  window  system  such  as  8½(1).
       Binit  also establishes 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  re‐
       sulting  Font  structure.   Another effect of binit is that it installs
       print(2) formats Pconv and Rconv as and for printing Points and Rectan‐

       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  pro‐
       grams.   Bexit  completes any pending graphics.  It is called automati‐
       cally 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 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(2),   balloc(2),
       cachechars(2), and subfalloc(2) are implemented by writing commands  to
       /dev/bitblt (see bit(3)); the writes are buffered, so the functions may
       not take effect immediately.  Bflush  flushes  the  buffer,  doing  all
       pending graphics operations.  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  di‐
       rectly can use bneed and bwrite.  Bneed returns a pointer to a place in
       the write buffer, allocating space for 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.

       /lib/font/bit    directory of bitmap fonts


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

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