1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
<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>
|