Merge pull request matplotlib#31521 from QuLogic/drop-hinting-factor

tacaswell · web-flow · commit e450468d0cc7 · 2026-04-20T23:26:54.000-04:00
Drop support for font hinting factor
diff --git a/doc/api/next_api_changes/deprecations/31521-ES.rst b/doc/api/next_api_changes/deprecations/31521-ES.rst
@@ -0,0 +1,7 @@
+Font hinting factor is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Due to internal changes to support complex text rendering, the hinting factor on fonts is
+no longer used. Setting the ``text.hinting_factor`` rcParam to any value other than None
+is deprecated, and the rcParam will be removed in the future. Likewise, passing the
+``hinting_factor`` argument to the `.FT2Font` constructor is deprecated.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -779,8 +779,8 @@ def __setitem__(self, key, val):
             cval = valid_key(val)
         except ValueError as ve:
             raise ValueError(f"Key {key}: {ve}") from None
-        if key == "text.kerning_factor" and cval is not None:
-           _api.warn_deprecated("3.11", name="text.kerning_factor", obj_type="rcParam")
+        if key in {"text.hinting_factor", "text.kerning_factor"} and cval is not None:
+            _api.warn_deprecated("3.11", name=key, obj_type="rcParam")
         self._set(key, cval)
 
     def __getitem__(self, key):
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -179,11 +179,9 @@ def _draw_text_glyphs_and_boxes(self, gc, x, y, angle, glyphs, boxes):
         load_flags = get_hinting_flag()
         for font, size, glyph_index, slant, extend, dx, dy in glyphs:  # dy is upwards.
             font.set_size(size, self.dpi)
-            hf = font._hinting_factor
             font._set_transform(
                 (0x10000 * np.array([[cos, -sin], [sin, cos]])
-                 @ [[extend, extend * slant], [0, 1]]
-                 @ [[1 / hf, 0], [0, 1]]).round().astype(int),
+                 @ [[extend, extend * slant], [0, 1]]).round().astype(int),
                 [round(0x40 * (x + dx * cos - dy * sin)),
                  # FreeType's y is upwards.
                  round(0x40 * (self.height - y + dx * sin + dy * cos))]
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -597,7 +597,7 @@ def _flush(self):
 
 
 def _get_pdf_charprocs(font_path, glyph_indices):
-    font = get_font(font_path, hinting_factor=1)
+    font = get_font(font_path)
     conv = 1000 / font.units_per_EM  # Conversion to PS units (1/1000's).
     procs = {}
     for glyph_index in glyph_indices:
diff --git a/lib/matplotlib/backends/backend_ps.py b/lib/matplotlib/backends/backend_ps.py
@@ -107,7 +107,7 @@ def _font_to_ps_type3(font_path, subset_index, glyph_indices):
         The string representation of a Type 3 font, which can be included
         verbatim into a PostScript file.
     """
-    font = get_font(font_path, hinting_factor=1)
+    font = get_font(font_path)
 
     preamble = """\
 %!PS-Adobe-3.0 Resource-Font
diff --git a/lib/matplotlib/dviread.py b/lib/matplotlib/dviread.py
@@ -1026,7 +1026,7 @@ def get_metrics(self, idx):
 
 class TtfMetrics:
     def __init__(self, filename):
-        self._face = font_manager.get_font(filename, hinting_factor=1)
+        self._face = font_manager.get_font(filename)
 
     def get_metrics(self, idx):
         # _mul1220 uses a truncating bitshift for compatibility with dvitype.
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -1731,11 +1731,11 @@ def is_opentype_cff_font(filename):
 
 
 @lru_cache(64)
