glenda.party
term% ls -F
term% cat index.txt
SUBFALLOC(2)                  System Calls Manual                 SUBFALLOC(2)



NAME
       subfalloc, subffree, rdsubfontfile, wrsubfontfile, mkfont - subfont ma‐
       nipulation

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 charac‐
       ters 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  subfonts  (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 subf‐
       free.

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

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

       where size is approximately the height in pixels of the lower case let‐
       ters (without ascenders or descenders).  If there is only  one  version
       of  the  subfont, the .ldepth extension is elided.  Class describes the
       range of runes encoded 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 information.  Rdsubfontfile reads a  sub‐
       font  from  the  file descriptor fd.  If b is zero, rdsubfontfile reads
       the bitmap as well as the character information from the file  and  al‐
       lows  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, rdsub‐
       fontfile  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.   Rdsubfont‐
       file 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 subfont is  unavailable  to
       the  application, without extraordinary 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.



                                                                  SUBFALLOC(2)