Improve documentation of the Control Instructions file.
[ttfautohint.git] / lib / ttfautohint.h
blob325997fcbdbffdea9a5b0ee7b1c97626659d7190
1 /* ttfautohint.h */
3 /*
4 * Copyright (C) 2011-2015 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 */
16 #ifndef __TTFAUTOHINT_H__
17 #define __TTFAUTOHINT_H__
19 #include <stdarg.h>
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
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 */
35 /* pandoc-start */
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 */
49 /*
50 * Preprocessor Macros and Typedefs
51 * --------------------------------
52 *
53 * Some default values.
54 *
55 * ```C
56 */
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
63 /*
64 *```
65 *
66 * An error type.
67 *
68 * ```C
69 */
71 typedef int TA_Error;
73 /*
74 * ```
75 *
76 */
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 */
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);
107 /*
108 * ```
110 */
113 /*
114 * Callback: `TA_Error_Func`
115 * -------------------------
117 * A callback function to get error information.
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.
124 * *error_string*, if non-NULL, is a pointer to an error message that
125 * represents *error*.
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.
133 * *error_data* is a void pointer to user-supplied data.
135 * ```C
136 */
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);
146 /*
147 * ```
149 */
152 /*
153 * Callback: `TA_Info_Func`
154 * ------------------------
156 * A callback function to access or modify strings in the `name` table; it
157 * is called in a loop that iterates over all `name` table entries. If
158 * defined, [`TA_Info_Post_Func`](#callback-ta_info_post_func) gets executed
159 * after this loop so that the collected data can be written back to the
160 * `name` table.
162 * *platform_id*, *encoding_id*, *language_id*, and *name_id* are the
163 * identifiers of a `name` table entry pointed to by *str* with a length
164 * pointed to by *str_len* (in bytes; the string has no trailing NULL byte).
165 * Please refer to the [OpenType specification of the `name` table] for a
166 * detailed description of the various parameters, in particular which
167 * encoding is used for a given platform and encoding ID.
169 * [OpenType specification of the `name` table]: http://www.microsoft.com/typography/otspec/name.htm
171 * The string *str* is allocated with `malloc`; the application should
172 * reallocate the data if necessary, ensuring that the string length doesn't
173 * exceed 0xFFFF.
175 * *info_data* is a void pointer to user-supplied data.
177 * If an error occurs, return a non-zero value and don't modify *str* and
178 * *str_len* (such errors are handled as non-fatal).
180 * ```C
181 */
183 typedef int
184 (*TA_Info_Func)(unsigned short platform_id,
185 unsigned short encoding_id,
186 unsigned short language_id,
187 unsigned short name_id,
188 unsigned short* str_len,
189 unsigned char** str,
190 void* info_data);
192 /*
193 * ```
195 */
198 /*
199 * Callback: `TA_Info_Post_Func`
200 * -----------------------------
202 * A callback function, giving the application the possibility to access or
203 * modify strings in the `name` table after
204 * [`TA_Info_Func`](#callback-ta_info_func) has iterated over all `name`
205 * table entries.
207 * It is expected that `TA_Info_Func` stores pointers to the `name` table
208 * entries it wants to access or modify; the only parameter is thus
209 * *info_data*, which is a void pointer to the user-supplied data already
210 * provided to `TA_Info_Func`. Obviously, calling `TA_Info_Post_Func` with
211 * `TA_Info_Func` undefined has no effect.
213 * The `name` table strings are allocated with `malloc`; the application
214 * should reallocate the data if necessary, ensuring that no string length
215 * exceeds 0xFFFF.
217 * If an error occurs, return a non-zero value and don't modify the affected
218 * string and string length (such errors are handled as non-fatal).
220 * ```C
221 */
223 typedef int
224 (*TA_Info_Post_Func)(void* info_data);
226 /*
227 * ```
229 */
231 /* pandoc-end */
234 /*
235 * Error values in addition to the FT_Err_XXX constants from FreeType.
237 * All error values specific to ttfautohint start with `TA_Err_'.
238 */
239 #include <ttfautohint-errors.h>
242 /* pandoc-start */
244 /*
245 * Function: `TTF_autohint`
246 * ------------------------
249 * Read a TrueType font, remove existing bytecode (in the SFNT tables
250 * `prep`, `fpgm`, `cvt `, and `glyf`), and write a new TrueType font with
251 * new bytecode based on the autohinting of the FreeType library.
253 * It expects a format string *options* and a variable number of arguments,
254 * depending on the fields in *options*. The fields are comma separated;
255 * whitespace within the format string is not significant, a trailing comma
256 * is ignored. Fields are parsed from left to right; if a field occurs
257 * multiple times, the last field's argument wins. The same is true for
258 * fields that are mutually exclusive. Depending on the field, zero or one
259 * argument is expected.
261 * Note that fields marked as 'not implemented yet' are subject to change.
264 * ### I/O
266 * `in-file`
267 * : A pointer of type `FILE*` to the data stream of the input font,
268 * opened for binary reading. Mutually exclusive with `in-buffer`.
270 * `in-buffer`
271 * : A pointer of type `const char*` to a buffer that contains the input
272 * font. Needs `in-buffer-len`. Mutually exclusive with `in-file`.
274 * `in-buffer-len`
275 * : A value of type `size_t`, giving the length of the input buffer.
276 * Needs `in-buffer`.
278 * `out-file`
279 * : A pointer of type `FILE*` to the data stream of the output font,
280 * opened for binary writing. Mutually exclusive with `out-buffer`.
282 * `out-buffer`
283 * : A pointer of type `char**` to a buffer that contains the output
284 * font. Needs `out-buffer-len`. Mutually exclusive with `out-file`.
285 * Deallocate the memory with `free`.
287 * `out-buffer-len`
288 * : A pointer of type `size_t*` to a value giving the length of the
289 * output buffer. Needs `out-buffer`.
291 * `control-file`
292 * : A pointer of type `FILE*` to the data stream of control instructions.
293 * Mutually exclusive with `control-buffer`.
295 * An entry in a control instructions file or buffer has one of the
296 * following syntax forms (with brackets showing optional elements):
298 * > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`l`\[`eft`\]|`r`\[`ight`\]*\ points\ \ *\[*\ *`(`*\ left‑offset\ *`,`*\ right‑offset\ *`)`*\ *\]*\
299 * > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`n`\[`odir`\]*\ points\
300 * > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`t`\[`ouch`\]|`p`\[`oint`\]*\ points\ \ *\[*\ *`x`\[`shift`\]*\ x‑shift\ *\]*\ \ *\[*\ *`y`\[`shift`\]*\ y‑shift\ *\]*\ \ *`@`*\ ppems
302 * *font‑idx* gives the index of the font in a TrueType Collection. If
303 * missing, it is set to zero. For normal TrueType fonts, only value
304 * zero is valid. If starting with `0x` the number is interpreted as
305 * hexadecimal. If starting with `0` it gets interpreted as an octal
306 * value, and as a decimal value otherwise.
308 * *glyph‑id* is a glyph's name as listed in the `post` SFNT table or a
309 * glyph index. A glyph name consists of characters from the set
310 * '`A-Za-z0-9._`' only and does not start with a digit or period, with
311 * the exceptions of the names '`.notdef`' and '`.null`'. A glyph index
312 * can be specified in decimal, octal, or hexadecimal format, the latter
313 * two indicated by the prefixes `0` and `0x`, respectively.
315 * The mutually exclusive parameters `left` and `right` (which can be
316 * abbreviated as '`l`' and '`r`', respectively) indicate that the
317 * following points have left or right 'out' direction, respectively,
318 * overriding ttfautohint's algorithm for setting point directions. The
319 * 'out direction' of a point is the direction of the outline *leaving*
320 * the point (or passing the control point). If the specified direction
321 * is identical to what ttfautohint computes, nothing special happens.
322 * Otherwise, a one-point segment with the specified direction gets
323 * created. By default, its length is zero. Setting *left‑offset* and
324 * *right‑offset*, you can change the segment's horizontal start and end
325 * position relative to the point position. *left‑offset* and
326 * *right‑offset* are integers measured in font units.
328 * Parameter `nodir` (or '`n`') sets the 'out' direction of the
329 * following points to 'no direction'. If the specified direction is
330 * identical to what ttfautohint computes, nothing special happens.
331 * Otherwise, ttfautohint no longer considers those points as part of
332 * horizontal segments, thus treating them as 'weak' points.
334 * Modifying or adding segments don't directly modify the outlines; it
335 * only influences the hinting process.
337 * The mutually exclusive parameters `touch` and `point` (which can be
338 * abbreviated as '`t`' and '`p`', respectively) make ttfautohint apply
339 * delta exceptions for the given points, shifting them by the given
340 * values. Delta exceptions entered with `touch` are applied before the
341 * final `IUP` instructions in a glyph's bytecode, exceptions entered
342 * with `point` after `IUP`. Additionally, the `touch` parameter makes
343 * the bytecode *touch* the affected points; such points are no longer
344 * affected by `IUP` at all. Note that in ClearType mode all deltas
345 * along the x\ axis are discarded, and deltas along the y\ axis are
346 * only executed for touched points. As a consequence, vertical delta
347 * exceptions entered with `point` should not be used in ClearType mode.
349 * Both *points* and *ppems* are number ranges, similar to the
350 * `x-height-snapping-exceptions` syntax.
352 * *x‑shift* and *y‑shift* represent real numbers that get rounded to
353 * multiples of 1/8 pixels. The entries for `xshift` ('`x`') and
354 * `yshift` ('`y`') are optional; if missing, the corresponding value is
355 * set to zero. If both values are zero, the delta exception entry is
356 * ignored as a whole.
358 * Values for *x‑shift* and *y‑shift* must be in the range [−1.0;1.0].
359 * Values for *ppems* must be in the range [6;53]. Values for *points*
360 * are limited by the number of points in the glyph.
362 * Control instruction entries can be either separated with newlines or
363 * with character '`;`'. Additionally, a line can be continued on the
364 * next line by ending it with backslash character ('`\`'). A backslash
365 * followed by a newline gets treated similar to a whitespace character.
367 * A comment starts with character '`#`'; the rest of the line is
368 * ignored. An empty line is ignored also.
370 * Note that only character '`.`' is recognized as a decimal point, and
371 * a thousands separator is not accepted.
373 * `control-buffer`
374 * : A pointer of type `const char*` to a buffer that contains control
375 * instructions. Needs `control-buffer-len`. Mutually exclusive with
376 * `control-file`.
378 * `control-buffer-len`
379 * : A value of type `size_t`, giving the length of the control
380 * instructions buffer. Needs `control-buffer`.
383 * ### Messages and Callbacks
385 * `progress-callback`
386 * : A pointer of type [`TA_Progress_Func`](#callback-ta_progress_func),
387 * specifying a callback function for progress reports. This function
388 * gets called after a single glyph has been processed. If this field
389 * is not set or set to NULL, no progress callback function is used.
391 * `progress-callback-data`
392 * : A pointer of type `void*` to user data that is passed to the
393 * progress callback function.
395 * `error-string`
396 * : A pointer of type `unsigned char**` to a string (in UTF-8 encoding)
397 * that verbally describes the error code. You must not change the
398 * returned value.
400 * `error-callback`
401 * : A pointer of type [`TA_Error_Func`](#callback-ta_error_func),
402 * specifying a callback function for error messages. This function
403 * gets called right before `TTF_autohint` exits. If this field is not
404 * set or set to NULL, no error callback function is used.
406 * Use it as a more sophisticated alternative to `error-string`.
408 * `error-callback-data`
409 * : A point of type `void*` to user data that is passed to the error
410 * callback function.
412 * `info-callback`
413 * : A pointer of type [`TA_Info_Func`](#callback-ta_info_func),
414 * specifying a callback function for manipulating the `name` table.
415 * This function gets called for each `name` table entry. If not set or
416 * set to NULL, `TA_Info_Func` is not called.
418 * `info-post-callback`
419 * : A pointer of type [`TA_Info_Post_Func`](#callback-ta_info_post_func),
420 * specifying a callback function for manipulating the `name` table. It
421 * is called after the function specified with `info-callback` has
422 * iterated over all `name` table entries. If not set or set to NULL,
423 * `TA_Info_Post_Func` is not called.
425 * `info-callback-data`
426 * : A pointer of type `void*` to user data that is passed to the info
427 * callback functions.
429 * `debug`
430 * : If this integer is set to\ 1, lots of debugging information is print
431 * to stderr. The default value is\ 0.
434 * ### General Hinting Options
436 * `hinting-range-min`
437 * : An integer (which must be larger than or equal to\ 2) giving the
438 * lowest PPEM value used for autohinting. If this field is not set, it
439 * defaults to `TA_HINTING_RANGE_MIN`.
441 * `hinting-range-max`
442 * : An integer (which must be larger than or equal to the value of
443 * `hinting-range-min`) giving the highest PPEM value used for
444 * autohinting. If this field is not set, it defaults to
445 * `TA_HINTING_RANGE_MAX`.
447 * `hinting-limit`
448 * : An integer (which must be larger than or equal to the value of
449 * `hinting-range-max`) that gives the largest PPEM value at which
450 * hinting is applied. For larger values, hinting is switched off. If
451 * this field is not set, it defaults to `TA_HINTING_LIMIT`. If it is
452 * set to\ 0, no hinting limit is added to the bytecode.
454 * `hint-composites`
455 * : If this integer is set to\ 1, composite glyphs get separate hints.
456 * This implies adding a special glyph to the font called
457 * ['.ttfautohint'](#the-.ttfautohint-glyph). Setting it to\ 0 (which
458 * is the default), the hints of the composite glyphs' components are
459 * used. Adding hints for composite glyphs increases the size of the
460 * resulting bytecode a lot, but it might deliver better hinting
461 * results. However, this depends on the processed font and must be
462 * checked by inspection.
464 * `adjust-subglyphs`
465 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) to
466 * specify whether native TrueType hinting of the *input font* shall be
467 * applied to all glyphs before passing them to the (internal)
468 * autohinter. The used resolution is the em-size in font units; for
469 * most fonts this is 2048ppem. Use this only if the old hints move or
470 * scale subglyphs independently of the output resolution, for example
471 * some exotic CJK fonts.
473 * `pre-hinting` is a deprecated alias name for this option.
476 * ### Hinting Algorithms
478 * `gray-strong-stem-width`
479 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) that
480 * specifies whether horizontal stems should be snapped and positioned
481 * to integer pixel values for normal grayscale rendering.
483 * `gdi-cleartype-strong-stem-width`
484 * : An integer (1\ for 'on', which is the default, and 0\ for 'off') that
485 * specifies whether horizontal stems should be snapped and positioned
486 * to integer pixel values for GDI ClearType rendering, this is, the
487 * rasterizer version (as returned by the GETINFO bytecode instruction)
488 * is in the range 36\ <= version <\ 38 and ClearType is enabled.
490 * `dw-cleartype-strong-stem-width`
491 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) that
492 * specifies whether horizontal stems should be snapped and positioned
493 * to integer pixel values for DW ClearType rendering, this is, the
494 * rasterizer version (as returned by the GETINFO bytecode instruction)
495 * is >=\ 38, ClearType is enabled, and subpixel positioning is enabled
496 * also.
498 * `increase-x-height`
499 * : An integer. For PPEM values in the range 6\ <= PPEM
500 * <= `increase-x-height`, round up the font's x\ height much more often
501 * than normally (to use the terminology of TrueType's 'Super Round'
502 * bytecode instruction, the threshold gets increased from 5/8px to
503 * 13/16px). If it is set to\ 0, this feature is switched off. If this
504 * field is not set, it defaults to `TA_INCREASE_X_HEIGHT`. Use this
505 * flag to improve the legibility of small font sizes if necessary.
507 * `x-height-snapping-exceptions`
508 * : A pointer of type `const char*` to a null-terminated string that
509 * gives a list of comma separated PPEM values or value ranges at which
510 * no x\ height snapping shall be applied. A value range has the form
511 * *value*~1~`-`*value*~2~, meaning *value*~1~ <= PPEM <= *value*~2~.
512 * *value*~1~ or *value*~2~ (or both) can be missing; a missing value is
513 * replaced by the beginning or end of the whole interval of valid PPEM
514 * values, respectively. Whitespace is not significant; superfluous
515 * commas are ignored, and ranges must be specified in increasing order.
516 * For example, the string `"3, 5-7, 9-"` means the values 3, 5, 6, 7,
517 * 9, 10, 11, 12, etc. Consequently, if the supplied argument is `"-"`,
518 * no x\ height snapping takes place at all. The default is the empty
519 * string (`""`), meaning no snapping exceptions.
521 * `windows-compatibility`
522 * : If this integer is set to\ 1, two artificial blue zones are used,
523 * positioned at the `usWinAscent` and `usWinDescent` values (from the
524 * font's `OS/2` table). The idea is to help ttfautohint so that the
525 * hinted glyphs stay within this horizontal stripe since Windows clips
526 * everything falling outside. The default is\ 0.
529 * ### Scripts
531 * `default-script`
532 * : A string consisting of four lowercase characters that specifies the
533 * default script for OpenType features. After applying all features
534 * that are handled specially, use this value for the remaining
535 * features. The default value is `"latn"`; if set to `"none"`, no
536 * script is used. Valid values can be found in the header file
537 * `ttfautohint-scripts.h`.
539 * `fallback-script`
540 * : A string consisting of four lowercase characters that specifies the
541 * default script for glyphs that can't be mapped to a script
542 * automatically. If set to `"none"` (which is the default), no script
543 * is used. Valid values can be found in the header file
544 * `ttfautohint-scripts.h`.
546 * `symbol`
547 * : Set this integer to\ 1 if you want to process a font that ttfautohint
548 * would refuse otherwise because it can't find a single standard
549 * character for any of the supported scripts. ttfautohint then uses a
550 * default (hinting) value for the standard stem width instead of
551 * deriving it from a script's set of standard characters (for the latin
552 * script, one of them is character 'o'). The default value of this
553 * option is\ 0.
555 * `fallback-stem-width`
556 * : Set the horizontal stem width (hinting) value for all scripts that
557 * lack proper standard characters. The value is given in font units
558 * and must be a positive integer. If not set, or the value is zero,
559 * ttfautohint uses a hard-coded default (50\ units at 2048 units per
560 * EM, and linearly scaled for other UPEM values, for example 24\ units
561 * at 1000 UPEM).
563 * For symbol fonts (i.e., option `symbol` is given),
564 * `fallback-stem-width` has an effect only if `fallback-script` is set
565 * also.
568 * ### Miscellaneous
570 * `ignore-restrictions`
571 * : If the font has set bit\ 1 in the 'fsType' field of the `OS/2` table,
572 * the ttfautohint library refuses to process the font since a
573 * permission to do that is required from the font's legal owner. In
574 * case you have such a permission you might set the integer argument to
575 * value\ 1 to make ttfautohint handle the font. The default value
576 * is\ 0.
578 * `TTFA-info`
579 * : If set to\ 1, ttfautohint creates an SFNT table called `TTFA` and
580 * fills it with information on the parameters used while calling
581 * `TTF_autohint`. The format of the output data resembles the
582 * information at the very beginning of the dump emitted by option
583 * `debug`. The default value is\ 0.
585 * Main use of this option is for font editing purposes. For example,
586 * after a font editor has added some glyphs, a front-end to
587 * `TTF_autohint` can parse `TTFA` and feed the parameters into another
588 * call of `TTF_autohint`. The new glyphs are then hinted while hints
589 * of the old glyphs stay unchanged.
591 * If this option is not set, and the font to be processed contains a
592 * `TTFA` table, it gets removed.
594 * Note that such a `TTFA` table gets ignored by all font rendering
595 * engines. In TrueType Collections, the `TTFA` table is added to the
596 * first subfont.
598 * `dehint`
599 * : If set to\ 1, remove all hints from the font. All other hinting
600 * options are ignored.
603 * ### Remarks
605 * * Obviously, it is necessary to have an input and an output data
606 * stream. All other options are optional.
608 * * `hinting-range-min` and `hinting-range-max` specify the range for
609 * which the autohinter generates optimized hinting code. If a PPEM
610 * value is smaller than the value of `hinting-range-min`, hinting still
611 * takes place but the configuration created for `hinting-range-min` is
612 * used. The analogous action is taken for `hinting-range-max`, only
613 * limited by the value given with `hinting-limit`. The font's `gasp`
614 * table is set up to always use grayscale rendering with grid-fitting
615 * for standard hinting, and symmetric grid-fitting and symmetric
616 * smoothing for horizontal subpixel hinting (ClearType).
618 * * ttfautohint can process its own output a second time only if option
619 * `hint-composites` is not set (or if the font doesn't contain
620 * composite glyphs at all). This limitation might change in the
621 * future.
623 * ```C
624 */
626 TA_Error
627 TTF_autohint(const char* options,
628 ...);
630 /*
631 * ```
633 */
635 /* pandoc-end */
637 #ifdef __cplusplus
638 } /* extern "C" */
639 #endif
641 #endif /* __TTFAUTOHINT_H__ */
643 /* end of ttfautohint.h */