cachechars 6.9 KB

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