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
@@ -32,7 +32,7 @@
 from matplotlib.backend_bases import (
     _Backend, FigureCanvasBase, FigureManagerBase, RendererBase)
 from matplotlib.font_manager import fontManager as _fontManager, get_font
-from matplotlib.ft2font import LoadFlags
+from matplotlib.ft2font import LoadFlags, RenderMode
 from matplotlib.mathtext import MathTextParser
 from matplotlib.path import Path
 from matplotlib.transforms import Bbox, BboxBase
@@ -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,48 +173,68 @@ 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(),
+                RenderMode.NORMAL if gc.get_antialiased() else RenderMode.MONO)
+            buffer = np.asarray(bitmap.buffer)
+            if not gc.get_antialiased():
+                buffer *= 0xff
+            # draw_text_image's y is downwards & the bitmap bottom side.
+            self._renderer.draw_text_image(
+                buffer,
+                bitmap.left,
+                int(self.height) - bitmap.top + bitmap.buffer.shape[0],
+                0, gc)
+        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)
+        gc1.set_snap(gc.get_snap())
+        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(),
                       features=mtext.get_fontfeatures() if mtext is not None else None,
                       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,
+            RenderMode.NORMAL if gc.get_antialiased() else RenderMode.MONO,
+        ):
+            buffer = bitmap.buffer
+            if not gc.get_antialiased():
+                buffer *= 0xff
+            self._renderer.draw_text_image(
+                buffer,
+                bitmap.left, int(self.height) - bitmap.top + buffer.shape[0],
+                0, gc)
 
     def get_text_width_height_descent(self, s, prop, ismath):
         # docstring inherited
@@ -224,9 +244,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())
@@ -248,8 +267,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)

lib/matplotlib/ft2font.pyi

@@ -70,6 +70,14 @@ class LoadFlags(Flag):
     TARGET_LCD = cast(int, ...)
     TARGET_LCD_V = cast(int, ...)
 
+class RenderMode(Enum):
+    NORMAL = cast(int, ...)
+    LIGHT = cast(int, ...)
+    MONO = cast(int, ...)
+    LCD = cast(int, ...)
+    LCD_V = cast(int, ...)
+    SDF = cast(int, ...)
+
 class StyleFlags(Flag):
     NORMAL = cast(int, ...)
     ITALIC = cast(int, ...)

lib/matplotlib/text.py

@@ -871,6 +871,7 @@ def draw(self, renderer):
             gc.set_alpha(self.get_alpha())
             gc.set_url(self._url)
             gc.set_antialiased(self._antialiased)
+            gc.set_snap(self.get_snap())
             self._set_gc_clip(gc)
 
             angle = self.get_rotation()

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

