reactos/lib/3rdparty/freetype/src/autofit/afhints.h

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