Expose face index when loading fonts

This enables loading a non-initial font from collections (`.ttc` files).
Currently exposed for `FT2Font` and `font_manager.get_font`.

Author: QuLogic

lib/matplotlib/font_manager.py

@@ -1556,10 +1556,11 @@ def is_opentype_cff_font(filename):
 @lru_cache(64)
 def _get_font(font_filepaths, hinting_factor, *, _kerning_factor, thread_id,
               enable_last_resort):
-    first_fontpath, *rest = font_filepaths
+    (first_fontpath, first_fontindex), *rest = font_filepaths
     fallback_list = [
-        ft2font.FT2Font(fpath, hinting_factor, _kerning_factor=_kerning_factor)
-        for fpath in rest
+        ft2font.FT2Font(fpath, hinting_factor, face_index=index,
+                        _kerning_factor=_kerning_factor)
+        for fpath, index in rest
     ]
     last_resort_path = _cached_realpath(
         cbook._get_data_path('fonts', 'ttf', 'LastResortHE-Regular.ttf'))
@@ -1576,7 +1577,7 @@ def _get_font(font_filepaths, hinting_factor, *, _kerning_factor, thread_id,
                                 _warn_if_used=True))
             last_resort_index = len(fallback_list)
     font = ft2font.FT2Font(
-        first_fontpath, hinting_factor,
+        first_fontpath, hinting_factor, face_index=first_fontindex,
         _fallback_list=fallback_list,
         _kerning_factor=_kerning_factor
     )
@@ -1611,7 +1612,8 @@ def get_font(font_filepaths, hinting_factor=None):
 
     Parameters
     ----------
-    font_filepaths : Iterable[str, Path, bytes], str, Path, bytes
+    font_filepaths : Iterable[str, Path, bytes, tuple[str | Path | bytes, int]], \
+str, Path, bytes, tuple[str | Path | bytes, int]
         Relative or absolute paths to the font files to be used.
 
         If a single string, bytes, or `pathlib.Path`, then it will be treated
