CACHECHARS(2) CACHECHARS(2)
NAME
cachechars, agefont, loadchar, Subfont, Fontchar, Font -
font utilities
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <draw.h>
int cachechars(Font *f, char **s, Rune **r, ushort *c, int
max,
int *widp, char **sfname)
int loadchar(Font *f, Rune r, Cacheinfo *c, int h,
int noclr, char **sfname)
void agefont(Font *f)
DESCRIPTION
A Font may contain too many characters to hold in memory
simultaneously. The graphics library and draw device (see
draw(3)) cooperate to solve this problem by maintaining a
cache of recently used character images. The details of
this cooperation need not be known by most programs:
initdraw and its associated font variable, openfont,
stringwidth, string, and freefont are sufficient for most
purposes. The routines described below are used internally
by the graphics library to maintain the font cache.
A Subfont is a set of images for a contiguous range of char-
acters, stored as a single image with the characters placed
side-by-side on a common baseline. It is described by the
following data structures.
typedef
struct Fontchar {
int x; /* left edge of bits */
uchar top; /* first non-zero scan-line */
uchar bottom; /* last non-zero scan-line */
char left; /* offset of baseline */
uchar width; /* width of baseline */
} Fontchar;
typedef
struct Subfont {
char *name;
short n; /* number of chars in subfont */
uchar height; /* height of image */
char ascent; /* top of image to baseline */
Fontchar *info; /* n+1 Fontchars */
Image *bits; /* of font */
} Subfont;
The image fills the rectangle (0, 0, w, height), where w is
the sum of the horizontal extents (of non-zero pixels) for
all characters. The pixels to be displayed for character c
are in the rectangle (i->x, i->top, (i+1)->x, i->bottom)
where i is &subfont->info[c]. When a character is displayed
at Point p in an image, the character rectangle is placed at
(p.x+i->left, p.y) and the next character of the string is
displayed at (p.x+i->width, p.y). The baseline of the char-
acters is `ascent' rows down from the top of the subfont
image. The `info' array has n+1 elements, one each for
characters 0 to n-1 plus an additional entry so the size of
the last character can be calculated. Thus the width, w, of
the Image associated with a Subfont s is s->info[s->n].x.
A Font consists of an overall height and ascent and a col-
lection of subfonts together with the ranges of runes (see
utf(6)) they represent. Fonts are described by the follow-
ing structures.
typedef
struct Cachefont {
Rune min; /* value of 0th char in subfont */
Rune max; /* value+1 of last char in subfont */
int offset; /* posn in subfont of char at min */
char *name; /* stored in font */
char *subfontname;/* to access subfont */
} Cachefont;
typedef
struct Cacheinfo {
ushort x; /* left edge of bits */
uchar width; /* width of baseline */
schar left; /* offset of baseline */
Rune value; /* of char at this slot in cache */
ushort age;
} Cacheinfo;
typedef
struct Cachesubf {
ulong age; /* for replacement */
Cachefont *cf; /* font info that owns us */
Subfont *f; /* attached subfont */
} Cachesubf;
typedef
struct Font {
char *name;
Display *display;
short height; /* max ht of image;interline space*/
short ascent; /* top of image to baseline */
short width; /* widest so far; used in caching */
short nsub; /* number of subfonts */
ulong age; /* increasing counter; for LRU */
int ncache; /* size of cache */
int nsubf; /* size of subfont list */
Cacheinfo *cache;
Cachesubf *subf;
Cachefont **sub; /* as read from file */
Image *cacheimage;
} Font;
The `height' and `ascent' fields of Font are described in
graphics(2). `Sub' contains `nsub' pointers to Cachefonts.
A Cachefont connects runes `min' through `max', inclusive,
to the subfont with file name `name'; it corresponds to a
line of the file describing the font.
The characters are taken from the subfont starting at char-
acter number `offset' (usually zero) in the subfont, permit-
ting selection of parts of subfonts. Thus the image for
rune r is found in position r-min+offset of the subfont.
For each font, the library, with support from the graphics
server, maintains a cache of subfonts and a cache of
recently used character images. The subf and cache fields
are used by the library to maintain these caches. The
`width' of a font is the maximum of the horizontal extents
of the characters in the cache. String draws a string by
loading the cache and emitting a sequence of cache indices
to draw. Cachechars guarantees the images for the charac-
ters pointed to by *s or *r (one of these must be nil in
each call) are in the cache of f. It calls loadchar to put
missing characters into the cache. Cachechars translates
the character string into a set of cache indices which it
loads into the array c, up to a maximum of n indices or the
length of the string. Cachechars returns in c the number of
cache indices emitted, updates *s to point to the next char-
acter to be processed, and sets *widp to the total width of
the characters processed. Cachechars may return before the
end of the string if it cannot proceed without destroying
active data in the caches. If it needs to load a new sub-
font, it will fill *sfname with the name of the subfont it
needs and return -1. It can return zero if it is unable to
make progress because it cannot resize the caches.
Loadchar loads a character image into the character cache.
Then it tells the graphics server to copy the character into
position h in the character cache. If the current font
`width' is smaller than the horizontal extent of the charac-
ter being loaded, loadfont clears the cache and resets it to
accept characters with the bigger width, unless noclr is
set, in which case it just returns -1. If the character
does not exist in the font at all, loadfont returns 0; if it
is unable to load the character without destroying cached
information, it returns -1, updating *sfname as described
above. It returns 1 to indicate success.
The `age' fields record when subfonts and characters have
been used. The font `age' is increased every time the font
is used (agefont does this). A character or subfont `age'
is set to the font age at each use. Thus, characters or
subfonts with small ages are the best candidates for
replacement when the cache is full.
SOURCE
/sys/src/libdraw
SEE ALSO
graphics(2), allocimage(2), draw(2), subfont(2), image(6),
font(6)
DIAGNOSTICS
All of the functions use the graphics error function (see
graphics(2)).
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 con-
vention 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 exten-
sion 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 sub-
font. 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 sub-
stituted 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 informa-
tion. 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 syn-
chronize 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 char-
acter 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 sub-
fonts. Rather than use the underlying font caching primi-
tives, 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)).
/plan9/man/2/