man(1) Manual page archive


     SUBFALLOC(2)                                         SUBFALLOC(2)

     NAME
          subfalloc, subffree, rdsubfontfile, wrsubfontfile, mkfont -
          subfont manipulation

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

          Subfont* subfalloc(int n, int height, int ascent,
                   Fontchar *info, Bitmap *b, ulong q0, ulong q1)

          void     subffree(Subfont *f)

          Subfont* rdsubfontfile(int fd, Bitmap *b)

          void     wrsubfontfile(int fd, Subfont *f)

          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 subfalloc. See cachechars(2) for the meaning of n,
          height, ascent, and info, and the arrangement of characters
          in bitmap b. The fields of the returned Subfont structure
          are set to the passed arguments, and the id field is set to
          the identifying number used by /dev/bitblt (see bit(3)).
          After a successful subfalloc, b is attached to the subfont
          and is unavailable to the application; it should not be
          used.  Subfalloc returns 0 on failure.

          The q0 and q1 arguments are used as tags in a cache of sub-
          fonts (see below).  If all ones, they disable caching.

          Subffree frees a subfont and all its associated structure
          including the associated bitmap.  Since subffree 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.ldepth

          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 .ldepth exten-
          sion is elided.  Class describes the range of runes encoded

     SUBFALLOC(2)                                         SUBFALLOC(2)

          in the subfont: ascii, latin1, greek, etc.

          The format of a subfont file is described in font(6)).
          Briefly, it contains a bitmap with all the characters in it,
          followed by a subfont header, followed by character informa-
          tion.  Rdsubfontfile reads a subfont from the file descrip-
          tor fd. If b is zero, rdsubfontfile reads the bitmap as well
          as the character information from the file and allows the
          resulting subfont and bitmap to be cached in the server for
          sharing with other applications.  The first thing such an
          rdsubfontfile call does is check to see if the subfont can
          be recovered directly from the server: if the qid (see
          intro(5)) of the file pointed to by fd matches q0 and q1 of
          a cache entry, the subfont is read from the server instead
          of from fd. This is the normal use of rdsubfontfile.

          Unusual applications such as font editors may choose to have
          uncached (hence unshared) subfonts or to associate arbitrary
          bitmaps with the character data.  If the b argument to
          rdsubfontfile is non-null, rdsubfontfile reads only the
          character information from fd (which must be positioned
          after the bitmap in the file) and the resulting subfont is
          uncached.  Nonetheless, rdsubfontfile calls subfalloc with b
          and hence b is unusable afterwards; make a copy first if
          necessary.  Rdsubfontfile returns 0 on error.

          Wrsubfontfile writes on fd the part of a subfont file that
          comes after the bitmap.  Because the bitmap of a cached sub-
          font is unavailable to the application, without extraordi-
          nary measures only uncached subfonts may be written whole to
          files.

          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/libg

     SEE ALSO
          graphics(2), balloc(2), bitblt(2), cachechars(2), bitmap(6),
          font(6)

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

     BUGS
          Subfonts can contain no more than about 1300 characters.