• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /***************************************************************************/
2 /*                                                                         */
3 /*  aftypes.h                                                              */
4 /*                                                                         */
5 /*    Auto-fitter types (specification only).                              */
6 /*                                                                         */
7 /*  Copyright 2003-2017 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   /*************************************************************************
20    *
21    *  The auto-fitter is a complete rewrite of the old auto-hinter.
22    *  Its main feature is the ability to differentiate between different
23    *  writing systems and scripts in order to apply specific rules.
24    *
25    *  The code has also been compartmentalized into several entities that
26    *  should make algorithmic experimentation easier than with the old
27    *  code.
28    *
29    *************************************************************************/
30 
31 
32 #ifndef AFTYPES_H_
33 #define AFTYPES_H_
34 
35 #include <ft2build.h>
36 
37 #include FT_FREETYPE_H
38 #include FT_OUTLINE_H
39 #include FT_INTERNAL_OBJECTS_H
40 #include FT_INTERNAL_DEBUG_H
41 
42 #include "afblue.h"
43 
44 #ifdef FT_DEBUG_AUTOFIT
45 #include FT_CONFIG_STANDARD_LIBRARY_H
46 #endif
47 
48 
49 FT_BEGIN_HEADER
50 
51   /*************************************************************************/
52   /*************************************************************************/
53   /*****                                                               *****/
54   /*****                    D E B U G G I N G                          *****/
55   /*****                                                               *****/
56   /*************************************************************************/
57   /*************************************************************************/
58 
59 #ifdef FT_DEBUG_AUTOFIT
60 
61 extern int    _af_debug_disable_horz_hints;
62 extern int    _af_debug_disable_vert_hints;
63 extern int    _af_debug_disable_blue_hints;
64 extern void*  _af_debug_hints;
65 
66 #endif /* FT_DEBUG_AUTOFIT */
67 
68 
69   /*************************************************************************/
70   /*************************************************************************/
71   /*****                                                               *****/
72   /*****                 U T I L I T Y   S T U F F                     *****/
73   /*****                                                               *****/
74   /*************************************************************************/
75   /*************************************************************************/
76 
77   typedef struct  AF_WidthRec_
78   {
79     FT_Pos  org;  /* original position/width in font units              */
80     FT_Pos  cur;  /* current/scaled position/width in device sub-pixels */
81     FT_Pos  fit;  /* current/fitted position/width in device sub-pixels */
82 
83   } AF_WidthRec, *AF_Width;
84 
85 
86   FT_LOCAL( void )
87   af_sort_pos( FT_UInt  count,
88                FT_Pos*  table );
89 
90   FT_LOCAL( void )
91   af_sort_and_quantize_widths( FT_UInt*  count,
92                                AF_Width  widths,
93                                FT_Pos    threshold );
94 
95 
96   /*************************************************************************/
97   /*************************************************************************/
98   /*****                                                               *****/
99   /*****                   A N G L E   T Y P E S                       *****/
100   /*****                                                               *****/
101   /*************************************************************************/
102   /*************************************************************************/
103 
104   /*
105    *  The auto-fitter doesn't need a very high angular accuracy;
106    *  this allows us to speed up some computations considerably with a
107    *  light Cordic algorithm (see afangles.c).
108    */
109 
110   typedef FT_Int  AF_Angle;
111 
112 
113 #define AF_ANGLE_PI   256
114 #define AF_ANGLE_2PI  ( AF_ANGLE_PI * 2 )
115 #define AF_ANGLE_PI2  ( AF_ANGLE_PI / 2 )
116 #define AF_ANGLE_PI4  ( AF_ANGLE_PI / 4 )
117 
118 
119 #if 0
120   /*
121    *  compute the angle of a given 2-D vector
122    */
123   FT_LOCAL( AF_Angle )
124   af_angle_atan( FT_Pos  dx,
125                  FT_Pos  dy );
126 
127 
128   /*
129    *  compute `angle2 - angle1'; the result is always within
130    *  the range [-AF_ANGLE_PI .. AF_ANGLE_PI - 1]
131    */
132   FT_LOCAL( AF_Angle )
133   af_angle_diff( AF_Angle  angle1,
134                  AF_Angle  angle2 );
135 #endif /* 0 */
136 
137 
138 #define AF_ANGLE_DIFF( result, angle1, angle2 ) \
139   FT_BEGIN_STMNT                                \
140     AF_Angle  _delta = (angle2) - (angle1);     \
141                                                 \
142                                                 \
143     while ( _delta <= -AF_ANGLE_PI )            \
144       _delta += AF_ANGLE_2PI;                   \
145                                                 \
146     while ( _delta > AF_ANGLE_PI )              \
147       _delta -= AF_ANGLE_2PI;                   \
148                                                 \
149     result = _delta;                            \
150   FT_END_STMNT
151 
152 
153   /*  opaque handle to glyph-specific hints -- see `afhints.h' for more
154    *  details
155    */
156   typedef struct AF_GlyphHintsRec_*  AF_GlyphHints;
157 
158 
159   /*************************************************************************/
160   /*************************************************************************/
161   /*****                                                               *****/
162   /*****                       S C A L E R S                           *****/
163   /*****                                                               *****/
164   /*************************************************************************/
165   /*************************************************************************/
166 
167   /*
168    *  A scaler models the target pixel device that will receive the
169    *  auto-hinted glyph image.
170    */
171 
172 #define AF_SCALER_FLAG_NO_HORIZONTAL  1U /* disable horizontal hinting */
173 #define AF_SCALER_FLAG_NO_VERTICAL    2U /* disable vertical hinting   */
174 #define AF_SCALER_FLAG_NO_ADVANCE     4U /* disable advance hinting    */
175 #define AF_SCALER_FLAG_NO_WARPER      8U /* disable warper             */
176 
177 
178   typedef struct  AF_ScalerRec_
179   {
180     FT_Face         face;        /* source font face                        */
181     FT_Fixed        x_scale;     /* from font units to 1/64th device pixels */
182     FT_Fixed        y_scale;     /* from font units to 1/64th device pixels */
183     FT_Pos          x_delta;     /* in 1/64th device pixels                 */
184     FT_Pos          y_delta;     /* in 1/64th device pixels                 */
185     FT_Render_Mode  render_mode; /* monochrome, anti-aliased, LCD, etc.     */
186     FT_UInt32       flags;       /* additional control flags, see above     */
187 
188   } AF_ScalerRec, *AF_Scaler;
189 
190 
191 #define AF_SCALER_EQUAL_SCALES( a, b )      \
192           ( (a)->x_scale == (b)->x_scale && \
193             (a)->y_scale == (b)->y_scale && \
194             (a)->x_delta == (b)->x_delta && \
195             (a)->y_delta == (b)->y_delta )
196 
197 
198   typedef struct AF_StyleMetricsRec_*  AF_StyleMetrics;
199 
200   /*  This function parses an FT_Face to compute global metrics for
201    *  a specific style.
202    */
203   typedef FT_Error
204   (*AF_WritingSystem_InitMetricsFunc)( AF_StyleMetrics  metrics,
205                                        FT_Face          face );
206 
207   typedef void
208   (*AF_WritingSystem_ScaleMetricsFunc)( AF_StyleMetrics  metrics,
209                                         AF_Scaler        scaler );
210 
211   typedef void
212   (*AF_WritingSystem_DoneMetricsFunc)( AF_StyleMetrics  metrics );
213 
214   typedef void
215   (*AF_WritingSystem_GetStdWidthsFunc)( AF_StyleMetrics  metrics,
216                                         FT_Pos*          stdHW,
217                                         FT_Pos*          stdVW );
218 
219 
220   typedef FT_Error
221   (*AF_WritingSystem_InitHintsFunc)( AF_GlyphHints    hints,
222                                      AF_StyleMetrics  metrics );
223 
224   typedef FT_Error
225   (*AF_WritingSystem_ApplyHintsFunc)( FT_UInt          glyph_index,
226                                       AF_GlyphHints    hints,
227                                       FT_Outline*      outline,
228                                       AF_StyleMetrics  metrics );
229 
230 
231   /*************************************************************************/
232   /*************************************************************************/
233   /*****                                                               *****/
234   /*****                W R I T I N G   S Y S T E M S                  *****/
235   /*****                                                               *****/
236   /*************************************************************************/
237   /*************************************************************************/
238 
239   /*
240    *  For the auto-hinter, a writing system consists of multiple scripts that
241    *  can be handled similarly *in a typographical way*; the relationship is
242    *  not based on history.  For example, both the Greek and the unrelated
243    *  Armenian scripts share the same features like ascender, descender,
244    *  x-height, etc.  Essentially, a writing system is covered by a
245    *  submodule of the auto-fitter; it contains
246    *
247    *  - a specific global analyzer that computes global metrics specific to
248    *    the script (based on script-specific characters to identify ascender
249    *    height, x-height, etc.),
250    *
251    *  - a specific glyph analyzer that computes segments and edges for each
252    *    glyph covered by the script,
253    *
254    *  - a specific grid-fitting algorithm that distorts the scaled glyph
255    *    outline according to the results of the glyph analyzer.
256    */
257 
258 #define AFWRTSYS_H_  /* don't load header files */
259 #undef  WRITING_SYSTEM
260 #define WRITING_SYSTEM( ws, WS )    \
261           AF_WRITING_SYSTEM_ ## WS,
262 
263   /* The list of known writing systems. */
264   typedef enum  AF_WritingSystem_
265   {
266 
267 #include "afwrtsys.h"
268 
269     AF_WRITING_SYSTEM_MAX   /* do not remove */
270 
271   } AF_WritingSystem;
272 
273 #undef  AFWRTSYS_H_
274 
275 
276   typedef struct  AF_WritingSystemClassRec_
277   {
278     AF_WritingSystem  writing_system;
279 
280     FT_Offset                          style_metrics_size;
281     AF_WritingSystem_InitMetricsFunc   style_metrics_init;
282     AF_WritingSystem_ScaleMetricsFunc  style_metrics_scale;
283     AF_WritingSystem_DoneMetricsFunc   style_metrics_done;
284     AF_WritingSystem_GetStdWidthsFunc  style_metrics_getstdw;
285 
286     AF_WritingSystem_InitHintsFunc     style_hints_init;
287     AF_WritingSystem_ApplyHintsFunc    style_hints_apply;
288 
289   } AF_WritingSystemClassRec;
290 
291   typedef const AF_WritingSystemClassRec*  AF_WritingSystemClass;
292 
293 
294   /*************************************************************************/
295   /*************************************************************************/
296   /*****                                                               *****/
297   /*****                        S C R I P T S                          *****/
298   /*****                                                               *****/
299   /*************************************************************************/
300   /*************************************************************************/
301 
302   /*
303    *  Each script is associated with two sets of Unicode ranges to test
304    *  whether the font face supports the script, and which non-base
305    *  characters the script contains.
306    *
307    *  We use four-letter script tags from the OpenType specification,
308    *  extended by `NONE', which indicates `no script'.
309    */
310 
311 #undef  SCRIPT
312 #define SCRIPT( s, S, d, h, H, ss ) \
313           AF_SCRIPT_ ## S,
314 
315   /* The list of known scripts. */
316   typedef enum  AF_Script_
317   {
318 
319 #include "afscript.h"
320 
321     AF_SCRIPT_MAX   /* do not remove */
322 
323   } AF_Script;
324 
325 
326   typedef struct  AF_Script_UniRangeRec_
327   {
328     FT_UInt32  first;
329     FT_UInt32  last;
330 
331   } AF_Script_UniRangeRec;
332 
333 #define AF_UNIRANGE_REC( a, b ) { (FT_UInt32)(a), (FT_UInt32)(b) }
334 
335   typedef const AF_Script_UniRangeRec*  AF_Script_UniRange;
336 
337 
338   typedef struct  AF_ScriptClassRec_
339   {
340     AF_Script  script;
341 
342     /* last element in the ranges must be { 0, 0 } */
343     AF_Script_UniRange  script_uni_ranges;
344     AF_Script_UniRange  script_uni_nonbase_ranges;
345 
346     FT_Bool  top_to_bottom_hinting;
347 
348     const char*  standard_charstring;      /* for default width and height */
349 
350   } AF_ScriptClassRec;
351 
352   typedef const AF_ScriptClassRec*  AF_ScriptClass;
353 
354 
355   /*************************************************************************/
356   /*************************************************************************/
357   /*****                                                               *****/
358   /*****                      C O V E R A G E S                        *****/
359   /*****                                                               *****/
360   /*************************************************************************/
361   /*************************************************************************/
362 
363   /*
364    *  Usually, a font contains more glyphs than can be addressed by its
365    *  character map.
366    *
367    *  In the PostScript font world, encoding vectors specific to a given
368    *  task are used to select such glyphs, and these glyphs can be often
369    *  recognized by having a suffix in its glyph names.  For example, a
370    *  superscript glyph `A' might be called `A.sup'.  Unfortunately, this
371    *  naming scheme is not standardized and thus unusable for us.
372    *
373    *  In the OpenType world, a better solution was invented, namely
374    *  `features', which cleanly separate a character's input encoding from
375    *  the corresponding glyph's appearance, and which don't use glyph names
376    *  at all.  For our purposes, and slightly generalized, an OpenType
377    *  feature is a name of a mapping that maps character codes to
378    *  non-standard glyph indices (features get used for other things also).
379    *  For example, the `sups' feature provides superscript glyphs, thus
380    *  mapping character codes like `A' or `B' to superscript glyph
381    *  representation forms.  How this mapping happens is completely
382    *  uninteresting to us.
383    *
384    *  For the auto-hinter, a `coverage' represents all glyphs of an OpenType
385    *  feature collected in a set (as listed below) that can be hinted
386    *  together.  To continue the above example, superscript glyphs must not
387    *  be hinted together with normal glyphs because the blue zones
388    *  completely differ.
389    *
390    *  Note that FreeType itself doesn't compute coverages; it only provides
391    *  the glyphs addressable by the default Unicode character map.  Instead,
392    *  we use the HarfBuzz library (if available), which has many functions
393    *  exactly for this purpose.
394    *
395    *  AF_COVERAGE_DEFAULT is special: It should cover everything that isn't
396    *  listed separately (including the glyphs addressable by the character
397    *  map).  In case HarfBuzz isn't available, it exactly covers the glyphs
398    *  addressable by the character map.
399    *
400    */
401 
402 #undef  COVERAGE
403 #define COVERAGE( name, NAME, description, \
404                   tag1, tag2, tag3, tag4 ) \
405           AF_COVERAGE_ ## NAME,
406 
407 
408   typedef enum  AF_Coverage_
409   {
410 #include "afcover.h"
411 
412     AF_COVERAGE_DEFAULT
413 
414   } AF_Coverage;
415 
416 
417   /*************************************************************************/
418   /*************************************************************************/
419   /*****                                                               *****/
420   /*****                         S T Y L E S                           *****/
421   /*****                                                               *****/
422   /*************************************************************************/
423   /*************************************************************************/
424 
425   /*
426    *  The topmost structure for modelling the auto-hinter glyph input data
427    *  is a `style class', grouping everything together.
428    */
429 
430 #undef  STYLE
431 #define STYLE( s, S, d, ws, sc, ss, c ) \
432           AF_STYLE_ ## S,
433 
434   /* The list of known styles. */
435   typedef enum  AF_Style_
436   {
437 
438 #include "afstyles.h"
439 
440     AF_STYLE_MAX   /* do not remove */
441 
442   } AF_Style;
443 
444 
445   typedef struct  AF_StyleClassRec_
446   {
447     AF_Style  style;
448 
449     AF_WritingSystem   writing_system;
450     AF_Script          script;
451     AF_Blue_Stringset  blue_stringset;
452     AF_Coverage        coverage;
453 
454   } AF_StyleClassRec;
455 
456   typedef const AF_StyleClassRec*  AF_StyleClass;
457 
458 
459   /*************************************************************************/
460   /*************************************************************************/
461   /*****                                                               *****/
462   /*****                   S T Y L E   M E T R I C S                   *****/
463   /*****                                                               *****/
464   /*************************************************************************/
465   /*************************************************************************/
466 
467   typedef struct AF_FaceGlobalsRec_*  AF_FaceGlobals;
468 
469   /* This is the main structure that combines everything.  Autofit modules */
470   /* specific to writing systems derive their structures from it, for      */
471   /* example `AF_LatinMetrics'.                                            */
472 
473   typedef struct  AF_StyleMetricsRec_
474   {
475     AF_StyleClass   style_class;
476     AF_ScalerRec    scaler;
477     FT_Bool         digits_have_same_width;
478 
479     AF_FaceGlobals  globals;    /* to access properties */
480 
481   } AF_StyleMetricsRec;
482 
483 
484 #define AF_HINTING_BOTTOM_TO_TOP  0
485 #define AF_HINTING_TOP_TO_BOTTOM  1
486 
487 
488   /* Declare and define vtables for classes */
489 #ifndef FT_CONFIG_OPTION_PIC
490 
491 #define AF_DECLARE_WRITING_SYSTEM_CLASS( writing_system_class ) \
492   FT_CALLBACK_TABLE const AF_WritingSystemClassRec              \
493   writing_system_class;
494 
495 #define AF_DEFINE_WRITING_SYSTEM_CLASS(                  \
496           writing_system_class,                          \
497           system,                                        \
498           m_size,                                        \
499           m_init,                                        \
500           m_scale,                                       \
501           m_done,                                        \
502           m_stdw,                                        \
503           h_init,                                        \
504           h_apply )                                      \
505   FT_CALLBACK_TABLE_DEF                                  \
506   const AF_WritingSystemClassRec  writing_system_class = \
507   {                                                      \
508     system,                                              \
509                                                          \
510     m_size,                                              \
511                                                          \
512     m_init,                                              \
513     m_scale,                                             \
514     m_done,                                              \
515     m_stdw,                                              \
516                                                          \
517     h_init,                                              \
518     h_apply                                              \
519   };
520 
521 
522 #define AF_DECLARE_SCRIPT_CLASS( script_class ) \
523   FT_CALLBACK_TABLE const AF_ScriptClassRec     \
524   script_class;
525 
526 #define AF_DEFINE_SCRIPT_CLASS(           \
527           script_class,                   \
528           script,                         \
529           ranges,                         \
530           nonbase_ranges,                 \
531           top_to_bottom,                  \
532           std_charstring )                \
533   FT_CALLBACK_TABLE_DEF                   \
534   const AF_ScriptClassRec  script_class = \
535   {                                       \
536     script,                               \
537     ranges,                               \
538     nonbase_ranges,                       \
539     top_to_bottom,                        \
540     std_charstring,                       \
541   };
542 
543 
544 #define AF_DECLARE_STYLE_CLASS( style_class ) \
545   FT_CALLBACK_TABLE const AF_StyleClassRec    \
546   style_class;
547 
548 #define AF_DEFINE_STYLE_CLASS(          \
549           style_class,                  \
550           style,                        \
551           writing_system,               \
552           script,                       \
553           blue_stringset,               \
554           coverage )                    \
555   FT_CALLBACK_TABLE_DEF                 \
556   const AF_StyleClassRec  style_class = \
557   {                                     \
558     style,                              \
559     writing_system,                     \
560     script,                             \
561     blue_stringset,                     \
562     coverage                            \
563   };
564 
565 #else /* FT_CONFIG_OPTION_PIC */
566 
567 #define AF_DECLARE_WRITING_SYSTEM_CLASS( writing_system_class )            \
568   FT_LOCAL( void )                                                         \
569   FT_Init_Class_ ## writing_system_class( AF_WritingSystemClassRec*  ac );
570 
571 #define AF_DEFINE_WRITING_SYSTEM_CLASS(                                   \
572           writing_system_class,                                           \
573           system,                                                         \
574           m_size,                                                         \
575           m_init,                                                         \
576           m_scale,                                                        \
577           m_done,                                                         \
578           m_stdw,                                                         \
579           h_init,                                                         \
580           h_apply )                                                       \
581   FT_LOCAL_DEF( void )                                                    \
582   FT_Init_Class_ ## writing_system_class( AF_WritingSystemClassRec*  ac ) \
583   {                                                                       \
584     ac->writing_system        = system;                                   \
585                                                                           \
586     ac->style_metrics_size    = m_size;                                   \
587                                                                           \
588     ac->style_metrics_init    = m_init;                                   \
589     ac->style_metrics_scale   = m_scale;                                  \
590     ac->style_metrics_done    = m_done;                                   \
591     ac->style_metrics_getstdw = m_stdw;                                   \
592                                                                           \
593     ac->style_hints_init      = h_init;                                   \
594     ac->style_hints_apply     = h_apply;                                  \
595   }
596 
597 
598 #define AF_DECLARE_SCRIPT_CLASS( script_class )             \
599   FT_LOCAL( void )                                          \
600   FT_Init_Class_ ## script_class( AF_ScriptClassRec*  ac );
601 
602 #define AF_DEFINE_SCRIPT_CLASS(                            \
603           script_class,                                    \
604           script_,                                         \
605           ranges,                                          \
606           nonbase_ranges,                                  \
607           top_to_bottom,                                   \
608           std_charstring )                                 \
609   FT_LOCAL_DEF( void )                                     \
610   FT_Init_Class_ ## script_class( AF_ScriptClassRec*  ac ) \
611   {                                                        \
612     ac->script                    = script_;               \
613     ac->script_uni_ranges         = ranges;                \
614     ac->script_uni_nonbase_ranges = nonbase_ranges;        \
615     ac->top_to_bottom_hinting     = top_to_bottom;         \
616     ac->standard_charstring       = std_charstring;        \
617   }
618 
619 
620 #define AF_DECLARE_STYLE_CLASS( style_class )             \
621   FT_LOCAL( void )                                        \
622   FT_Init_Class_ ## style_class( AF_StyleClassRec*  ac );
623 
624 #define AF_DEFINE_STYLE_CLASS(                           \
625           style_class,                                   \
626           style_,                                        \
627           writing_system_,                               \
628           script_,                                       \
629           blue_stringset_,                               \
630           coverage_ )                                    \
631   FT_LOCAL_DEF( void )                                   \
632   FT_Init_Class_ ## style_class( AF_StyleClassRec*  ac ) \
633   {                                                      \
634     ac->style          = style_;                         \
635     ac->writing_system = writing_system_;                \
636     ac->script         = script_;                        \
637     ac->blue_stringset = blue_stringset_;                \
638     ac->coverage       = coverage_;                      \
639   }
640 
641 #endif /* FT_CONFIG_OPTION_PIC */
642 
643 
644 /* */
645 
646 FT_END_HEADER
647 
648 #endif /* AFTYPES_H_ */
649 
650 
651 /* END */
652