lib/ttfautohint.h

   1 /* ttfautohint.h */
   2
   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  */
  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 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.
 161  *
 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.
 168  *
 169  * [OpenType specification of the `name` table]: http://www.microsoft.com/typography/otspec/name.htm
 170  *
 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.
 174  *
 175  * *info_data* is a void pointer to user-supplied data.
 176  *
 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).
 179  *
 180  * ```C
 181  */
 182
 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);
 191
 192 /*
 193  * ```
 194  *
 195  */
 196
 197
 198 /*
 199  * Callback: `TA_Info_Post_Func`
 200  * -----------------------------
 201  *
 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.
 206  *
 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.
 212  *
 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.
 216  *
 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).
 219  *
 220  * ```C
 221  */
 222
 223 typedef int
 224 (*TA_Info_Post_Func)(void* info_data);
 225
 226 /*
 227  * ```
 228  *
 229  */
 230
 231 /* pandoc-end */
 232
 233
 234 /*
 235  * Error values in addition to the FT_Err_XXX constants from FreeType.
 236  *
 237  * All error values specific to ttfautohint start with `TA_Err_'.
 238  */
 239 #include <ttfautohint-errors.h>
 240
 241
 242 /* pandoc-start */
 243
 244 /*
 245  * Function: `TTF_autohint`
 246  * ------------------------
 247  *
 248  *
 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.
 252  *
 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.
 260  *
 261  * Note that fields marked as 'not implemented yet' are subject to change.
 262  *
 263  *
 264  * ### I/O
 265  *
 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`.
 269  *
 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`.
 273  *
 274  * `in-buffer-len`
 275  * :   A value of type `size_t`, giving the length of the input buffer.
 276  *     Needs `in-buffer`.
 277  *
 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`.
 281  *
 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`.
 286  *
 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`.
 290  *
 291  * `control-file`
 292  * :   A pointer of type `FILE*` to the data stream of control instructions.
 293  *     Mutually exclusive with `control-buffer`.
 294  *
 295  *     An entry in a control instructions file or buffer has one of the
 296  *     following syntax forms (with brackets showing optional elements):
 297  *
 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
 301  *
 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.
 307  *
 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.
 314  *
 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.
 327  *
 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.
 333  *
 334  *     Modifying or adding segments don't directly modify the outlines; it
 335  *     only influences the hinting process.
 336  *
 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.
 348  *
 349  *     Both *points* and *ppems* are number ranges, similar to the
 350  *     `x-height-snapping-exceptions` syntax.
 351  *
 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.
 357  *
 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.
 361  *
 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.
 366  *
 367  *     A comment starts with character '`#`'; the rest of the line is
 368  *     ignored.  An empty line is ignored also.
 369  *
 370  *     Note that only character '`.`' is recognized as a decimal point, and
 371  *     a thousands separator is not accepted.
 372  *
 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`.
 377  *
 378  * `control-buffer-len`
 379  * :   A value of type `size_t`, giving the length of the control
 380  *     instructions buffer.  Needs `control-buffer`.
 381  *
 382  *
 383  * ### Messages and Callbacks
 384  *
 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.
 390  *
 391  * `progress-callback-data`
 392  * :   A pointer of type `void*` to user data that is passed to the
 393  *     progress callback function.
 394  *
 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.
 399  *
 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.
 405  *
 406  *     Use it as a more sophisticated alternative to `error-string`.
 407  *
 408  * `error-callback-data`
 409  * :   A point of type `void*` to user data that is passed to the error
 410  *     callback function.
 411  *
 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.
 417  *
 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.
 424  *
 425  * `info-callback-data`
 426  * :   A pointer of type `void*` to user data that is passed to the info
 427  *     callback functions.
 428  *
 429  * `debug`
 430  * :   If this integer is set to\ 1, lots of debugging information is print
 431  *     to stderr.  The default value is\ 0.
 432  *
 433  *
 434  * ### General Hinting Options
 435  *
 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`.
 440  *
 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`.
 446  *
 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.
 453  *
 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.
 463  *
 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.
 472  *
 473  *     `pre-hinting` is a deprecated alias name for this option.
 474  *
 475  *
 476  * ### Hinting Algorithms
 477  *
 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.
 482  *
 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.
 489  *
 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.
 497  *
 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.
 506  *
 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.
 520  *
 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.
 527  *
 528  *
 529  * ### Scripts
 530  *
 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`.
 538  *
 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`.
 545  *
 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.
 554  *
 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).
 562  *
 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.
 566  *
 567  *
 568  * ### Miscellaneous
 569  *
 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.
 577  *
 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.
 584  *
 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.
 590  *
 591  *     If this option is not set, and the font to be processed contains a
 592  *     `TTFA` table, it gets removed.
 593  *
 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.
 597  *
 598  * `dehint`
 599  * :   If set to\ 1, remove all hints from the font.  All other hinting
 600  *     options are ignored.
 601  *
 602  *
 603  * ### Remarks
 604  *
 605  *   * Obviously, it is necessary to have an input and an output data
 606  *     stream.  All other options are optional.
 607  *
 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).
 617  *
 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.
 622  *
 623  * ```C
 624  */
 625
 626 TA_Error
 627 TTF_autohint(const char* options,
 628              ...);
 629
 630 /*
 631  * ```
 632  *
 633  */
 634
 635 /* pandoc-end */
 636
 637 #ifdef __cplusplus
 638 } /* extern "C" */
 639 #endif
 640
 641 #endif /* __TTFAUTOHINT_H__ */
 642
 643 /* end of ttfautohint.h */