From 181ed704c93208439faf47cab00e2f90af16f3aa Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Tue, 23 Feb 2021 08:48:52 -0800 Subject: [PATCH] docs for freetype_load_target and deprecation of font_antialias refs: #491 --- config/src/font.rs | 3 +- docs/changelog.md | 3 +- docs/config/lua/config/font_antialias.md | 2 ++ docs/config/lua/config/font_hinting.md | 2 ++ docs/config/lua/config/freetype_load_flags.md | 30 +++++++++++++++++++ .../config/lua/config/freetype_load_target.md | 19 ++++++++++++ 6 files changed, 56 insertions(+), 3 deletions(-) create mode 100644 docs/config/lua/config/freetype_load_flags.md create mode 100644 docs/config/lua/config/freetype_load_target.md diff --git a/config/src/font.rs b/config/src/font.rs index d91fab8e8..70a8654fc 100644 --- a/config/src/font.rs +++ b/config/src/font.rs @@ -40,8 +40,7 @@ bitflags! { const DEFAULT = 0; /// Disable hinting. This generally generates ‘blurrier’ /// bitmap glyph when the glyph is rendered in any of the - /// anti-aliased modes. See also the note below. This flag is - /// implied by FT_LOAD_NO_SCALE. + /// anti-aliased modes. const NO_HINTING = 2; const NO_BITMAP = 8; /// Indicates that the auto-hinter is preferred over the diff --git a/docs/changelog.md b/docs/changelog.md index 8fc6be0d7..62fc20537 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -10,8 +10,9 @@ daily) from the master branch. It may not be usable and the feature set may change. As features stabilize some brief notes about them may accumulate here. +* Fonts: `font_antialias` and `font_hinting` are now deprecated in favor of the new [freetype_load_target](config/lua/config/freetype_load_target.md) and [freetype_load_flags](config/lua/config/freetype_load_flags.md) options. The deprecated options have no effect and will be removed in a future release. The new options provide more direct control over how freetype rasterizes text. * Fonts: when computing default `font_rules` for bold and italic fonts, strip italic and bold components from the family name. eg: if you set `font = wezterm.font("Source Code Pro Medium")` then the ` Medium` text will be stripped from the font name used to locate bold and italic variants so that we don't report an error loading a non-sensical `Source Code Pro Medium Bold`. [#456](https://github.com/wez/wezterm/issues/456) -* Fonts: fix a regression where bright windows behind wezterm could "shine through" on the alpha channel, and adjust the tinting operation to avoid anti-aliased dark fringes [#470](https://github.com/wez/wezterm/issues/470) +* Fonts: fix a regression where bright windows behind wezterm could "shine through" on the alpha channel, and adjust the tinting operation to avoid anti-aliased dark fringes [#470](https://github.com/wez/wezterm/issues/470) [#491](https://github.com/wez/wezterm/issues/491) * Added `--config-file` CLI option to specify an alternate config file location. [Read more about config file resolution](config/files.md). Thanks to [@bew](https://github.com/bew)! [#459](https://github.com/wez/wezterm/pull/459) * Fixed an issue where large pastes could result in a hang * Updated bundled JetBrainsMono font to version 2.225 diff --git a/docs/config/lua/config/font_antialias.md b/docs/config/lua/config/font_antialias.md index 1925df976..bda0dbc15 100644 --- a/docs/config/lua/config/font_antialias.md +++ b/docs/config/lua/config/font_antialias.md @@ -1,5 +1,7 @@ # `font_antialias = "Greyscale"` +*Deprecated in the nightly; this option no longer does anything and will be removed in a future release. Use [freetype_load_target](freetype_load_target.md) instead* + Adjusts the anti-aliasing portion of the font rasterizer. Possible values are `None`, `Greyscale`, `Subpixel`. diff --git a/docs/config/lua/config/font_hinting.md b/docs/config/lua/config/font_hinting.md index 0c38cde94..9fdfd870f 100644 --- a/docs/config/lua/config/font_hinting.md +++ b/docs/config/lua/config/font_hinting.md @@ -1,5 +1,7 @@ # `font_hinting = "Full"` +*Deprecated in the nightly; this option no longer does anything and will be removed in a future release. Use [freetype_load_target](freetype_load_target.md) instead* + Adjust the hinting portion of the font rasterizer. Possible values are `None`, `Vertical`, `VerticalSubpixel`, `Full`. diff --git a/docs/config/lua/config/freetype_load_flags.md b/docs/config/lua/config/freetype_load_flags.md new file mode 100644 index 000000000..ee6a79640 --- /dev/null +++ b/docs/config/lua/config/freetype_load_flags.md @@ -0,0 +1,30 @@ +# `freetype_load_flags = "DEFAULT"` + +*Since: nightly* + +An advanced option to fine tune the freetype rasterizer. This is a bitfield, +so you can combine one or more of these options together, separated by the `|` +character, although not many of the available options necessarily make sense to +be combined. + +Available flags are: + +* `DEFAULT` - This is the default! +* `NO_HINTING` - Disable hinting. This generally generates ‘blurrier’ + bitmap glyph when the glyph is rendered in any of the + anti-aliased modes. +* `NO_BITMAP` - don't load any pre-rendered bitmap strikes +* `FORCE_AUTOHINT` - Use the freetype auto-hinter rather than the font's + native hinter. +* `MONOCHROME` - instructs renderer to use 1-bit monochrome rendering. + This option doesn't impact the hinter. +* `NO_AUTOHINT` - don't use the freetype auto-hinter + +```lua +return { + -- You probably don't want to do this, but this demonstrates + -- that the flags can be combined + freetype_load_flags = "NO_HINTING|MONOCHROME" +} +``` + diff --git a/docs/config/lua/config/freetype_load_target.md b/docs/config/lua/config/freetype_load_target.md new file mode 100644 index 000000000..87b8722e6 --- /dev/null +++ b/docs/config/lua/config/freetype_load_target.md @@ -0,0 +1,19 @@ +# `freetype_load_target = "Normal"` + +*Since: nightly* + +Configures the rendering mode used with the freetype rasterizer. +The following values are possible: + +* `"Normal"` - This corresponds to the default hinting algorithm, optimized for standard gray-level rendering. This is the default setting. +* `"Light"` - A lighter hinting algorithm for non-monochrome modes. Many + generated glyphs are more fuzzy but better resemble its + original shape. A bit like rendering on Mac OS X. +* `"Mono"` - Strong hinting algorithm that should only be used for + monochrome output. The result is probably unpleasant if the + glyph is rendered in non-monochrome modes. +* `"HorizontalLcd"` - A subpixel-rendering variant of `Normal` optimized for horizontally decimated LCD displays. + +See also [freetype_load_flags](freetype_load_flags.md) for more advanced flags +that can be primarily used to influence font hinting. +