CACHECHARS(3G)                                                  CACHECHARS(3G)

       cachechars, Subfont, Cachesubf, Fontchar, Font  - font utilities

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

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

       A Font may contain too many characters to hold in memory
       simultaneously.  The graphics library and X server 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 programs:
       xtbinit and its associated *p9font X resource, rdfontfile, charwidth,
       string, and ffree are sufficient for most purposes.  The routines
       described below are used internally by the graphics library to maintain
       the font cache.

       A Subfont may be considered to be 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   cwidth;   /* width of glyph */
                    uchar    top;      /* first non-zero scan-line */
                    uchar    bottom;   /* last non-zero scan-line */
                    char     left;     /* offset of baseline */
                    uchar    width;    /* advance to next char's origin */
              } Fontchar;

              struct Subfont {
                    short    minrow;   /* first character row in font (for X subfonts) */
                    short    mincol;   /* first character col in font (for X subfonts) */
                    short    minchar;  /* first char code in font (for X subfonts) */
                    short    maxchar;  /* last char code in font (for X subfonts) */
                    short    width;    /* number of chars in row (for X subfonts) */
                    short    n;        /* number of chars in subfont */
                    unsigned char height;/* height of bitmap */
                    char     ascent;   /* top of bitmap to baseline */
                    Fontchar *info;    /* n+1 character descriptors */
                    int      id;       /* of font */
              } Subfont;

       The actual bitmap for each character is stored on the server but the
       metrics associated with character c are cached locally in
       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+(i+1)->left,
       p.y).  The baseline of the characters is ascent rows down from the top
       of the subfont bitmap.  Each Fontchar has two widths associated with
       it: width is the width of the rectangular bitmap to contain the
       character; cwidth is the true width of the character, that is, the
       number of pixels between the leftmost and rightmost pixels of the
       character glyph.

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

              struct Cachesubf {
                    Rune      min;      /* rune value of 0th char in subfont */
                    Rune      max;      /* rune value+1 of last char in subfont */
                    char      *name;
                    Subfont   *f;       /* attached subfont */
              } Cachefont;

              struct Font {
                    char      *name;
                    uchar     height;   /* max height of bitmap, interline spacing */
                    char      ascent;   /* top of bitmap to baseline */
                    char      width;    /* widest so far; used in caching only */
                    char      ldepth;   /* of images */
                    short     id;       /* of font */
                    short     nsubf;    /* number of subfonts */
                    Cachesubf *subf;    /* as read from file */
              } Font;

       The height, ascent, and ldepth fields of Font are described in
       graphics(3).  Subf contains nsubf pointers to Cachesubfs.  A Cachesubf
       connects runes min through max, inclusive, to the subfont name; it
       corresponds to a line of the file describing the font.

       The image for rune r is found in position r−min+minchar of the subfont.

       For each font, the library, with support from the graphics server,
       maintains a list of subfonts.  The width of a font is the maximum of
       the horizontal extents of the characters in the cache.  [ width is
       unused in the X implementation of libg.]  String draws a string by
       calling cachechars and emitting a sequence of X font indices to draw.
       Cachechars calculates the subfont/index pairs for the characters
       pointed to by *s.  It calls getsubfont to fetch subfonts which are not
       yet in the subfont list of f.  Cachechars translates the character
       string into a set of subfont/index pairs.  It loads the character
       indices into the array c, up to a maximum of n indices or the length of
       the string.  It also loads the corresponding element of fp with the
       subfont index for each character.  Cachechars returns in c the number
       of subfont indices emitted, updates *s to point to the next character
       to be processed, and sets *widp to the total width of the characters
       processed.  Cachechars may return before the end of the string if it
       cannot proceed.  It can return zero if it is unable to make progress
       because a character code does not covered by any subfont range.

       graphics(3), balloc(3), bitblt(3), font(4).

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