Drop the FT2Font intermediate buffer

Directly render FT glyphs to the Agg buffer.  In particular, this
naturally provides, with no extra work, subpixel positioning of glyphs
(which could also have been implemented in the old framework, but would
have required careful tracking of subpixel offets).

Note that all baseline images should be regenerated.  The new APIs added
to FT2Font are also up to bikeshedding (but they are all private).

Author: anntzer

lib/matplotlib/backends/backend_agg.py

@@ -22,7 +22,7 @@
 """
 
 from contextlib import nullcontext
-from math import radians, cos, sin
+import math
 
 import numpy as np
 from PIL import features
@@ -71,7 +71,7 @@ def __init__(self, width, height, dpi):
         self._filter_renderers = []
 
         self._update_methods()
-        self.mathtext_parser = MathTextParser('agg')
+        self.mathtext_parser = MathTextParser('path')
 
         self.bbox = Bbox.from_bounds(0, 0, self.width, self.height)
 
@@ -173,47 +173,63 @@ def draw_path(self, gc, path, transform, rgbFace=None):
 
     def draw_mathtext(self, gc, x, y, s, prop, angle):
         """Draw mathtext using :mod:`matplotlib.mathtext`."""
-        ox, oy, width, height, descent, font_image = \
-            self.mathtext_parser.parse(s, self.dpi, prop,
-                                       antialiased=gc.get_antialiased())
-
-        xd = descent * sin(radians(angle))
-        yd = descent * cos(radians(angle))
-        x = round(x + ox + xd)
-        y = round(y - oy + yd)
-        self._renderer.draw_text_image(font_image, x, y + 1, angle, gc)
+        # y is downwards.
+        parse = self.mathtext_parser.parse(
+            s, self.dpi, prop, antialiased=gc.get_antialiased())
+        cos = math.cos(math.radians(angle))
+        sin = math.sin(math.radians(angle))
+        for font, size, char, glyph_index, dx, dy in parse.glyphs:  # dy is upwards.
+            font.set_size(size, self.dpi)
+            hf = font._hinting_factor
+            font._set_transform(
+                [[round(0x10000 * cos / hf), round(0x10000 * -sin)],
+                 [round(0x10000 * sin / hf), round(0x10000 * cos)]],
+                [round(0x40 * (x + dx * cos - dy * sin)),
+                 # FreeType's y is upwards.
+                 round(0x40 * (self.height - y + dx * sin + dy * cos))]
+            )
+            bitmap = font._render_glyph(glyph_index, get_hinting_flag())
+            # draw_text_image's y is downwards & the bitmap bottom side.
+            self._renderer.draw_text_image(
+                bitmap["buffer"],
+                bitmap["left"],
+                int(self.height) - bitmap["top"] + bitmap["buffer"].shape[0],
+                0, gc)
+        if not angle:
+            for dx, dy, w, h in parse.rects:  # dy is upwards & the rect top side.
+                self._renderer.draw_text_image(
+                    np.full((round(h), round(w)), np.uint8(0xff)),
+                    round(x + dx), round(y - dy - h),
+                    0, gc)
+        else:
+            rgba = gc.get_rgb()
+            if len(rgba) == 3 or gc.get_forced_alpha():
+                rgba = rgba[:3] + (gc.get_alpha(),)
+            gc1 = self.new_gc()
+            gc1.set_linewidth(0)
+            for dx, dy, w, h in parse.rects:  # dy is upwards & the rect top side.
+                path = Path._create_closed(
+                    [(dx, dy), (dx + w, dy), (dx + w, dy + h), (dx, dy + h)])
+                self._renderer.draw_path(
+                    gc1, path,
+                    mpl.transforms.Affine2D()
+                    .rotate_deg(angle).translate(x, self.height - y),
+                    rgba)
+            gc1.restore()
 
     def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
         # docstring inherited
         if ismath:
             return self.draw_mathtext(gc, x, y, s, prop, angle)
         font = self._prepare_font(prop)
-        # We pass '0' for angle here, since it will be rotated (in raster
-        # space) in the following call to draw_text_image).
-        font.set_text(s, 0, flags=get_hinting_flag(),
+        font.set_text(s, angle, flags=get_hinting_flag(),
                       language=mtext.get_language() if mtext is not None else None)
-        font.draw_glyphs_to_bitmap(
-            antialiased=gc.get_antialiased())
-        d = font.get_descent() / 64.0
-        # The descent needs to be adjusted for the angle.
-        xo, yo = font.get_bitmap_offset()
-        xo /= 64.0
-        yo /= 64.0
-
-        rad = radians(angle)
-        xd = d * sin(rad)
-        yd = d * cos(rad)
-        # Rotating the offset vector ensures text rotates around the anchor point.
-        # Without this, rotated text offsets incorrectly, causing a horizontal shift.
-        # Applying the 2D rotation matrix.
-        rotated_xo = xo * cos(rad) - yo * sin(rad)
-        rotated_yo = xo * sin(rad) + yo * cos(rad)
-        # Subtract rotated_yo to account for the inverted y-axis in computer graphics,
-        # compared to the mathematical convention.
-        x = round(x + rotated_xo + xd)
-        y = round(y - rotated_yo + yd)
-
-        self._renderer.draw_text_image(font, x, y + 1, angle, gc)
+        for bitmap in font._render_glyphs(x, self.height - y):
+            self._renderer.draw_text_image(
+                bitmap["buffer"],
+                bitmap["left"],
+                int(self.height) - bitmap["top"] + bitmap["buffer"].shape[0],
+                0, gc)
 
     def get_text_width_height_descent(self, s, prop, ismath):
         # docstring inherited
@@ -223,9 +239,8 @@ def get_text_width_height_descent(self, s, prop, ismath):
             return super().get_text_width_height_descent(s, prop, ismath)
 
         if ismath:
-            ox, oy, width, height, descent, font_image = \
-                self.mathtext_parser.parse(s, self.dpi, prop)
-            return width, height, descent
+            parse = self.mathtext_parser.parse(s, self.dpi, prop)
+            return parse.width, parse.height, parse.depth
 
         font = self._prepare_font(prop)
         font.set_text(s, 0.0, flags=get_hinting_flag())
@@ -247,8 +262,8 @@ def draw_tex(self, gc, x, y, s, prop, angle, *, mtext=None):
         Z = np.array(Z * 255.0, np.uint8)
 
         w, h, d = self.get_text_width_height_descent(s, prop, ismath="TeX")
-        xd = d * sin(radians(angle))
-        yd = d * cos(radians(angle))
+        xd = d * math.sin(math.radians(angle))
+        yd = d * math.cos(math.radians(angle))
         x = round(x + xd)
         y = round(y + yd)
         self._renderer.draw_text_image(Z, x, y, angle, gc)

src/ft2font.cpp

@@ -283,6 +283,17 @@ void FT2Font::set_size(double ptsize, double dpi)
     }
 }
 
+void FT2Font::_set_transform(
+    std::array<std::array<FT_Fixed, 2>, 2> matrix, std::array<FT_Fixed, 2> delta)
+{
+    FT_Matrix m = {matrix[0][0], matrix[0][1], matrix[1][0], matrix[1][1]};
+    FT_Vector d = {delta[0], delta[1]};
+    FT_Set_Transform(face, &m, &d);
+    for (auto & fallback : fallbacks) {
+        fallback->_set_transform(matrix, delta);
+    }
+}
+
 void FT2Font::set_charmap(int i)
 {
     if (i >= face->num_charmaps) {

src/ft2font.h

@@ -111,6 +111,8 @@ class FT2Font
     void close();
     void clear();
     void set_size(double ptsize, double dpi);
+    void _set_transform(
+        std::array<std::array<FT_Fixed, 2>, 2> matrix, std::array<FT_Fixed, 2> delta);
     void set_charmap(int i);
     void select_charmap(unsigned long i);
     void set_text(std::u32string_view codepoints, double angle, FT_Int32 flags,
@@ -179,7 +181,9 @@ class FT2Font
     py::array_t<uint8_t, py::array::c_style> image;
     FT_Face face;
     FT_Vector pen;    /* untransformed origin  */
+  public:
     std::vector<FT_Glyph> glyphs;
+  private:
     std::vector<FT2Font *> fallbacks;
     std::unordered_map<long, FT2Font *> char_to_font;
     FT_BBox bbox;

src/ft2font_wrapper.cpp

@@ -535,6 +535,19 @@ const char *PyFT2Font_set_size__doc__ = R"""(
         The DPI used for rendering the text.
 )""";
 
+const char *PyFT2Font__set_transform__doc__ = R"""(
+    Set the transform of the text.
+
+    This is a low-level function, where *matrix* and *delta* are directly in
+    16.16 and 26.6 formats respectively.  Refer to the FreeType docs of
+    FT_Set_Transform for further description.
+
+    Parameters
+    ----------
+    matrix : (2, 2) array of int
+    delta : (2,) array of int
+)""";
+
 const char *PyFT2Font_set_charmap__doc__ = R"""(
     Make the i-th charmap current.
 
@@ -1542,6 +1555,8 @@ PYBIND11_MODULE(ft2font, m, py::mod_gil_not_used())
         .def("clear", &PyFT2Font::clear, PyFT2Font_clear__doc__)
         .def("set_size", &PyFT2Font::set_size, "ptsize"_a, "dpi"_a,
              PyFT2Font_set_size__doc__)
+        .def("_set_transform", &PyFT2Font::_set_transform, "matrix"_a, "delta"_a,
+             PyFT2Font__set_transform__doc__)
         .def("set_charmap", &PyFT2Font::set_charmap, "i"_a,
              PyFT2Font_set_charmap__doc__)
         .def("select_charmap", &PyFT2Font::select_charmap, "i"_a,
@@ -1699,10 +1714,49 @@ PYBIND11_MODULE(ft2font, m, py::mod_gil_not_used())
         .def_property_readonly(
           "fname", &PyFT2Font_fname,
           "The original filename for this object.")
+        .def_property_readonly(
+          "_hinting_factor", [](PyFT2Font *self) {
+            return self->get_hinting_factor();
+          }, "The hinting factor.")
 
         .def_buffer([](PyFT2Font &self) -> py::buffer_info {
             return self.get_image().request();
-        });
+        })
+
+        // TODO: Return a nicer structure than dicts.
+        // NOTE: The lifetime of the buffers is limited and could get invalidated...
+        // TODO: Real antialiasing flag.
+        .def("_render_glyph", [](PyFT2Font *self, FT_UInt idx, LoadFlags flags) {
+            auto face = self->get_face();
+            FT_CHECK(FT_Load_Glyph, face, idx, static_cast<FT_Int32>(flags));
+            FT_CHECK(FT_Render_Glyph, face->glyph, FT_RENDER_MODE_NORMAL);
+            py::dict d;
+            d["left"] = face->glyph->bitmap_left;
+            d["top"] = face->glyph->bitmap_top;
+            d["buffer"] = py::array_t<uint8_t>{
+                {face->glyph->bitmap.rows, face->glyph->bitmap.width},
+                {face->glyph->bitmap.pitch, 1},
+                face->glyph->bitmap.buffer};
+            return d;
+        })
+        .def("_render_glyphs", [](PyFT2Font *self, double x, double y) {
+            auto origin = FT_Vector{std::lround(x * 64), std::lround(y * 64)};
+            py::list gs;
+            for (auto &g: self->glyphs) {
+                FT_CHECK(FT_Glyph_To_Bitmap, &g, FT_RENDER_MODE_NORMAL, &origin, 1);
+                auto bg = reinterpret_cast<FT_BitmapGlyph>(g);
+                py::dict d;
+                d["left"] = bg->left;
+                d["top"] = bg->top;
+                d["buffer"] = py::array_t<uint8_t>{
+                    {bg->bitmap.rows, bg->bitmap.width},
+                    {bg->bitmap.pitch, 1},
+                    bg->bitmap.buffer};
+                gs.append(d);
+            }
+            return gs;
+        })
+        ;
 
     m.attr("__freetype_version__") = version_string;
     m.attr("__freetype_build_type__") = FREETYPE_BUILD_TYPE;