1.\" $NetBSD: wsfont.9,v 1.15 2010/12/02 12:54:13 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.\" 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 72The 73.Nm 74module is a component of the 75.Xr wscons 9 76framework to provide access to display fonts. 77Fonts may be loaded dynamically into the kernel or included statically 78in the kernel at compile time. 79Display drivers which emulate a glass-tty console on a bit-mapped 80display can add, remove and find fonts for use by device-dependent 81blitter operations. 82.Pp 83The primary data type for manipulating fonts is the 84.Em wsdisplay_font 85structure in 86.Pa dev/wscons/wsconsio.h : 87.Bd -literal 88struct 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 102The maximum font table size is 103.Em WSDISPLAY_MAXFONTSZ . 104.Pp 105The 106.Nm 107framework supports fonts with the following encodings: 108.Bl -tag -width compact 109.It WSDISPLAY_FONTENC_ISO 110ISO-encoded fonts. 111.It WSDISPLAY_FONTENC_IBM 112IBM-encoded fonts commonly available for IBM CGA, EGA and VGA display 113adapters. 114.It WSDISPLAY_FONTENC_PCVT 115PCVT-encoding fonts distributed as part of the old PCVT terminal 116emulation driver. 117.It WSDISPLAY_FONTENC_ISO7 118ISO-encoded Greek fonts. 119.It WSDISPLAY_FONTENC_ISO2 120ISO-encoded East European fonts. 121.El 122.Sh FUNCTIONS 123.Bl -tag -width compact 124.It Fn wsfont_init "void" 125Initialise the font list with the built-in fonts. 126.It Fn wsfont_matches "font" "name" "width" "height" "stride" 127Matches the font 128.Fa font 129with the specifications 130.Fa name , 131.Fa width , 132.Fa height 133and 134.Fa stride . 135Return zero if not matched and non-zero if matched. 136.It Fn wsfont_find "name" "width" "height" "stride" "bitorder" "byteorder" 137Find the font called 138.Fa name 139from the fonts loaded into the kernel. 140The font aspect is specified by 141.Fa width , 142.Fa height , 143and 144.Fa stride . 145If 146.Fn wsfont_find 147is called with any of the parameters as 0, it indicates that we don't 148care about that aspect of the font. 149If the font is found, a (nonnegative-valued) cookie is returned which 150can be used with the other functions. 151.Pp 152The 153.Fa bitorder 154and 155.Fa byteorder 156arguments are the bit order and byte order required. 157Valid values are: 158.Bl -tag -width compact 159.It WSDISPLAY_FONTORDER_KNOWN 160The font is in known ordered format and doesn't need converting. 161.It WSDISPLAY_FONTORDER_L2R 162The font is ordered left to right. 163.It WSDISPLAY_FONTORDER_R2L 164The font is ordered right to left. 165.El 166.Pp 167When more flexibility is required, 168.Fn wsfont_enum 169should be used. 170.It Fn wsfont_add "font" "copy" 171Add a font 172.Fa font 173to the font list. 174If the 175.Fa copy 176argument is non-zero, then the font is physically copied, otherwise a 177reference to the original font is made. 178.It Fn wsfont_remove "cookie" 179Remove the font specified by 180.Fa cookie 181from the font list. 182The value of cookie was returned by 183.Fn wsfont_add . 184.It Fn wsfont_enum "callback" 185Enumerate the list of fonts. 186For each font in the font list, the 187.Fa callback 188function argument is called with the arguments specifying the font 189name, width, height and stride. 190.It Fn wsfont_lock "cookie" "ptr" 191Lock access to the font specified by 192.Fa cookie 193so that it cannot be unloaded from the kernel while is being used. 194If the bit or byte order of the font to be locked differs from what 195has been requested with 196.Fn wsfont_find 197then the glyph data will be modified to match. 198At this point it may be necessary for 199.Fn wsfont_lock 200to make a copy of the font data; this action is transparent to the caller. 201A later call to 202.Fn wsfont_unlock 203will free resources used by temporary copies. 204.Pp 205The address of the wsdisplay_font pointer for the specified font is returned in 206the 207.Fa ptr 208argument. 209.Pp 210.Fn wsfont_lock 211returns zero on success, or an error code on failure. 212.It Fn wsfont_unlock "cookie" 213Unlock the font specified by 214.Fa cookie . 215Returns zero on success, or an error code on failure. 216.It Fn wsfont_map_unichar "font" "c" 217Remap the unicode character 218.Fa c 219to glyph for font 220.Fa font . 221Returns the glyph on success or \-1 on error. 222.El 223.Sh CODE REFERENCES 224The wscons subsystem is implemented within the directory 225.Pa sys/dev/wscons . 226The wsfont subsystem itself is implemented within the file 227.Pa sys/dev/wsfont/wsfont.c . 228.Sh SEE ALSO 229.Xr wsfont 4 , 230.Xr wsfontload 8 , 231.Xr autoconf 9 , 232.Xr driver 9 , 233.Xr intro 9 , 234.Xr wscons 9 , 235.Xr wsdisplay 9 236