docs/reference/ft2-auto_hinter.html

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