SUBFONT(2)SUBFONT(2)
NAME
allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, 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 calling
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 letters
(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.
Uninstallsubfont
removes the subfont from the cache.
Finally,
lookupsubfont
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 routine 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 contains 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
allocimage(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
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)).