-def _get_font(font_filepaths, hinting_factor, *, _kerning_factor, thread_id,
+def _get_font(font_filepaths, *, _kerning_factor, thread_id,
               enable_last_resort):
     (first_fontpath, first_fontindex), *rest = font_filepaths
     fallback_list = [
-        ft2font.FT2Font(fpath, hinting_factor, face_index=index,
+        ft2font.FT2Font(fpath, face_index=index,
                         _kerning_factor=_kerning_factor)
         for fpath, index in rest
     ]
@@ -1749,12 +1749,12 @@ def _get_font(font_filepaths, hinting_factor, *, _kerning_factor, thread_id,
         # already in the list.
         if enable_last_resort:
             fallback_list.append(
-                ft2font.FT2Font(last_resort_path, hinting_factor,
+                ft2font.FT2Font(last_resort_path,
                                 _kerning_factor=_kerning_factor,
                                 _warn_if_used=True))
             last_resort_index = len(fallback_list)
     font = ft2font.FT2Font(
-        first_fontpath, hinting_factor, face_index=first_fontindex,
+        first_fontpath, face_index=first_fontindex,
         _fallback_list=fallback_list,
         _kerning_factor=_kerning_factor
     )
@@ -1783,6 +1783,7 @@ def _cached_realpath(path):
     return os.path.realpath(path)
 
 
+@_api.delete_parameter('3.11', 'hinting_factor')
 def get_font(font_filepaths, hinting_factor=None):
     """
     Get an `.ft2font.FT2Font` object given a list of file paths.
@@ -1816,20 +1817,16 @@ def get_font(font_filepaths, hinting_factor=None):
                 if isinstance(fname, FontPath) else (_cached_realpath(fname), 0)
                 for fname in font_filepaths)
 
-    hinting_factor = mpl._val_or_rc(hinting_factor, 'text.hinting_factor')
-
     font = _get_font(
         # must be a tuple to be cached
         paths,
-        hinting_factor,
         _kerning_factor=mpl.rcParams['text.kerning_factor'],
         # also key on the thread ID to prevent segfaults with multi-threading
         thread_id=threading.get_ident(),
         enable_last_resort=mpl.rcParams['font.enable_last_resort'],
     )
     # Ensure the transform is always consistent.
-    font._set_transform([[round(0x10000 / font._hinting_factor), 0], [0, 0x10000]],
-                        [0, 0])
+    font._set_transform([[0x10000, 0], [0, 0x10000]], [0, 0])
     return font
 
 
diff --git a/lib/matplotlib/font_manager.pyi b/lib/matplotlib/font_manager.pyi
@@ -142,7 +142,6 @@ class FontManager:
 def is_opentype_cff_font(filename: str) -> bool: ...
 def get_font(
     font_filepaths: Iterable[str | bytes | os.PathLike | FontPath] | str | bytes | os.PathLike | FontPath,
-    hinting_factor: int | None = ...,
 ) -> ft2font.FT2Font: ...
 
 fontManager: FontManager
diff --git a/lib/matplotlib/ft2font.pyi b/lib/matplotlib/ft2font.pyi
@@ -236,7 +236,6 @@ class FT2Font(Buffer):
     def __init__(
         self,
         filename: str | bytes | PathLike | BinaryIO,
-        hinting_factor: int = ...,
         *,
         face_index: int = ...,
         _fallback_list: list[FT2Font] | None = ...,
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -308,9 +308,7 @@
 ## - no_hinting: Disable hinting.  ("none" is a synonym.)
 #text.hinting: default
 
-#text.hinting_factor: 1  # 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.
+#text.hinting_factor: None  # This setting does nothing and is deprecated.
 #text.kerning_factor: None  # Specifies the scaling factor for kerning values. Values
                             # other than 0, 6, or None have no defined meaning.
                             # This setting is deprecated.
diff --git a/lib/matplotlib/mpl-data/stylelib/_classic_test_patch.mplstyle b/lib/matplotlib/mpl-data/stylelib/_classic_test_patch.mplstyle
@@ -6,4 +6,3 @@ ytick.alignment: center_baseline
 hatch.color: edge
 
 text.hinting: default
-text.hinting_factor: 1
diff --git a/lib/matplotlib/mpl-data/stylelib/bmh.mplstyle b/lib/matplotlib/mpl-data/stylelib/bmh.mplstyle
@@ -8,8 +8,6 @@ patch.facecolor: blue
 patch.edgecolor: eeeeee
 patch.antialiased: True
 
-text.hinting_factor : 8
-
 mathtext.fontset : cm
 
 axes.facecolor: eeeeee
diff --git a/lib/matplotlib/mpl-data/stylelib/classic.mplstyle b/lib/matplotlib/mpl-data/stylelib/classic.mplstyle
@@ -137,9 +137,6 @@ text.hinting : auto   # May be one of the following:
                       #             or the autohinter if none is available.
                       # For backward compatibility, this value may also be
                       # True === 'auto' or False === 'none'.
-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.
 
 text.antialiased : True # If True (default), the text will be antialiased.
                         # This only affects the Agg backend.
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1115,7 +1115,7 @@ def _convert_validator_spec(key, conv):
     "text.latex.preamble": validate_string,
     "text.hinting":        ["default", "no_autohint", "force_autohint",
                             "no_hinting", "auto", "native", "either", "none"],
-    "text.hinting_factor": validate_int,
+    "text.hinting_factor": validate_int_or_None,
     "text.kerning_factor": validate_int_or_None,
     "text.antialiased":    validate_bool,
     "text.parse_math":     validate_bool,
@@ -1875,11 +1875,9 @@ class _Subsection:
     ),
     _Param(
         "text.hinting_factor",
-        default=1,
-        validator=validate_int,
-        description="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."
+        default=None,
+        validator=validate_int_or_None,
+        description="[DEPRECATED] This setting has no effect."
     ),
     _Param(
         "text.kerning_factor",
diff --git a/lib/matplotlib/testing/__init__.py b/lib/matplotlib/testing/__init__.py
@@ -20,7 +20,6 @@
 def set_font_settings_for_testing():
     mpl.rcParams['font.family'] = 'DejaVu Sans'
     mpl.rcParams['text.hinting'] = 'default'
-    mpl.rcParams['text.hinting_factor'] = 1
 
 
 def set_reproducibility_for_testing():
diff --git a/lib/matplotlib/tests/test_font_manager.py b/lib/matplotlib/tests/test_font_manager.py
@@ -8,7 +8,6 @@
 import sys
 import warnings
 
-import numpy as np
 import pytest
 
 from unittest.mock import MagicMock, patch
@@ -118,25 +117,6 @@ def test_get_fontconfig_fonts():
     assert len(_get_fontconfig_fonts()) > 1
 
 
-@pytest.mark.parametrize('factor', [2, 4, 6, 8])
-def test_hinting_factor(factor):
-    font = findfont(FontProperties(family=["sans-serif"]))
-
-    font1 = get_font(font, hinting_factor=1)
-    font1.clear()
-    font1.set_size(12, 100)
-    font1.set_text('abc')
-    expected = font1.get_width_height()
-
-    hinted_font = get_font(font, hinting_factor=factor)
-    hinted_font.clear()
-    hinted_font.set_size(12, 100)
-    hinted_font.set_text('abc')
-    # Check that hinting only changes text layout by a small (10%) amount.
-    np.testing.assert_allclose(hinted_font.get_width_height(), expected,
-                               rtol=0.1)
-
-
 def test_utf16m_sfnt():
     try:
         # seguisbi = Microsoft Segoe UI Semibold
diff --git a/lib/matplotlib/tests/test_ft2font.py b/lib/matplotlib/tests/test_ft2font.py
@@ -179,7 +179,11 @@ def test_ft2font_invalid_args(tmp_path):
     # hinting_factor argument.
     with pytest.raises(TypeError, match='incompatible constructor arguments'):
         ft2font.FT2Font(file, 1.3)
-    with pytest.raises(ValueError, match='hinting_factor must be greater than 0'):
+    with pytest.warns(mpl.MatplotlibDeprecationWarning,
+                      match='text.hinting_factor rcParam was deprecated .+ 3.11'):
+        mpl.rcParams['text.hinting_factor'] = 8
+    with pytest.warns(mpl.MatplotlibDeprecationWarning,
+                      match='The hinting_factor parameter was deprecated'):
         ft2font.FT2Font(file, 0)
 
     with pytest.raises(TypeError, match='incompatible constructor arguments'):
@@ -236,7 +240,7 @@ def test_ft2font_clear():
 
 def test_ft2font_set_size():
     file = fm.findfont('DejaVu Sans')
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     font.set_size(12, 72)
     font.set_text('ABabCDcd')
     orig = font.get_width_height()
@@ -791,7 +795,7 @@ def test_ft2font_get_sfnt_table(font_name, header):
 def test_ft2font_get_kerning(left, right, unscaled, unfitted, default):
     file = fm.findfont('DejaVu Sans')
     # With unscaled, these settings should produce exact values found in FontForge.
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     font.set_size(100, 100)
     assert font.get_kerning(font.get_char_index(ord(left)),
                             font.get_char_index(ord(right)),
@@ -830,7 +834,7 @@ def test_ft2font_get_kerning(left, right, unscaled, unfitted, default):
 
 def test_ft2font_set_text():
     file = fm.findfont('DejaVu Sans')
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     font.set_size(12, 72)
     xys = font.set_text('')
     np.testing.assert_array_equal(xys, np.empty((0, 2)))
@@ -867,23 +871,23 @@ def test_ft2font_set_text():
 )
 def test_ft2font_language_invalid(input):
     file = fm.findfont('DejaVu Sans')
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     with pytest.raises(TypeError):
         font.set_text('foo', language=input)
 
 
 def test_ft2font_language():
     # This is just a smoke test.
     file = fm.findfont('DejaVu Sans')
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     font.set_text('foo')
     font.set_text('foo', language='en')
     font.set_text('foo', language=[('en', 1, 2)])
 
 
 def test_ft2font_loading():
     file = fm.findfont('DejaVu Sans')
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     font.set_size(12, 72)
     for glyph in [font.load_char(ord('M')),
                   font.load_glyph(font.get_char_index(ord('M')))]:
@@ -924,13 +928,13 @@ def test_ft2font_drawing():
     ])
     expected *= 255
     file = fm.findfont('DejaVu Sans')
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     font.set_size(12, 72)
     font.set_text('M')
     font.draw_glyphs_to_bitmap(antialiased=False)
     image = font.get_image()
     np.testing.assert_array_equal(image, expected)
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     font.set_size(12, 72)
     glyph = font.load_char(ord('M'))
     image = np.zeros(expected.shape, np.uint8)
@@ -940,7 +944,7 @@ def test_ft2font_drawing():
 
 def test_ft2font_get_path():
     file = fm.findfont('DejaVu Sans')
-    font = ft2font.FT2Font(file, hinting_factor=1)
+    font = ft2font.FT2Font(file)
     font.set_size(12, 72)
     vertices, codes = font.get_path()
     assert vertices.shape == (0, 2)
diff --git a/lib/matplotlib/tests/test_text.py b/lib/matplotlib/tests/test_text.py
@@ -591,20 +591,6 @@ def test_nonfinite_pos():
     fig.canvas.draw()
 
 
-def test_hinting_factor_backends():
-    plt.rcParams['text.hinting_factor'] = 1
-    fig = plt.figure()
-    t = fig.text(0.5, 0.5, 'some text')
-
-    fig.savefig(io.BytesIO(), format='svg')
-    expected = t.get_window_extent().intervalx
-
-    fig.savefig(io.BytesIO(), format='png')
-    # Backends should apply hinting_factor consistently (within 10%).
-    np.testing.assert_allclose(t.get_window_extent().intervalx, expected,
-                               rtol=0.1)
-
-
 @needs_usetex
 def test_usetex_is_copied():
     # Indirectly tests that update_from (which is used to copy tick label
diff --git a/src/ft2font.cpp b/src/ft2font.cpp
@@ -207,10 +207,8 @@ FT2Font::get_path(std::vector<double> &vertices, std::vector<unsigned char> &cod
     codes.push_back(CLOSEPOLY);
 }
 
-FT2Font::FT2Font(long hinting_factor_, std::vector<FT2Font *> &fallback_list,
-                 bool warn_if_used)
+FT2Font::FT2Font(std::vector<FT2Font *> &fallback_list, bool warn_if_used)
     : warn_if_used(warn_if_used), image({1, 1}), face(nullptr), fallbacks(fallback_list),
-      hinting_factor(hinting_factor_),
       // set default kerning factor to 0, i.e., no kerning manipulation
       kerning_factor(0)
 {
@@ -274,8 +272,8 @@ void FT2Font::set_size(double ptsize, double dpi)
 {
     FT_CHECK(
         FT_Set_Char_Size,
-        face, (FT_F26Dot6)(ptsize * 64), 0, (FT_UInt)(dpi * hinting_factor), (FT_UInt)dpi);
-    FT_Matrix transform = { 65536 / hinting_factor, 0, 0, 65536 };
+        face, (FT_F26Dot6)(ptsize * 64), 0, (FT_UInt)dpi, (FT_UInt)dpi);
+    FT_Matrix transform = { 65536, 0, 0, 65536 };
     FT_Set_Transform(face, &transform, nullptr);
 
     for (auto & fallback : fallbacks) {
@@ -315,7 +313,7 @@ int FT2Font::get_kerning(FT_UInt left, FT_UInt right, FT_Kerning_Mode mode)
 
     FT_Vector delta;
     if (!FT_Get_Kerning(face, left, right, mode, &delta)) {
-        return (int)(delta.x) / (hinting_factor << kerning_factor);
+        return (int)(delta.x) / (1 << kerning_factor);
     } else {
         return 0;
     }
@@ -527,11 +525,7 @@ void FT2Font::set_text(
         bbox.yMin = std::min(bbox.yMin, glyph_bbox.yMin);
         bbox.yMax = std::max(bbox.yMax, glyph_bbox.yMax);
 
-        if ((flags & FT_LOAD_NO_HINTING) != 0) {
-            pen.x += rglyph.x_advance - rglyph.x_offset;
-        } else {
-            pen.x += hinting_factor * rglyph.x_advance - rglyph.x_offset;
-        }
+        pen.x += rglyph.x_advance - rglyph.x_offset;
         pen.y += rglyph.y_advance - rglyph.y_offset;
 
         glyphs.push_back(thisGlyph);
diff --git a/src/ft2font.h b/src/ft2font.h
diff --git a/src/ft2font_wrapper.cpp b/src/ft2font_wrapper.cpp
