Skip to content

Remove embedded font blobs, improve font hinting#2

Open
kdedev wants to merge 1 commit intomarchaesen:mainfrom
kdedev:remove-embedded-fonts-improve-hinting
Open

Remove embedded font blobs, improve font hinting#2
kdedev wants to merge 1 commit intomarchaesen:mainfrom
kdedev:remove-embedded-fonts-improve-hinting

Conversation

@kdedev
Copy link

@kdedev kdedev commented Feb 10, 2026

Summary

Two related improvements to font handling: remove embedded font data that bloats the binary by 97%, and fix font rendering to produce sharp, legible text.

1. Remove embedded JetBrainsMono Nerd Font blobs

The problem

Four header files in wld/ embed the entire JetBrainsMono Nerd Font family as C arrays (Regular, Bold, Italic, BoldItalic). Each file is ~14MB, totaling 56MB of font data compiled into the binary.

Before After
Binary size 9.4 MB 212 KB
Repository ~56MB of .h files Clean

Why the embedded fonts aren't needed

The FT_New_Memory_Face fallback in wld_font_open_pattern() only triggers when match is NULL -- meaning fontconfig couldn't resolve any font at all. In practice:

  • st-wl already requires JetBrainsMono Nerd Font to be installed (it's the hardcoded default font string)
  • If fontconfig is broken or the font is missing, the user has bigger problems than an embedded fallback can solve
  • No other Wayland terminal (foot, alacritty, kitty) embeds fonts -- they all rely on system-installed fonts via fontconfig
  • The embedded font versions become stale immediately and can't be updated by the user

What changed

  • Deleted the 4 .h files from wld/
  • Removed the fontdatas[] and fontdatasizes[] arrays from wld/font.c
  • Replaced the FT_New_Memory_Face fallback with DEBUGPRNT + goto error1 (clean error path)

2. Improve font rendering clarity

The problem

Text in st-wl is noticeably fuzzier than in other terminals (foot, kitty, alacritty). Characters with fine details -- m, w, 0 vs O, l vs 1 vs I, : vs ; -- are harder to read, especially at common terminal sizes (12-16px) on 1080p displays.

This is because st-wl uses suboptimal FreeType settings that produce blurry, poorly-hinted glyphs.

Root cause

Two settings work against each other:

  1. FT_LOAD_DEFAULT for glyph loading -- this doesn't specify a hinting target, so FreeType doesn't optimize glyph outlines for the actual rendering mode. Stem widths and character edges don't snap cleanly to pixel boundaries.

  2. autohint=true in the font string -- this tells fontconfig to ignore the font's own hand-tuned hinting instructions and use FreeType's generic auto-hinter instead. For well-hinted professional fonts like JetBrains Mono (which ships with carefully crafted TrueType hinting), the auto-hinter produces objectively worse results.

Fix

Setting Before After
Glyph loading FT_LOAD_DEFAULT FT_LOAD_TARGET_NORMAL
Font string autohint=true hintstyle=hintfull
  • FT_LOAD_TARGET_NORMAL tells FreeType to optimize hinting specifically for the rendering mode being used (greyscale anti-aliasing). Glyph stems snap to pixel boundaries, producing sharper, more defined characters.
  • hintstyle=hintfull uses JetBrains Mono's own hinting instructions -- professionally designed to maximize legibility at screen sizes -- instead of FreeType's one-size-fits-all algorithm.

The result is noticeably crisper text that matches the rendering quality of other modern terminals.

Build verification

Clean build, zero warnings. Tested on Arch Linux with JetBrainsMono Nerd Font installed via system packages.

Remove 56MB of JetBrainsMono Nerd Font data embedded as C arrays in
wld/font.c header files. The FT_New_Memory_Face fallback that loaded
these embedded fonts is replaced with an error path - system-installed
fonts via fontconfig should always be used.

Additionally improve font rendering quality:
- Use FT_LOAD_TARGET_NORMAL instead of FT_LOAD_DEFAULT for glyph loading,
  which enables the font's native hinting program for sharper glyphs
- Use hintstyle=hintfull instead of autohint=true in the font string,
  preferring the font's own hinting instructions over FreeType's
  auto-hinter (better results for well-hinted fonts like JetBrains Mono)

Binary size: 9.4MB -> 212KB (97.8% reduction)
Repository size: ~56MB smaller (the .h files alone were 14MB each)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant