Support standard names for freetype hinting flags.

anntzer · anntzer · commit 8167e81a3109 · 2020-05-11T13:08:16.000+02:00
We have a custom mapping of FreeType hinting flags (FT_LOAD_DEFAULT,
FT_LOAD_NO_AUTOHINT, FT_LOAD_FORCE_AUTOHINT, FT_LOAD_NO_HINTING) to our
own string names ("either", "native", "auto", "default") which is
basically not documented anywhere and makes searching the docs tricky,
*even* when one knows where to look for FreeType flags.  Add support for
synonyms which map directly to the standard flag names ("default",
"no_autohint", "force_autohint", "no_hinting") which should at least
make the correspondence more transparent.

There's not much benefit in killing the old synonyms, so I left them in
place.
diff --git a/doc/api/api_changes_3.3/behaviour.rst b/doc/api/api_changes_3.3/behaviour.rst
@@ -278,3 +278,11 @@ Qt and wx backends no longer create a status bar by default
 The coordinates information is now displayed in the toolbar, consistently with
 the other backends.  This is intended to simplify embedding of Matplotlib in
 larger GUIs, where Matplotlib may control the toolbar but not the status bar.
+
+:rc:`text.hinting` now supports names mapping to FreeType flags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:rc:`text.hinting` now supports the values "default", "no_autohint",
+"force_autohint", and "no_hinting", which directly map to the FreeType flags
+FT_LOAD_DEFAULT, etc.  The old synonyms (respectively "either", "native",
+"auto", and "none") are still supported.  To get normalized values, use
+`.backend_agg.get_hinting_flag`, which returns integer flag values.
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -54,13 +54,17 @@
 
 def get_hinting_flag():
     mapping = {
+        'default': LOAD_DEFAULT,
+        'no_autohint': LOAD_NO_AUTOHINT,
+        'force_autohint': LOAD_FORCE_AUTOHINT,
+        'no_hinting': LOAD_NO_HINTING,
         True: LOAD_FORCE_AUTOHINT,
         False: LOAD_NO_HINTING,
         'either': LOAD_DEFAULT,
         'native': LOAD_NO_AUTOHINT,
         'auto': LOAD_FORCE_AUTOHINT,
-        'none': LOAD_NO_HINTING
-        }
+        'none': LOAD_NO_HINTING,
+    }
     return mapping[mpl.rcParams['text.hinting']]
 
 
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -691,9 +691,11 @@ def _validate_hinting(s):
             "True or False is deprecated since %(since)s and will be removed "
             "%(removal)s; set it to its synonyms 'auto' or 'none' instead.")
         return s
-    if s.lower() in ('auto', 'native', 'either', 'none'):
-        return s.lower()
-    raise ValueError("hinting should be 'auto', 'native', 'either' or 'none'")
+    return ValidateInStrings(
+        'text.hinting',
+        ['default', 'no_autohint', 'force_autohint', 'no_hinting',
+         'auto', 'native', 'either', 'none'],
+        ignorecase=True)(s)
 
 
 validate_pgf_texsystem = ValidateInStrings(
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -292,14 +292,15 @@
                         # Adobe Postscript (PSSNFS) font packages may also be
                         # loaded, depending on your font settings.
 
-#text.hinting: auto  # May be one of the following:
-                     #     - none: Perform no hinting
-                     #     - auto: Use FreeType's autohinter
-                     #     - native: Use the hinting information in the
-                     #               font file, if available, and if your
-                     #               FreeType library supports it
-                     #     - either: Use the native hinting information,
-                     #               or the autohinter if none is available.
+## FreeType hinting flag ("foo" corresponds to FT_LOAD_FOO); may be one of the following:
+## - default: Use the font's native hinter if possible, else FreeType's auto-hinter.
+##            ("either" is a synonym).
+## - no_autohint: Use the font's native hinter if possible, else don't hint.
+##                ("native" is a synonym.)
+## - force_autohint: Use FreeType's auto-hinter.  ("auto" is a synonym.)
+## - no_hinting: Disable hinting.  ("none" is a synonym.)
+#text.hinting: force_autohint
+
 #text.hinting_factor: 8  # Specifies the amount of softness for hinting in the
                          # horizontal direction.  A value of 1 will hint to full
                          # pixels.  A value of 2 will hint to half pixels etc.
