SUBFONT(2)                                             SUBFONT(2)

     NAME
          allocsubfont, freesubfont, installsubfont, lookupsubfont,
          uninstallsubfont, subfontname, readsubfont, readsubfonti,
          writesubfont, stringsubfont, strsubfontwidth, mkfont -
          subfont manipulation

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

          Subfont* allocsubfont(char *name, int n, int height, int
          ascent,
                   Fontchar *info, Image *i)

          void     freesubfont(Subfont *f)

          void     installsubfont(char *name, Subfont *f)

          Subfont* lookupsubfont(Display *d, char *name)

          void     uninstallsubfont(Subfont *f)

          Subfont* readsubfont(Display *d, char *name, int fd, int
          dolock)

          Subfont* readsubfonti(Display *d, char *name, int fd, Image
          *im,
                     int dolock)

          int      writesubfont(int fd, Subfont *f)

          Point    stringsubfont(Image *dst, Point p, Image *src,
                   Subfont *f, char *str)

          Point    strsubfontwidth(Subfont *f, char *s)

          Font*    mkfont(Subfont *f, Rune min)

     DESCRIPTION
          Subfonts are the components of fonts that hold the character
          images.  A font comprises an array of subfonts; see
          cachechars(2). A new Subfont is allocated and initialized
          with allocsubfont. See cachechars(2) for the meaning of n,
          height, ascent, and info, and the arrangement of characters
          in image i. The name is used to identify the subfont in the
          subfont cache; see the descriptions lookupsubfont and
          installsubfont (q.v.).  The appropriate fields of the
          returned Subfont structure are set to the passed arguments,
          and the image is registered as a subfont with the graphics

     Page 1                       Plan 9            (printed 12/25/24)

     SUBFONT(2)                                             SUBFONT(2)

          device draw(3). Allocsubfont returns 0 on failure.

          Freesubfont frees a subfont and all its associated structure
          including the associated image.  Since freesbufont calls
          free on f->info, if f->info was not allocated by malloc(2)
          it should be zeroed before calling subffree.

          A number of subfonts are kept in external files.  The con-
          vention for naming subfont files is:

               /lib/font/bit/name/class.size.depth

          where size is approximately the height in pixels of the
          lower case letters (without ascenders or descenders).  If
          there is only one version of the subfont, the .depth exten-
          sion is elided.  Class describes the range of runes encoded
          in the subfont: ascii, latin1, greek, etc.

          Subfonts are cached within the program, so a subfont shared
          between fonts will be loaded only once.  Installsubfont
          stores subfont f under the given name, typically the file
          name from which it was read.  Uninstallsubfont removes the
          subfont from the cache.  Finally, lookupsubfont searches for
          a subfont with the given name in the cache and returns it,
          or nil if no such subfont exists.

          Subfontname is used to locate subfonts given their names
          within the fonts.  The default version constructs a name
          given the cfname, its name within the font, fname, the name
          of the font, and the maximum depth suitable for this sub-
          font.  This interface allows a partially specified name
          within a font to be resolved at run-time to the name of a
          file holding a suitable subfont.  Although it is principally
          a routine internal to the library, subfontname may be sub-
          stituted by the application to provide a less file-oriented
          subfont naming scheme.

          The format of a subfont file is described in font(6).
          Briefly, it contains a image with all the characters in it,
          followed by a subfont header, followed by character informa-
          tion.  Readsubfont reads a subfont from the file descriptor
          fd. The name is used to identify the font in the cache.  The
          dolock argument specifies whether the routine should syn-
          chronize use of the Display with other processes; for
          single-threaded applications it may always be zero.
          Readsubfonti does the same for a subfont whose associated
          image is already in memory; it is passed as the argument im.
          In other words, readsubfonti reads only the header and char-
          acter information from the file descriptor.

          Writesubfont writes on fd the part of a subfont file that
          comes after the image.  It should be preceded by a call to

     Page 2                       Plan 9            (printed 12/25/24)

     SUBFONT(2)                                             SUBFONT(2)

          writeimage (see allocimage(2)).

          Stringsubfont is analogous to string (see draw(2)) for sub-
          fonts.  Rather than use the underlying font caching primi-
          tives, it calls draw for each character.  It is intended for
          stand-alone environments such as operating system kernels.
          Strsubfontwidth returns the width of the string s in as it
          would appear if drawn with stringsubfont in Subfont f.

          Mkfont takes as argument a Subfont s and returns a pointer
          to a Font that maps the character images in s into the Runes
          min to min+s->n-1.

     FILES
          /lib/font/bit  bitmap font file tree

     SOURCE
          /sys/src/libdraw

     SEE ALSO
          graphics(2), allocimage(2), draw(2), cachechars(2),
          image(6), font(6)

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

     Page 3                       Plan 9            (printed 12/25/24)