docs for freetype_load_target and deprecation of font_antialias

refs: #491

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
+        /// anti-aliased modes.
-        /// implied by FT_LOAD_NO_SCALE.
         const NO_HINTING = 2;
         const NO_BITMAP = 8;
         /// Indicates that the auto-hinter is preferred over the

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

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`.

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`.

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"
+}
+```
+

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.
+