ftautoh.h revision 9c745321260bb728ab1cd1c8fd5f075854b2ad49 
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
32FT_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
397FT_END_HEADER
398
399#endif /* __FTAUTOH_H__ */
400
401
402/* END */
403