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)