tsubfont.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
---
tsubfont.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) ).