ft2font: Convert loading flags into an enum

Unfortunately, FreeType doesn't define this as an enum of any sort, just
as a bunch of macro `#define`s. So we have to make our own for pybind11
to bind.

Author: QuLogic

doc/api/next_api_changes/deprecations/28842-ES.rst

@@ -10,3 +10,27 @@ prefix):
 - ``KERNING_DEFAULT``
 - ``KERNING_UNFITTED``
 - ``KERNING_UNSCALED``
+
+The following constants are now part of `.ft2font.LoadFlags` (without the ``LOAD_``
+prefix):
+
+- ``LOAD_DEFAULT``
+- ``LOAD_NO_SCALE``
+- ``LOAD_NO_HINTING``
+- ``LOAD_RENDER``
+- ``LOAD_NO_BITMAP``
+- ``LOAD_VERTICAL_LAYOUT``
+- ``LOAD_FORCE_AUTOHINT``
+- ``LOAD_CROP_BITMAP``
+- ``LOAD_PEDANTIC``
+- ``LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH``
+- ``LOAD_NO_RECURSE``
+- ``LOAD_IGNORE_TRANSFORM``
+- ``LOAD_MONOCHROME``
+- ``LOAD_LINEAR_DESIGN``
+- ``LOAD_NO_AUTOHINT``
+- ``LOAD_TARGET_NORMAL``
+- ``LOAD_TARGET_LIGHT``
+- ``LOAD_TARGET_MONO``
+- ``LOAD_TARGET_LCD``
+- ``LOAD_TARGET_LCD_V``

lib/matplotlib/_mathtext.py

@@ -29,7 +29,7 @@
 from ._mathtext_data import (
     latex_to_bakoma, stix_glyph_fixes, stix_virtual_fonts, tex2uni)
 from .font_manager import FontProperties, findfont, get_font
-from .ft2font import FT2Font, FT2Image, Kerning
+from .ft2font import FT2Font, FT2Image, Kerning, LoadFlags
 
 from packaging.version import parse as parse_version
 from pyparsing import __version__ as pyparsing_version
@@ -227,14 +227,14 @@ class Fonts(abc.ABC):
     to do the actual drawing.
     """
 
-    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: int):
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
         """
         Parameters
         ----------
         default_font_prop : `~.font_manager.FontProperties`
             The default non-math font, or the base font for Unicode (generic)
             font rendering.
-        load_glyph_flags : int
+        load_glyph_flags : `.ft2font.LoadFlags`
             Flags passed to the glyph loader (e.g. ``FT_Load_Glyph`` and
             ``FT_Load_Char`` for FreeType-based fonts).
         """
@@ -332,7 +332,7 @@ class TruetypeFonts(Fonts, metaclass=abc.ABCMeta):
     (through FT2Font).
     """
 
-    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: int):
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
         super().__init__(default_font_prop, load_glyph_flags)
         # Per-instance cache.
         self._get_info = functools.cache(self._get_info)  # type: ignore[method-assign]
@@ -448,7 +448,7 @@ class BakomaFonts(TruetypeFonts):
         'ex':  'cmex10',
     }
 
-    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: int):
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
         self._stix_fallback = StixFonts(default_font_prop, load_glyph_flags)
 
         super().__init__(default_font_prop, load_glyph_flags)
@@ -557,7 +557,7 @@ class UnicodeFonts(TruetypeFonts):
         0x2212: 0x00A1,  # Minus sign.
     }
 
-    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: int):
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
         # This must come first so the backend's owner is set correctly
         fallback_rc = mpl.rcParams['mathtext.fallback']
         font_cls: type[TruetypeFonts] | None = {
@@ -672,7 +672,7 @@ def get_sized_alternatives_for_symbol(self, fontname: str,
 class DejaVuFonts(UnicodeFonts, metaclass=abc.ABCMeta):
     _fontmap: dict[str | int, str] = {}
 
-    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: int):
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
         # This must come first so the backend's owner is set correctly
         if isinstance(self, DejaVuSerifFonts):
             self._fallback_font = StixFonts(default_font_prop, load_glyph_flags)
@@ -776,7 +776,7 @@ class StixFonts(UnicodeFonts):
     _fallback_font = None
     _sans = False
 
-    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: int):
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
         TruetypeFonts.__init__(self, default_font_prop, load_glyph_flags)
         for key, name in self._fontmap.items():
             fullpath = findfont(name)

