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