1.\" $NetBSD: wsfont.9,v 1.2 2001/10/22 08:21:33 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 <dev/wscons/wsconsio.h> 55.Fd #include <dev/wsfont/wsfont.h> 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.Ft int 64.Fn wsfont_add "struct wsdisplay_font *font" "int copy" 65.Ft int 66.Fn wsfont_remove "int cookie" 67.Ft void 68.Fn wsfont_enum "void (*callback)(char *, int, int, int)" 69.Ft int 70.Fn wsfont_lock "int cookie" "struct wsdisplay_font **ptr" \ 71"int bitorder" "int byteorder" 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. Fonts may be loaded 84dynamically into the kernel or included statically in the kernel at 85compile time. Display drivers which emulate a glass-tty console on a 86bit-mapped display can add, remove and find fonts for use by 87device-dependent blitter operations. 88.Pp 89The primary data type for manipulating fonts is the 90.Em wsdisplay_font 91structure in 92.Pa dev/wscons/wsconsio.h : 93.Bd -literal 94struct wsdisplay_font { 95 char *name; /* font name */ 96 int firstchar; 97 int numchars; /* size of font table */ 98 int encoding; /* font encoding 99 u_int fontwidth; /* character width */ 100 u_int fontheight; /* character width */ 101 u_int stride; 102 int bitorder; 103 int byteorder; 104 void *data; /* pointer to font table */ 105}; 106.Ed 107.Pp 108The maximum font table size is 109.Em WSDISPLAY_MAXFONTSZ . 110.Pp 111The 112.Nm 113framework supports fonts with the following encodings: 114.Bl -tag -width compact 115.It WSDISPLAY_FONTENC_ISO 116ISO-encoded fonts. 117.It WSDISPLAY_FONTENC_IBM 118IBM-encoded fonts commonly available for IBM CGA, EGA and VGA display 119adapters. 120.It WSDISPLAY_FONTENC_PCVT 121PCVT-encoding fonts distributed as part of the old PCVT terminal 122emulation driver. 123.It WSDISPLAY_FONTENC_ISO7 124ISO-encoded Greek fonts. 125.It WSDISPLAY_FONTENC_ISO2 126ISO-encoded East European fonts. 127.El 128.Sh FUNCTIONS 129.Bl -tag -width compact 130.It Fn wsfont_init "void" 131Initialise the font list with the built-in fonts. 132.It Fn wsfont_matches "font" "name" "width" "height" "stride" 133Matches the font 134.Fa font 135with the specifications 136.Fa name , 137.Fa width , 138.Fa height 139and 140.Fa stride . 141Return zero if not matched and non-zero if matched. 142.It Fn wsfont_find "name" "width" "height" "stride" 143Find the font called 144.Fa name 145from the fonts loaded into the kernel. The font aspect is specified 146by 147.Fa width , 148.Fa height , 149.and 150.Fa stride . 151If 152.Fn wsfont_find 153is called with any of the parameters as 0, it indicates that we don't 154care about that aspect of the font. If the font is found a 155(nonnegative-valued) cookie is returned which can used with the other 156functions. 157.Pp 158When more flexibility is required, 159.Fn wsfont_enum 160should be used. 161.It Fn wsfont_add "font" "copy" 162Add a font 163.Fa font 164to the font list. 165If the 166.Fa copy 167argument is non-zero, then the font is physically copied, otherwise a 168reference to the original font is made. 169.It Fn wsfont_remove "cookie" 170Remove the font specified by 171.Fa cookie 172from the font list. 173The value of cookie was returned by 174.Fn wsfont_add . 175.It Fn wsfont_enum "callback" 176Enumerate the list of fonts. For each font in the font list, the 177.Fa callback 178function argument is called with the arguments specifying the font 179name, width, height and stride. 180.It Fn wsfont_lock "cookie" "ptr" "bitorder" "byteorder" 181Lock access to the font specified by 182.Fa cookie 183so that it cannot be unloaded from the kernel while is being used. 184The address of the wsdisplay_font pointer for the specified font is 185return in the 186.Fa ptr 187argument. The 188.Fa bitorder 189and 190.Fa byteorder 191arguments are the bit order and byte order required. Valid values 192are: 193.Bl -tag -width compact 194.It WSDISPLAY_FONTORDER_KNOWN 195The font is in known ordered format and doesn't need converting. 196.It WSDISPLAY_FONTORDER_L2R 197The font is ordered left to right. 198.It WSDISPLAY_FONTORDER_R2L 199The font is ordered right to left. 200.El 201.Pp 202.Fn wsfont_lock 203returns the new lockcount on success. The function will fail if 204.Fa cookie 205is invalid or if the font is already locked and the bit/byte order 206requested by the caller differs. 207.It Fn wsfont_unlock "cookie" 208Unlock the font specified by 209.Fa cookie . 210Returns the new lockcount. 211.It Fn wsfont_getflg "cookie" "flg" "lc" 212Get font flags and lockcount for font 213.Fa cookie . 214The flags are returned in 215.Fa flg 216and the lockcount for the font in 217.Fa lc . 218.It Fn wsfont_map_unichar "font" "c" 219Remap the unicode character 220.Fa c 221to glyph for font 222.Fa font . 223Returns the glyph or success or -1 on error. 224.El 225.Sh CODE REFERENCES 226This section describes places within the 227.Nx 228source tree where actual code implementing or utilising the 229machine-independent wsfont subsystem can be found. All pathnames are 230relative to 231.Pa /usr/src . 232.Pp 233The wscons subsystem is implemented within the directory 234.Pa sys/dev/wscons . 235The wsfont subsystem itself is implemented within the file 236.Pa sys/dev/wsfont/wsfont.c . 237.Sh SEE ALSO 238.Xr autoconf 9 , 239.Xr driver 9 , 240.Xr intro 9 , 241.Xr wscons 9 , 242.Xr wsdisplay 9 243