lib/matplotlib/_text_helpers.py

@@ -7,7 +7,7 @@
 import dataclasses
 
 from . import _api
-from .ft2font import LOAD_NO_HINTING, FT2Font, Kerning
+from .ft2font import FT2Font, Kerning, LoadFlags
 
 
 @dataclasses.dataclass(frozen=True)
@@ -76,7 +76,7 @@ def layout(string, font, *, kern_mode=Kerning.DEFAULT):
             if prev_glyph_idx is not None else 0.
         )
         x += kern
-        glyph = font.load_glyph(glyph_idx, flags=LOAD_NO_HINTING)
+        glyph = font.load_glyph(glyph_idx, flags=LoadFlags.NO_HINTING)
         yield LayoutItem(font, char, glyph_idx, x, kern)
         x += glyph.linearHoriAdvance / 65536
         prev_glyph_idx = glyph_idx

lib/matplotlib/backends/_backend_pdf_ps.py

@@ -123,7 +123,7 @@ def get_text_width_height_descent(self, s, prop, ismath):
             return w, h, d
         else:
             font = self._get_font_ttf(prop)
-            font.set_text(s, 0.0, flags=ft2font.LOAD_NO_HINTING)
+            font.set_text(s, 0.0, flags=ft2font.LoadFlags.NO_HINTING)
             w, h = font.get_width_height()
             d = font.get_descent()
             scale = 1 / 64

lib/matplotlib/backends/backend_agg.py

@@ -31,8 +31,7 @@
 from matplotlib.backend_bases import (
     _Backend, FigureCanvasBase, FigureManagerBase, RendererBase)
 from matplotlib.font_manager import fontManager as _fontManager, get_font
-from matplotlib.ft2font import (LOAD_FORCE_AUTOHINT, LOAD_NO_HINTING,
-                                LOAD_DEFAULT, LOAD_NO_AUTOHINT)
+from matplotlib.ft2font import LoadFlags
 from matplotlib.mathtext import MathTextParser
 from matplotlib.path import Path
 from matplotlib.transforms import Bbox, BboxBase
@@ -41,16 +40,16 @@
 
 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,
+        'default': LoadFlags.DEFAULT,
+        'no_autohint': LoadFlags.NO_AUTOHINT,
+        'force_autohint': LoadFlags.FORCE_AUTOHINT,
+        'no_hinting': LoadFlags.NO_HINTING,
+        True: LoadFlags.FORCE_AUTOHINT,
+        False: LoadFlags.NO_HINTING,
+        'either': LoadFlags.DEFAULT,
+        'native': LoadFlags.NO_AUTOHINT,
+        'auto': LoadFlags.FORCE_AUTOHINT,
+        'none': LoadFlags.NO_HINTING,
     }
     return mapping[mpl.rcParams['text.hinting']]
 

lib/matplotlib/backends/backend_pdf.py

@@ -35,8 +35,7 @@
 from matplotlib.figure import Figure
 from matplotlib.font_manager import get_font, fontManager as _fontManager
 from matplotlib._afm import AFM
-from matplotlib.ft2font import (FIXED_WIDTH, ITALIC, LOAD_NO_SCALE,
-                                LOAD_NO_HINTING, FT2Font, Kerning)
+from matplotlib.ft2font import FIXED_WIDTH, ITALIC, FT2Font, Kerning, LoadFlags
 from matplotlib.transforms import Affine2D, BboxBase
 from matplotlib.path import Path
 from matplotlib.dates import UTC
@@ -617,7 +616,7 @@ def _get_pdf_charprocs(font_path, glyph_ids):
     conv = 1000 / font.units_per_EM  # Conversion to PS units (1/1000's).
     procs = {}
     for glyph_id in glyph_ids:
