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