Makes the "hinting factor" tweakable at runtime.

The hinting factor is the amount of softness in hinting is applied in
the horizontal direction.  For years, matplotlib has hinted to 1/8
pixels in the horizontal direction and whole pixels in the vertical
direction.  This results in text that is often more
legible (particularly at smaller sizes) than standard 1:1 hinting.
This is based on idea from this paper from the author of Agg:

    http://www.antigrain.com/research/font_rasterization/

However, sometimes the user may want full-on hinting, so this value is
now tweakable using the `text.hinting_factor` rcParam.

Author: mdboom

lib/matplotlib/backends/backend_agg.py

@@ -220,7 +220,9 @@ def _get_agg_font(self, prop):
             fname = findfont(prop)
             font = self._fontd.get(fname)
             if font is None:
-                font = FT2Font(str(fname))
+                font = FT2Font(
+                    str(fname),
+                    hinting_factor=rcParams['text.hinting_factor'])
                 self._fontd[fname] = font
             self._fontd[key] = font
 

lib/matplotlib/rcsetup.py

@@ -408,6 +408,7 @@ def __call__(self, s):
     'text.latex.preview' : [False, validate_bool],
     'text.dvipnghack'     : [None, validate_bool_maybe_none],
     'text.hinting'        : [True, validate_bool],
+    'text.hinting_factor' : [8, validate_int],
 
     # The following are deprecated and replaced by, e.g., 'font.style'
     #'text.fontstyle'      : ['normal', str],

lib/matplotlib/tests/__init__.py

@@ -12,3 +12,4 @@ def setup():
     rcdefaults() # Start with all defaults
     rcParams['font.family'] = 'Bitstream Vera Sans'
     rcParams['text.hinting'] = False
+    rcParams['text.hinting_factor'] = 8

matplotlibrc.template

@@ -172,6 +172,9 @@ backend      : %(backend)s
 
 #text.hinting : True # If True, text will be hinted, otherwise not.  This only
                      # affects the Agg backend.
+#text.hinting_factor : 8 # Specifies the amount of softness for hinting in the
+                         # horizontal direction.  A value of 1 will hint to full
+                         # pixels.  A value of 2 will hint to half pixels etc.
 
 # The following settings allow you to select the fonts in math mode.
 # They map from a TeX font name to a fontconfig font pattern.

src/ft2font.cpp

@@ -36,17 +36,7 @@
       at the size at 12 pixels scaled by 2 through a transform,
       because the hints will have been computed differently (except
       you have disabled hints).
-
- This hack is enabled only when VERTICAL_HINTING is defined, and will
- only be effective when load_char and set_text are called with 'flags=
- LOAD_DEFAULT', which is the default.
  */
-#define VERTICAL_HINTING
-#ifdef VERTICAL_HINTING
-#define HORIZ_HINTING 8
-#else
-#define HORIZ_HINTING 1
-#endif
 
 FT_Library _ft2Library;
 
