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(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 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 re‐
turns 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 ap‐
plication 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)