Implement support for OpenType font variations

This works similar to OpenType font features, in that you tack on an
additional string to the path with a pipe, e.g.,
`font.ttf|feat=1|vari=2` specifies `font.ttf` with features of `feat=1`
and variations of `vari=2`.

Author: QuLogic

README.rst

@@ -33,7 +33,8 @@ Noteworthy points include:
   kerning; floating point surfaces are supported with cairo≥1.17.2).
 - Optional multithreaded drawing of markers and path collections.
 - Optional support for complex text layout (right-to-left languages, etc.) and
-  OpenType font features (see `examples/opentype_features.py`_), and partial
+  OpenType font features (see `examples/opentype_features.py`_) and variations
+  (see `examples/opentype_variations.py`_) (requires cairo≥1.16.0), and partial
   support for color fonts (e.g., emojis), using Raqm_.  **Note** that Raqm
   depends by default on Fribidi, which is licensed under the LGPLv2.1+.
 - Support for embedding URLs in PDF (but not SVG) output (requires
@@ -49,6 +50,7 @@ Noteworthy points include:
 .. _Matplotlib: http://matplotlib.org/
 .. _Raqm: https://github.com/HOST-Oman/libraqm
 .. _examples/opentype_features.py: examples/opentype_features.py
+.. _examples/opentype_variations.py: examples/opentype_variations.py
 .. _examples/operators.py: examples/operators.py
 
 Installation
@@ -106,6 +108,9 @@ path <add_dll_directory_>`_).
    cairo 1.15.4 added support for PDF metadata and links; the presence of this
    feature is detected at runtime.
 
+   cairo 1.16.0 added support for font variations; the presence of this feature
+   is detected at runtime.
+
    cairo 1.17.2 added support for floating point surfaces, usable with
    ``mplcairo.set_options(float_surface=True)``; the presence of this feature
    is detected at runtime.  However, cairo 1.17.2 (and only that version) also
@@ -456,7 +461,16 @@ language_ tag can likewise be set with ``|language=...``; currently, this
 always applies to the whole buffer, but a PR adding support for slicing syntax
 (similar to font features) would be considered.
 
+OpenType font variations can be selected by appending an additional ``|`` to
+the filename, followed by a `Cairo font variation string`_ (e.g.,
+``"/path/to/font.otf||wdth=75"``); see `examples/opentype_variations.py`_. This
+support requires Cairo>=1.16. Note that features are parsed first, so if you do
+not wish to specify any features, you must specify an empty set with two pipes,
+i.e., ``font.otf|variations`` will treat ``variations`` as features, *not*
+variations.
+
 .. _HarfBuzz feature string: https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string
+.. _Cairo font variation string: https://www.cairographics.org/manual/cairo-cairo-font-options-t.html#cairo-font-options-set-variations
 .. _language: https://host-oman.github.io/libraqm/raqm-Raqm.html#raqm-set-language
 
 The syntaxes for selecting TTC subfonts and OpenType font features and language

examples/.gitignore

@@ -0,0 +1 @@
+Roboto Flex.ttf

examples/opentype_variations.py

@@ -0,0 +1,84 @@
+from collections import namedtuple
+from pathlib import Path
+import string
+from urllib.parse import quote
+from urllib.request import urlretrieve
+from zipfile import ZipFile
+
+from matplotlib import font_manager as fm, gridspec, pyplot as plt
+from matplotlib.widgets import Slider
+
+
+VariableAxis = namedtuple("VariableAxis", "min max default name")
+
+DEFAULT_FONT = "Roboto Flex"
+DEFAULT_SIZE = 32
+VARIABLE_AXES = {
+    "Optical Size": VariableAxis(8, 144, DEFAULT_SIZE, "opsz"),
+    "Weight": VariableAxis(100, 1000, 400, "wght"),
+    "Width": VariableAxis(25, 151, 100, "wdth"),
+    "Slant": VariableAxis(-10, 0, 0, "slnt"),
+    "Ascender Height": VariableAxis(649, 854, 750, "YTAS"),
+    "Counter Width": VariableAxis(323, 603, 468, "XTRA"),
+    "Descender Depth": VariableAxis(-305, -98, -203, "YTDE"),
+    "Figure Height": VariableAxis(560, 788, 738, "YTFI"),
+    "Grade": VariableAxis(-200, 150, 0, "GRAD"),
+    "Lowercase Height": VariableAxis(416, 570, 514, "YTLC"),
+    "Thin Stroke": VariableAxis(25, 135, 79, "YOPQ"),
+    "Uppercase Height": VariableAxis(528, 760, 712, "YTUC"),
+}
+
+path = Path(__file__).with_name(f"{DEFAULT_FONT}.ttf")
+if not path.exists():
+    url = f"https://fonts.google.com/download?family={quote(DEFAULT_FONT)}"
+    print(f"Downloading {url} to {path}")
+    tmpfile, _ = urlretrieve(url)
+    with ZipFile(tmpfile) as zfd:
+        for member in zfd.namelist():
+            if (member.startswith(DEFAULT_FONT.replace(" ", "")) and
+                    member.endswith(".ttf")):
+                path.write_bytes(zfd.read(member))
+                break
+
+
+def generate_font(family, size, axes):
+    args = ",".join(f"{VARIABLE_AXES[title].name}={value}"
+                    for title, value in axes.items())
+    font = Path(__file__).with_name(f"{family}.ttf||{args}")
+    return fm.FontProperties(fname=font, size=size)
+
+
+fig = plt.figure(figsize=(10, 3))
+gs = gridspec.GridSpec(2, 1, figure=fig, height_ratios=[2, 1],
+                       bottom=0.05, top=1, left=0.14, right=0.95)
+
+default_font = generate_font(
+    DEFAULT_FONT, DEFAULT_SIZE,
+    {title: axis.default for title, axis in VARIABLE_AXES.items()})
+text = fig.text(
+    0.5, 2/3,
+    f"{string.ascii_uppercase}\n{string.ascii_lowercase}\n{string.digits}",
+    font=default_font,
+    horizontalalignment="center", verticalalignment="center")
+
+fig.text(0.5, 0.36, "Font Variations", horizontalalignment="center")
+option_gs = gs[1].subgridspec(6, 2, wspace=0.6)
+
+sliders = {
+    title: Slider(fig.add_subplot(ss), title,
+                  axis.min, axis.max, valstep=1, valinit=axis.default)
+    for (title, axis), ss in zip(VARIABLE_AXES.items(), option_gs)
+}
+
+
+def update_font(value):
+    fp = generate_font(
+        DEFAULT_FONT, DEFAULT_SIZE,
+        {title: slider.val for title, slider in sliders.items()})
+    text.set_font(fp)
+
+
+for slider in sliders.values():
+    slider.on_changed(update_font)
+
+plt.show()

src/_util.cpp

@@ -59,6 +59,7 @@ cairo_user_data_key_t const REFS_KEY{},
                             INIT_MATRIX_KEY{},
                             FT_KEY{},
                             FEATURES_KEY{},
+                            VARIATIONS_KEY{},
                             IS_COLOR_FONT_KEY{};
 py::object RC_PARAMS{},
            PIXEL_MARKER{},
@@ -665,13 +666,14 @@ cairo_font_face_t* font_face_from_path(std::string pathspec)
   if (!font_face) {
     auto match = std::smatch{};
     if (!std::regex_match(pathspec, match,
-                          std::regex{"(.*?)(#(\\d+))?(\\|(.*))?"})) {
+                          std::regex{"(.*?)(#(\\d+))?(\\|([^|]*))?(\\|(.*))?"})) {
       throw std::runtime_error{
         "Failed to parse pathspec {}"_format(pathspec).cast<std::string>()};
     }
     auto const& path = match.str(1);
     auto const& face_index = std::atoi(match.str(3).c_str());  // 0 if absent.
     auto const& features_s = match.str(5);
+    auto const& variations = match.str(7);
     FT_Face ft_face;
     if (auto const& error =
         FT_New_Face(detail::ft_library, path.c_str(), face_index, &ft_face)) {
@@ -709,6 +711,12 @@ cairo_font_face_t* font_face_from_path(std::string pathspec)
       [](void* ptr) -> void {
         delete static_cast<std::vector<std::string>*>(ptr);
       });
+    CAIRO_CHECK_SET_USER_DATA(
+      cairo_font_face_set_user_data,
+      font_face, &detail::VARIATIONS_KEY, new std::string(variations),
+      [](void* ptr) -> void {
+        delete static_cast<std::string*>(ptr);
+      });
     // Color fonts need special handling due to cairo#404 and raqm#123; see
     // corresponding sections of the code.
     if (FT_IS_SFNT(ft_face)) {
@@ -775,6 +783,16 @@ void adjust_font_options(cairo_t* cr)
       : aa.ptr() == Py_False ? CAIRO_ANTIALIAS_NONE
       : aa.cast<cairo_antialias_t>());
   }
+  auto const& variations = *static_cast<std::string*>(
+    cairo_font_face_get_user_data(font_face, &detail::VARIATIONS_KEY));
+  if (!variations.empty()) {
+    if (detail::cairo_font_options_set_variations) {
+      detail::cairo_font_options_set_variations(options, variations.c_str());
+    } else {
+        py::module::import("warnings").attr("warn")(
+          "cairo_font_options_set_variations requires cairo>=1.16.0");
+    }
+  }
   // The hint style is not set here: it is passed directly as load_flags to
   // cairo_ft_font_face_create_for_ft_face.
   cairo_set_font_options(cr, options);

src/_util.h

@@ -31,6 +31,8 @@ extern std::array<uint8_t, 0x10000>
 #define CAIRO_TAG_LINK "Link"
 extern void (*cairo_tag_begin)(cairo_t*, char const*, char const*);
 extern void (*cairo_tag_end)(cairo_t*, char const*);
+// Copy-pasted from cairo.h, backported from 1.16.
+extern void (*cairo_font_options_set_variations)(cairo_font_options_t *, const char *);
 
 // Modified from cairo-pdf.h.
 enum cairo_pdf_version_t {};
@@ -75,6 +77,7 @@ extern void (*cairo_svg_surface_restrict_to_version)(
 #define ITER_CAIRO_OPTIONAL_API(_) \
   _(cairo_tag_begin) \
   _(cairo_tag_end) \
+  _(cairo_font_options_set_variations) \
   _(cairo_pdf_get_versions) \
   _(cairo_pdf_surface_create_for_stream) \
   _(cairo_pdf_surface_restrict_to_version) \