-        g = font.load_glyph(glyph_id, LOAD_NO_SCALE)
+        g = font.load_glyph(glyph_id, LoadFlags.NO_SCALE)
         # NOTE: We should be using round(), but instead use
         # "(x+.5).astype(int)" to keep backcompat with the old ttconv code
         # (this is different for negative x's).
@@ -1185,7 +1184,7 @@ def embedTTFType3(font, characters, descriptor):
             def get_char_width(charcode):
                 s = ord(cp1252.decoding_table[charcode])
                 width = font.load_char(
-                    s, flags=LOAD_NO_SCALE | LOAD_NO_HINTING).horiAdvance
+                    s, flags=LoadFlags.NO_SCALE | LoadFlags.NO_HINTING).horiAdvance
                 return cvt(width)
             with warnings.catch_warnings():
                 # Ignore 'Required glyph missing from current font' warning
@@ -1321,7 +1320,7 @@ def embedTTFType42(font, characters, descriptor):
                 ccode = c
                 gind = font.get_char_index(ccode)
                 glyph = font.load_char(ccode,
-                                       flags=LOAD_NO_SCALE | LOAD_NO_HINTING)
+                                       flags=LoadFlags.NO_SCALE | LoadFlags.NO_HINTING)
                 widths.append((ccode, cvt(glyph.horiAdvance)))
                 if ccode < 65536:
                     cid_to_gid_map[ccode] = chr(gind)

lib/matplotlib/backends/backend_ps.py

@@ -25,7 +25,7 @@
     _Backend, FigureCanvasBase, FigureManagerBase, RendererBase)
 from matplotlib.cbook import is_writable_file_like, file_requires_unicode
 from matplotlib.font_manager import get_font
-from matplotlib.ft2font import LOAD_NO_SCALE, FT2Font
+from matplotlib.ft2font import FT2Font, LoadFlags
 from matplotlib._ttconv import convert_ttf_to_ps
 from matplotlib._mathtext_data import uni2type1
 from matplotlib.path import Path
@@ -160,7 +160,7 @@ def _font_to_ps_type3(font_path, chars):
 
     entries = []
     for glyph_id in glyph_ids:
