Add `ttfautohint.pc' file.
[ttfautohint.git] / lib / ttfautohint.h
blobe27d0450b3f36e48a7bfc534edd46816c2548c10
1 /* ttfautohint.h */
3 /*
4 * Copyright (C) 2011-2017 by Werner Lemberg.
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.
11 * The file `COPYING' mentioned in the previous paragraph is distributed
12 * with the ttfautohint library.
16 #ifndef TTFAUTOHINT_H_
17 #define TTFAUTOHINT_H_
19 #include <stdarg.h>
20 #include <stdint.h>
23 #ifdef _WIN32
24 # ifdef DLL_EXPORT
25 # define LT_LIB_EXPORT __declspec(dllexport)
26 # elif defined(DLL_IMPORT)
27 # define LT_LIB_EXPORT __declspec(dllimport)
28 # endif
29 #endif
31 #ifndef LT_LIB_EXPORT
32 # define LT_LIB_EXPORT
33 #endif
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
42 * This file gets processed with a simple sed script to extract the
43 * documentation (written in pandoc's markdown format); code between the
44 * `pandoc' markers are retained, everything else is discarded. C comments
45 * are uncommented so that column 4 becomes column 1; empty lines outside of
46 * comments are removed.
50 /* pandoc-start */
53 * The ttfautohint API
54 * ===================
56 * This section documents the single function of the ttfautohint library,
57 * `TTF_autohint`, together with its callback functions (`TA_Progress_Func`
58 * `TA_Error_Func`, `TA_Info_Func`, and `TA_Info_Post_Func`). All
59 * information has been directly extracted from the `ttfautohint.h` header
60 * file.
66 * Preprocessor Macros and Typedefs
67 * --------------------------------
69 * Some default values.
71 * ```C
74 #define TA_HINTING_RANGE_MIN 8
75 #define TA_HINTING_RANGE_MAX 50
76 #define TA_HINTING_LIMIT 200
77 #define TA_INCREASE_X_HEIGHT 14
80 *```
82 * An error type.
84 * ```C
87 typedef int TA_Error;
90 * ```
96 * Callback: `TA_Progress_Func`
97 * ----------------------------
99 * A callback function to get progress information. *curr_idx* gives the
100 * currently processed glyph index; if it is negative, an error has
101 * occurred. *num_glyphs* holds the total number of glyphs in the font
102 * (this value can't be larger than 65535).
104 * *curr_sfnt* gives the current subfont within a TrueType Collection (TTC),
105 * and *num_sfnts* the total number of subfonts.
107 * If the return value is non-zero, `TTF_autohint` aborts with
108 * `TA_Err_Canceled`. Use this for a 'Cancel' button or similar features in
109 * interactive use.
111 * *progress_data* is a void pointer to user-supplied data.
113 * ```C
116 typedef int
117 (*TA_Progress_Func)(long curr_idx,
118 long num_glyphs,
119 long curr_sfnt,
120 long num_sfnts,
121 void* progress_data);
124 * ```
130 * Callback: `TA_Error_Func`
131 * -------------------------
133 * A callback function to get error information.
135 * *error* is the value `TTF_autohint` returns. See file
136 * `ttfautohint-errors.h` for a list. Error codes not in this list are
137 * directly taken from FreeType; see the FreeType header file `fterrdef.h`
138 * for more.
140 * *error_string*, if non-NULL, is a pointer to an error message that
141 * represents *error*.
143 * The next three parameters help identify the origin of text string parsing
144 * errors. *linenum*, if non-zero, contains the line number. *line*, if
145 * non-NULL, is a pointer to the input line that can't be processed.
146 * *errpos*, if non-NULL, holds a pointer to the position in *line* where
147 * the problem occurs.
149 * *error_data* is a void pointer to user-supplied data.
151 * ```C
154 typedef void
155 (*TA_Error_Func)(TA_Error error,
156 const char* error_string,
157 unsigned int linenum,
158 const char* line,
159 const char* errpos,
160 void* error_data);
163 * ```
169 * Callback: `TA_Info_Func`
170 * ------------------------
172 * A callback function to access or modify strings in the `name` table; it
173 * is called in a loop that iterates over all `name` table entries. If
174 * defined, [`TA_Info_Post_Func`](#callback-ta_info_post_func) gets executed
175 * after this loop so that the collected data can be written back to the
176 * `name` table.
178 * *platform_id*, *encoding_id*, *language_id*, and *name_id* are the
179 * identifiers of a `name` table entry pointed to by *str* with a length
180 * pointed to by *str_len* (in bytes; the string has no trailing NULL byte).
181 * Please refer to the [OpenType specification of the `name` table] for a
182 * detailed description of the various parameters, in particular which
183 * encoding is used for a given platform and encoding ID.
185 * [OpenType specification of the `name` table]: http://www.microsoft.com/typography/otspec/name.htm
187 * The string *str* is allocated with `malloc`; the application should
188 * reallocate the data if necessary, ensuring that the string length doesn't
189 * exceed 0xFFFF.
191 * *info_data* is a void pointer to user-supplied data.
193 * If an error occurs, return a non-zero value and don't modify *str* and
194 * *str_len* (such errors are handled as non-fatal).
196 * ```C
199 typedef int
200 (*TA_Info_Func)(unsigned short platform_id,
201 unsigned short encoding_id,
202 unsigned short language_id,
203 unsigned short name_id,
204 unsigned short* str_len,
205 unsigned char** str,
206 void* info_data);
209 * ```
215 * Callback: `TA_Info_Post_Func`
216 * -----------------------------
218 * A callback function, giving the application the possibility to access or
219 * modify strings in the `name` table after
220 * [`TA_Info_Func`](#callback-ta_info_func) has iterated over all `name`
221 * table entries.
223 * It is expected that `TA_Info_Func` stores pointers to the `name` table
224 * entries it wants to access or modify; the only parameter is thus
225 * *info_data*, which is a void pointer to the user-supplied data already
226 * provided to `TA_Info_Func`. Obviously, calling `TA_Info_Post_Func` with
227 * `TA_Info_Func` undefined has no effect.
229 * The `name` table strings are allocated with `malloc`; the application
230 * should reallocate the data if necessary, ensuring that no string length
231 * exceeds 0xFFFF.
233 * If an error occurs, return a non-zero value and don't modify the affected
234 * string and string length (such errors are handled as non-fatal).
236 * ```C
239 typedef int
240 (*TA_Info_Post_Func)(void* info_data);
243 * ```
247 /* pandoc-end */
251 * Error values in addition to the FT_Err_XXX constants from FreeType.
253 * All error values specific to ttfautohint start with `TA_Err_'.
255 #include <ttfautohint-errors.h>
258 /* pandoc-start */
261 * Function: `TTF_autohint`
262 * ------------------------
265 * Read a TrueType font, remove existing bytecode (in the SFNT tables
266 * `prep`, `fpgm`, `cvt `, and `glyf`), and write a new TrueType font with
267 * new bytecode based on the autohinting of the FreeType library, optionally
268 * using a reference font to derive blue zones.
270 * It expects a format string *options* and a variable number of arguments,
271 * depending on the fields in *options*. The fields are comma separated;
272 * whitespace within the format string is not significant, a trailing comma
273 * is ignored. Fields are parsed from left to right; if a field occurs
274 * multiple times, the last field's argument wins. The same is true for
275 * fields that are mutually exclusive. Depending on the field, zero or one
276 * argument is expected.
278 * Note that fields marked as 'not implemented yet' are subject to change.
281 * ### I/O
283 * `in-file`
284 * : A pointer of type `FILE*` to the data stream of the input font,
285 * opened for binary reading. Mutually exclusive with `in-buffer`.
287 * `in-buffer`
288 * : A pointer of type `const char*` to a buffer that contains the input
289 * font. Needs `in-buffer-len`. Mutually exclusive with `in-file`.
291 * `in-buffer-len`
292 * : A value of type `size_t`, giving the length of the input buffer.
293 * Needs `in-buffer`.
295 * `out-file`
296 * : A pointer of type `FILE*` to the data stream of the output font,
297 * opened for binary writing. Mutually exclusive with `out-buffer`.
299 * `out-buffer`
300 * : A pointer of type `char**` to a buffer that contains the output
301 * font. Needs `out-buffer-len`. Mutually exclusive with `out-file`.
302 * Deallocate the memory with `free`.
304 * `out-buffer-len`
305 * : A pointer of type `size_t*` to a value giving the length of the
306 * output buffer. Needs `out-buffer`.
308 * `control-file`
309 * : A pointer of type `FILE*` to the data stream of control instructions.
310 * Mutually exclusive with `control-buffer`.
312 * See '[Control Instructions](#control-instructions)' for the syntax
313 * used in such a file or buffer.
315 * `control-buffer`
316 * : A pointer of type `const char*` to a buffer that contains control
317 * instructions. Needs `control-buffer-len`. Mutually exclusive with
318 * `control-file`.
320 * `control-buffer-len`
321 * : A value of type `size_t`, giving the length of the control
322 * instructions buffer. Needs `control-buffer`.
324 * `reference-file`
325 * : A pointer of type `FILE*` to the data stream of the reference font,
326 * opened for binary reading. Mutually exclusive with
327 * `reference-buffer`.
329 * `reference-buffer`
330 * : A pointer of type `const char*` to a buffer that contains the
331 * reference font. Needs `reference-buffer-len`. Mutually exclusive
332 * with `reference-file`.
334 * `reference-buffer-len`
335 * : A value of type `size_t`, giving the length of the reference buffer.
336 * Needs `reference-buffer`.
338 * `reference-index`
339 * : The face index to be used in the reference font. The default value
340 * is\ 0.
342 * `reference-name`
343 * : A string that specifies the name of the reference font. It is only
344 * used to emit a sensible value for the `TTFA` table if `TTFA-info` is
345 * set.
348 * ### Messages and Callbacks
350 * `progress-callback`
351 * : A pointer of type [`TA_Progress_Func`](#callback-ta_progress_func),
352 * specifying a callback function for progress reports. This function
353 * gets called after a single glyph has been processed. If this field
354 * is not set or set to NULL, no progress callback function is used.
356 * `progress-callback-data`
357 * : A pointer of type `void*` to user data that is passed to the
358 * progress callback function.
360 * `error-string`
361 * : A pointer of type `unsigned char**` to a string (in UTF-8 encoding)
362 * that verbally describes the error code. You must not change the
363 * returned value.
365 * `error-callback`
366 * : A pointer of type [`TA_Error_Func`](#callback-ta_error_func),
367 * specifying a callback function for error messages. This function
368 * gets called right before `TTF_autohint` exits. If this field is not
369 * set or set to NULL, no error callback function is used.
371 * Use it as a more sophisticated alternative to `error-string`.
373 * `error-callback-data`
374 * : A point of type `void*` to user data that is passed to the error
375 * callback function.
377 * `info-callback`
378 * : A pointer of type [`TA_Info_Func`](#callback-ta_info_func),
379 * specifying a callback function for manipulating the `name` table.
380 * This function gets called for each `name` table entry. If not set or
381 * set to NULL, `TA_Info_Func` is not called.
383 * `info-post-callback`
384 * : A pointer of type [`TA_Info_Post_Func`](#callback-ta_info_post_func),
385 * specifying a callback function for manipulating the `name` table. It
386 * is called after the function specified with `info-callback` has
387 * iterated over all `name` table entries. If not set or set to NULL,
388 * `TA_Info_Post_Func` is not called.
390 * `info-callback-data`
391 * : A pointer of type `void*` to user data that is passed to the info
392 * callback functions.
394 * `debug`
395 * : If this integer is set to\ 1, lots of debugging information is print
396 * to stderr. The default value is\ 0.
399 * ### General Hinting Options
401 * `hinting-range-min`
402 * : An integer (which must be larger than or equal to\ 2) giving the
403 * lowest PPEM value used for autohinting. If this field is not set, it
404 * defaults to `TA_HINTING_RANGE_MIN`.
406 * `hinting-range-max`
407 * : An integer (which must be larger than or equal to the value of
408 * `hinting-range-min`) giving the highest PPEM value used for
409 * autohinting. If this field is not set, it defaults to
410 * `TA_HINTING_RANGE_MAX`.
412 * `hinting-limit`
413 * : An integer (which must be larger than or equal to the value of
414 * `hinting-range-max`) that gives the largest PPEM value at which
415 * hinting is applied. For larger values, hinting is switched off. If
416 * this field is not set, it defaults to `TA_HINTING_LIMIT`. If it is
417 * set to\ 0, no hinting limit is added to the bytecode.
419 * `hint-composites`
420 * : If this integer is set to\ 1, composite glyphs get separate hints.
421 * This implies adding a special glyph to the font called
422 * ['.ttfautohint'](#the-.ttfautohint-glyph). Setting it to\ 0 (which
423 * is the default), the hints of the composite glyphs' components are
424 * used. Adding hints for composite glyphs increases the size of the
425 * resulting bytecode a lot, but it might deliver better hinting
426 * results. However, this depends on the processed font and must be
427 * checked by inspection.
429 * `adjust-subglyphs`
430 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) to
431 * specify whether native TrueType hinting of the *input font* shall be
432 * applied to all glyphs before passing them to the (internal)
433 * autohinter. The used resolution is the em-size in font units; for
434 * most fonts this is 2048ppem. Use this only if the old hints move or
435 * scale subglyphs independently of the output resolution, for example
436 * some exotic CJK fonts.
438 * `pre-hinting` is a deprecated alias name for this option.
441 * ### Hinting Algorithms
443 * `gray-strong-stem-width`
444 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) that
445 * specifies whether horizontal stems should be snapped and positioned
446 * to integer pixel values for normal grayscale rendering.
448 * `gdi-cleartype-strong-stem-width`
449 * : An integer (1\ for 'on', which is the default, and 0\ for 'off') that
450 * specifies whether horizontal stems should be snapped and positioned
451 * to integer pixel values for GDI ClearType rendering, this is, the
452 * rasterizer version (as returned by the GETINFO bytecode instruction)
453 * is in the range 36\ <= version <\ 38 and ClearType is enabled.
455 * `dw-cleartype-strong-stem-width`
456 * : An integer (1\ for 'on' and 0\ for 'off', which is the default) that
457 * specifies whether horizontal stems should be snapped and positioned
458 * to integer pixel values for DW ClearType rendering, this is, the
459 * rasterizer version (as returned by the GETINFO bytecode instruction)
460 * is >=\ 38, ClearType is enabled, and subpixel positioning is enabled
461 * also.
463 * `increase-x-height`
464 * : An integer. For PPEM values in the range 6\ <= PPEM
465 * <= `increase-x-height`, round up the font's x\ height much more often
466 * than normally (to use the terminology of TrueType's 'Super Round'
467 * bytecode instruction, the threshold gets increased from 5/8px to
468 * 13/16px). If it is set to\ 0, this feature is switched off. If this
469 * field is not set, it defaults to `TA_INCREASE_X_HEIGHT`. Use this
470 * flag to improve the legibility of small font sizes if necessary.
472 * `x-height-snapping-exceptions`
473 * : A pointer of type `const char*` to a null-terminated string that
474 * gives a list of comma separated PPEM values or value ranges at which
475 * no x\ height snapping shall be applied. A value range has the form
476 * *value*~1~`-`*value*~2~, meaning *value*~1~ <= PPEM <= *value*~2~.
477 * *value*~1~ or *value*~2~ (or both) can be missing; a missing value is
478 * replaced by the beginning or end of the whole interval of valid PPEM
479 * values, respectively. Whitespace is not significant; superfluous
480 * commas are ignored, and ranges must be specified in increasing order.
481 * For example, the string `"3, 5-7, 9-"` means the values 3, 5, 6, 7,
482 * 9, 10, 11, 12, etc. Consequently, if the supplied argument is `"-"`,
483 * no x\ height snapping takes place at all. The default is the empty
484 * string (`""`), meaning no snapping exceptions.
486 * `windows-compatibility`
487 * : If this integer is set to\ 1, two artificial blue zones are used,
488 * positioned at the `usWinAscent` and `usWinDescent` values (from the
489 * font's `OS/2` table). The idea is to help ttfautohint so that the
490 * hinted glyphs stay within this horizontal stripe since Windows clips
491 * everything falling outside. The default is\ 0.
494 * ### Scripts
496 * `default-script`
497 * : A string consisting of four lowercase characters that specifies the
498 * default script for OpenType features. After applying all features
499 * that are handled specially, use this value for the remaining
500 * features. The default value is `"latn"`; if set to `"none"`, no
501 * script is used. Valid values can be found in the header file
502 * `ttfautohint-scripts.h`.
504 * `fallback-script`
505 * : A string consisting of four lowercase characters, specifying the
506 * default script for glyphs that can't be mapped to a script
507 * automatically. By default, such glyphs are hinted; if option
508 * `fallback-scaling` is set, they are scaled only instead. Valid
509 * values can be found in the header file `ttfautohint-scripts.h`.
511 * Default value is `"none"`, which means hinting without using a
512 * script's blue zones if `fallback-scaling` isn't set. If
513 * `fallback_scaling` is set, value `"none"` implies no hinting for
514 * unmapped glyphs.
516 * `fallback-scaling`
517 * : Set this integer to\ 1 if glyphs handled by the fallback script
518 * should be scaled only with the fallback script's scaling value,
519 * instead of being hinted with the fallback script's hinting
520 * parameters.
522 * `symbol`
523 * : Set this integer to\ 1 if you want to process a font that ttfautohint
524 * would refuse otherwise because it can't find a single standard
525 * character for any of the supported scripts. ttfautohint then uses a
526 * default (hinting) value for the standard stem width instead of
527 * deriving it from a script's set of standard characters (for the latin
528 * script, one of them is character 'o'). The default value of this
529 * option is\ 0.
531 * `fallback-stem-width`
532 * : Set the horizontal stem width (hinting) value for all scripts that
533 * lack proper standard characters. The value is given in font units
534 * and must be a positive integer. If not set, or the value is zero,
535 * ttfautohint uses a hard-coded default (50\ units at 2048 units per
536 * EM, and linearly scaled for other UPEM values, for example 24\ units
537 * at 1000 UPEM).
539 * For symbol fonts (i.e., option `symbol` is given),
540 * `fallback-stem-width` has an effect only if `fallback-script` is set
541 * also.
544 * ### Miscellaneous
546 * `ignore-restrictions`
547 * : If the font has set bit\ 1 in the 'fsType' field of the `OS/2` table,
548 * the ttfautohint library refuses to process the font since a
549 * permission to do that is required from the font's legal owner. In
550 * case you have such a permission you might set the integer argument to
551 * value\ 1 to make ttfautohint handle the font. The default value
552 * is\ 0.
554 * `TTFA-info`
555 * : If set to\ 1, ttfautohint creates an SFNT table called `TTFA` and
556 * fills it with information on the parameters used while calling
557 * `TTF_autohint`. The format of the output data resembles the
558 * information at the very beginning of the dump emitted by option
559 * `debug`. The default value is\ 0.
561 * Main use of this option is for font editing purposes. For example,
562 * after a font editor has added some glyphs, a front-end to
563 * `TTF_autohint` can parse `TTFA` and feed the parameters into another
564 * call of `TTF_autohint`. The new glyphs are then hinted while hints
565 * of the old glyphs stay unchanged.
567 * If this option is not set, and the font to be processed contains a
568 * `TTFA` table, it gets removed.
570 * Note that such a `TTFA` table gets ignored by all font rendering
571 * engines. In TrueType Collections, the `TTFA` table is added to the
572 * first subfont.
574 * `dehint`
575 * : If set to\ 1, remove all hints from the font. All other hinting
576 * options are ignored.
578 * `epoch`
579 * : An integer of type `unsigned long long`, defined as the number of
580 * seconds (excluding leap seconds) since 01 Jan 1970 00:00:00 UTC. If
581 * set, or if the value is not equal to `ULLONG_MAX`, this epoch gets
582 * used instead of the current date and time for the 'modification time'
583 * field in the TTF header. Use this to get [reproducible
584 * builds](https://reproducible-builds.org/).
587 * ### Remarks
589 * * Obviously, it is necessary to have an input and an output data
590 * stream. All other options are optional.
592 * * `hinting-range-min` and `hinting-range-max` specify the range for
593 * which the autohinter generates optimized hinting code. If a PPEM
594 * value is smaller than the value of `hinting-range-min`, hinting still
595 * takes place but the configuration created for `hinting-range-min` is
596 * used. The analogous action is taken for `hinting-range-max`, only
597 * limited by the value given with `hinting-limit`. The font's `gasp`
598 * table is set up to always use grayscale rendering with grid-fitting
599 * for standard hinting, and symmetric grid-fitting and symmetric
600 * smoothing for horizontal subpixel hinting (ClearType).
602 * * ttfautohint can process its own output a second time only if option
603 * `hint-composites` is not set (or if the font doesn't contain
604 * composite glyphs at all). This limitation might change in the
605 * future.
607 * ```C
610 LT_LIB_EXPORT TA_Error
611 TTF_autohint(const char* options,
612 ...);
615 * ```
619 /* pandoc-end */
621 #ifdef __cplusplus
622 } /* extern "C" */
623 #endif
625 #endif /* TTFAUTOHINT_H_ */
627 /* end of ttfautohint.h */