1.\" $NetBSD: wsfont.9,v 1.6 2002/03/16 12:10:18 ad 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. 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" "bitorder" "byteorder" 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 , 149and 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 158The 159.Fa bitorder 160and 161.Fa byteorder 162arguments are the bit order and byte order required. Valid values 163are: 164.Bl -tag -width compact 165.It WSDISPLAY_FONTORDER_KNOWN 166The font is in known ordered format and doesn't need converting. 167.It WSDISPLAY_FONTORDER_L2R 168The font is ordered left to right. 169.It WSDISPLAY_FONTORDER_R2L 170The font is ordered right to left. 171.El 172.Pp 173When more flexibility is required, 174.Fn wsfont_enum 175should be used. 176.It Fn wsfont_add "font" "copy" 177Add a font 178.Fa font 179to the font list. 180If the 181.Fa copy 182argument is non-zero, then the font is physically copied, otherwise a 183reference to the original font is made. 184.It Fn wsfont_remove "cookie" 185Remove the font specified by 186.Fa cookie 187from the font list. 188The value of cookie was returned by 189.Fn wsfont_add . 190.It Fn wsfont_enum "callback" 191Enumerate the list of fonts. For each font in the font list, the 192.Fa callback 193function argument is called with the arguments specifying the font 194name, width, height and stride. 195.It Fn wsfont_lock "cookie" "ptr" 196Lock access to the font specified by 197.Fa cookie 198so that it cannot be unloaded from the kernel while is being used. 199If the bit or byte order of the font to be locked differs from what 200has been requested with 201.Fn wsfont_find 202then the glyph data will be modified to match. At this point it may be 203necessary for 204.Fn wsfont_lock 205to make a copy of the font data; this action is transparent to the caller. 206A later call to 207.Fn wsfont_unlock 208will free resources used by temporary copies. 209.Pp 210The address of the wsdisplay_font pointer for the specified font is return in 211the 212.Fa ptr 213argument. 214.Pp 215.Fn wsfont_lock 216returns zero on success, or an error code on failure. 217.It Fn wsfont_unlock "cookie" 218Unlock the font specified by 219.Fa cookie . 220Returns zero on succss, or an error code on failure. 221.It Fn wsfont_map_unichar "font" "c" 222Remap the unicode character 223.Fa c 224to glyph for font 225.Fa font . 226Returns the glyph or success or -1 on error. 227.El 228.Sh CODE REFERENCES 229This section describes places within the 230.Nx 231source tree where actual code implementing or utilising the 232machine-independent wsfont subsystem can be found. All pathnames are 233relative to 234.Pa /usr/src . 235.Pp 236The wscons subsystem is implemented within the directory 237.Pa sys/dev/wscons . 238The wsfont subsystem itself is implemented within the file 239.Pa sys/dev/wsfont/wsfont.c . 240.Sh SEE ALSO 241.Xr autoconf 9 , 242.Xr driver 9 , 243.Xr intro 9 , 244.Xr wscons 9 , 245.Xr wsdisplay 9 246