tcachechars.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tcachechars.3 (7067B)
---
1 .TH CACHECHARS 3
2 .SH NAME
3 cachechars, agefont, loadchar, Subfont, Fontchar, Font \- font utilities
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .br
9 .B #include <draw.h>
10 .PP
11 .ta \w'\fLCacheinfo 'u
12 .PP
13 .B
14 int cachechars(Font *f, char **s, Rune **r, ushort *c, int max,
15 .PP
16 .B
17 int *widp, char **sfname)
18 .PP
19 .B
20 int loadchar(Font *f, Rune r, Cacheinfo *c, int h,
21 .PP
22 .B
23 int noclr, char **sfname)
24 .PP
25 .B
26 void agefont(Font *f)
27 .SH DESCRIPTION
28 A
29 .I Font
30 may contain too many characters to hold in memory
31 simultaneously.
32 The graphics library and draw device (see
33 .MR draw (3) )
34 cooperate to solve this problem by maintaining a cache of recently used
35 character images.
36 The details of this cooperation need not be known by most programs:
37 .I initdraw
38 and its associated
39 .I font
40 variable,
41 .IR openfont ,
42 .IR stringwidth ,
43 .IR string ,
44 and
45 .I freefont
46 are sufficient for most purposes.
47 The routines described below are used internally by the graphics library
48 to maintain the font cache.
49 .PP
50 A
51 .B Subfont
52 is a set of images for a contiguous range of characters, stored as a single
53 image
54 with the characters
55 placed side-by-side on a common baseline.
56 It is described by the following data structures.
57 .IP
58 .EX
59 .ta 6n +\w'Fontchar 'u +\w'bottom; 'u
60 typedef
61 struct Fontchar {
62 int x; /* left edge of bits */
63 uchar top; /* first non-zero scan-line */
64 uchar bottom; /* last non-zero scan-line */
65 char left; /* offset of baseline */
66 uchar width; /* width of baseline */
67 } Fontchar;
68
69 typedef
70 struct Subfont {
71 char *name;
72 short n; /* number of chars in subfont */
73 uchar height; /* height of image */
74 char ascent; /* top of image to baseline */
75 Fontchar *info; /* n+1 Fontchars */
76 Image *bits; /* of font */
77 } Subfont;
78 .EE
79 .PP
80 The image fills the rectangle
81 \fL(0, 0, \fIw\fP, height)\fR,
82 where
83 .I w
84 is the sum of the horizontal extents (of non-zero pixels)
85 for all characters.
86 The pixels to be displayed for character
87 .I c
88 are in the rectangle
89 \fL(\fIi\fP->x, \fIi\fP->top, (\fIi\fP+1)->x, \%\fIi\fP->bottom)\fR
90 where
91 .I i
92 is
93 .B
94 &subfont->info[\fIc\fP]\fR.
95 When a character is displayed at
96 .B Point
97 .B p
98 in an image,
99 the character rectangle is placed at
100 .BI (p.x+ i ->left,
101 .B p.y)
102 and the next character of the string is displayed at
103 .BI (p.x+ i ->width,
104 .BR p.y) .
105 The baseline of the characters is
106 .L ascent
107 rows down from the top of the subfont image.
108 The
109 .L info
110 array has
111 .B n+1
112 elements, one each for characters 0 to
113 .BR n-1
114 plus an additional entry so the size of the last character
115 can be calculated.
116 Thus the width,
117 .IR w ,
118 of the
119 .B Image
120 associated with a
121 .B Subfont
122 .B s
123 is
124 .BR s->info[s->n].x .
125 .PP
126 A
127 .B Font
128 consists of an overall height and ascent
129 and a collection of subfonts together with the ranges of runes (see
130 .MR utf (7) )
131 they represent.
132 Fonts are described by the following structures.
133 .IP
134 .EX
135 .ta 6n +\w'Cacheinfo 'u +\w'height; 'u
136 typedef
137 struct Cachefont {
138 Rune min; /* value of 0th char in subfont */
139 Rune max; /* value+1 of last char in subfont */
140 int offset; /* posn in subfont of char at min */
141 char *name; /* stored in font */
142 char *subfontname; /* to access subfont */
143 } Cachefont;
144
145 typedef
146 struct Cacheinfo {
147 ushort x; /* left edge of bits */
148 uchar width; /* width of baseline */
149 schar left; /* offset of baseline */
150 Rune value; /* of char at this slot in cache */
151 ushort age;
152 } Cacheinfo;
153
154 typedef
155 struct Cachesubf {
156 ulong age; /* for replacement */
157 Cachefont *cf; /* font info that owns us */
158 Subfont *f; /* attached subfont */
159 } Cachesubf;
160
161 typedef
162 struct Font {
163 char *name;
164 Display *display;
165 short height; /* max ht of image;interline space*/
166 short ascent; /* top of image to baseline */
167 short width; /* widest so far; used in caching */
168 int nsub; /* number of subfonts */
169 ulong age; /* increasing counter; for LRU */
170 int ncache; /* size of cache */
171 int nsubf; /* size of subfont list */
172 Cacheinfo *cache;
173 Cachesubf *subf;
174 Cachefont **sub; /* as read from file */
175 Image *cacheimage;
176 } Font;
177 .EE
178 .PP
179 The
180 .LR height
181 and
182 .LR ascent
183 fields of Font are described in
184 .MR graphics (3) .
185 .L Sub
186 contains
187 .L nsub
188 pointers to
189 .BR Cachefonts .
190 A
191 .B Cachefont
192 connects runes
193 .L min
194 through
195 .LR max ,
196 inclusive, to the subfont
197 with file name
198 .LR name ;
199 it corresponds to a line of the file describing the font.
200 .PP
201 The characters
202 are taken from the subfont starting at character number
203 .L offset
204 (usually zero) in the subfont, permitting selection of parts of subfonts.
205 Thus
206 the image for rune
207 .I r
208 is found in position
209 .IB r -min+offset
210 of the subfont.
211 .PP
212 For each font, the library, with support from the
213 graphics server,
214 maintains a cache of
215 subfonts and a cache of recently used
216 character images.
217 The
218 .B subf
219 and
220 .B cache
221 fields are used by the library to maintain these caches.
222 The
223 .L width
224 of a font is the maximum of the horizontal extents of the characters
225 in the cache.
226 .I String
227 draws a string by loading the cache and emitting a sequence of
228 cache indices to draw.
229 .I Cachechars
230 guarantees the images for the characters pointed to by
231 .I *s
232 or
233 .I *r
234 (one of these must be nil in each call)
235 are in the cache of
236 .IR f .
237 It calls
238 .I loadchar
239 to put missing characters into the cache.
240 .I Cachechars
241 translates the character string into a set of cache indices
242 which it loads into the array
243 .IR c ,
244 up to a maximum of
245 .I n
246 indices or the length of the string.
247 .I Cachechars
248 returns in
249 .I c
250 the number of cache indices emitted,
251 updates
252 .I *s
253 to point to the next character to be processed, and sets
254 .I *widp
255 to the total width of the characters processed.
256 .I Cachechars
257 may return before the end of the string if it cannot
258 proceed without destroying active data in the caches.
259 If it needs to load a new subfont, it will fill
260 .B *sfname
261 with the name of the subfont it needs and return \-1.
262 It can return zero if it is unable to make progress because
263 it cannot resize the caches.
264 .PP
265 .I Loadchar
266 loads a character image into the character cache.
267 Then it tells the graphics server to copy the character
268 into position
269 .I h
270 in the character cache.
271 If the current font
272 .L width
273 is smaller than the horizontal extent of the character being loaded,
274 .I loadfont
275 clears the cache and resets it to
276 accept characters with the bigger width, unless
277 .I noclr
278 is set, in which case it just returns \-1.
279 If the character does not exist in the font at all,
280 .I loadfont
281 returns 0; if it is unable to load the character
282 without destroying cached information, it returns \-1,
283 updating
284 .B *sfname
285 as described above.
286 It returns 1 to indicate success.
287 .PP
288 The
289 .L age
290 fields record when
291 subfonts and characters have been used.
292 The font
293 .L age
294 is increased every time the font is used
295 .RI ( agefont
296 does this).
297 A character or subfont
298 .L age
299 is set to the font age at each use.
300 Thus, characters or subfonts with small ages are the best candidates
301 for replacement when the cache is full.
302 .SH SOURCE
303 .B \*9/src/libdraw
304 .SH SEE ALSO
305 .MR graphics (3) ,
306 .MR allocimage (3) ,
307 .MR draw (3) ,
308 .MR subfont (3) ,
309 .MR image (7) ,
310 .MR font (7)
311 .SH DIAGNOSTICS
312 All of the functions use the graphics error function (see
313 .MR graphics (3) ).