New (untested) code to parse descriptions of delta exceptions.
[ttfautohint.git] / lib / ttfautohint.h
1 /* ttfautohint.h */
2
3 /*
4 * Copyright (C) 2011-2014 by Werner Lemberg.
5 *
6 * This file is part of the ttfautohint library, and may only be used,
7 * modified, and distributed under the terms given in `COPYING'. By
8 * continuing to use, modify, or distribute this file you indicate that you
9 * have read `COPYING' and understand and accept it fully.
10 *
11 * The file `COPYING' mentioned in the previous paragraph is distributed
12 * with the ttfautohint library.
13 */
14
15
16 #ifndef __TTFAUTOHINT_H__
17 #define __TTFAUTOHINT_H__
18
19 #include <stdarg.h>
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25
26 /*
27 * This file gets processed with a simple sed script to extract the
28 * documentation (written in pandoc's markdown format); code between the
29 * `pandoc' markers are retained, everything else is discarded. C comments
30 * are uncommented so that column 4 becomes column 1; empty lines outside of
31 * comments are removed.
32 */
33
34
35 /* pandoc-start */
36
37 /*
38 * The ttfautohint API
39 * ===================
40 *
41 * This section documents the single function of the ttfautohint library,
42 * `TTF_autohint`, together with its callback functions, `TA_Progress_Func`
43 * and `TA_Info_Func`. All information has been directly extracted from the
44 * `ttfautohint.h` header file.
45 *
46 */
47
48
49 /*
50 * Preprocessor Macros and Typedefs
51 * --------------------------------
52 *
53 * Some default values.
54 *
55 * ```C
56 */
57
58 #define TA_HINTING_RANGE_MIN 8
59 #define TA_HINTING_RANGE_MAX 50
60 #define TA_HINTING_LIMIT 200
61 #define TA_INCREASE_X_HEIGHT 14
62
63 /*
64 *```
65 *
66 * An error type.
67 *
68 * ```C
69 */
70
71 typedef int TA_Error;
72
73 /*
74 * ```
75 *
76 */
77
78
79 /*
80 * Callback: `TA_Progress_Func`
81 * ----------------------------
82 *
83 * A callback function to get progress information. *curr_idx* gives the
84 * currently processed glyph index; if it is negative, an error has
85 * occurred. *num_glyphs* holds the total number of glyphs in the font
86 * (this value can't be larger than 65535).
87 *
88 * *curr_sfnt* gives the current subfont within a TrueType Collection (TTC),
89 * and *num_sfnts* the total number of subfonts.
90 *
91 * If the return value is non-zero, `TTF_autohint` aborts with
92 * `TA_Err_Canceled`. Use this for a 'Cancel' button or similar features in
93 * interactive use.
94 *
95 * *progress_data* is a void pointer to user-supplied data.
96 *
97 * ```C
98 */
99
100 typedef int
101 (*TA_Progress_Func)(long curr_idx,
102 long num_glyphs,
103 long curr_sfnt,
104 long num_sfnts,
105 void* progress_data);
106
107 /*
108 * ```
109 *
110 */
111
112
113 /*
114 * Callback: `TA_Error_Func`
115 * -------------------------
116 *
117 * A callback function to get error information.
118 *
119 * *error* is the value `TTF_autohint` returns. See file
120 * `ttfautohint-errors.h` for a list. Error codes not in this list are
121 * directly taken from FreeType; see the FreeType header file `fterrdef.h`
122 * for more.
123 *
124 * *error_string*, if non-NULL, is a pointer to an error message that
125 * represents *error*.
126 *
127 * The next three parameters help identify the origin of text string parsing
128 * errors. *linenum*, if non-zero, contains the line number. *line*, if
129 * non-NULL, is a pointer to the input line that can't be processed.
130 * *errpos*, if non-NULL, holds a pointer to the position in *line* where
131 * the problem occurs.
132 *
133 * *error_data* is a void pointer to user-supplied data.
134 *
135 * ```C
136 */
137
138 typedef void
139 (*TA_Error_Func)(TA_Error error,
140 const char* error_string,
141 unsigned int linenum,
142 const char* line,
143 const char* errpos,
144 void* error_data);
145
146 /*
147 * ```
148 *
149 */
150
151
152 /*
153 * Callback: `TA_Info_Func`
154 * ------------------------
155 *
156 * A callback function to manipulate strings in the `name` table.
157 * *platform_id*, *encoding_id*, *language_id*, and *name_id* are the
158 * identifiers of a `name` table entry pointed to by *str* with a length
159 * pointed to by *str_len* (in bytes; the string has no trailing NULL byte).
160 * Please refer to the [OpenType specification of the `name` table] for a
161 * detailed description of the various parameters, in particular which
162 * encoding is used for a given platform and encoding ID.
163 *
164 * [OpenType specification of the `name` table]: http://www.microsoft.com/typography/otspec/name.htm
165 *
166 * The string *str* is allocated with `malloc`; the application should
167 * reallocate the data if necessary, ensuring that the string length doesn't
168 * exceed 0xFFFF.
169 *
170 * *info_data* is a void pointer to user-supplied data.
171 *
172 * If an error occurs, return a non-zero value and don't modify *str* and
173 * *str_len* (such errors are handled as non-fatal).
174 *
175 * ```C
176 */
177
178 typedef int
179 (*TA_Info_Func)(unsigned short platform_id,
180 unsigned short encoding_id,
181 unsigned short language_id,
182 unsigned short name_id,
183 unsigned short* str_len,
184 unsigned char** str,
185 void* info_data);
186
187 /*
188 * ```
189 *
190 */
191
192 /* pandoc-end */
193
194
195 /*
196 * Error values in addition to the FT_Err_XXX constants from FreeType.
197 *
198 * All error values specific to ttfautohint start with `TA_Err_'.
199 */
200 #include <ttfautohint-errors.h>
201
202
203 /* pandoc-start */
204
205 /*
206 * Function: `TTF_autohint`
207 * ------------------------
208 *
209 *
210 * Read a TrueType font, remove existing bytecode (in the SFNT tables
211 * `prep`, `fpgm`, `cvt `, and `glyf`), and write a new TrueType font with
212 * new bytecode based on the autohinting of the FreeType library.
213 *
214 * It expects a format string *options* and a variable number of arguments,
215 * depending on the fields in *options*. The fields are comma separated;
216 * whitespace within the format string is not significant, a trailing comma
217 * is ignored. Fields are parsed from left to right; if a field occurs
218 * multiple times, the last field's argument wins. The same is true for
219 * fields that are mutually exclusive. Depending on the field, zero or one
220 * argument is expected.
221 *
222 * Note that fields marked as 'not implemented yet' are subject to change.
223 *
224 *
225 * ### I/O
226 *
227 * `in-file`
228 * : A pointer of type `FILE*` to the data stream of the input font,
229 * opened for binary reading. Mutually exclusive with `in-buffer`.
230 *
231 * `in-buffer`
232 * : A pointer of type `const char*` to a buffer that contains the input
233 * font. Needs `in-buffer-len`. Mutually exclusive with `in-file`.
234 *
235 * `in-buffer-len`
236 * : A value of type `size_t`, giving the length of the input buffer.
237 * Needs `in-buffer`.
238 *
239 * `out-file`
240 * : A pointer of type `FILE*` to the data stream of the output font,
241 * opened for binary writing. Mutually exclusive with `out-buffer`.
242 *
243 * `out-buffer`
244 * : A pointer of type `char**` to a buffer that contains the output
245 * font. Needs `out-buffer-len`. Mutually exclusive with `out-file`.
246 * Deallocate the memory with `free`.
247 *
248 * `out-buffer-len`
249 * : A pointer of type `size_t*` to a value giving the length of the
250 * output buffer. Needs `out-buffer`.
251 *
252 *
253 * ### Messages and Callbacks
254 *
255 * `progress-callback`
256 * : A pointer of type [`TA_Progress_Func`](#callback-ta_progress_func),
257 * specifying a callback function for progress reports. This function
258 * gets called after a single glyph has been processed. If this field
259 * is not set or set to NULL, no progress callback function is used.
260 *
261 * `progress-callback-data`
262 * : A pointer of type `void*` to user data that is passed to the
263 * progress callback function.
264 *
265 * `error-string`
266 * : A pointer of type `unsigned char**` to a string (in UTF-8 encoding)
267 * that verbally describes the error code. You must not change the
268 * returned value.
269 *
270 * `error-callback`
271 * : A pointer of type [`TA_Error_Func`](#callback-ta_error_func),
272 * specifying a callback function for error messages. This function
273 * gets called right before `TTF_autohint` exits. If this field is not
274 * set or set to NULL, no error callback function is used.
275 *
276 * Use it as a more sophisticated alternative to `error-string`.
277 *
278 * `error-callback-data`
279 * : A point of type `void*` to user data that is passed to the error
280 * callback function.
281 *
282 * `info-callback`
283 * : A pointer of type [`TA_Info_Func`](#callback-ta_info_func),
284 * specifying a callback function for manipulating the `name` table.
285 * This function gets called for each `name` table entry. If not set or
286 * set to NULL, the table data stays unmodified.
287 *
288 * `info-callback-data`
289 * : A pointer of type `void*` to user data that is passed to the info
290 * callback function.
291 *
292 * `debug`
293 * : If this integer is set to\ 1, lots of debugging information is print
294 * to stderr. The default value is\ 0.
295 *
296 *
297 * ### General Hinting Options
298 *
299 * `hinting-range-min`
300 * : An integer (which must be larger than or equal to\ 2) giving the
301 * lowest PPEM value used for autohinting. If this field is not set, it
302 * defaults to `TA_HINTING_RANGE_MIN`.
303 *
304 * `hinting-range-max`
305 * : An integer (which must be larger than or equal to the value of
306 * `hinting-range-min`) giving the highest PPEM value used for
307 * autohinting. If this field is not set, it defaults to
308 * `TA_HINTING_RANGE_MAX`.
309 *
310 * `hinting-limit`
311 * : An integer (which must be larger than or equal to the value of
312 * `hinting-range-max`) that gives the largest PPEM value at which
313 * hinting is applied. For larger values, hinting is switched off. If
314 * this field is not set, it defaults to `TA_HINTING_LIMIT`. If it is
315 * set to\ 0, no hinting limit is added to the bytecode.
316 *
317 * `hint-composites`
318 * : If this integer is set to\ 1, composite glyphs get separate hints.
319 * This implies adding a special glyph to the font called
320 * ['.ttfautohint'](#the-.ttfautohint-glyph). Setting it to\ 0 (which
321 * is the default), the hints of the composite glyphs' components are
322 * used. Adding hints for composite glyphs increases the size of the
323 * resulting bytecode a lot, but it might deliver better hinting
324 * results. However, this depends on the processed font and must be
325 * checked by inspection.
326 *
327 * `adjust-subglyphs`
328 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) to
329 * specify whether native TrueType hinting of the *input font* shall be
330 * applied to all glyphs before passing them to the (internal)
331 * autohinter. The used resolution is the em-size in font units; for
332 * most fonts this is 2048ppem. Use this only if the old hints move or
333 * scale subglyphs independently of the output resolution, for example
334 * some exotic CJK fonts.
335 *
336 * `pre-hinting` is a deprecated alias name for this option.
337 *
338 *
339 * ### Hinting Algorithms
340 *
341 * `gray-strong-stem-width`
342 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) that
343 * specifies whether horizontal stems should be snapped and positioned
344 * to integer pixel values for normal grayscale rendering.
345 *
346 * `gdi-cleartype-strong-stem-width`
347 * : An integer (1\ for 'on', which is the default, and 0\ for 'off') that
348 * specifies whether horizontal stems should be snapped and positioned
349 * to integer pixel values for GDI ClearType rendering, this is, the
350 * rasterizer version (as returned by the GETINFO bytecode instruction)
351 * is in the range 36\ <= version <\ 38 and ClearType is enabled.
352 *
353 * `dw-cleartype-strong-stem-width`
354 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) that
355 * specifies whether horizontal stems should be snapped and positioned
356 * to integer pixel values for DW ClearType rendering, this is, the
357 * rasterizer version (as returned by the GETINFO bytecode instruction)
358 * is >=\ 38, ClearType is enabled, and subpixel positioning is enabled
359 * also.
360 *
361 * `increase-x-height`
362 * : An integer. For PPEM values in the range 6\ <= PPEM <=\
363 * `increase-x-height`, round up the font's x\ height much more often
364 * than normally (to use the terminology of TrueType's 'Super Round'
365 * bytecode instruction, the threshold gets increased from 5/8px to
366 * 13/16px). If it is set to\ 0, this feature is switched off. If this
367 * field is not set, it defaults to `TA_INCREASE_X_HEIGHT`. Use this
368 * flag to improve the legibility of small font sizes if necessary.
369 *
370 * `x-height-snapping-exceptions`
371 * : A pointer of type `const char*` to a null-terminated string that
372 * gives a list of comma separated PPEM values or value ranges at which
373 * no x\ height snapping shall be applied. A value range has the form
374 * *value1*`-`*value2*, meaning *value1* <= PPEM <= *value2*. *value1*
375 * or *value2* (or both) can be missing; a missing value is replaced by
376 * the beginning or end of the whole interval of valid PPEM values,
377 * respectively. Whitespace is not significant; superfluous commas are
378 * ignored, and ranges must be specified in increasing order. For
379 * example, the string `"3, 5-7, 9-"` means the values 3, 5, 6, 7, 9,
380 * 10, 11, 12, etc. Consequently, if the supplied argument is `"-"`, no
381 * x\ height snapping takes place at all. The default is the empty
382 * string (`""`), meaning no snapping exceptions.
383 *
384 * `windows-compatibility`
385 * : If this integer is set to\ 1, two artificial blue zones are used,
386 * positioned at the `usWinAscent` and `usWinDescent` values (from the
387 * font's `OS/2` table). The idea is to help ttfautohint so that the
388 * hinted glyphs stay within this horizontal stripe since Windows clips
389 * everything falling outside. The default is\ 0.
390 *
391 *
392 * ### Scripts
393 *
394 * `default-script`
395 * : A string consisting of four lowercase characters that specifies the
396 * default script for OpenType features. After applying all features
397 * that are handled specially, use this value for the remaining
398 * features. The default value is `"latn"`; if set to `"none"`, no
399 * script is used. Valid values can be found in the header file
400 * `ttfautohint-scripts.h`.
401 *
402 * `fallback-script`
403 * : A string consisting of four lowercase characters that specifies the
404 * default script for glyphs that can't be mapped to a script
405 * automatically. If set to `"none"` (which is the default), no script
406 * is used. Valid values can be found in the header file
407 * `ttfautohint-scripts.h`.
408 *
409 * `symbol`
410 * : Set this integer to\ 1 if you want to process a font that ttfautohint
411 * would refuse otherwise because it can't find a single standard
412 * character for any of the supported scripts. ttfautohint then uses a
413 * default (hinting) value for the standard stem width instead of
414 * deriving it from a script's set of standard characters (for the latin
415 * script, one of them is character 'o'). The default value of this
416 * option is\ 0.
417 *
418 * `fallback-stem-width`
419 * : Set the horizontal stem width (hinting) value for all scripts that
420 * lack proper standard characters. The value is given in font units
421 * and must be a positive integer. If not set, or the value is zero,
422 * ttfautohint uses a hard-coded default (50\ units at 2048 units per
423 * EM, and linearly scaled for other UPEM values, for example 24\ units
424 * at 1000 UPEM).
425 *
426 * For symbol fonts (i.e., option `symbol` is given),
427 * `fallback-stem-width` has an effect only if `fallback-script` is set
428 * also.
429 *
430 *
431 * ### Miscellaneous
432 *
433 * `ignore-restrictions`
434 * : If the font has set bit\ 1 in the 'fsType' field of the `OS/2` table,
435 * the ttfautohint library refuses to process the font since a
436 * permission to do that is required from the font's legal owner. In
437 * case you have such a permission you might set the integer argument to
438 * value\ 1 to make ttfautohint handle the font. The default value
439 * is\ 0.
440 *
441 * `dehint`
442 * : If set to\ 1, remove all hints from the font. All other hinting
443 * options are ignored.
444 *
445 *
446 * ### Remarks
447 *
448 * * Obviously, it is necessary to have an input and an output data
449 * stream. All other options are optional.
450 *
451 * * `hinting-range-min` and `hinting-range-max` specify the range for
452 * which the autohinter generates optimized hinting code. If a PPEM
453 * value is smaller than the value of `hinting-range-min`, hinting still
454 * takes place but the configuration created for `hinting-range-min` is
455 * used. The analogous action is taken for `hinting-range-max`, only
456 * limited by the value given with `hinting-limit`. The font's `gasp`
457 * table is set up to always use grayscale rendering with grid-fitting
458 * for standard hinting, and symmetric grid-fitting and symmetric
459 * smoothing for horizontal subpixel hinting (ClearType).
460 *
461 * * ttfautohint can process its own output a second time only if option
462 * `hint-composites` is not set (or if the font doesn't contain
463 * composite glyphs at all). This limitation might change in the
464 * future.
465 *
466 * ```C
467 */
468
469 TA_Error
470 TTF_autohint(const char* options,
471 ...);
472
473 /*
474 * ```
475 *
476 */
477
478 /* pandoc-end */
479
480 #ifdef __cplusplus
481 } /* extern "C" */
482 #endif
483
484 #endif /* __TTFAUTOHINT_H__ */
485
486 /* end of ttfautohint.h */