WSFONT(9)

📦 version 11.0, in nixpkgs unstable

🌸 WSFONT(9) — the wsfont manual page, bestie edition 🌸

okay so this is from the Kernel Developer's Manual (the Wsfont one, section 9, iykyk) and it's literally all about how the kernel handles fonts. let's get into it 💅

✨ NAME ✨

wsfont, wsfont_init, wsfont_matches, wsfont_find, wsfont_add, wsfont_remove, wsfont_enum, wsfont_lock, wsfont_unlock, wsfont_map_unichar — the whole wscons font support squad 🫶

🦋 SYNOPSIS 🦋

#include <dev/wscons/wsconsio.h>
#include <dev/wsfont/wsfont.h>

void
wsfont_init(void);

int
wsfont_matches(struct wsdisplay_font *font, const char *name, int width,
    int height, int stride, int flags);

int
wsfont_find(const char *name, int width, int height, int stride,
    int bitorder, int byteorder, int flags);

int
wsfont_add(struct wsdisplay_font *font, int copy);

int
wsfont_remove(int cookie);

void
wsfont_enum(void (*callback)(const char *, int, int, int));

int
wsfont_lock(int cookie, struct wsdisplay_font **ptr);

int
wsfont_unlock(int cookie);

int
wsfont_map_unichar(struct wsdisplay_font *font, int c);

💖 DESCRIPTION 💖

so the wsfont module is a whole component of the wscons(9) framework, and its entire job is giving you access to display fonts. that's it, that's the vibe ✨

fonts can be loaded dynamically into the kernel OR included statically in the kernel at compile time — both are valid, no cap. and display drivers that emulate a glass-tty console on a bit-mapped display can add, remove, and find fonts for use by device-dependent blitter operations. iconic behavior honestly 🔥

the main character of this whole page is the wsdisplay_font structure over in dev/wscons/wsconsio.h:

struct wsdisplay_font {
        const char *name;       /* font name */
        int firstchar;
        int numchars;           /* size of font table */
        int encoding;           /* font encoding */
        u_int fontwidth;        /* character width */
        u_int fontheight;       /* character height */
        u_int stride;
        int bitorder;
        int byteorder;
        void *data;             /* pointer to font table */
};

the maximum font table size is WSDISPLAY_MAXFONTSZ — remember that, it matters 🎀

🌈 the encodings the framework supports

  • WSDISPLAY_FONTENC_ISO — ISO-encoded fonts, classic.
  • WSDISPLAY_FONTENC_IBM — IBM-encoded fonts, the ones you'll commonly find for IBM CGA, EGA and VGA display adapters. retro slay 💀
  • WSDISPLAY_FONTENC_PCVT — PCVT-encoding fonts, distributed as part of the old PCVT terminal emulation driver. vintage.
  • WSDISPLAY_FONTENC_ISO7 — ISO-encoded Greek fonts 🇬🇷
  • WSDISPLAY_FONTENC_ISO2 — ISO-encoded East European fonts.

🎀 FUNCTIONS 🎀

wsfont_init(void)

Initialises the font list with the built-in fonts. starting fresh, periodt ✨

wsfont_matches(font, name, width, height, stride)

Matches the font font against the specs name, width, height, stride and flags. returns zero if not matched and non-zero if matched 💖 and just so you know, the flags parameter means the exact same thing as it does in wsfont_find().

wsfont_find(name, width, height, stride, bitorder, byteorder, flags)

Finds the font called name from the fonts loaded into the kernel. the font's whole aspect is specified by width, height, and stride. and here's the bestie hack: if wsfont_find() is called with any of those parameters as 0, that literally means "we don't care about that aspect of the font" 🙈. if the font is found, a (nonnegative-valued) cookie gets returned, and you can use that cookie with all the other functions. cookie 🍪 honestly cute.

the bitorder and byteorder arguments are the bit order and byte order you require. valid values are:

  • WSDISPLAY_FONTORDER_KNOWN — the font is in known ordered format and doesn't need converting. already perfect, no notes 👑
  • WSDISPLAY_FONTORDER_L2R — the font is ordered left to right.
  • WSDISPLAY_FONTORDER_R2L — the font is ordered right to left.

the flags parameter decides what type of font can be returned, and any combination of these values is allowed:

  • WSFONT_FIND_BITMAP — to search bitmap fonts,
  • WSFONT_FIND_ALPHA — to search anti-aliased fonts.

when you need more flexibility than that, you should use wsfont_enum() instead. that's the move 💅

wsfont_add(font, copy)

Adds a font font to the font list. and the copy argument? if it's non-zero, then the font is physically copied. otherwise a reference to the original font is made. your call bestie 🫶

Removes the font specified by cookie from the font list. and the value of cookie was returned by wsfont_add(), so don't just make one up 😭

wsfont_enum(callback)

Enumerates the list of fonts. for every single font in the font list, the callback function argument gets called with arguments specifying the font name, width, height and stride. it's giving roll call 📋

Locks access to the font specified by cookie so it cannot be unloaded from the kernel while it's being used — very important, don't skip this one 🔒

now here's the spicy part: if the bit or byte order of the font to be locked differs from what was requested with wsfont_find(), then the glyph data will be modified to match. at that point it may be necessary for wsfont_lock() to make a copy of the font data — and that action is transparent to the caller, so don't worry about it. a later call to wsfont_unlock() will free resources used by temporary copies. very demure, very mindful of resources 🧚

the address of the wsdisplay_font pointer for the specified font gets returned in the ptr argument.

wsfont_lock() returns zero on success, or an error code on failure.

Unlocks the font specified by cookie. returns zero on success, or an error code on failure. that's it, she's simple 🎀

wsfont_map_unichar(font, c)

Remaps the unicode character c to a glyph for font font. returns the glyph on success or -1 on error. the remapping™ ✨

🦋 CODE REFERENCES 🦋

the wscons subsystem lives inside the directory sys/dev/wscons. and the wsfont subsystem itself? implemented within the file sys/dev/wsfont/wsfont.c — now you know exactly where to look 🔍

🌸 SEE ALSO 🌸

wsfont(4), wsfontload(8), autoconf(9), driver(9), intro(9), wscons(9), wsdisplay(9)

go read those too, they're all in their own little ecosystem 💜

and that's the whole page bestie, mwah 💋 — this one came from Debian, dated January 13, 2012, so yeah it's got some vintage energy but she still ate. periodt. 🌈✨

📦 where this page comes from