include/ftautoh.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftautoh.h                                                              */
   4 /*                                                                         */
   5 /*    FreeType API for controlling the auto-hinter (specification only).   */
   6 /*                                                                         */
   7 /*  Copyright 2012, 2013 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 __FTAUTOH_H__
  20 #define __FTAUTOH_H__
  21
  22 #include <ft2build.h>
  23 #include FT_FREETYPE_H
  24
  25 #ifdef FREETYPE_H
  26 #error "freetype.h of FreeType 1 has been loaded!"
  27 #error "Please fix the directory search order for header files"
  28 #error "so that freetype.h of FreeType 2 is found first."
  29 #endif
  30
  31
  32 FT_BEGIN_HEADER
  33
  34
  35   /**************************************************************************
  36    *
  37    * @section:
  38    *   auto_hinter
  39    *
  40    * @title:
  41    *   The auto-hinter
  42    *
  43    * @abstract:
  44    *   Controlling the auto-hinting module.
  45    *
  46    * @description:
  47    *   While FreeType's auto-hinter doesn't expose API functions by itself,
  48    *   it is possible to control its behaviour with @FT_Property_Set and
  49    *   @FT_Property_Get.  The following lists the available properties
  50    *   together with the necessary macros and structures.
  51    *
  52    *   Note that the auto-hinter's module name is `autofitter' for
  53    *   historical reasons.
  54    *
  55    */
  56
  57
  58   /**************************************************************************
  59    *
  60    * @property:
  61    *   glyph-to-script-map
  62    *
  63    * @description:
  64    *   *Experimental* *only*
  65    *
  66    *   The auto-hinter provides various script modules to hint glyphs.
  67    *   Examples of supported scripts are Latin or CJK.  Before a glyph is
  68    *   auto-hinted, the Unicode character map of the font gets examined, and
  69    *   the script is then determined based on Unicode character ranges, see
  70    *   below.
  71    *
  72    *   OpenType fonts, however, often provide much more glyphs than
  73    *   character codes (small caps, superscripts, ligatures, swashes, etc.),
  74    *   to be controlled by so-called `features'.  Handling OpenType features
  75    *   can be quite complicated and thus needs a separate library on top of
  76    *   FreeType.
  77    *
  78    *   The mapping between glyph indices and scripts (in the auto-hinter
  79    *   sense, see the @FT_AUTOHINTER_SCRIPT_XXX values) is stored as an
  80    *   array with `num_glyphs' elements, as found in the font's @FT_Face
  81    *   structure.  The `glyph-to-script-map' property returns a pointer to
  82    *   this array, which can be modified as needed.  Note that the
  83    *   modification should happen before the first glyph gets processed by
  84    *   the auto-hinter so that the global analysis of the font shapes
  85    *   actually uses the modified mapping.
  86    *
  87    *   The following example code demonstrates how to access it (omitting
  88    *   the error handling).
  89    *
  90    *   {
  91    *     FT_Library                library;
  92    *     FT_Face                   face;
  93    *     FT_Prop_GlyphToScriptMap  prop;
  94    *
  95    *
  96    *     FT_Init_FreeType( &library );
  97    *     FT_New_Face( library, "foo.ttf", 0, &face );
  98    *
  99    *     prop.face = face;
 100    *
 101    *     FT_Property_Get( library, "autofitter",
 102    *                               "glyph-to-script-map", &prop );
 103    *
 104    *     // adjust `prop.map' as needed right here
 105    *
 106    *     FT_Load_Glyph( face, ..., FT_LOAD_FORCE_AUTOHINT );
 107    *   }
 108    *
 109    */
 110
 111
 112   /**************************************************************************
 113    *
 114    * @enum:
 115    *   FT_AUTOHINTER_SCRIPT_XXX
 116    *
 117    * @description:
 118    *   *Experimental* *only*
 119    *
 120    *   A list of constants used for the @glyph-to-script-map property to
 121    *   specify the script submodule the auto-hinter should use for hinting a
 122    *   particular glyph.
 123    *
 124    * @values:
 125    *   FT_AUTOHINTER_SCRIPT_NONE ::
 126    *     Don't auto-hint this glyph.
 127    *
 128    *   FT_AUTOHINTER_SCRIPT_LATIN ::
 129    *     Apply the latin auto-hinter.  For the auto-hinter, `latin' is a
 130    *     very broad term, including Cyrillic and Greek also since characters
 131    *     from those scripts share the same design constraints.
 132    *
 133    *     By default, characters from the following Unicode ranges are
 134    *     assigned to this submodule.
 135    *
 136    *     {
 137    *       U+0020 - U+007F  // Basic Latin (no control characters)
 138    *       U+00A0 - U+00FF  // Latin-1 Supplement (no control characters)
 139    *       U+0100 - U+017F  // Latin Extended-A
 140    *       U+0180 - U+024F  // Latin Extended-B
 141    *       U+0250 - U+02AF  // IPA Extensions
 142    *       U+02B0 - U+02FF  // Spacing Modifier Letters
 143    *       U+0300 - U+036F  // Combining Diacritical Marks
 144    *       U+0370 - U+03FF  // Greek and Coptic
 145    *       U+0400 - U+04FF  // Cyrillic
 146    *       U+0500 - U+052F  // Cyrillic Supplement
 147    *       U+1D00 - U+1D7F  // Phonetic Extensions
 148    *       U+1D80 - U+1DBF  // Phonetic Extensions Supplement
 149    *       U+1DC0 - U+1DFF  // Combining Diacritical Marks Supplement
 150    *       U+1E00 - U+1EFF  // Latin Extended Additional
 151    *       U+1F00 - U+1FFF  // Greek Extended
 152    *       U+2000 - U+206F  // General Punctuation
 153    *       U+2070 - U+209F  // Superscripts and Subscripts
 154    *       U+20A0 - U+20CF  // Currency Symbols
 155    *       U+2150 - U+218F  // Number Forms
 156    *       U+2460 - U+24FF  // Enclosed Alphanumerics
 157    *       U+2C60 - U+2C7F  // Latin Extended-C
 158    *       U+2DE0 - U+2DFF  // Cyrillic Extended-A
 159    *       U+2E00 - U+2E7F  // Supplemental Punctuation
 160    *       U+A640 - U+A69F  // Cyrillic Extended-B
 161    *       U+A720 - U+A7FF  // Latin Extended-D
 162    *       U+FB00 - U+FB06  // Alphab. Present. Forms (Latin Ligatures)
 163    *      U+1D400 - U+1D7FF // Mathematical Alphanumeric Symbols
 164    *      U+1F100 - U+1F1FF // Enclosed Alphanumeric Supplement
 165    *     }
 166    *
 167    *   FT_AUTOHINTER_SCRIPT_CJK ::
 168    *     Apply the CJK auto-hinter, covering Chinese, Japanese, Korean, old
 169    *     Vietnamese, and some other scripts.
 170    *
 171    *     By default, characters from the following Unicode ranges are
 172    *     assigned to this submodule.
 173    *
 174    *     {
 175    *       U+1100 - U+11FF  // Hangul Jamo
 176    *       U+2E80 - U+2EFF  // CJK Radicals Supplement
 177    *       U+2F00 - U+2FDF  // Kangxi Radicals
 178    *       U+2FF0 - U+2FFF  // Ideographic Description Characters
 179    *       U+3000 - U+303F  // CJK Symbols and Punctuation
 180    *       U+3040 - U+309F  // Hiragana
 181    *       U+30A0 - U+30FF  // Katakana
 182    *       U+3100 - U+312F  // Bopomofo
 183    *       U+3130 - U+318F  // Hangul Compatibility Jamo
 184    *       U+3190 - U+319F  // Kanbun
 185    *       U+31A0 - U+31BF  // Bopomofo Extended
 186    *       U+31C0 - U+31EF  // CJK Strokes
 187    *       U+31F0 - U+31FF  // Katakana Phonetic Extensions
 188    *       U+3200 - U+32FF  // Enclosed CJK Letters and Months
 189    *       U+3300 - U+33FF  // CJK Compatibility
 190    *       U+3400 - U+4DBF  // CJK Unified Ideographs Extension A
 191    *       U+4DC0 - U+4DFF  // Yijing Hexagram Symbols
 192    *       U+4E00 - U+9FFF  // CJK Unified Ideographs
 193    *       U+A960 - U+A97F  // Hangul Jamo Extended-A
 194    *       U+AC00 - U+D7AF  // Hangul Syllables
 195    *       U+D7B0 - U+D7FF  // Hangul Jamo Extended-B
 196    *       U+F900 - U+FAFF  // CJK Compatibility Ideographs
 197    *       U+FE10 - U+FE1F  // Vertical forms
 198    *       U+FE30 - U+FE4F  // CJK Compatibility Forms
 199    *       U+FF00 - U+FFEF  // Halfwidth and Fullwidth Forms
 200    *      U+1B000 - U+1B0FF // Kana Supplement
 201    *      U+1D300 - U+1D35F // Tai Xuan Hing Symbols
 202    *      U+1F200 - U+1F2FF // Enclosed Ideographic Supplement
 203    *      U+20000 - U+2A6DF // CJK Unified Ideographs Extension B
 204    *      U+2A700 - U+2B73F // CJK Unified Ideographs Extension C
 205    *      U+2B740 - U+2B81F // CJK Unified Ideographs Extension D
 206    *      U+2F800 - U+2FA1F // CJK Compatibility Ideographs Supplement
 207    *     }
 208    *
 209    *   FT_AUTOHINTER_SCRIPT_INDIC ::
 210    *     Apply the indic auto-hinter, covering all major scripts from the
 211    *     Indian sub-continent and some other related scripts like Thai, Lao,
 212    *     or Tibetan.
 213    *
 214    *     By default, characters from the following Unicode ranges are
 215    *     assigned to this submodule.
 216    *
 217    *     {
 218    *       U+0900 - U+0DFF  // Indic Range
 219    *       U+0F00 - U+0FFF  // Tibetan
 220    *       U+1900 - U+194F  // Limbu
 221    *       U+1B80 - U+1BBF  // Sundanese
 222    *       U+1C80 - U+1CDF  // Meetei Mayak
 223    *       U+A800 - U+A82F  // Syloti Nagri
 224    *      U+11800 - U+118DF // Sharada
 225    *     }
 226    *
 227    *     Note that currently Indic support is rudimentary only, missing blue
 228    *     zone support.
 229    *
 230    */
 231 #define FT_AUTOHINTER_SCRIPT_NONE   0
 232 #define FT_AUTOHINTER_SCRIPT_LATIN  1
 233 #define FT_AUTOHINTER_SCRIPT_CJK    2
 234 #define FT_AUTOHINTER_SCRIPT_INDIC  3
 235
 236
 237   /**************************************************************************
 238    *
 239    * @struct:
 240    *   FT_Prop_GlyphToScriptMap
 241    *
 242    * @description:
 243    *   *Experimental* *only*
 244    *
 245    *   The data exchange structure for the @glyph-to-script-map property.
 246    *
 247    */
 248   typedef struct  FT_Prop_GlyphToScriptMap_
 249   {
 250     FT_Face   face;
 251     FT_Byte*  map;
 252
 253   } FT_Prop_GlyphToScriptMap;
 254
 255
 256   /**************************************************************************
 257    *
 258    * @property:
 259    *   fallback-script
 260    *
 261    * @description:
 262    *   *Experimental* *only*
 263    *
 264    *   If no auto-hinter script module can be assigned to a glyph, a
 265    *   fallback script gets assigned to it (see also the
 266    *   @glyph-to-script-map property).  By default, this is
 267    *   @FT_AUTOHINTER_SCRIPT_CJK.  Using the `fallback-script' property,
 268    *   this fallback value can be changed.
 269    *
 270    *   {
 271    *     FT_Library  library;
 272    *     FT_UInt     fallback_script = FT_AUTOHINTER_SCRIPT_NONE;
 273    *
 274    *
 275    *     FT_Init_FreeType( &library );
 276    *
 277    *     FT_Property_Set( library, "autofitter",
 278    *                               "fallback-script", &fallback_script );
 279    *   }
 280    *
 281    * @note:
 282    *   This property can be used with @FT_Property_Get also.
 283    *
 284    *   It's important to use the right timing for changing this value: The
 285    *   creation of the glyph-to-script map that eventually uses the
 286    *   fallback script value gets triggered either by setting or reading a
 287    *   face-specific property like @glyph-to-script-map, or by auto-hinting
 288    *   any glyph from that face.  In particular, if you have already created
 289    *   an @FT_Face structure but not loaded any glyph (using the
 290    *   auto-hinter), a change of the fallback script will affect this face.
 291    *
 292    */
 293
 294
 295   /**************************************************************************
 296    *
 297    * @property:
 298    *   default-script
 299    *
 300    * @description:
 301    *   *Experimental* *only*
 302    *
 303    *   If Freetype gets compiled with FT_CONFIG_OPTION_USE_HARFBUZZ to make
 304    *   the HarfBuzz library access OpenType features for getting better
 305    *   glyph coverages, this property sets the (auto-fitter) script to be
 306    *   used for the default (OpenType) script data of a font's GSUB table.
 307    *   Features for the default script are intended for all scripts not
 308    *   explicitly handled in GSUB; an example is a `dlig' feature,
 309    *   containing the combination of the characters `T', `E', and `L' to
 310    *   form a `TEL' ligature.
 311    *
 312    *   By default, this is @FT_AUTOHINTER_SCRIPT_LATIN.  Using the
 313    *   `default-script' property, this default value can be changed.
 314    *
 315    *   {
 316    *     FT_Library  library;
 317    *     FT_UInt     default_script = FT_AUTOHINTER_SCRIPT_NONE;
 318    *
 319    *
 320    *     FT_Init_FreeType( &library );
 321    *
 322    *     FT_Property_Set( library, "autofitter",
 323    *                               "default-script", &default_script );
 324    *   }
 325    *
 326    * @note:
 327    *   This property can be used with @FT_Property_Get also.
 328    *
 329    *   It's important to use the right timing for changing this value: The
 330    *   creation of the glyph-to-script map that eventually uses the
 331    *   default script value gets triggered either by setting or reading a
 332    *   face-specific property like @glyph-to-script-map, or by auto-hinting
 333    *   any glyph from that face.  In particular, if you have already created
 334    *   an @FT_Face structure but not loaded any glyph (using the
 335    *   auto-hinter), a change of the default script will affect this face.
 336    *
 337    */
 338
 339
 340   /**************************************************************************
 341    *
 342    * @property:
 343    *   increase-x-height
 344    *
 345    * @description:
 346    *   For ppem values in the range 6~<= ppem <= `increase-x-height', round
 347    *   up the font's x~height much more often than normally.  If the value
 348    *   is set to~0, which is the default, this feature is switched off.  Use
 349    *   this property to improve the legibility of small font sizes if
 350    *   necessary.
 351    *
 352    *   {
 353    *     FT_Library               library;
 354    *     FT_Face                  face;
 355    *     FT_Prop_IncreaseXHeight  prop;
 356    *
 357    *
 358    *     FT_Init_FreeType( &library );
 359    *     FT_New_Face( library, "foo.ttf", 0, &face );
 360    *     FT_Set_Char_Size( face, 10 * 64, 0, 72, 0 );
 361    *
 362    *     prop.face  = face;
 363    *     prop.limit = 14;
 364    *
 365    *     FT_Property_Set( library, "autofitter",
 366    *                               "increase-x-height", &prop );
 367    *   }
 368    *
 369    * @note:
 370    *   This property can be used with @FT_Property_Get also.
 371    *
 372    *   Set this value right after calling @FT_Set_Char_Size, but before
 373    *   loading any glyph (using the auto-hinter).
 374    *
 375    */
 376
 377
 378   /**************************************************************************
 379    *
 380    * @struct:
 381    *   FT_Prop_IncreaseXHeight
 382    *
 383    * @description:
 384    *   The data exchange structure for the @increase-x-height property.
 385    *
 386    */
 387   typedef struct  FT_Prop_IncreaseXHeight_
 388   {
 389     FT_Face  face;
 390     FT_UInt  limit;
 391
 392   } FT_Prop_IncreaseXHeight;
 393
 394   /* */
 395
 396
 397 FT_END_HEADER
 398
 399 #endif /* __FTAUTOH_H__ */
 400
 401
 402 /* END */