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



NAME
       allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsub‐
       font, subfontname, readsubfont, readsubfonti, writesubfont,  stringsub‐
       font, 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(Subfont *f)

       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 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 call‐
       ing subffree.

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

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

       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 .depth extension 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.   Unin‐
       stallsubfont  removes  the subfont from the cache.  Finally, lookupsub‐
       font 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 subfont.  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  rou‐
       tine  internal  to  the  library, subfontname may be substituted 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 con‐
       tains  a  image  with  all  the characters in it, followed by a subfont
       header, followed by character information.  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
       synchronize  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 character 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 writeimage (see allocim‐
       age(2)).

       Stringsubfont  is  analogous  to  string  (see  draw(2))  for subfonts.
       Rather than use the underlying font caching primitives, 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)).



                                                                    SUBFONT(2)