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

       cachechars,  agefont,  loadchar, Subfont, Fontchar, Font  - font utili‐

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

       int  cachechars(Font *f, char **s, ushort *c, int n, int *widp)

       int  loadchar(Font *f, Rune r, Cacheinfo *c, int h, int noclr)

       void agefont(Font *f)

       A Font may contain too many characters to  hold  in  memory  simultane‐
       ously.   The  graphics library and bitblt device (see bit(3)) cooperate
       to solve this problem by maintaining a cache of recently used character
       images.  The details of this cooperation need not be known by most pro‐
       grams: binit and its associated font variable,  rdfontfile,  charwidth,
       string,  and  ffree are sufficient for most purposes.  The routines de‐
       scribed below are used internally by the graphics library  to  maintain
       the font cache.

       A  Subfont  is  a  set  of images for a contiguous range of characters,
       stored as a single bitmap with the characters placed side-by-side on  a
       common baseline.  It is described by the following data structures.

              struct Fontchar {
                    ushort   x;        /* left edge of bits */
                    uchar    top;      /* first non-zero scan-line */
                    uchar    bottom;   /* last non-zero scan-line */
                    char     left;     /* offset of baseline */
                    uchar    width;    /* width of baseline */
              } Fontchar;

              struct Subfont {
                    short    n;        /* number of chars in subfont */
                    uchar    height;   /* height of bitmap */
                    char     ascent;   /* top of bitmap to baseline */
                    Fontchar *info;    /* n+1 Fontchars */
                    int      id;       /* id as known in /dev/bitblt */
              } Subfont;

       The bitmap fills the rectangle (0, 0, w, height), where w is the sum of
       the horizontal extents (of non-zero pixels) for  all  characters.   The
       pixels  to  be  displayed  for  character c are in the rectangle (i->x,
       i->top, (i+1)->x, i->bottom) where  i  is  &subfont->info[c].   When  a
       character  is displayed at Point p in a bitmap, the character rectangle
       is placed at (p.x+i->left, p.y) and the next character of the string is
       displayed  at  (p.x+i->width,  p.y).  The baseline of the characters is
       rows down from the top of the subfont bitmap.  The array has  n+1  ele‐
       ments, one each for characters 0 to n-1 plus an additional entry so the
       size of the last character can be calculated.  Thus the  width,  w,  of
       the Bitmap associated with a Subfont s is s->info[s->n].x.

       A  Font  consists  of  an overall height and ascent and a collection of
       subfonts together with the ranges of runes (see utf(6)) they represent.
       Fonts are described by the following structures.

              struct Cachefont {
                    Rune      min;      /* value of 0th char in subfont */
                    Rune      max;      /* value+1 of last char in subfont */
                    int       offset;   /* posn in subfont of char at min */
                    int       abs;      /* name has been made absolute */
                    char      *name;
              } Cachefont;

              struct Cacheinfo {
                    Rune      value;    /* of char at this slot in cache */
                    ushort    age;
                    ulong     xright;   /* right edge of bits */
              } Cacheinfo;

              struct Cachesubf {
                    ulong     age;      /* for replacement */
                    Cachefont *cf;      /* font info that owns us */
                    Subfont   *f;       /* attached subfont */
              } Cachesubf;

              struct Font {
                    char      *name;
                    uchar     height;   /* max ht of bitmap;interline space*/
                    char      ascent;   /* top of bitmap to baseline */
                    char      width;    /* widest so far; used in caching */
                    char      ldepth;   /* of images */
                    short     id;       /* of font */
                    short     nsub;     /* number of subfonts */
                    ulong     age;      /* increasing counter; for LRU */
                    int       ncache;   /* size of cache */
                    int       nsubf;    /* size of subfont list */
                    Cacheinfo *cache;
                    Cachesubf *subf;
                    Cachefont **sub;    /* as read from file */
              } Font;

       The  and  fields  of Font are described in graphics(2).  is that of the
       cache, set by the argument to rdfontfile.  contains pointers to  Cache‐
       fonts.   A  Cachefont  connects runes through inclusive, to the subfont
       with file name it corresponds to a line  of  the  file  describing  the

       The  characters are taken from the subfont starting at character number
       (usually zero) in the subfont, permitting selection of  parts  of  sub‐
       fonts.   Thus the image for rune r is found in position r-min+offset of
       the subfont.

       For each font, the library, with  support  from  the  graphics  server,
       maintains  a  cache  of subfonts and a cache of recently used character
       images.  The subf and cache fields are used by the library to  maintain
       these  caches.   The of a font is the maximum of the horizontal extents
       of the characters in the cache.  String draws a string by  loading  the
       cache  and  emitting  a  sequence of cache indices to draw.  Cachechars
       guarantees the images for the characters pointed to by *s  are  in  the
       cache  of  f.   It  calls  loadchar  to put missing characters into the
       cache.  Cachechars translates the character string into a set of  cache
       indices  which  it loads into the array c, up to a maximum of n indices
       or the length of the string.  Cachechars returns in  c  the  number  of
       cache  indices emitted, updates *s to point to the next character to be
       processed, and sets *widp to the total width  of  the  characters  pro‐
       cessed.   Cachechars may return before the end of the string if it can‐
       not proceed without destroying active data in the caches.  It  can  re‐
       turn  zero if it is unable to make progress because it is unable to re‐
       size the caches.

       Loadchar loads a character image into the character cache.   First,  if
       necessary,  it  loads  the  subfont  containing the character.  Then it
       tells the graphics server to copy the character into position h in  the
       character  cache.   If  the current font is smaller than the horizontal
       extent of the character being loaded, loadfont clears the cache and re‐
       sets  it  to  accept  characters with the bigger width, unless noclr is
       set, in which case it just returns -1.  If the character does not exist
       in  the  font  at  all, loadfont returns 0; if it is unable to load the
       character without destroying cached information, it returns -1.  It re‐
       turns 1 to indicate success.

       The  fields  record  when  subfonts and characters have been used.  The
       font is increased every time the font is used (agefont does  this).   A
       character  or subfont is set to the font age.  Thus, characters or sub‐
       fonts with small ages are the best candidates for replacement when  the
       cache is full.


       graphics(2), balloc(2), bitblt(2), subfalloc(2), bitmap(6), font(6)

       All of the functions use the graphics error function (see graphics(2)).