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