1.\" $NetBSD: wsfont.9,v 1.18 2012/01/13 23:09:51 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 January 13, 2012 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" "int flags" 53.Ft int 54.Fn wsfont_find "const char *name" "int width" "int height" "int stride" \ 55"int bitorder" "int byteorder" "int flags" 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 Dv WSDISPLAY_FONTENC_ISO 107ISO-encoded fonts. 108.It Dv WSDISPLAY_FONTENC_IBM 109IBM-encoded fonts commonly available for IBM CGA, EGA and VGA display 110adapters. 111.It Dv WSDISPLAY_FONTENC_PCVT 112PCVT-encoding fonts distributed as part of the old PCVT terminal 113emulation driver. 114.It Dv WSDISPLAY_FONTENC_ISO7 115ISO-encoded Greek fonts. 116.It Dv 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 , 130.Fa stride 131and 132.Fa flags . 133Return zero if not matched and non-zero if matched. 134The 135.Fa flags 136parameter has the same meaning as in 137.Fn wsfont_find . 138.It Fn wsfont_find "name" "width" "height" "stride" "bitorder" "byteorder" "flags" 139Find the font called 140.Fa name 141from the fonts loaded into the kernel. 142The font aspect is specified by 143.Fa width , 144.Fa height , 145and 146.Fa stride . 147If 148.Fn wsfont_find 149is called with any of the parameters as 0, it indicates that we don't 150care about that aspect of the font. 151If the font is found, a (nonnegative-valued) cookie is returned which 152can be used with the other functions. 153.Pp 154The 155.Fa bitorder 156and 157.Fa byteorder 158arguments are the bit order and byte order required. 159Valid values are: 160.Bl -tag -width compact 161.It Dv WSDISPLAY_FONTORDER_KNOWN 162The font is in known ordered format and doesn't need converting. 163.It Dv WSDISPLAY_FONTORDER_L2R 164The font is ordered left to right. 165.It Dv WSDISPLAY_FONTORDER_R2L 166The font is ordered right to left. 167.El 168.Pp 169The 170.Fa flags 171parameter determines what type of font can be returned. 172Any combination of the following values is allowed: 173.Bl -tag -width compact 174.It Dv WSFONT_FIND_BITMAP 175To search bitmap fonts, 176.It Dv WSFONT_FIND_ALPHA 177to search anti-aliased fonts. 178.El 179When more flexibility is required, 180.Fn wsfont_enum 181should be used. 182.It Fn wsfont_add "font" "copy" 183Add a font 184.Fa font 185to the font list. 186If the 187.Fa copy 188argument is non-zero, then the font is physically copied, otherwise a 189reference to the original font is made. 190.It Fn wsfont_remove "cookie" 191Remove the font specified by 192.Fa cookie 193from the font list. 194The value of cookie was returned by 195.Fn wsfont_add . 196.It Fn wsfont_enum "callback" 197Enumerate the list of fonts. 198For each font in the font list, the 199.Fa callback 200function argument is called with the arguments specifying the font 201name, width, height and stride. 202.It Fn wsfont_lock "cookie" "ptr" 203Lock access to the font specified by 204.Fa cookie 205so that it cannot be unloaded from the kernel while is being used. 206If the bit or byte order of the font to be locked differs from what 207has been requested with 208.Fn wsfont_find 209then the glyph data will be modified to match. 210At this point it may be necessary for 211.Fn wsfont_lock 212to make a copy of the font data; this action is transparent to the caller. 213A later call to 214.Fn wsfont_unlock 215will free resources used by temporary copies. 216.Pp 217The address of the wsdisplay_font pointer for the specified font is returned in 218the 219.Fa ptr 220argument. 221.Pp 222.Fn wsfont_lock 223returns zero on success, or an error code on failure. 224.It Fn wsfont_unlock "cookie" 225Unlock the font specified by 226.Fa cookie . 227Returns zero on success, or an error code on failure. 228.It Fn wsfont_map_unichar "font" "c" 229Remap the unicode character 230.Fa c 231to glyph for font 232.Fa font . 233Returns the glyph on success or \-1 on error. 234.El 235.Sh CODE REFERENCES 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 wsfont 4 , 242.Xr wsfontload 8 , 243.Xr autoconf 9 , 244.Xr driver 9 , 245.Xr intro 9 , 246.Xr wscons 9 , 247.Xr wsdisplay 9 248