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