[base] Improve kerning tracing and documentation.

* src/base/ftobjs.c (FT_Get_Kerning): Emit tracing message if
scaled-down kerning values differ.

ChangeLog

@@ -1,3 +1,10 @@
+2015-08-25  Werner Lemberg  <wl@gnu.org>
+
+	[base] Improve kerning tracing and documentation.
+
+	* src/base/ftobjs.c (FT_Get_Kerning): Emit tracing message if
+	scaled-down kerning values differ.
+
 2015-08-18  Werner Lemberg  <wl@gnu.org>
 
 	[raster] Remove last remnants of `raster5' driver.

include/freetype/freetype.h

@@ -3041,6 +3041,11 @@ FT_BEGIN_HEADER
   /*    FT_KERNING_UNSCALED :: Return the kerning vector in original font  */
   /*                           units.                                      */
   /*                                                                       */
+  /* <Note>                                                                */
+  /*    FT_KERNING_DEFAULT returns full pixel values; it also makes        */
+  /*    FreeType heuristically scale down kerning distances at small ppem  */
+  /*    values so that they don't become too big.                          */
+  /*                                                                       */
   typedef enum  FT_Kerning_Mode_
   {
     FT_KERNING_DEFAULT  = 0,

src/base/ftobjs.c

@@ -3073,18 +3073,37 @@
 
           if ( kern_mode != FT_KERNING_UNFITTED )
           {
+            FT_Pos  orig_x = akerning->x;
+            FT_Pos  orig_y = akerning->y;
+
+
             /* we scale down kerning values for small ppem values */
             /* to avoid that rounding makes them too big.         */
             /* `25' has been determined heuristically.            */
             if ( face->size->metrics.x_ppem < 25 )
-              akerning->x = FT_MulDiv( akerning->x,
+              akerning->x = FT_MulDiv( orig_x,
                                        face->size->metrics.x_ppem, 25 );
             if ( face->size->metrics.y_ppem < 25 )
-              akerning->y = FT_MulDiv( akerning->y,
+              akerning->y = FT_MulDiv( orig_y,
                                        face->size->metrics.y_ppem, 25 );
 
             akerning->x = FT_PIX_ROUND( akerning->x );
             akerning->y = FT_PIX_ROUND( akerning->y );
+
+#ifdef FT_DEBUG_LEVEL_TRACE
+            {
+              FT_Pos  orig_x_rounded = FT_PIX_ROUND( orig_x );
+              FT_Pos  orig_y_rounded = FT_PIX_ROUND( orig_y );
+
+
+              if ( akerning->x != orig_x_rounded ||
+                   akerning->y != orig_y_rounded )
+                FT_TRACE5(( "FT_Get_Kerning: horizontal kerning"
+                            " (%d, %d) scaled down to (%d, %d) pixels\n",
+                            orig_x_rounded / 64, orig_y_rounded / 64,
+                            akerning->x / 64, akerning->y / 64 ));
+            }
+#endif
           }
         }
       }