@@ -19,6 +19,7 @@
 
 extern "C" {
 #include <ft2build.h>
+#include FT_BITMAP_H
 #include FT_FREETYPE_H
 #include FT_GLYPH_H
 #include FT_OUTLINE_H
@@ -111,6 +112,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);
     std::vector<raqm_glyph_t> layout(std::u32string_view text, FT_Int32 flags,
@@ -156,6 +159,10 @@ class FT2Font
     {
         return image;
     }
+    std::vector<FT_Glyph> &get_glyphs()
+    {
+        return glyphs;
+    }
     FT_Glyph const &get_last_glyph() const
     {
         return glyphs.back();

src/ft2font_wrapper.cpp

@@ -204,6 +204,25 @@ P11X_DECLARE_ENUM(
     {"TARGET_LCD_V", LoadFlags::TARGET_LCD_V},
 );
 
+const char *RenderMode__doc__ = R"""(
+    Render modes.
+
+    For more information, see `the FreeType documentation
+    <https://freetype.org/freetype2/docs/reference/ft2-glyph_retrieval.html#ft_render_mode>`_.
+
+    .. versionadded:: 3.10
+)""";
+
+P11X_DECLARE_ENUM(
+    "RenderMode", "Enum",
+    {"NORMAL", FT_RENDER_MODE_NORMAL},
+    {"LIGHT", FT_RENDER_MODE_LIGHT},
+    {"MONO", FT_RENDER_MODE_MONO},
+    {"LCD", FT_RENDER_MODE_LCD},
+    {"LCD_V", FT_RENDER_MODE_LCD_V},
+    {"SDF", FT_RENDER_MODE_SDF},
+);
+
 const char *StyleFlags__doc__ = R"""(
     Flags returned by `FT2Font.style_flags`.
 
@@ -265,6 +284,45 @@ PyFT2Image_draw_rect_filled(FT2Image *self,
     self->draw_rect_filled(x0, y0, x1, y1);
 }
 
+/**********************************************************************
+ * Positioned Bitmap; owns the FT_Bitmap!
+ * */
+
+struct PyPositionedBitmap {
+    FT_Int left, top;
+    bool owning;
+    FT_Bitmap bitmap;
+
+    PyPositionedBitmap(FT_GlyphSlot slot) :
+        left{slot->bitmap_left}, top{slot->bitmap_top}, owning{true}
+    {
+        FT_Bitmap_Init(&bitmap);
+        FT_CHECK(FT_Bitmap_Convert, _ft2Library, &slot->bitmap, &bitmap, 1);
+    }
+
+    PyPositionedBitmap(FT_BitmapGlyph bg) :
+        left{bg->left}, top{bg->top}, owning{true}
+    {
+        FT_Bitmap_Init(&bitmap);
+        FT_CHECK(FT_Bitmap_Convert, _ft2Library, &bg->bitmap, &bitmap, 1);
+    }
+
+    PyPositionedBitmap(PyPositionedBitmap& other) = delete;  // Non-copyable.
+
+    PyPositionedBitmap(PyPositionedBitmap&& other) :
+        left{other.left}, top{other.top}, owning{true}, bitmap{other.bitmap}
+    {
+        other.owning = false;  // Prevent double deletion.
+    }
+
+    ~PyPositionedBitmap()
+    {
+        if (owning) {
+            FT_Bitmap_Done(_ft2Library, &bitmap);
+        }
+    }
+};
+
 /**********************************************************************
  * Glyph
  * */
@@ -538,6 +596,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.
 
@@ -1493,6 +1564,7 @@ PYBIND11_MODULE(ft2font, m, py::mod_gil_not_used())
     p11x::bind_enums(m);
     p11x::enums["Kerning"].attr("__doc__") = Kerning__doc__;
     p11x::enums["LoadFlags"].attr("__doc__") = LoadFlags__doc__;
+    p11x::enums["RenderMode"].attr("__doc__") = RenderMode__doc__;
     p11x::enums["FaceFlags"].attr("__doc__") = FaceFlags__doc__;
     p11x::enums["StyleFlags"].attr("__doc__") = StyleFlags__doc__;
 
@@ -1519,6 +1591,17 @@ PYBIND11_MODULE(ft2font, m, py::mod_gil_not_used())
             return py::buffer_info(self.get_buffer(), shape, strides);
         });
 
+    py::class_<PyPositionedBitmap>(m, "_PositionedBitmap", py::is_final())
+        .def_readonly("left", &PyPositionedBitmap::left)
+        .def_readonly("top", &PyPositionedBitmap::top)
+        .def_property_readonly(
+          "buffer", [](PyPositionedBitmap &self) -> py::array {
+            return {{self.bitmap.rows, self.bitmap.width},
+                    {self.bitmap.pitch, 1},
+                    self.bitmap.buffer};
+        })
+        ;
+
     py::class_<PyGlyph>(m, "Glyph", py::is_final(), PyGlyph__doc__)
         .def(py::init<>([]() -> PyGlyph {
             // Glyph is not useful from Python, so mark it as not constructible.
@@ -1553,6 +1636,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,
@@ -1710,10 +1795,32 @@ 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::get_hinting_factor,
+          "The hinting factor.")
 
         .def_buffer([](PyFT2Font &self) -> py::buffer_info {
             return self.get_image().request();
-        });
+        })
+
+        .def("_render_glyph",
+             [](PyFT2Font *self, FT_UInt idx, LoadFlags flags, FT_Render_Mode render_mode) {
+                auto face = self->get_face();
+                FT_CHECK(FT_Load_Glyph, face, idx, static_cast<FT_Int32>(flags));
+                FT_CHECK(FT_Render_Glyph, face->glyph, render_mode);
+                return PyPositionedBitmap{face->glyph};
+            })
+        .def("_render_glyphs",
+             [](PyFT2Font *self, double x, double y, FT_Render_Mode render_mode) {
+                auto origin = FT_Vector{std::lround(x * 64), std::lround(y * 64)};
+                auto pbs = std::vector<PyPositionedBitmap>{};
+                for (auto &g: self->get_glyphs()) {
+                    FT_CHECK(FT_Glyph_To_Bitmap, &g, render_mode, &origin, 1);
+                    pbs.emplace_back(reinterpret_cast<FT_BitmapGlyph>(g));
+                }
+                return pbs;
+            })
+        ;
 
     m.attr("__freetype_version__") = version_string;
     m.attr("__freetype_build_type__") = FREETYPE_BUILD_TYPE;