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