subfont.3 (5135B)
1 .TH SUBFONT 3 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 .MR cachechars (3) . 57 A new 58 .B Subfont 59 is allocated and initialized with 60 .IR allocsubfont . 61 See 62 .MR cachechars (3) 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 .MR 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 .MR malloc (3) 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 \*9/font/\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 .MR font (7) . 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 .MR allocimage (3) ). 185 .PP 186 .I Stringsubfont 187 is analogous to 188 .B string 189 (see 190 .MR draw (3) ) 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 \*9/font 221 .TP 222 .B \*9/font 223 bitmap font file tree 224 .SH SOURCE 225 .B \*9/src/libdraw 226 .SH SEE ALSO 227 .MR graphics (3) , 228 .MR allocimage (3) , 229 .MR draw (3) , 230 .MR cachechars (3) , 231 .MR image (7) , 232 .MR font (7) 233 .SH DIAGNOSTICS 234 All of the functions use the graphics error function (see 235 .MR graphics (3) ).