src/autofit/afhints.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  afhints.h                                                              */
   4 /*                                                                         */
   5 /*    Auto-fitter hinting routines (specification).                        */
   6 /*                                                                         */
   7 /*  Copyright 2003-2008, 2010-2012, 2014 by                                */
   8 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
   9 /*                                                                         */
  10 /*  This file is part of the FreeType project, and may only be used,       */
  11 /*  modified, and distributed under the terms of the FreeType project      */
  12 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
  13 /*  this file you indicate that you have read the license and              */
  14 /*  understand and accept it fully.                                        */
  15 /*                                                                         */
  16 /***************************************************************************/
  17
  18
  19 #ifndef __AFHINTS_H__
  20 #define __AFHINTS_H__
  21
  22 #include "aftypes.h"
  23
  24 #define xxAF_SORT_SEGMENTS
  25
  26 FT_BEGIN_HEADER
  27
  28   /*
  29    *  The definition of outline glyph hints.  These are shared by all
  30    *  writing system analysis routines (until now).
  31    */
  32
  33   typedef enum  AF_Dimension_
  34   {
  35     AF_DIMENSION_HORZ = 0,  /* x coordinates,                    */
  36                             /* i.e., vertical segments & edges   */
  37     AF_DIMENSION_VERT = 1,  /* y coordinates,                    */
  38                             /* i.e., horizontal segments & edges */
  39
  40     AF_DIMENSION_MAX  /* do not remove */
  41
  42   } AF_Dimension;
  43
  44
  45   /* hint directions -- the values are computed so that two vectors are */
  46   /* in opposite directions iff `dir1 + dir2 == 0'                      */
  47   typedef enum  AF_Direction_
  48   {
  49     AF_DIR_NONE  =  4,
  50     AF_DIR_RIGHT =  1,
  51     AF_DIR_LEFT  = -1,
  52     AF_DIR_UP    =  2,
  53     AF_DIR_DOWN  = -2
  54
  55   } AF_Direction;
  56
  57
  58   /*
  59    *  The following explanations are mostly taken from the article
  60    *
  61    *    Real-Time Grid Fitting of Typographic Outlines
  62    *
  63    *  by David Turner and Werner Lemberg
  64    *
  65    *    http://www.tug.org/TUGboat/Articles/tb24-3/lemberg.pdf
  66    *
  67    *  with appropriate updates.
  68    *
  69    *
  70    *  Segments
  71    *
  72    *    `af_{cjk,latin,...}_hints_compute_segments' are the functions to
  73    *    find segments in an outline.
  74    *
  75    *    A segment is a series of at least two consecutive points that are
  76    *    approximately aligned along a coordinate axis.  The analysis to do
  77    *    so is specific to a writing system.
  78    *
  79    *
  80    *  Edges
  81    *
  82    *    `af_{cjk,latin,...}_hints_compute_edges' are the functions to find
  83    *    edges.
  84    *
  85    *    As soon as segments are defined, the auto-hinter groups them into
  86    *    edges.  An edge corresponds to a single position on the main
  87    *    dimension that collects one or more segments (allowing for a small
  88    *    threshold).
  89    *
  90    *    As an example, the `latin' writing system first tries to grid-fit
  91    *    edges, then to align segments on the edges unless it detects that
  92    *    they form a serif.
  93    *
  94    *
  95    *                      A          H
  96    *                       |        |
  97    *                       |        |
  98    *                       |        |
  99    *                       |        |
 100    *         C             |        |             F
 101    *          +------<-----+        +-----<------+
 102    *          |             B      G             |
 103    *          |                                  |
 104    *          |                                  |
 105    *          +--------------->------------------+
 106    *         D                                    E
 107    *
 108    *
 109    *  Stems
 110    *
 111    *    Stems are detected by `af_{cjk,latin,...}_hint_edges'.
 112    *
 113    *    Segments need to be `linked' to other ones in order to detect stems.
 114    *    A stem is made of two segments that face each other in opposite
 115    *    directions and that are sufficiently close to each other.  Using
 116    *    vocabulary from the TrueType specification, stem segments form a
 117    *    `black distance'.
 118    *
 119    *    In the above ASCII drawing, the horizontal segments are BC, DE, and
 120    *    FG; the vertical segments are AB, CD, EF, and GH.
 121    *
 122    *    Each segment has at most one `best' candidate to form a black
 123    *    distance, or no candidate at all.  Notice that two distinct segments
 124    *    can have the same candidate, which frequently means a serif.
 125    *
 126    *    A stem is recognized by the following condition:
 127    *
 128    *      best segment_1 = segment_2 && best segment_2 = segment_1
 129    *
 130    *    The best candidate is stored in field `link' in structure
 131    *    `AF_Segment'.
 132    *
 133    *    In the above ASCII drawing, the best candidate for both AB and CD is
 134    *    GH, while the best candidate for GH is AB.  Similarly, the best
 135    *    candidate for EF and GH is AB, while the best candidate for AB is
 136    *    GH.
 137    *
 138    *    The detection and handling of stems is dependent on the writing
 139    *    system.
 140    *
 141    *
 142    *  Serifs
 143    *
 144    *    Serifs are detected by `af_{cjk,latin,...}_hint_edges'.
 145    *
 146    *    In comparison to a stem, a serif (as handled by the auto-hinter
 147    *    module that takes care of the `latin' writing system) has
 148    *
 149    *      best segment_1 = segment_2 && best segment_2 != segment_1
 150    *
 151    *    where segment_1 corresponds to the serif segment (CD and EF in the
 152    *    above ASCII drawing).
 153    *
 154    *    The best candidate is stored in field `serif' in structure
 155    *    `AF_Segment' (and `link' is set to NULL).
 156    *
 157    *
 158    *  Touched points
 159    *
 160    *    A point is called `touched' if it has been processed somehow by the
 161    *    auto-hinter.  It basically means that it shouldn't be moved again
 162    *    (or moved only under certain constraints to preserve the already
 163    *    applied processing).
 164    *
 165    *
 166    *  Flat and round segments
 167    *
 168    *    Segments are `round' or `flat', depending on the series of points
 169    *    that define them.  A segment is round if the next and previous point
 170    *    of an extremum (which can be either a single point or sequence of
 171    *    points) are both conic or cubic control points.  Otherwise, a
 172    *    segment with an extremum is flat.
 173    *
 174    *
 175    *  Strong Points
 176    *
 177    *    Experience has shown that points not part of an edge need to be
 178    *    interpolated linearly between their two closest edges, even if these
 179    *    are not part of the contour of those particular points.  Typical
 180    *    candidates for this are
 181    *
 182    *    - angle points (i.e., points where the `in' and `out' direction
 183    *      differ greatly)
 184    *
 185    *    - inflection points (i.e., where the `in' and `out' angles are the
 186    *      same, but the curvature changes sign) [currently, such points
 187    *      aren't handled specially in the auto-hinter]
 188    *
 189    *    `af_glyph_hints_align_strong_points' is the function that takes
 190    *    care of such situations; it is equivalent to the TrueType `IP'
 191    *    hinting instruction.
 192    *
 193    *
 194    *  Weak Points
 195    *
 196    *    Other points in the outline must be interpolated using the
 197    *    coordinates of their previous and next unfitted contour neighbours.
 198    *    These are called `weak points' and are touched by the function
 199    *    `af_glyph_hints_align_weak_points', equivalent to the TrueType `IUP'
 200    *    hinting instruction.  Typical candidates are control points and
 201    *    points on the contour without a major direction.
 202    *
 203    *    The major effect is to reduce possible distortion caused by
 204    *    alignment of edges and strong points, thus weak points are processed
 205    *    after strong points.
 206    */
 207
 208
 209   /* point hint flags */
 210   typedef enum  AF_Flags_
 211   {
 212     AF_FLAG_NONE = 0,
 213
 214     /* point type flags */
 215     AF_FLAG_CONIC   = 1 << 0,
 216     AF_FLAG_CUBIC   = 1 << 1,
 217     AF_FLAG_CONTROL = AF_FLAG_CONIC | AF_FLAG_CUBIC,
 218
 219     /* point touch flags */
 220     AF_FLAG_TOUCH_X = 1 << 2,
 221     AF_FLAG_TOUCH_Y = 1 << 3,
 222
 223     /* candidates for weak interpolation have this flag set */
 224     AF_FLAG_WEAK_INTERPOLATION = 1 << 4
 225
 226   } AF_Flags;
 227
 228
 229   /* edge hint flags */
 230   typedef enum  AF_Edge_Flags_
 231   {
 232     AF_EDGE_NORMAL  = 0,
 233     AF_EDGE_ROUND   = 1 << 0,
 234     AF_EDGE_SERIF   = 1 << 1,
 235     AF_EDGE_DONE    = 1 << 2,
 236     AF_EDGE_NEUTRAL = 1 << 3  /* set if edge aligns to a neutral blue zone */
 237
 238   } AF_Edge_Flags;
 239
 240
 241   typedef struct AF_PointRec_*    AF_Point;
 242   typedef struct AF_SegmentRec_*  AF_Segment;
 243   typedef struct AF_EdgeRec_*     AF_Edge;
 244
 245
 246   typedef struct  AF_PointRec_
 247   {
 248     FT_UShort  flags;    /* point flags used by hinter   */
 249     FT_Char    in_dir;   /* direction of inwards vector  */
 250     FT_Char    out_dir;  /* direction of outwards vector */
 251
 252     FT_Pos     ox, oy;   /* original, scaled position                   */
 253     FT_Short   fx, fy;   /* original, unscaled position (in font units) */
 254     FT_Pos     x, y;     /* current position                            */
 255     FT_Pos     u, v;     /* current (x,y) or (y,x) depending on context */
 256
 257     AF_Point   next;     /* next point in contour     */
 258     AF_Point   prev;     /* previous point in contour */
 259
 260   } AF_PointRec;
 261
 262
 263   typedef struct  AF_SegmentRec_
 264   {
 265     FT_Byte     flags;       /* edge/segment flags for this segment */
 266     FT_Char     dir;         /* segment direction                   */
 267     FT_Short    pos;         /* position of segment                 */
 268     FT_Short    min_coord;   /* minimum coordinate of segment       */
 269     FT_Short    max_coord;   /* maximum coordinate of segment       */
 270     FT_Short    height;      /* the hinted segment height           */
 271
 272     AF_Edge     edge;        /* the segment's parent edge           */
 273     AF_Segment  edge_next;   /* link to next segment in parent edge */
 274
 275     AF_Segment  link;        /* (stem) link segment        */
 276     AF_Segment  serif;       /* primary segment for serifs */
 277     FT_Pos      num_linked;  /* number of linked segments  */
 278     FT_Pos      score;       /* used during stem matching  */
 279     FT_Pos      len;         /* used during stem matching  */
 280
 281     AF_Point    first;       /* first point in edge segment */
 282     AF_Point    last;        /* last point in edge segment  */
 283
 284   } AF_SegmentRec;
 285
 286
 287   typedef struct  AF_EdgeRec_
 288   {
 289     FT_Short    fpos;       /* original, unscaled position (in font units) */
 290     FT_Pos      opos;       /* original, scaled position                   */
 291     FT_Pos      pos;        /* current position                            */
 292
 293     FT_Byte     flags;      /* edge flags                                   */
 294     FT_Char     dir;        /* edge direction                               */
 295     FT_Fixed    scale;      /* used to speed up interpolation between edges */
 296
 297     AF_Width    blue_edge;  /* non-NULL if this is a blue edge */
 298     AF_Edge     link;       /* link edge                       */
 299     AF_Edge     serif;      /* primary edge for serifs         */
 300     FT_Short    num_linked; /* number of linked edges          */
 301     FT_Int      score;      /* used during stem matching       */
 302
 303     AF_Segment  first;      /* first segment in edge */
 304     AF_Segment  last;       /* last segment in edge  */
 305
 306   } AF_EdgeRec;
 307
 308
 309   typedef struct  AF_AxisHintsRec_
 310   {
 311     FT_Int        num_segments; /* number of used segments      */
 312     FT_Int        max_segments; /* number of allocated segments */
 313     AF_Segment    segments;     /* segments array               */
 314 #ifdef AF_SORT_SEGMENTS
 315     FT_Int        mid_segments;
 316 #endif
 317
 318     FT_Int        num_edges;    /* number of used edges      */
 319     FT_Int        max_edges;    /* number of allocated edges */
 320     AF_Edge       edges;        /* edges array               */
 321
 322     AF_Direction  major_dir;    /* either vertical or horizontal */
 323
 324   } AF_AxisHintsRec, *AF_AxisHints;
 325
 326
 327   typedef struct  AF_GlyphHintsRec_
 328   {
 329     FT_Memory        memory;
 330
 331     FT_Fixed         x_scale;
 332     FT_Pos           x_delta;
 333
 334     FT_Fixed         y_scale;
 335     FT_Pos           y_delta;
 336
 337     FT_Int           max_points;    /* number of allocated points */
 338     FT_Int           num_points;    /* number of used points      */
 339     AF_Point         points;        /* points array               */
 340
 341     FT_Int           max_contours;  /* number of allocated contours */
 342     FT_Int           num_contours;  /* number of used contours      */
 343     AF_Point*        contours;      /* contours array               */
 344
 345     AF_AxisHintsRec  axis[AF_DIMENSION_MAX];
 346
 347     FT_UInt32        scaler_flags;  /* copy of scaler flags    */
 348     FT_UInt32        other_flags;   /* free for style-specific */
 349                                     /* implementations         */
 350     AF_StyleMetrics  metrics;
 351
 352     FT_Pos           xmin_delta;    /* used for warping */
 353     FT_Pos           xmax_delta;
 354
 355   } AF_GlyphHintsRec;
 356
 357
 358 #define AF_HINTS_TEST_SCALER( h, f )  ( (h)->scaler_flags & (f) )
 359 #define AF_HINTS_TEST_OTHER( h, f )   ( (h)->other_flags  & (f) )
 360
 361
 362 #ifdef FT_DEBUG_AUTOFIT
 363
 364 #define AF_HINTS_DO_HORIZONTAL( h )                                     \
 365           ( !_af_debug_disable_horz_hints                            && \
 366             !AF_HINTS_TEST_SCALER( h, AF_SCALER_FLAG_NO_HORIZONTAL ) )
 367
 368 #define AF_HINTS_DO_VERTICAL( h )                                     \
 369           ( !_af_debug_disable_vert_hints                          && \
 370             !AF_HINTS_TEST_SCALER( h, AF_SCALER_FLAG_NO_VERTICAL ) )
 371
 372 #define AF_HINTS_DO_ADVANCE( h )                                \
 373           !AF_HINTS_TEST_SCALER( h, AF_SCALER_FLAG_NO_ADVANCE )
 374
 375 #define AF_HINTS_DO_BLUES( h )  ( !_af_debug_disable_blue_hints )
 376
 377 #else /* !FT_DEBUG_AUTOFIT */
 378
 379 #define AF_HINTS_DO_HORIZONTAL( h )                                \
 380           !AF_HINTS_TEST_SCALER( h, AF_SCALER_FLAG_NO_HORIZONTAL )
 381
 382 #define AF_HINTS_DO_VERTICAL( h )                                \
 383           !AF_HINTS_TEST_SCALER( h, AF_SCALER_FLAG_NO_VERTICAL )
 384
 385 #define AF_HINTS_DO_ADVANCE( h )                                \
 386           !AF_HINTS_TEST_SCALER( h, AF_SCALER_FLAG_NO_ADVANCE )
 387
 388 #define AF_HINTS_DO_BLUES( h )  1
 389
 390 #endif /* !FT_DEBUG_AUTOFIT */
 391
 392
 393   FT_LOCAL( AF_Direction )
 394   af_direction_compute( FT_Pos  dx,
 395                         FT_Pos  dy );
 396
 397
 398   FT_LOCAL( FT_Error )
 399   af_axis_hints_new_segment( AF_AxisHints  axis,
 400                              FT_Memory     memory,
 401                              AF_Segment   *asegment );
 402
 403   FT_LOCAL( FT_Error)
 404   af_axis_hints_new_edge( AF_AxisHints  axis,
 405                           FT_Int        fpos,
 406                           AF_Direction  dir,
 407                           FT_Memory     memory,
 408                           AF_Edge      *edge );
 409
 410   FT_LOCAL( void )
 411   af_glyph_hints_init( AF_GlyphHints  hints,
 412                        FT_Memory      memory );
 413
 414   FT_LOCAL( void )
 415   af_glyph_hints_rescale( AF_GlyphHints    hints,
 416                           AF_StyleMetrics  metrics );
 417
 418   FT_LOCAL( FT_Error )
 419   af_glyph_hints_reload( AF_GlyphHints  hints,
 420                          FT_Outline*    outline );
 421
 422   FT_LOCAL( void )
 423   af_glyph_hints_save( AF_GlyphHints  hints,
 424                        FT_Outline*    outline );
 425
 426   FT_LOCAL( void )
 427   af_glyph_hints_align_edge_points( AF_GlyphHints  hints,
 428                                     AF_Dimension   dim );
 429
 430   FT_LOCAL( void )
 431   af_glyph_hints_align_strong_points( AF_GlyphHints  hints,
 432                                       AF_Dimension   dim );
 433
 434   FT_LOCAL( void )
 435   af_glyph_hints_align_weak_points( AF_GlyphHints  hints,
 436                                     AF_Dimension   dim );
 437
 438 #ifdef AF_CONFIG_OPTION_USE_WARPER
 439   FT_LOCAL( void )
 440   af_glyph_hints_scale_dim( AF_GlyphHints  hints,
 441                             AF_Dimension   dim,
 442                             FT_Fixed       scale,
 443                             FT_Pos         delta );
 444 #endif
 445
 446   FT_LOCAL( void )
 447   af_glyph_hints_done( AF_GlyphHints  hints );
 448
 449 /* */
 450
 451 #define AF_SEGMENT_LEN( seg )          ( (seg)->max_coord - (seg)->min_coord )
 452
 453 #define AF_SEGMENT_DIST( seg1, seg2 )  ( ( (seg1)->pos > (seg2)->pos )   \
 454                                            ? (seg1)->pos - (seg2)->pos   \
 455                                            : (seg2)->pos - (seg1)->pos )
 456
 457
 458 FT_END_HEADER
 459
 460 #endif /* __AFHINTS_H__ */
 461
 462
 463 /* END */