Expose face index when loading fonts

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

Author: QuLogic

lib/matplotlib/ft2font.pyi

@@ -191,6 +191,7 @@ class FT2Font(Buffer):
         filename: str | bytes | PathLike | BinaryIO,
         hinting_factor: int = ...,
         *,
+        face_index: int = ...,
         _fallback_list: list[FT2Font] | None = ...,
         _kerning_factor: int | None = ...
     ) -> None: ...
@@ -248,6 +249,8 @@ class FT2Font(Buffer):
     @property
     def face_flags(self) -> FaceFlags: ...
     @property
+    def face_index(self) -> int: ...
+    @property
     def family_name(self) -> str: ...
     @property
     def fname(self) -> str | bytes: ...

lib/matplotlib/tests/test_ft2font.py

@@ -198,6 +198,24 @@ def test_ft2font_invalid_args(tmp_path):
         ft2font.FT2Font(file, _kerning_factor=123)
 
 
+@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.
 
@@ -440,7 +443,7 @@ 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,
                std::optional<int> kerning_factor = std::nullopt,
                bool warn_if_used = false)
@@ -456,6 +459,10 @@ PyFT2Font_init(py::object filename, long hinting_factor = 8,
         kerning_factor = 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));
@@ -502,8 +509,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);
 
@@ -1609,7 +1616,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=py::none(),
              "_warn_if_used"_a=false,
              PyFT2Font_init__doc__)
@@ -1682,8 +1689,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) {