1
0

subfont 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235
  1. .TH SUBFONT 2
  2. .SH NAME
  3. allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, strsubfontwidth, mkfont \- subfont manipulation
  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'\fLSubfont* 'u
  12. .B
  13. Subfont* allocsubfont(char *name, int n, int height, int ascent,
  14. .br
  15. .B
  16. Fontchar *info, Image *i)
  17. .PP
  18. .B
  19. void freesubfont(Subfont *f)
  20. .PP
  21. .B
  22. void installsubfont(char *name, Subfont *f)
  23. .PP
  24. .B
  25. Subfont* lookupsubfont(Subfont *f)
  26. .PP
  27. .B
  28. void uninstallsubfont(Subfont *f)
  29. .PP
  30. .B
  31. Subfont* readsubfont(Display *d, char *name, int fd, int dolock)
  32. .PP
  33. .B
  34. Subfont* readsubfonti(Display *d, char *name, int fd, Image *im,
  35. .br
  36. .B
  37. int dolock)
  38. .PP
  39. .B
  40. int writesubfont(int fd, Subfont *f)
  41. .PP
  42. .B
  43. Point stringsubfont(Image *dst, Point p, Image *src,
  44. .br
  45. .B
  46. Subfont *f, char *str)
  47. .PP
  48. .B
  49. Point strsubfontwidth(Subfont *f, char *s)
  50. .PP
  51. .B
  52. Font* mkfont(Subfont *f, Rune min)
  53. .SH DESCRIPTION
  54. Subfonts are the components of fonts that hold the character images.
  55. A font comprises an array of subfonts; see
  56. .IR cachechars (2).
  57. A new
  58. .B Subfont
  59. is allocated and initialized with
  60. .IR allocsubfont .
  61. See
  62. .IR cachechars (2)
  63. for the meaning of
  64. .IR n ,
  65. .IR height ,
  66. .IR ascent ,
  67. and
  68. .IR info ,
  69. and the arrangement of characters in
  70. image
  71. .IR i .
  72. The
  73. .I name
  74. is used to identify the subfont in the subfont cache; see the descriptions
  75. .I lookupsubfont
  76. and
  77. .IR installsubfont
  78. .RI ( q.v. ).
  79. The appropriate fields of the returned
  80. .B Subfont
  81. structure are set to
  82. the passed arguments, and the image is registered as a subfont
  83. with the graphics device
  84. .IR draw (3).
  85. .I Allocsubfont
  86. returns 0 on failure.
  87. .PP
  88. .I Freesubfont
  89. frees a subfont and all its associated structure including the
  90. associated image.
  91. Since
  92. .I freesbufont
  93. calls
  94. .I free
  95. on
  96. .BR f->info ,
  97. if
  98. .B f->info
  99. was not allocated by
  100. .IR malloc (2)
  101. it should be zeroed before calling
  102. .IR subffree .
  103. .PP
  104. A number of subfonts are kept in external files.
  105. The convention for naming subfont files is:
  106. .IP
  107. .B /lib/font/bit/\fIname\fP/\fIclass\fP.\fIsize\fP.\fIdepth
  108. .PD
  109. .PP
  110. where
  111. .I size
  112. is approximately the height in pixels of the lower case letters
  113. (without ascenders or descenders).
  114. If there is only one version of the subfont, the
  115. .BI \&. depth
  116. extension is elided.
  117. .I Class
  118. describes the range of runes encoded in the subfont:
  119. .BR ascii ,
  120. .BR latin1 ,
  121. .BR greek ,
  122. etc.
  123. .PP
  124. Subfonts are cached within the program, so a subfont shared between fonts will be loaded only once.
  125. .I Installsubfont
  126. stores subfont
  127. .I f
  128. under the given
  129. .IR name ,
  130. typically the file name from which it was read.
  131. .I Uninstallsubfont
  132. removes the subfont from the cache.
  133. Finally,
  134. .I lookupsubfont
  135. searches for a subfont with the given
  136. .I name
  137. in the cache and returns it, or nil if no such subfont exists.
  138. .PP
  139. .I Subfontname
  140. is used to locate subfonts given their names within the fonts.
  141. The default version constructs a name given the
  142. .IR cfname ,
  143. its name within the font,
  144. .IR fname ,
  145. the name of the font, and the maximum depth suitable for this subfont.
  146. This interface allows a partially specified name within a font to be resolved
  147. at run-time to the name of a file holding a suitable subfont.
  148. Although it is principally a routine internal to the library,
  149. .I subfontname
  150. may be substituted by the application to provide a less file-oriented subfont naming scheme.
  151. .PP
  152. The format of a subfont file is described in
  153. .IR font (6).
  154. Briefly, it contains a image with all the characters in it,
  155. followed by a subfont header, followed by character information.
  156. .I Readsubfont
  157. reads a subfont from the file descriptor
  158. .IR fd .
  159. The
  160. .I name
  161. is used to identify the font in the cache.
  162. The
  163. .I dolock
  164. argument specifies whether the routine should synchronize
  165. use of the
  166. .I Display
  167. with other processes; for single-threaded applications it may
  168. always be zero.
  169. .I Readsubfonti
  170. does the same for a subfont whose associated image is already in memory; it is passed as the
  171. argument
  172. .IR im .
  173. In other words,
  174. .I readsubfonti
  175. reads only the header and character information from the file descriptor.
  176. .PP
  177. .I Writesubfont
  178. writes on
  179. .I fd
  180. the part of a subfont file that comes after the image. It should be preceded by
  181. a call to
  182. .IR writeimage
  183. (see
  184. .IR allocimage (2)).
  185. .PP
  186. .I Stringsubfont
  187. is analogous to
  188. .B string
  189. (see
  190. .IR draw (2))
  191. for subfonts. Rather than use the underlying font caching primitives,
  192. it calls
  193. .B draw
  194. for each character.
  195. It is intended for stand-alone environments such as operating system kernels.
  196. .I Strsubfontwidth
  197. returns the width of the string
  198. .I s
  199. in
  200. as it would appear if drawn with
  201. .I stringsubfont
  202. in
  203. .B Subfont
  204. .BR f .
  205. .PP
  206. .I Mkfont
  207. takes as argument a
  208. .B Subfont
  209. .I s
  210. and returns a pointer to a
  211. .B Font
  212. that maps the character images in
  213. .I s
  214. into the
  215. .B Runes
  216. .I min
  217. to
  218. .IB min + s ->n-1\f1.
  219. .SH FILES
  220. .TF /lib/font/bit
  221. .TP
  222. .B /lib/font/bit
  223. bitmap font file tree
  224. .SH SOURCE
  225. .B /sys/src/libdraw
  226. .SH SEE ALSO
  227. .IR graphics (2),
  228. .IR allocimage (2),
  229. .IR draw (2),
  230. .IR cachechars (2),
  231. .IR image (6),
  232. .IR font (6)
  233. .SH DIAGNOSTICS
  234. All of the functions use the graphics error function (see
  235. .IR graphics (2)).