Add the license back to ftmodule.h after the freetype 2.5.4 upgrade.
[pdfium.git] / third_party / freetype / 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 */