From c5bda503b9b15bdd042e2c9696f2b1975f49d98c Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Wed, 16 Feb 2011 21:59:44 +0100 Subject: [autofit] Add a lot of comments and do some minor formatting. --- src/autofit/afhints.c | 98 ++++++++++++++++++--------- src/autofit/afhints.h | 179 +++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 215 insertions(+), 62 deletions(-) diff --git a/src/autofit/afhints.c b/src/autofit/afhints.c index c3497091..98593700 100644 --- a/src/autofit/afhints.c +++ b/src/autofit/afhints.c @@ -4,7 +4,7 @@ /* */ /* Auto-fitter hinting routines (body). */ /* */ -/* Copyright 2003, 2004, 2005, 2006, 2007, 2009, 2010 by */ +/* Copyright 2003-2007, 2009-2011 by */ /* David Turner, Robert Wilhelm, and Werner Lemberg. */ /* */ /* This file is part of the FreeType project, and may only be used, */ @@ -21,6 +21,8 @@ #include FT_INTERNAL_CALC_H + /* Get new segment for given axis. */ + FT_LOCAL_DEF( FT_Error ) af_axis_hints_new_segment( AF_AxisHints axis, FT_Memory memory, @@ -61,6 +63,8 @@ } + /* Get new edge for given axis, direction, and position. */ + FT_LOCAL( FT_Error ) af_axis_hints_new_edge( AF_AxisHints axis, FT_Int fpos, @@ -169,20 +173,20 @@ printf( "Table of points:\n" ); - printf( " [ index | xorg | yorg | xscale | yscale " - "| xfit | yfit | flags ]\n" ); + printf( " [ index | xorg | yorg | xscale | yscale" + " | xfit | yfit | flags ]\n" ); for ( point = points; point < limit; point++ ) { - printf( " [ %5d | %5d | %5d | %-5.2f | %-5.2f " - "| %-5.2f | %-5.2f | %c%c%c%c%c%c ]\n", + printf( " [ %5d | %5d | %5d | %-5.2f | %-5.2f" + " | %-5.2f | %-5.2f | %c%c%c%c%c%c ]\n", point - points, point->fx, point->fy, - point->ox/64.0, - point->oy/64.0, - point->x/64.0, - point->y/64.0, + point->ox / 64.0, + point->oy / 64.0, + point->x / 64.0, + point->y / 64.0, ( point->flags & AF_FLAG_WEAK_INTERPOLATION ) ? 'w' : ' ', ( point->flags & AF_FLAG_INFLECTION ) ? 'i' : ' ', ( point->flags & AF_FLAG_EXTREMA_X ) ? '<' : ' ', @@ -222,7 +226,8 @@ } - /* A function to dump the array of linked segments. */ + /* Dump the array of linked segments. */ + void af_glyph_hints_dump_segments( AF_GlyphHints hints ) { @@ -260,6 +265,8 @@ } + /* Dump the array of linked edges. */ + void af_glyph_hints_dump_edges( AF_GlyphHints hints ) { @@ -276,7 +283,7 @@ /* * note: AF_DIMENSION_HORZ corresponds to _vertical_ edges - * since they have constant a X coordinate. + * since they have a constant X coordinate. */ printf ( "Table of %s edges:\n", dimension == AF_DIMENSION_HORZ ? "vertical" : "horizontal" ); @@ -329,7 +336,8 @@ #endif /* !AF_DEBUG */ - /* compute the direction value of a given vector */ + /* Compute the direction value of a given vector. */ + FT_LOCAL_DEF( AF_Direction ) af_direction_compute( FT_Pos dx, FT_Pos dy ) @@ -369,6 +377,8 @@ } } + /* return no direction if arm lengths differ too much */ + /* (value 14 is heuristic) */ ss *= 14; if ( FT_ABS( ll ) <= FT_ABS( ss ) ) dir = AF_DIR_NONE; @@ -397,7 +407,7 @@ /* * note that we don't need to free the segment and edge - * buffers, since they are really within the hints->points array + * buffers since they are really within the hints->points array */ for ( dim = 0; dim < AF_DIMENSION_MAX; dim++ ) { @@ -408,8 +418,8 @@ axis->max_segments = 0; FT_FREE( axis->segments ); - axis->num_edges = 0; - axis->max_edges = 0; + axis->num_edges = 0; + axis->max_edges = 0; FT_FREE( axis->edges ); } @@ -426,6 +436,8 @@ } + /* Reset metrics. */ + FT_LOCAL_DEF( void ) af_glyph_hints_rescale( AF_GlyphHints hints, AF_ScriptMetrics metrics ) @@ -435,6 +447,9 @@ } + /* Recompute all AF_Point in AF_GlyphHints from the definitions */ + /* in a source outline. */ + FT_LOCAL_DEF( FT_Error ) af_glyph_hints_reload( AF_GlyphHints hints, FT_Outline* outline ) @@ -457,12 +472,12 @@ hints->axis[1].num_segments = 0; hints->axis[1].num_edges = 0; - /* first of all, reallocate the contours array when necessary */ + /* first of all, reallocate the contours array if necessary */ new_max = (FT_UInt)outline->n_contours; old_max = hints->max_contours; if ( new_max > old_max ) { - new_max = ( new_max + 3 ) & ~3; + new_max = ( new_max + 3 ) & ~3; /* round up to a multiple of 4 */ if ( FT_RENEW_ARRAY( hints->contours, old_max, new_max ) ) goto Exit; @@ -479,7 +494,7 @@ old_max = hints->max_points; if ( new_max > old_max ) { - new_max = ( new_max + 2 + 7 ) & ~7; + new_max = ( new_max + 2 + 7 ) & ~7; /* round up to a multiple of 8 */ if ( FT_RENEW_ARRAY( hints->points, old_max, new_max ) ) goto Exit; @@ -545,7 +560,7 @@ point->flags = AF_FLAG_CUBIC; break; default: - point->flags = 0; + point->flags = AF_FLAG_NONE; } point->prev = prev; @@ -563,7 +578,7 @@ } } - /* set-up the contours array */ + /* set up the contours array */ { AF_Point* contour = hints->contours; AF_Point* contour_limit = contour + hints->num_contours; @@ -611,6 +626,8 @@ in_dir = af_direction_compute( out_x, out_y ); point->out_dir = (FT_Char)in_dir; + /* check for weak points */ + if ( point->flags & ( AF_FLAG_CONIC | AF_FLAG_CUBIC ) ) { Is_Weak_Point: @@ -639,6 +656,8 @@ } + /* Store the hinted outline in an FT_Outline structure. */ + FT_LOCAL_DEF( void ) af_glyph_hints_save( AF_GlyphHints hints, FT_Outline* outline ) @@ -671,6 +690,9 @@ ****************************************************************/ + /* Align all points of an edge to the same coordinate value, */ + /* either horizontally or vertically. */ + FT_LOCAL_DEF( void ) af_glyph_hints_align_edge_points( AF_GlyphHints hints, AF_Dimension dim ) @@ -704,7 +726,6 @@ break; point = point->next; - } } } @@ -744,8 +765,8 @@ ****************************************************************/ - /* hint the strong points -- this is equivalent to the TrueType `IP' */ - /* hinting instruction */ + /* Hint the strong points -- this is equivalent to the TrueType `IP' */ + /* hinting instruction. */ FT_LOCAL_DEF( void ) af_glyph_hints_align_strong_points( AF_GlyphHints hints, @@ -827,11 +848,12 @@ max = edge_limit - edges; #if 1 - /* for small edge counts, a linear search is better */ + /* for a small number of edges, a linear search is better */ if ( max <= 8 ) { FT_PtrDist nn; + for ( nn = 0; nn < max; nn++ ) if ( edges[nn].fpos >= u ) break; @@ -863,6 +885,7 @@ } } + /* point is not on an edge */ { AF_Edge before = edges + min - 1; AF_Edge after = edges + min + 0; @@ -898,6 +921,10 @@ ****************************************************************/ + /* Shift the original coordinates of all points between `p1' and */ + /* `p2' to get hinted coordinates, using the same difference as */ + /* given by `ref'. */ + static void af_iup_shift( AF_Point p1, AF_Point p2, @@ -906,6 +933,7 @@ AF_Point p; FT_Pos delta = ref->u - ref->v; + if ( delta == 0 ) return; @@ -917,6 +945,13 @@ } + /* Interpolate the original coordinates of all points between `p1' and */ + /* `p2' to get hinted coordinates, using `ref1' and `ref2' as the */ + /* reference points. The `u' and `v' members are the current and */ + /* original coordinate values, respectively. */ + /* */ + /* Details can be found in the TrueType bytecode specification. */ + static void af_iup_interp( AF_Point p1, AF_Point p2, @@ -985,6 +1020,9 @@ } + /* Hint the weak points -- this is equivalent to the TrueType `IUP' */ + /* hinting instruction. */ + FT_LOCAL_DEF( void ) af_glyph_hints_align_weak_points( AF_GlyphHints hints, AF_Dimension dim ) @@ -1050,17 +1088,18 @@ for (;;) { - FT_ASSERT( point <= end_point && + FT_ASSERT( point <= end_point && ( point->flags & touch_flag ) != 0 ); - /* skip any touched neighbhours */ - while ( point < end_point && ( point[1].flags & touch_flag ) != 0 ) + /* skip any touched neighbours */ + while ( point < end_point && + ( point[1].flags & touch_flag ) != 0 ) point++; last_touched = point; /* find the next touched point, if any */ - point ++; + point++; for (;;) { if ( point > end_point ) @@ -1080,9 +1119,8 @@ EndContour: /* special case: only one point was touched */ if ( last_touched == first_touched ) - { af_iup_shift( first_point, end_point, first_touched ); - } + else /* interpolate the last part */ { if ( last_touched < end_point ) diff --git a/src/autofit/afhints.h b/src/autofit/afhints.h index 10e673b3..d63b9796 100644 --- a/src/autofit/afhints.h +++ b/src/autofit/afhints.h @@ -4,7 +4,7 @@ /* */ /* Auto-fitter hinting routines (specification). */ /* */ -/* Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2010 by */ +/* Copyright 2003-2008, 2010-2011 by */ /* David Turner, Robert Wilhelm, and Werner Lemberg. */ /* */ /* This file is part of the FreeType project, and may only be used, */ @@ -25,10 +25,10 @@ FT_BEGIN_HEADER - /* - * The definition of outline glyph hints. These are shared by all - * script analysis routines (until now). - */ + /* + * The definition of outline glyph hints. These are shared by all + * script analysis routines (until now). + */ typedef enum AF_Dimension_ { @@ -55,6 +55,128 @@ FT_BEGIN_HEADER } AF_Direction; + /* + * The following explanations are mostly taken from the article + * + * Real-Time Grid Fitting of Typographic Outlines + * + * by David Turner and Werner Lemberg + * + * http://www.tug.org/TUGboat/Articles/tb24-3/lemberg.pdf + * + * + * Segments + * + * `af_{cjk,latin,...}_hints_compute_segments' are the functions to + * find segments in an outline. A segment is a series of consecutive + * points that are approximately aligned along a coordinate axis. The + * analysis to do so is specific to a script. + * + * A segment must have at least two points, except in the case of + * `fake' segments that are generated to hint metrics appropriately, + * and which consist of a single point. + * + * + * Edges + * + * As soon as segments are defined, the auto-hinter groups them into + * edges. An edge corresponds to a single position on the main + * dimension that collects one or more segments (allowing for a small + * threshold). + * + * The auto-hinter first tries to grid fit edges, then to align + * segments on the edges unless it detects that they form a serif. + * + * `af_{cjk,latin,...}_hints_compute_edges' are the functions to find + * edges; they are specific to a script. + * + * + * Stems + * + * Segments need to be `linked' to other ones in order to detect stems. + * A stem is made of two segments that face each other in opposite + * directions and that are sufficiently close to each other. Using + * vocabulary from the TrueType specification, stem segments form a + * `black distance'. + * + * Each segment has at most one `best' candidate to form a black + * distance, or no candidate at all. Notice that two distinct segments + * can have the same candidate, which frequently means a serif. + * + * A stem is recognized by the following condition: + * + * best segment_1 = segment_2 && best segment_2 = segment_1 + * + * The best candidate is stored in field `link' in structure + * `AF_Segment'. + * + * Stems are detected by `af_{cjk,latin,...}_hint_edges'. + * + * + * Serifs + * + * On the opposite, a serif has + * + * best segment_1 = segment_2 && best segment_2 != segment_1 + * + * where segment_1 corresponds to the serif segment. + * + * The best candidate is stored in field `serif' in structure + * `AF_Segment' (and `link' is set to NULL). + * + * Serifs are detected by `af_{cjk,latin,...}_hint_edges'. + * + * + * Touched points + * + * A point is called `touched' if it has been processed somehow by the + * auto-hinter. It basically means that it shouldn't be moved again + * (or moved only under certain constraints to preserve the already + * applied processing). + * + * + * Flat and round segments + * + * Segments are `round' or `flat', depending on the series of points + * that define them. A segment is round if the next and previous point + * of an extremum (which can be either a single point or sequence of + * points) are both conic or cubic control points. Otherwise, a + * segment with an extremum is flat. + * + * + * Strong Points + * + * Experience has shown that points which are not part of an edge need + * to be interpolated linearly between their two closest edges, even if + * these are not part of the contour of those particular points. + * Typical candidates for this are + * + * - angle points (i.e., points where the `in' and `out' direction + * differ greatly) + * + * - inflection points (i.e., where the `in' and `out' angles are the + * same, but the curvature changes sign) + * + * `af_glyph_hints_align_strong_points' is the function which takes + * care of such situations; it is equivalent to the TrueType `IP' + * hinting instruction. + * + * + * Weak Points + * + * Other points in the outline must be interpolated using the + * coordinates of their previous and next unfitted contour neighbours. + * These are called `weak points' and are touched by the function + * `af_glyph_hints_align_weak_points', equivalent to the TrueType `IUP' + * hinting instruction. Typical candidates are control points and + * points on the contour without a major direction. + * + * The major effect is to reduce possible distortion caused by + * alignment of edges and strong points, thus weak points are processed + * after strong points. + */ + + /* point hint flags */ typedef enum AF_Flags_ { @@ -155,32 +277,31 @@ FT_BEGIN_HEADER FT_Fixed scale; /* used to speed up interpolation between edges */ AF_Width blue_edge; /* non-NULL if this is a blue edge */ - AF_Edge link; - AF_Edge serif; - FT_Short num_linked; + AF_Edge link; /* link edge */ + AF_Edge serif; /* primary edge for serifs */ + FT_Short num_linked; /* number of linked edges */ + FT_Int score; /* used during stem matching */ - FT_Int score; - - AF_Segment first; - AF_Segment last; + AF_Segment first; /* first segment in edge */ + AF_Segment last; /* last segment in edge */ } AF_EdgeRec; typedef struct AF_AxisHintsRec_ { - FT_Int num_segments; - FT_Int max_segments; - AF_Segment segments; + FT_Int num_segments; /* number of used segments */ + FT_Int max_segments; /* number of allocated segments */ + AF_Segment segments; /* segments array */ #ifdef AF_SORT_SEGMENTS FT_Int mid_segments; #endif - FT_Int num_edges; - FT_Int max_edges; - AF_Edge edges; + FT_Int num_edges; /* number of used edges */ + FT_Int max_edges; /* number of allocated edges */ + AF_Edge edges; /* edges array */ - AF_Direction major_dir; + AF_Direction major_dir; /* either vertical or horizontal */ } AF_AxisHintsRec, *AF_AxisHints; @@ -197,13 +318,13 @@ FT_BEGIN_HEADER FT_Pos edge_distance_threshold; - FT_Int max_points; - FT_Int num_points; - AF_Point points; + FT_Int max_points; /* number of allocated points */ + FT_Int num_points; /* number of used points */ + AF_Point points; /* points array */ - FT_Int max_contours; - FT_Int num_contours; - AF_Point* contours; + FT_Int max_contours; /* number of allocated contours */ + FT_Int num_contours; /* number of used contours */ + AF_Point* contours; /* contours array */ AF_AxisHintsRec axis[AF_DIMENSION_MAX]; @@ -214,7 +335,7 @@ FT_BEGIN_HEADER FT_Pos xmin_delta; /* used for warping */ FT_Pos xmax_delta; - + } AF_GlyphHintsRec; @@ -274,12 +395,6 @@ FT_BEGIN_HEADER af_glyph_hints_init( AF_GlyphHints hints, FT_Memory memory ); - - - /* - * recompute all AF_Point in a AF_GlyphHints from the definitions - * in a source outline - */ FT_LOCAL( void ) af_glyph_hints_rescale( AF_GlyphHints hints, AF_ScriptMetrics metrics ); -- cgit v1.2.3