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

@@ -198,6 +198,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: ...
@@ -261,6 +262,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

@@ -199,6 +199,25 @@ 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
+        assert font.face_index == index
+    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

@@ -222,9 +222,9 @@ FT2Font::~FT2Font()
     close();
 }
 
-void FT2Font::open(FT_Open_Args &open_args)
+void FT2Font::open(FT_Long face_index, FT_Open_Args &open_args)
 {
-    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

@@ -107,7 +107,7 @@ class FT2Font
     FT2Font(long hinting_factor, std::vector<FT2Font *> &fallback_list,
             bool warn_if_used);
     virtual ~FT2Font();
-    void open(FT_Open_Args &open_args);
+    void open(FT_Long face_index, FT_Open_Args &open_args);
     void close();
     void clear();
     void set_size(double ptsize, double dpi);

src/ft2font_wrapper.cpp

@@ -430,6 +430,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.
 
@@ -444,7 +447,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)
@@ -460,6 +463,10 @@ PyFT2Font_init(py::object filename, long hinting_factor = 8,
         kerning_factor = 0;
     }
 
+    if (face_index < 0 || face_index > 0xffff) {
+        throw std::range_error("face_index must be between 0 and 65535, inclusive");
+    }
+
     std::vector<FT2Font *> fallback_fonts;
     if (fallback_list) {
         // go through fallbacks to add them to our lists
@@ -509,7 +516,7 @@ PyFT2Font_init(py::object filename, long hinting_factor = 8,
         self->stream.close = nullptr;
     }
 
-    self->open(open_args);
+    self->open(face_index, open_args);
 
     return self;
 }
@@ -1546,7 +1553,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__)
@@ -1622,8 +1629,12 @@ PYBIND11_MODULE(ft2font, m, py::mod_gil_not_used())
           }, "PostScript name of the font.")
         .def_property_readonly(
           "num_faces", [](PyFT2Font *self) {
-            return self->get_face()->num_faces;
+            return self->get_face()->num_faces & 0xffff;
           }, "Number of faces in file.")
+        .def_property_readonly(
+          "face_index", [](PyFT2Font *self) {
+            return self->get_face()->face_index;
+          }, "The index of the font in the file.")
         .def_property_readonly(
           "family_name", [](PyFT2Font *self) {
             if (const char *name = self->get_face()->family_name) {