@@ -408,7 +398,7 @@ FT2Image::py_get_height(const Py::Tuple & args)
 PYCXX_VARARGS_METHOD_DECL(FT2Image, py_get_height)
 
 Py::PythonClassObject<Glyph> Glyph::factory(
-        const FT_Face& face, const FT_Glyph& glyph, size_t ind)
+        const FT_Face& face, const FT_Glyph& glyph, size_t ind, long hinting_factor)
 {
     Py::Callable class_type(type());
     Py::PythonClassObject<Glyph> obj = Py::PythonClassObject<Glyph>(
@@ -419,12 +409,12 @@ Py::PythonClassObject<Glyph> Glyph::factory(
     FT_BBox bbox;
     FT_Glyph_Get_CBox(glyph, ft_glyph_bbox_subpixels, &bbox);
 
-    o->setattro("width",        Py::Int(face->glyph->metrics.width / HORIZ_HINTING));
+    o->setattro("width",        Py::Int(face->glyph->metrics.width / hinting_factor));
     o->setattro("height",       Py::Int(face->glyph->metrics.height));
-    o->setattro("horiBearingX", Py::Int(face->glyph->metrics.horiBearingX / HORIZ_HINTING));
+    o->setattro("horiBearingX", Py::Int(face->glyph->metrics.horiBearingX / hinting_factor));
     o->setattro("horiBearingY", Py::Int(face->glyph->metrics.horiBearingY));
     o->setattro("horiAdvance",  Py::Int(face->glyph->metrics.horiAdvance));
-    o->setattro("linearHoriAdvance",  Py::Int(face->glyph->linearHoriAdvance / HORIZ_HINTING));
+    o->setattro("linearHoriAdvance",  Py::Int(face->glyph->linearHoriAdvance / hinting_factor));
     o->setattro("vertBearingX", Py::Int(face->glyph->metrics.vertBearingX));
 
     o->setattro("vertBearingY", Py::Int(face->glyph->metrics.vertBearingY));
@@ -847,14 +837,15 @@ FT2Font::FT2Font(Py::PythonClassInstance *self, Py::Tuple &args, Py::Dict &kwds)
     }
 
     // set a default fontsize 12 pt at 72dpi
-#ifdef VERTICAL_HINTING
-    error = FT_Set_Char_Size(face, 12 * 64, 0, 72 * HORIZ_HINTING, 72);
-    static FT_Matrix transform = { 65536 / HORIZ_HINTING, 0, 0, 65536 };
+    hinting_factor = 8;
+    if (kwds.hasKey("hinting_factor"))
+    {
+        hinting_factor = Py::Long(kwds["hinting_factor"]);
+    }
+
+    error = FT_Set_Char_Size(face, 12 * 64, 0, 72 * hinting_factor, 72);
+    static FT_Matrix transform = { 65536 / hinting_factor, 0, 0, 65536 };
     FT_Set_Transform(face, &transform, 0);
-#else
-    error = FT_Set_Char_Size(face, 12 * 64, 0, 72, 72);
-#endif
-    //error = FT_Set_Char_Size( face, 20 * 64, 0, 80, 80 );
     if (error)
     {
         std::ostringstream s;
@@ -993,17 +984,12 @@ FT2Font::set_size(const Py::Tuple & args)
     double ptsize = Py::Float(args[0]);
     double dpi = Py::Float(args[1]);
 
-#ifdef VERTICAL_HINTING
     int error = FT_Set_Char_Size(face, (long)(ptsize * 64), 0,
-                                 (unsigned int)dpi * HORIZ_HINTING,
+                                 (unsigned int)dpi * hinting_factor,
                                  (unsigned int)dpi);
-    static FT_Matrix transform = { 65536 / HORIZ_HINTING, 0, 0, 65536 };
+    static FT_Matrix transform = { 65536 / hinting_factor, 0, 0, 65536 };
     FT_Set_Transform(face, &transform, 0);
-#else
-    int error = FT_Set_Char_Size(face, (long)(ptsize * 64), 0,
-                                 (unsigned int)dpi,
-                                 (unsigned int)dpi);
-#endif
+
     if (error)
     {
         throw Py::RuntimeError("Could not set the fontsize");
@@ -1126,7 +1112,7 @@ FT2Font::get_kerning(const Py::Tuple & args)
 
     if (!FT_Get_Kerning(face, left, right, mode, &delta))
     {
-        return Py::Int(delta.x / HORIZ_HINTING);
+        return Py::Int(delta.x / hinting_factor);
     }
     else
     {
@@ -1214,7 +1200,7 @@ FT2Font::set_text(const Py::Tuple & args, const Py::Dict & kwargs)
             FT_Vector delta;
             FT_Get_Kerning(face, previous, glyph_index,
                            FT_KERNING_DEFAULT, &delta);
-            pen.x += delta.x / HORIZ_HINTING;
+            pen.x += delta.x / hinting_factor;
         }
         error = FT_Load_Glyph(face, glyph_index, flags);
         if (error)
@@ -1319,7 +1305,7 @@ FT2Font::load_char(const Py::Tuple & args, const Py::Dict & kwargs)
 
     size_t num = glyphs.size();  //the index into the glyphs list
     glyphs.push_back(thisGlyph);
-    return Glyph::factory(face, thisGlyph, num);
+    return Glyph::factory(face, thisGlyph, num, hinting_factor);
 }
 PYCXX_KEYWORDS_METHOD_DECL(FT2Font, load_char)
 
@@ -1369,7 +1355,7 @@ FT2Font::load_glyph(const Py::Tuple & args, const Py::Dict & kwargs)
 
     size_t num = glyphs.size();  //the index into the glyphs list
     glyphs.push_back(thisGlyph);
-    return Glyph::factory(face, thisGlyph, num);
+    return Glyph::factory(face, thisGlyph, num, hinting_factor);
 }
 PYCXX_KEYWORDS_METHOD_DECL(FT2Font, load_glyph)
 

src/ft2font.h

@@ -83,7 +83,7 @@ class Glyph : public Py::PythonClass<Glyph>
     Glyph(Py::PythonClassInstance *self, Py::Tuple &args, Py::Dict &kwds) :
         Py::PythonClass<Glyph>::PythonClass(self, args, kwds) { }
     virtual ~Glyph();
-    static Py::PythonClassObject<Glyph> factory(const FT_Face&, const FT_Glyph&, size_t);
+    static Py::PythonClassObject<Glyph> factory(const FT_Face&, const FT_Glyph&, size_t, long);
     int setattro(const Py::String &name, const Py::Object &value);
     Py::Object getattro(const Py::String &name);
     static void init_type(void);
@@ -137,6 +137,7 @@ class FT2Font : public Py::PythonClass<FT2Font>
     double angle;
     double ptsize;
     double dpi;
+    long hinting_factor;
 
     FT_BBox compute_string_bbox();
     void set_scalable_attributes();