| blob | 25d79f1695177161f48f720e80ea2306632c80ee |
1 .\" $NetBSD: wsfont.9,v 1.13 2008/04/30 13:10:59 martin Exp $
2 .\"
3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd October 7, 2001
31 .Dt WSFONT 9
32 .Os
33 .Sh NAME
34 .Nm wsfont ,
35 .Nm wsfont_init ,
36 .Nm wsfont_matches ,
37 .Nm wsfont_find ,
38 .Nm wsfont_add ,
39 .Nm wsfont_remove ,
40 .Nm wsfont_enum ,
41 .Nm wsfont_lock ,
42 .Nm wsfont_unlock ,
43 .Nm wsfont_getflg ,
44 .Nm wsfont_map_unichar
45 .Nd wscons font support
46 .Sh SYNOPSIS
47 .In dev/wscons/wsconsio.h
48 .In dev/wsfont/wsfont.h
49 .Ft void
50 .Fn wsfont_init "void"
51 .Ft int
52 .Fn wsfont_matches "struct wsdisplay_font *font" "const char *name" \
53 "int width" "int height" "int stride"
54 .Ft int
55 .Fn wsfont_find "const char *name" "int width" "int height" "int stride" \
56 "int bitorder" "int byteorder"
57 .Ft int
58 .Fn wsfont_add "struct wsdisplay_font *font" "int copy"
59 .Ft int
60 .Fn wsfont_remove "int cookie"
61 .Ft void
62 .Fn wsfont_enum "void (*callback)(const char *, int, int, int)"
63 .Ft int
64 .Fn wsfont_lock "int cookie" "struct wsdisplay_font **ptr"
65 .Ft int
66 .Fn wsfont_unlock "int cookie"
67 .Ft int
68 .Fn wsfont_getflg "int cookie" "int *flg" "int *lc"
69 .Ft int
70 .Fn wsfont_map_unichar "struct wsdisplay_font *font" "int c"
71 .Sh DESCRIPTION
72 The
73 .Nm
74 module is a component of the
75 .Xr wscons 9
76 framework to provide access to display fonts.
77 Fonts may be loaded dynamically into the kernel or included statically
78 in the kernel at compile time.
79 Display drivers which emulate a glass-tty console on a bit-mapped
80 display can add, remove and find fonts for use by device-dependent
81 blitter operations.
82 .Pp
83 The primary data type for manipulating fonts is the
84 .Em wsdisplay_font
85 structure in
86 .Pa dev/wscons/wsconsio.h :
87 .Bd -literal
88 struct wsdisplay_font {
89 char *name; /* font name */
90 int firstchar;
91 int numchars; /* size of font table */
92 int encoding; /* font encoding
93 u_int fontwidth; /* character width */
94 u_int fontheight; /* character width */
95 u_int stride;
96 int bitorder;
97 int byteorder;
98 void *data; /* pointer to font table */
99 };
100 .Ed
101 .Pp
102 The maximum font table size is
103 .Em WSDISPLAY_MAXFONTSZ .
104 .Pp
105 The
106 .Nm
107 framework supports fonts with the following encodings:
108 .Bl -tag -width compact
109 .It WSDISPLAY_FONTENC_ISO
110 ISO-encoded fonts.
111 .It WSDISPLAY_FONTENC_IBM
112 IBM-encoded fonts commonly available for IBM CGA, EGA and VGA display
113 adapters.
114 .It WSDISPLAY_FONTENC_PCVT
115 PCVT-encoding fonts distributed as part of the old PCVT terminal
116 emulation driver.
117 .It WSDISPLAY_FONTENC_ISO7
118 ISO-encoded Greek fonts.
119 .It WSDISPLAY_FONTENC_ISO2
120 ISO-encoded East European fonts.
121 .El
122 .Sh FUNCTIONS
123 .Bl -tag -width compact
124 .It Fn wsfont_init "void"
125 Initialise the font list with the built-in fonts.
126 .It Fn wsfont_matches "font" "name" "width" "height" "stride"
127 Matches the font
128 .Fa font
129 with the specifications
130 .Fa name ,
131 .Fa width ,
132 .Fa height
133 and
134 .Fa stride .
135 Return zero if not matched and non-zero if matched.
136 .It Fn wsfont_find "name" "width" "height" "stride" "bitorder" "byteorder"
137 Find the font called
138 .Fa name
139 from the fonts loaded into the kernel.
140 The font aspect is specified by
141 .Fa width ,
142 .Fa height ,
143 and
144 .Fa stride .
145 If
146 .Fn wsfont_find
147 is called with any of the parameters as 0, it indicates that we don't
148 care about that aspect of the font.
149 If the font is found, a (nonnegative-valued) cookie is returned which
150 can be used with the other functions.
151 .Pp
152 The
153 .Fa bitorder
154 and
155 .Fa byteorder
156 arguments are the bit order and byte order required.
157 Valid values are:
158 .Bl -tag -width compact
159 .It WSDISPLAY_FONTORDER_KNOWN
160 The font is in known ordered format and doesn't need converting.
161 .It WSDISPLAY_FONTORDER_L2R
162 The font is ordered left to right.
163 .It WSDISPLAY_FONTORDER_R2L
164 The font is ordered right to left.
165 .El
166 .Pp
167 When more flexibility is required,
168 .Fn wsfont_enum
169 should be used.
170 .It Fn wsfont_add "font" "copy"
171 Add a font
172 .Fa font
173 to the font list.
174 If the
175 .Fa copy
176 argument is non-zero, then the font is physically copied, otherwise a
177 reference to the original font is made.
178 .It Fn wsfont_remove "cookie"
179 Remove the font specified by
180 .Fa cookie
181 from the font list.
182 The value of cookie was returned by
183 .Fn wsfont_add .
184 .It Fn wsfont_enum "callback"
185 Enumerate the list of fonts.
186 For each font in the font list, the
187 .Fa callback
188 function argument is called with the arguments specifying the font
189 name, width, height and stride.
190 .It Fn wsfont_lock "cookie" "ptr"
191 Lock access to the font specified by
192 .Fa cookie
193 so that it cannot be unloaded from the kernel while is being used.
194 If the bit or byte order of the font to be locked differs from what
195 has been requested with
196 .Fn wsfont_find
197 then the glyph data will be modified to match.
198 At this point it may be necessary for
199 .Fn wsfont_lock
200 to make a copy of the font data; this action is transparent to the caller.
201 A later call to
202 .Fn wsfont_unlock
203 will free resources used by temporary copies.
204 .Pp
205 The address of the wsdisplay_font pointer for the specified font is returned in
206 the
207 .Fa ptr
208 argument.
209 .Pp
210 .Fn wsfont_lock
211 returns zero on success, or an error code on failure.
212 .It Fn wsfont_unlock "cookie"
213 Unlock the font specified by
214 .Fa cookie .
215 Returns zero on success, or an error code on failure.
216 .It Fn wsfont_map_unichar "font" "c"
217 Remap the unicode character
218 .Fa c
219 to glyph for font
220 .Fa font .
221 Returns the glyph on success or \-1 on error.
222 .El
223 .Sh CODE REFERENCES
224 This section describes places within the
225 .Nx
226 source tree where actual code implementing or using the
227 machine-independent wsfont subsystem can be found.
228 All pathnames are relative to
229 .Pa /usr/src .
230 .Pp
231 The wscons subsystem is implemented within the directory
232 .Pa sys/dev/wscons .
233 The wsfont subsystem itself is implemented within the file
234 .Pa sys/dev/wsfont/wsfont.c .
235 .Sh SEE ALSO
236 .Xr wsfont 4 ,
237 .Xr wsfontload 8 ,
238 .Xr autoconf 9 ,
239 .Xr driver 9 ,
240 .Xr intro 9 ,
241 .Xr wscons 9 ,
242 .Xr wsdisplay 9