-        g = font.load_glyph(glyph_id, LOAD_NO_SCALE)
+        g = font.load_glyph(glyph_id, LoadFlags.NO_SCALE)
         v, c = font.get_path()
         entries.append(
             "/%(name)s{%(bbox)s sc\n" % {

lib/matplotlib/ft2font.pyi

@@ -1,4 +1,4 @@
-from enum import Enum
+from enum import Enum, Flag
 import sys
 from typing import BinaryIO, Literal, TypedDict, final, overload
 from typing_extensions import Buffer  # < Py 3.12
@@ -17,26 +17,6 @@ GLYPH_NAMES: int
 HORIZONTAL: int
 ITALIC: int
 KERNING: int
-LOAD_CROP_BITMAP: int
-LOAD_DEFAULT: int
-LOAD_FORCE_AUTOHINT: int
-LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH: int
-LOAD_IGNORE_TRANSFORM: int
-LOAD_LINEAR_DESIGN: int
-LOAD_MONOCHROME: int
-LOAD_NO_AUTOHINT: int
-LOAD_NO_BITMAP: int
-LOAD_NO_HINTING: int
-LOAD_NO_RECURSE: int
-LOAD_NO_SCALE: int
-LOAD_PEDANTIC: int
-LOAD_RENDER: int
-LOAD_TARGET_LCD: int
-LOAD_TARGET_LCD_V: int
-LOAD_TARGET_LIGHT: int
-LOAD_TARGET_MONO: int
-LOAD_TARGET_NORMAL: int
-LOAD_VERTICAL_LAYOUT: int
 MULTIPLE_MASTERS: int
 SCALABLE: int
 SFNT: int
@@ -47,6 +27,33 @@ class Kerning(Enum):
     UNFITTED: int
     UNSCALED: int
 
+class LoadFlags(Flag):
+    DEFAULT: int
+    NO_SCALE: int
+    NO_HINTING: int
+    RENDER: int
+    NO_BITMAP: int
+    VERTICAL_LAYOUT: int
+    FORCE_AUTOHINT: int
+    CROP_BITMAP: int
+    PEDANTIC: int
+    IGNORE_GLOBAL_ADVANCE_WIDTH: int
+    NO_RECURSE: int
+    IGNORE_TRANSFORM: int
+    MONOCHROME: int
+    LINEAR_DESIGN: int
+    NO_AUTOHINT: int
+    COLOR: int
+    COMPUTE_METRICS: int  # FT 2.6.1
+    # BITMAP_METRICS_ONLY: int  # FT 2.7.1
+    # NO_SVG: int  # FT 2.13.1
+    # The following should be unique, but the above can be OR'd together.
+    TARGET_NORMAL: int
+    TARGET_LIGHT: int
+    TARGET_MONO: int
+    TARGET_LCD: int
+    TARGET_LCD_V: int
+
 class _SfntHeadDict(TypedDict):
     version: tuple[int, int]
     fontRevision: tuple[int, int]
@@ -210,13 +217,13 @@ class FT2Font(Buffer):
     @overload
     def get_sfnt_table(self, name: Literal["pclt"]) -> _SfntPcltDict | None: ...
     def get_width_height(self) -> tuple[int, int]: ...
-    def load_char(self, charcode: int, flags: int = ...) -> Glyph: ...
-    def load_glyph(self, glyphindex: int, flags: int = ...) -> Glyph: ...
+    def load_char(self, charcode: int, flags: LoadFlags = ...) -> Glyph: ...
+    def load_glyph(self, glyphindex: int, flags: LoadFlags = ...) -> Glyph: ...
     def select_charmap(self, i: int) -> None: ...
     def set_charmap(self, i: int) -> None: ...
     def set_size(self, ptsize: float, dpi: float) -> None: ...
     def set_text(
-        self, string: str, angle: float = ..., flags: int = ...
+        self, string: str, angle: float = ..., flags: LoadFlags = ...
     ) -> NDArray[np.float64]: ...
     @property
     def ascender(self) -> int: ...

lib/matplotlib/mathtext.py

@@ -20,7 +20,7 @@
 
 import matplotlib as mpl
 from matplotlib import _api, _mathtext
-from matplotlib.ft2font import LOAD_NO_HINTING
+from matplotlib.ft2font import LoadFlags
 from matplotlib.font_manager import FontProperties
 from ._mathtext import (  # noqa: F401, reexported API
     RasterParse, VectorParse, get_unicode_index)
@@ -80,7 +80,7 @@ def parse(self, s, dpi=72, prop=None, *, antialiased=None):
         antialiased = mpl._val_or_rc(antialiased, 'text.antialiased')
         from matplotlib.backends import backend_agg
         load_glyph_flags = {
-            "vector": LOAD_NO_HINTING,
+            "vector": LoadFlags.NO_HINTING,
             "raster": backend_agg.get_hinting_flag(),
         }[self._output_type]
         return self._parse_cached(s, dpi, prop, antialiased, load_glyph_flags)

lib/matplotlib/tests/test_font_manager.py

@@ -250,7 +250,7 @@ def test_missing_family(caplog):
 
 def _test_threading():
     import threading
-    from matplotlib.ft2font import LOAD_NO_HINTING
+    from matplotlib.ft2font import LoadFlags
     import matplotlib.font_manager as fm
 
     def loud_excepthook(args):
@@ -265,7 +265,7 @@ def bad_idea(n):
         b.wait(timeout=5)
         for j in range(100):
             font = fm.get_font(fm.findfont("DejaVu Sans"))
-            font.set_text(str(n), 0.0, flags=LOAD_NO_HINTING)
+            font.set_text(str(n), 0.0, flags=LoadFlags.NO_HINTING)
 
     threads = [
         threading.Thread(target=bad_idea, name=f"bad_thread_{j}", args=(j,))