@@ -1626,10 +1628,16 @@ def get_font(font_filepaths, hinting_factor=None):
     `.ft2font.FT2Font`
 
     """
-    if isinstance(font_filepaths, (str, Path, bytes)):
-        paths = (_cached_realpath(font_filepaths),)
-    else:
-        paths = tuple(_cached_realpath(fname) for fname in font_filepaths)
+    match font_filepaths:
+        case str() | Path() | bytes() as path:
+            paths = ((_cached_realpath(path), 0), )
+        case (str() | Path() | bytes() as path, int() as index):
+            paths = ((_cached_realpath(path), index), )
+        case _:
+            paths = tuple(
+                (_cached_realpath(fname[0]), fname[1]) if isinstance(fname, tuple)
+                else (_cached_realpath(fname), 0)
+                for fname in font_filepaths)
 
     hinting_factor = mpl._val_or_rc(hinting_factor, 'text.hinting_factor')
 

lib/matplotlib/font_manager.pyi

@@ -3,11 +3,13 @@ from dataclasses import dataclass
 from numbers import Integral
 import os
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any, Literal, TypeAlias
 
 from matplotlib._afm import AFM
 from matplotlib import ft2font
 
+FontFace: TypeAlias = tuple[str | Path | bytes, int]
+
 font_scalings: dict[str | None, float]
 stretch_dict: dict[str, int]
 weight_dict: dict[str, int]
@@ -120,7 +122,7 @@ class FontManager:
 
 def is_opentype_cff_font(filename: str) -> bool: ...
 def get_font(
-    font_filepaths: Iterable[str | Path | bytes] | str | Path | bytes,
+    font_filepaths: Iterable[str | Path | bytes | FontFace] | str | Path | bytes | FontFace,
     hinting_factor: int | None = ...,
 ) -> ft2font.FT2Font: ...
 

lib/matplotlib/ft2font.pyi

@@ -190,6 +190,7 @@ class FT2Font(Buffer):
         filename: str | BinaryIO,
         hinting_factor: int = ...,
         *,
+        face_index: int = ...,
         _fallback_list: list[FT2Font] | None = ...,
         _kerning_factor: int = ...
     ) -> None: ...

lib/matplotlib/tests/test_ft2font.py

@@ -170,6 +170,24 @@ def test_ft2font_invalid_args(tmp_path):
         ft2font.FT2Font(file, _kerning_factor=1.3)
 
 
+@pytest.mark.parametrize('name, size, skippable',
+                         [('DejaVu Sans', 1, False), ('WenQuanYi Zen Hei', 3, True)])
+def test_ft2font_face_index(name, size, skippable):
+    try:
+        file = fm.findfont(name, fallback_to_default=False)
+    except ValueError:
+        if skippable:
+            pytest.skip(r'Font {name} may be missing')
+        raise
+    for index in range(size):
+        font = ft2font.FT2Font(file, face_index=index)
+        assert font.num_faces >= size
+    with pytest.raises(ValueError, match='must be between'):  # out of bounds for spec
+        ft2font.FT2Font(file, face_index=0x1ffff)
+    with pytest.raises(RuntimeError, match='invalid argument'):  # invalid for this font
+        ft2font.FT2Font(file, face_index=0xff)
+
+
 def test_ft2font_clear():
     file = fm.findfont('DejaVu Sans')
     font = ft2font.FT2Font(file)

src/ft2font.cpp

@@ -207,8 +207,7 @@ FT2Font::get_path(std::vector<double> &vertices, std::vector<unsigned char> &cod
     codes.push_back(CLOSEPOLY);
 }
 
-FT2Font::FT2Font(FT_Open_Args &open_args,
-                 long hinting_factor_,
+FT2Font::FT2Font(FT_Long face_index, FT_Open_Args &open_args, long hinting_factor_,
                  std::vector<FT2Font *> &fallback_list,
                  FT2Font::WarnFunc warn, bool warn_if_used)
     : ft_glyph_warn(warn), warn_if_used(warn_if_used), image({1, 1}), face(nullptr),
@@ -217,7 +216,7 @@ FT2Font::FT2Font(FT_Open_Args &open_args,
       kerning_factor(0)
 {
     clear();
-    FT_CHECK(FT_Open_Face, _ft2Library, &open_args, 0, &face);
+    FT_CHECK(FT_Open_Face, _ft2Library, &open_args, face_index, &face);
     if (open_args.stream != nullptr) {
         face->face_flags |= FT_FACE_FLAG_EXTERNAL_STREAM;
     }

src/ft2font.h

@@ -99,7 +99,7 @@ class FT2Font
     typedef void (*WarnFunc)(FT_ULong charcode, std::set<FT_String*> family_names);
 
   public:
-    FT2Font(FT_Open_Args &open_args, long hinting_factor,
+    FT2Font(FT_Long face_index, FT_Open_Args &open_args, long hinting_factor,
             std::vector<FT2Font *> &fallback_list,
             WarnFunc warn, bool warn_if_used);
     virtual ~FT2Font();

src/ft2font_wrapper.cpp

@@ -426,6 +426,9 @@ const char *PyFT2Font_init__doc__ = R"""(
     hinting_factor : int, optional
         Must be positive. Used to scale the hinting in the x-direction.
 
+    face_index : int, optional
+        The index of the face in the font file to load.
+
     _fallback_list : list of FT2Font, optional
         A list of FT2Font objects used to find missing glyphs.
 
@@ -446,14 +449,18 @@ const char *PyFT2Font_init__doc__ = R"""(
 )""";
 
 static PyFT2Font *
-PyFT2Font_init(py::object filename, long hinting_factor = 8,
+PyFT2Font_init(py::object filename, long hinting_factor = 8, FT_Long face_index = 0,
                std::optional<std::vector<PyFT2Font *>> fallback_list = std::nullopt,
                int kerning_factor = 0, bool warn_if_used = false)
 {
     if (hinting_factor <= 0) {
         throw py::value_error("hinting_factor must be greater than 0");
     }
 
+    if (face_index < 0 || face_index >= 1<<16) {
+        throw std::range_error("face_index must be between 0 and 65535, inclusive");
+    }
+
     PyFT2Font *self = new PyFT2Font();
     self->x = nullptr;
     memset(&self->stream, 0, sizeof(FT_StreamRec));
@@ -497,8 +504,8 @@ PyFT2Font_init(py::object filename, long hinting_factor = 8,
         self->stream.close = nullptr;
     }
 
-    self->x = new FT2Font(open_args, hinting_factor, fallback_fonts, ft_glyph_warn,
-                          warn_if_used);
+    self->x = new FT2Font(face_index, open_args, hinting_factor, fallback_fonts,
+                          ft_glyph_warn, warn_if_used);
 
     self->x->set_kerning_factor(kerning_factor);
 
@@ -1604,7 +1611,7 @@ PYBIND11_MODULE(ft2font, m, py::mod_gil_not_used())
         auto cls = py::class_<PyFT2Font>(m, "FT2Font", py::is_final(), py::buffer_protocol(),
                                          PyFT2Font__doc__)
         .def(py::init(&PyFT2Font_init),
-             "filename"_a, "hinting_factor"_a=8, py::kw_only(),
+             "filename"_a, "hinting_factor"_a=8, py::kw_only(), "face_index"_a=0,
              "_fallback_list"_a=py::none(), "_kerning_factor"_a=0,
              "_warn_if_used"_a=false,
              PyFT2Font_init__doc__)
@@ -1677,8 +1684,12 @@ PYBIND11_MODULE(ft2font, m, py::mod_gil_not_used())
           }, "PostScript name of the font.")
         .def_property_readonly(
           "num_faces", [](PyFT2Font *self) {
-            return self->x->get_face()->num_faces;
+            return self->x->get_face()->num_faces & 0xffff;
           }, "Number of faces in file.")
+        .def_property_readonly(
+          "face_index", [](PyFT2Font *self) {
+            return self->x->get_face()->face_index;
+          }, "The index of the font in the file.")
         .def_property_readonly(
           "family_name", [](PyFT2Font *self) {
             if (const char *name = self->x->get_face()->family_name) {