2 <title>subfont(3) - Plan 9 from User Space</title>
3 <meta content="text/html; charset=utf-8" http-equiv=Content-Type>
6 <table border=0 cellpadding=0 cellspacing=0 width=100%>
9 <tr><td width=20><td><b>SUBFONT(3)</b><td align=right><b>SUBFONT(3)</b>
10 <tr><td width=20><td colspan=2>
12 <p><font size=+1><b>NAME </b></font><br>
14 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
16 allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont,
17 subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont,
18 strsubfontwidth, mkfont – subfont manipulation<br>
21 <p><font size=+1><b>SYNOPSIS </b></font><br>
23 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
25 <tt><font size=+1>#include <u.h><br>
26 #include <libc.h><br>
27 #include <draw.h>
28 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
30 <tt><font size=+1>Subfont* allocsubfont(char *name, int n, int height, int ascent,<br>
32 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
35 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
37 Fontchar *info, Image *i)
38 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
44 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
47 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
54 <tt><font size=+1>void freesubfont(Subfont *f)
55 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
57 <tt><font size=+1>void installsubfont(char *name, Subfont *f)
58 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
60 <tt><font size=+1>Subfont* lookupsubfont(Subfont *f)
61 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
63 <tt><font size=+1>void uninstallsubfont(Subfont *f)
64 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
66 <tt><font size=+1>Subfont* readsubfont(Display *d, char *name, int fd, int dolock)
68 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
70 <tt><font size=+1>Subfont* readsubfonti(Display *d, char *name, int fd, Image *im,<br>
72 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
75 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
78 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
84 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
87 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
94 <tt><font size=+1>int writesubfont(int fd, Subfont *f)
95 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
97 <tt><font size=+1>Point stringsubfont(Image *dst, Point p, Image *src,<br>
99 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
102 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
104 Subfont *f, char *str)
105 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
111 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
114 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
121 <tt><font size=+1>Point strsubfontwidth(Subfont *f, char *s)
122 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
124 <tt><font size=+1>Font* mkfont(Subfont *f, Rune min)<br>
127 <p><font size=+1><b>DESCRIPTION </b></font><br>
129 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
131 Subfonts are the components of fonts that hold the character images.
132 A font comprises an array of subfonts; see <a href="../man3/cachechars.html"><i>cachechars</i>(3)</a>. A new
133 <tt><font size=+1>Subfont</font></tt> is allocated and initialized with <i>allocsubfont</i>. See <a href="../man3/cachechars.html"><i>cachechars</i>(3)</a>
134 for the meaning of <i>n</i>, <i>height</i>, <i>ascent</i>, and <i>info</i>, and the arrangement
135 of characters in image <i>i</i>. The <i>name</i> is
136 used to identify the subfont in the subfont cache; see the descriptions
137 <i>lookupsubfont</i> and <i>installsubfont</i> (<i>q.v.</i>). The appropriate fields
138 of the returned <tt><font size=+1>Subfont</font></tt> structure are set to the passed arguments,
139 and the image is registered as a subfont with the graphics device
140 <a href="../man3/draw.html"><i>draw</i>(3)</a>. <i>Allocsubfont</i> returns 0 on failure.
141 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
143 <i>Freesubfont</i> frees a subfont and all its associated structure including
144 the associated image. Since <i>freesbufont</i> calls <i>free</i> on <tt><font size=+1>f−>info</font></tt>,
145 if <tt><font size=+1>f−>info</font></tt> was not allocated by <a href="../man3/malloc.html"><i>malloc</i>(3)</a> it should be zeroed before
146 calling <i>subffree</i>.
147 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
149 A number of subfonts are kept in external files. The convention
150 for naming subfont files is:<br>
152 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
154 <tt><font size=+1>/usr/local/plan9/font/</font></tt><i>name</i><tt><font size=+1>/</font></tt><i>class</i><tt><font size=+1>.</font></tt><i>size</i><tt><font size=+1>.</font></tt><i>depth
155 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
159 where <i>size</i> is approximately the height in pixels of the lower
160 case letters (without ascenders or descenders). If there is only
161 one version of the subfont, the <tt><font size=+1>.</font></tt><i>depth</i> extension is elided. <i>Class</i>
162 describes the range of runes encoded in the subfont: <tt><font size=+1>ascii</font></tt>, <tt><font size=+1>latin1</font></tt>,
163 <tt><font size=+1>greek</font></tt>, etc.
164 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
166 Subfonts are cached within the program, so a subfont shared between
167 fonts will be loaded only once. <i>Installsubfont</i> stores subfont
168 <i>f</i> under the given <i>name</i>, typically the file name from which it
169 was read. <i>Uninstallsubfont</i> removes the subfont from the cache.
170 Finally, <i>lookupsubfont</i> searches for a subfont with the given
171 <i>name</i> in the cache and returns it, or nil if no such subfont exists.
173 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
175 <i>Subfontname</i> is used to locate subfonts given their names within
176 the fonts. The default version constructs a name given the <i>cfname</i>,
177 its name within the font, <i>fname</i>, the name of the font, and the
178 maximum depth suitable for this subfont. This interface allows
179 a partially specified name within a font to be resolved at
180 run-time to the name of a file holding a suitable subfont. Although
181 it is principally a routine internal to the library, <i>subfontname</i>
182 may be substituted by the application to provide a less file-oriented
183 subfont naming scheme.
184 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
186 The format of a subfont file is described in <a href="../man7/font.html"><i>font</i>(7)</a>. Briefly,
187 it contains a image with all the characters in it, followed by
188 a subfont header, followed by character information. <i>Readsubfont</i>
189 reads a subfont from the file descriptor <i>fd</i>. The <i>name</i> is used
190 to identify the font in the cache. The <i>dolock</i> argument specifies
192 the routine should synchronize use of the <i>Display</i> with other processes;
193 for single-threaded applications it may always be zero. <i>Readsubfonti</i>
194 does the same for a subfont whose associated image is already
195 in memory; it is passed as the argument <i>im</i>. In other words, <i>readsubfonti</i>
196 reads only the header and character
197 information from the file descriptor.
198 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
200 <i>Writesubfont</i> writes on <i>fd</i> the part of a subfont file that comes
201 after the image. It should be preceded by a call to <i>writeimage</i>
202 (see <a href="../man3/allocimage.html"><i>allocimage</i>(3)</a>).
203 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
205 <i>Stringsubfont</i> is analogous to <tt><font size=+1>string</font></tt> (see <a href="../man3/draw.html"><i>draw</i>(3)</a>) for subfonts.
206 Rather than use the underlying font caching primitives, it calls
207 <tt><font size=+1>draw</font></tt> for each character. It is intended for stand-alone environments
208 such as operating system kernels. <i>Strsubfontwidth</i> returns the
209 width of the string <i>s</i> in as it would appear if drawn with
210 <i>stringsubfont</i> in <tt><font size=+1>Subfont f</font></tt>.
211 <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
213 <i>Mkfont</i> takes as argument a <tt><font size=+1>Subfont</font></tt> <i>s</i> and returns a pointer to
214 a <tt><font size=+1>Font</font></tt> that maps the character images in <i>s</i> into the <tt><font size=+1>Runes</font></tt> <i>min</i>
215 to <i>min</i><tt><font size=+1>+</font></tt><i>s</i><tt><font size=+1>−>n−1</font></tt>.<br>
218 <p><font size=+1><b>FILES </b></font><br>
220 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
222 <tt><font size=+1>/usr/local/plan9/font</font></tt> bitmap font file tree<br>
225 <p><font size=+1><b>SOURCE </b></font><br>
227 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
229 <tt><font size=+1>/usr/local/plan9/src/libdraw<br>
232 <p><font size=+1><b>SEE ALSO </b></font><br>
234 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
236 <a href="../man3/graphics.html"><i>graphics</i>(3)</a>, <a href="../man3/allocimage.html"><i>allocimage</i>(3)</a>, <a href="../man3/draw.html"><i>draw</i>(3)</a>, <a href="../man3/cachechars.html"><i>cachechars</i>(3)</a>, <a href="../man7/image.html"><i>image</i>(7)</a>,
237 <a href="../man7/font.html"><i>font</i>(7)</a><br>
240 <p><font size=+1><b>DIAGNOSTICS </b></font><br>
242 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
244 All of the functions use the graphics error function (see <a href="../man3/graphics.html"><i>graphics</i>(3)</a>).<br>
252 <table border=0 cellpadding=0 cellspacing=0 width=100%>
253 <tr height=15><td width=10><td><td width=10>
256 <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
