1.\" $OpenBSD: wsfont_init.9,v 1.2 2019/05/10 17:24:53 schwarze Exp $ 2.\" $NetBSD: wsfont.9,v 1.18 2012/01/13 23:09:51 wiz Exp $ 3.\" 4.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Gregory McGarry. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: May 10 2019 $ 32.Dt WSFONT_INIT 9 33.Os 34.Sh NAME 35.Nm wsfont_init , 36.Nm wsfont_find , 37.Nm wsfont_add , 38.Nm wsfont_remove , 39.Nm wsfont_enum , 40.Nm wsfont_lock , 41.Nm wsfont_unlock , 42.Nm wsfont_map_unichar 43.Nd wscons font support 44.Sh SYNOPSIS 45.In dev/wscons/wsconsio.h 46.In dev/wsfont/wsfont.h 47.Ft void 48.Fn wsfont_init "void" 49.Ft int 50.Fn wsfont_find "const char *name" "int width" "int height" "int stride" 51.Ft int 52.Fn wsfont_add "struct wsdisplay_font *font" "int copy" 53.Ft int 54.Fn wsfont_remove "int cookie" 55.Ft void 56.Fn wsfont_enum "int (*cb)(void *, struct wsdisplay_font *)" "void *cbarg" 57.Ft int 58.Fn wsfont_lock "int cookie" "struct wsdisplay_font **ptr" "int bitorder" \ 59"int byteorder" 60.Ft int 61.Fn wsfont_unlock "int cookie" 62.Ft int 63.Fn wsfont_map_unichar "struct wsdisplay_font *font" "int c" 64.Sh DESCRIPTION 65The wsfont module is a component of the wscons 66.\" .Xr wscons 9 67framework to provide access to display fonts. 68Fonts may be loaded dynamically into the kernel or included statically 69in the kernel at compile time. 70Display drivers which emulate a glass-tty console on a bit-mapped 71display can add, remove and find fonts for use by device-dependent 72blitter operations. 73.Pp 74The primary data type for manipulating fonts is the 75.Vt wsdisplay_font 76structure in 77.In dev/wscons/wsconsio.h : 78.Bd -literal 79struct wsdisplay_font { 80 char name[WSFONT_NAME_SIZE]; /* font name */ 81 int index; 82 int firstchar; 83 int numchars; /* size of font table */ 84 int encoding; /* font encoding */ 85 u_int fontwidth; /* character width */ 86 u_int fontheight; /* character height */ 87 u_int stride; 88 int bitorder; 89 int byteorder; 90 void *cookie; 91 void *data; /* pointer to font table */ 92}; 93.Ed 94.Pp 95The maximum font table size is 96.Dv WSDISPLAY_MAXFONTSZ . 97.Pp 98The wsfont framework supports fonts with the following encodings: 99.Bl -tag -width compact 100.It Dv WSDISPLAY_FONTENC_ISO 101ISO-encoded fonts. 102.It Dv WSDISPLAY_FONTENC_IBM 103IBM-encoded fonts commonly available for IBM CGA, EGA and VGA display 104adapters. 105.El 106.Sh FUNCTIONS 107.Bl -tag -width compact 108.It Fn wsfont_init "void" 109Initialise the font list with the built-in fonts. 110.It Fn wsfont_find "name" "width" "height" "stride" 111Find the font called 112.Fa name 113from the fonts loaded into the kernel. 114The font aspect is specified by 115.Fa width , 116.Fa height , 117and 118.Fa stride . 119If 120.Fn wsfont_find 121is called with any of the parameters as 0, it indicates that we don't 122care about that aspect of the font. 123If the font is found, a (nonnegative-valued) cookie is returned which 124can be used with the other functions. 125.Pp 126When more flexibility is required, 127.Fn wsfont_enum 128should be used. 129.It Fn wsfont_add "font" "copy" 130Add a font 131.Fa font 132to the font list. 133If the 134.Fa copy 135argument is non-zero, then the font is physically copied, otherwise a 136reference to the original font is made. 137.It Fn wsfont_remove "cookie" 138Remove the font specified by 139.Fa cookie 140from the font list. 141The value of cookie was returned by 142.Fn wsfont_add . 143.It Fn wsfont_enum "callback" "cbarg" 144Enumerate the list of fonts. 145For each font in the font list, the 146.Fa callback 147function argument is called with the 148.Fa cbarg 149argument. 150.It Fn wsfont_lock "cookie" "ptr" "bitorder" "byteorder" 151Lock access to the font specified by 152.Fa cookie 153so that it cannot be unloaded from the kernel while it is being used. 154If the bit or byte order of the font to be locked differs from what 155has been requested via the 156.Fa bitorder 157and 158.Fa byteorder 159arguments, then the glyph data will be modified to match. 160.Pp 161The address of the 162.Vt wsdisplay_font 163pointer for the specified font is returned in 164the 165.Fa ptr 166argument. 167.Pp 168.Fn wsfont_lock 169returns lockcount on success, or an error code on failure. 170.It Fn wsfont_unlock "cookie" 171Unlock the font specified by 172.Fa cookie . 173Returns lockcount on success, or an error code on failure. 174.It Fn wsfont_map_unichar "font" "c" 175Remap the unicode character 176.Fa c 177to glyph for font 178.Fa font . 179Returns the glyph on success or \-1 on error. 180.El 181.Sh CODE REFERENCES 182The wscons subsystem is implemented within the directory 183.Pa sys/dev/wscons . 184The wsfont subsystem itself is implemented within the file 185.Pa sys/dev/wsfont/wsfont.c . 186.Sh SEE ALSO 187.Xr wsfontload 8 , 188.Xr intro 9 189