292 lines
16 KiB
HTML
292 lines
16 KiB
HTML
<head>
|
|
<title>cachechars(3) - Plan 9 from User Space</title>
|
|
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
|
|
</head>
|
|
<body bgcolor=#ffffff>
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=10><td>
|
|
<tr><td width=20><td>
|
|
<tr><td width=20><td><b>CACHECHARS(3)</b><td align=right><b>CACHECHARS(3)</b>
|
|
<tr><td width=20><td colspan=2>
|
|
<br>
|
|
<p><font size=+1><b>NAME </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
cachechars, agefont, loadchar, Subfont, Fontchar, Font – font utilities<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SYNOPSIS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>#include <u.h><br>
|
|
#include <libc.h><br>
|
|
#include <draw.h>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<tt><font size=+1>int cachechars(Font *f, char **s, Rune **r, ushort *c, int max,
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>int *widp, char **sfname)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
</table>
|
|
|
|
</table>
|
|
<tt><font size=+1>int loadchar(Font *f, Rune r, Cacheinfo *c, int h,
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>int noclr, char **sfname)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
</table>
|
|
|
|
</table>
|
|
<tt><font size=+1>void agefont(Font *f)<br>
|
|
</font></tt>
|
|
</table>
|
|
<p><font size=+1><b>DESCRIPTION </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
A <i>Font</i> may contain too many characters to hold in memory simultaneously.
|
|
The graphics library and draw device (see <a href="../man3/draw.html"><i>draw</i>(3)</a>) 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: <i>initdraw</i> and its associated
|
|
<i>font</i> variable, <i>openfont</i>, <i>stringwidth</i>, <i>string</i>, and <i>freefont</i> are
|
|
sufficient for most purposes. The routines described below are
|
|
used internally by the graphics library to maintain the font cache.
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
A <tt><font size=+1>Subfont</font></tt> is a set of images for a contiguous range of characters,
|
|
stored as a single image with the characters placed side-by-side
|
|
on a common baseline. It is described by the following data structures.<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>typedef<br>
|
|
struct Fontchar {<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
int x; /* left edge of bits */<br>
|
|
uchar top; /* first non−zero scan−line */<br>
|
|
uchar bottom; /* last non−zero scan−line */<br>
|
|
char left; /* offset of baseline */<br>
|
|
uchar width; /* width of baseline */<br>
|
|
|
|
</table>
|
|
} Fontchar;<br>
|
|
typedef<br>
|
|
struct Subfont {<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
char *name;<br>
|
|
short n; /* number of chars in subfont */<br>
|
|
uchar height; /* height of image */<br>
|
|
char ascent; /* top of image to baseline */<br>
|
|
Fontchar *info; /* n+1 Fontchars */<br>
|
|
Image *bits; /* of font */<br>
|
|
|
|
</table>
|
|
} Subfont;<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
</table>
|
|
The image fills the rectangle <tt><font size=+1>(0, 0,</font></tt> <i>w</i><tt><font size=+1>, height)</font></tt>, where <i>w</i> is the
|
|
sum of the horizontal extents (of non-zero pixels) for all characters.
|
|
The pixels to be displayed for character <i>c</i> are in the rectangle
|
|
<tt><font size=+1>(</font></tt><i>i</i><tt><font size=+1>−>x,</font></tt> <i>i</i><tt><font size=+1>−>top, (</font></tt><i>i</i><tt><font size=+1>+1)−>x,</font></tt> <i>i</i><tt><font size=+1>−>bottom)</font></tt> where <i>i</i> is <tt><font size=+1>&subfont−>info[</font></tt><i>c</i><tt><font size=+1>]</font></tt>. When
|
|
a character is displayed
|
|
at <tt><font size=+1>Point p</font></tt> in an image, the character rectangle is placed at <tt><font size=+1>(p.x+</font></tt><i>i</i><tt><font size=+1>−>left,
|
|
p.y)</font></tt> and the next character of the string is displayed at <tt><font size=+1>(p.x+</font></tt><i>i</i><tt><font size=+1>−>width,
|
|
p.y)</font></tt>. The baseline of the characters is <tt><font size=+1>ascent</font></tt> rows down from
|
|
the top of the subfont image. The <tt><font size=+1>info</font></tt> array has <tt><font size=+1>n+1</font></tt> elements,
|
|
one each for characters 0
|
|
to <tt><font size=+1>n−1</font></tt> plus an additional entry so the size of the last character
|
|
can be calculated. Thus the width, <i>w</i>, of the <tt><font size=+1>Image</font></tt> associated
|
|
with a <tt><font size=+1>Subfont s</font></tt> is <tt><font size=+1>s−>info[s−>n].x</font></tt>.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
A <tt><font size=+1>Font</font></tt> consists of an overall height and ascent and a collection
|
|
of subfonts together with the ranges of runes (see <a href="../man7/utf.html"><i>utf</i>(7)</a>) they
|
|
represent. Fonts are described by the following structures.<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>typedef<br>
|
|
struct Cachefont {<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
Rune min; /* value of 0th char in subfont */<br>
|
|
Rune max; /* value+1 of last char in subfont */<br>
|
|
int offset; /* posn in subfont of char at min */<br>
|
|
char *name; /* stored in font */<br>
|
|
char *subfontname;/* to access subfont */<br>
|
|
|
|
</table>
|
|
} Cachefont;<br>
|
|
typedef<br>
|
|
struct Cacheinfo {<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
ushort x; /* left edge of bits */<br>
|
|
uchar width; /* width of baseline */<br>
|
|
schar left; /* offset of baseline */<br>
|
|
Rune value; /* of char at this slot in cache */<br>
|
|
ushort age;<br>
|
|
|
|
</table>
|
|
} Cacheinfo;<br>
|
|
typedef<br>
|
|
struct Cachesubf {<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
ulong age; /* for replacement */<br>
|
|
Cachefont *cf; /* font info that owns us */<br>
|
|
Subfont *f; /* attached subfont */<br>
|
|
|
|
</table>
|
|
} Cachesubf;<br>
|
|
typedef<br>
|
|
struct Font {<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
char *name;<br>
|
|
Display *display;<br>
|
|
short height; /* max ht of image;interline space*/<br>
|
|
short ascent; /* top of image to baseline */<br>
|
|
short width; /* widest so far; used in caching */<br>
|
|
short nsub; /* number of subfonts */<br>
|
|
ulong age; /* increasing counter; for LRU */<br>
|
|
int ncache; /* size of cache */<br>
|
|
int nsubf; /* size of subfont list */<br>
|
|
Cacheinfo *cache;<br>
|
|
Cachesubf *subf;<br>
|
|
Cachefont **sub; /* as read from file */<br>
|
|
Image *cacheimage;<br>
|
|
|
|
</table>
|
|
} Font;<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
</table>
|
|
The <tt><font size=+1>height</font></tt> and <tt><font size=+1>ascent</font></tt> fields of Font are described in <a href="../man3/graphics.html"><i>graphics</i>(3)</a>.
|
|
<tt><font size=+1>Sub</font></tt> contains <tt><font size=+1>nsub</font></tt> pointers to <tt><font size=+1>Cachefonts</font></tt>. A <tt><font size=+1>Cachefont</font></tt> connects
|
|
runes <tt><font size=+1>min</font></tt> through <tt><font size=+1>max</font></tt>, inclusive, to the subfont with file name
|
|
<tt><font size=+1>name</font></tt>; it corresponds to a line of the file describing the font.
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The characters are taken from the subfont starting at character
|
|
number <tt><font size=+1>offset</font></tt> (usually zero) in the subfont, permitting selection
|
|
of parts of subfonts. Thus the image for rune <i>r</i> is found in position
|
|
<i>r</i><tt><font size=+1>−min+offset</font></tt> of the subfont.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
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 <tt><font size=+1>subf</font></tt> and <tt><font size=+1>cache</font></tt> fields are used by the library to maintain
|
|
these caches. The <tt><font size=+1>width</font></tt> of a font is the maximum of the horizontal
|
|
extents of the characters in the cache.
|
|
<i>String</i> draws a string by loading the cache and emitting a sequence
|
|
of cache indices to draw. <i>Cachechars</i> guarantees the images for
|
|
the characters pointed to by <i>*s</i> or <i>*r</i> (one of these must be nil
|
|
in each call) are in the cache of <i>f</i>. It calls <i>loadchar</i> to put
|
|
missing characters into the cache. <i>Cachechars</i> translates the
|
|
character string into a set of cache indices which it loads into
|
|
the array <i>c</i>, up to a maximum of <i>n</i> indices or the length of the
|
|
string. <i>Cachechars</i> returns in <i>c</i> the number of cache indices emitted,
|
|
updates <i>*s</i> to point to the next character to be processed, and
|
|
sets <i>*widp</i> to the total width of the characters processed.
|
|
<i>Cachechars</i> 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 subfont, it will fill <tt><font size=+1>*sfname</font></tt> 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.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Loadchar</i> loads a character image into the character cache. Then
|
|
it tells the graphics server to copy the character into position
|
|
<i>h</i> in the character cache. If the current font <tt><font size=+1>width</font></tt> is smaller
|
|
than the horizontal extent of the character being loaded, <i>loadfont</i>
|
|
clears the cache and resets it to accept characters with the
|
|
bigger width, unless <i>noclr</i> is set, in which case it just returns
|
|
–1. If the character does not exist in the font at all, <i>loadfont</i>
|
|
returns 0; if it is unable to load the character without destroying
|
|
cached information, it returns –1, updating <tt><font size=+1>*sfname</font></tt> as described
|
|
above. It returns 1 to indicate success.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The <tt><font size=+1>age</font></tt> fields record when subfonts and characters have been used.
|
|
The font <tt><font size=+1>age</font></tt> is increased every time the font is used (<i>agefont</i>
|
|
does this). A character or subfont <tt><font size=+1>age</font></tt> 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.
|
|
|
|
</table>
|
|
<p><font size=+1><b>SOURCE </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>/usr/local/plan9/src/libdraw<br>
|
|
</font></tt>
|
|
</table>
|
|
<p><font size=+1><b>SEE ALSO </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<a href="../man3/graphics.html"><i>graphics</i>(3)</a>, <a href="../man3/allocimage.html"><i>allocimage</i>(3)</a>, <a href="../man3/draw.html"><i>draw</i>(3)</a>, <a href="../man3/subfont.html"><i>subfont</i>(3)</a>, <a href="../man7/image.html"><i>image</i>(7)</a>, <a href="../man7/font.html"><i>font</i>(7)</a><br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>DIAGNOSTICS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
All of the functions use the graphics error function (see <a href="../man3/graphics.html"><i>graphics</i>(3)</a>).<br>
|
|
|
|
</table>
|
|
|
|
<td width=20>
|
|
<tr height=20><td>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=15><td width=10><td><td width=10>
|
|
<tr><td><td>
|
|
<center>
|
|
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
|
|
</center>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
</body></html>
|