lib/ttfautohint.h.in

   1 /* ttfautohint.h */
   2
   3 /*
   4  * Copyright (C) 2011-2020 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 #include <stdlib.h>
  21 #include <stdint.h>
  22
  23
  24 #ifdef _WIN32
  25 #  ifdef DLL_EXPORT
  26 #    define TA_LIB_EXPORT __declspec(dllexport)
  27 #  elif defined(DLL_IMPORT)
  28 #    define TA_LIB_EXPORT __declspec(dllimport)
  29 #  endif
  30 #endif
  31
  32 #ifndef TA_LIB_EXPORT
  33 #  define TA_LIB_EXPORT
  34 #endif
  35
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41
  42 /*
  43  * This file gets processed with a simple sed script to extract the
  44  * documentation (written in pandoc's markdown format); code between the
  45  * `pandoc' markers are retained, everything else is discarded.  C comments
  46  * are uncommented so that column 4 becomes column 1; empty lines outside of
  47  * comments are removed.
  48  */
  49
  50
  51 /* pandoc-start */
  52
  53 /*
  54  * The ttfautohint API
  55  * ===================
  56  *
  57  * This section documents the public functions of the ttfautohint library
  58  * together with its callback functions.  All information has been directly
  59  * extracted from the `ttfautohint.h` header file.
  60  *
  61  */
  62
  63
  64 /*
  65  * Preprocessor Macros, Typedefs, and Enums
  66  * ----------------------------------------
  67  *
  68  * Some default values.
  69  *
  70  * ```C
  71  */
  72
  73 #define TA_HINTING_RANGE_MIN 8
  74 #define TA_HINTING_RANGE_MAX 50
  75 #define TA_HINTING_LIMIT 200
  76 #define TA_INCREASE_X_HEIGHT 14
  77
  78 /*
  79  *```
  80  *
  81  * An error type.
  82  *
  83  * ```C
  84  */
  85
  86 typedef int TA_Error;
  87
  88 /*
  89  *```
  90  *
  91  * An enum type for stem width algorithm selection.
  92  *
  93  * ```C
  94  */
  95
  96 enum
  97 {
  98   TA_STEM_WIDTH_MODE_NATURAL = -1,
  99   TA_STEM_WIDTH_MODE_QUANTIZED = 0,
 100   TA_STEM_WIDTH_MODE_STRONG = 1
 101 };
 102
 103 /*
 104  * ```
 105  *
 106  */
 107
 108
 109 /*
 110  * Function Pointer: `TA_Alloc_Func`
 111  * ---------------------------------
 112  *
 113  * A pointer to a function provided by the calling application to allocate
 114  * memory.  The ttfautohint library uses this for allocating the buffer
 115  * given by the `out-buffer` field of
 116  * [`TTF_autohint`](#function-ttf_autohint) and for allocating the `str`
 117  * buffer in the [`TA_Info_Func`](#callback-ta_info_func) callback.
 118  *
 119  * The signature is identical to standard\ C's `malloc` function (in header
 120  * file `stdlib.h`).
 121  *
 122  * ```C
 123  */
 124
 125 typedef void *
 126 (*TA_Alloc_Func)(size_t size);
 127
 128 /*
 129  * ```
 130  *
 131  */
 132
 133
 134 /*
 135  * Function Pointer: `TA_Free_Func`
 136  * --------------------------------
 137  *
 138  * A pointer to a function provided by the calling application to free
 139  * memory allocated with [`TA_Alloc_Func`](#function-pointer-ta_alloc_func).
 140  * The ttfautohint library calls this for deallocating the `str` buffers in
 141  * the [`TA_Info_Func`](#callback-ta_info_func) callback after they have
 142  * been used.
 143  *
 144  * The signature is identical to standard\ C's `free` function (in header
 145  * file `stdlib.h`).
 146  *
 147  * ```C
 148  */
 149
 150 typedef void
 151 (*TA_Free_Func)(void *ptr);
 152
 153 /*
 154  * ```
 155  *
 156  */
 157
 158
 159 /*
 160  * Callback: `TA_Progress_Func`
 161  * ----------------------------
 162  *
 163  * A callback function to get progress information.  *curr_idx* gives the
 164  * currently processed glyph index; if it is negative, an error has
 165  * occurred.  *num_glyphs* holds the total number of glyphs in the font
 166  * (this value can't be larger than 65535).
 167  *
 168  * *curr_sfnt* gives the current subfont within a TrueType Collection (TTC),
 169  * and *num_sfnts* the total number of subfonts.
 170  *
 171  * If the return value is non-zero, `TTF_autohint` aborts with
 172  * `TA_Err_Canceled`.  Use this for a 'Cancel' button or similar features in
 173  * interactive use.
 174  *
 175  * *progress_data* is a void pointer to user-supplied data.
 176  *
 177  * ```C
 178  */
 179
 180 typedef int
 181 (*TA_Progress_Func)(long curr_idx,
 182                     long num_glyphs,
 183                     long curr_sfnt,
 184                     long num_sfnts,
 185                     void* progress_data);
 186
 187 /*
 188  * ```
 189  *
 190  */
 191
 192
 193 /*
 194  * Callback: `TA_Error_Func`
 195  * -------------------------
 196  *
 197  * A callback function to get error information.
 198  *
 199  * *error* is the value `TTF_autohint` returns.  See file
 200  * `ttfautohint-errors.h` for a list.  Error codes not in this list are
 201  * directly taken from FreeType; see the FreeType header file `fterrdef.h`
 202  * for more.
 203  *
 204  * *error_string*, if non-NULL, is a pointer to an error message that
 205  * represents *error*.
 206  *
 207  * The next three parameters help identify the origin of text string parsing
 208  * errors.  *linenum*, if non-zero, contains the line number.  *line*, if
 209  * non-NULL, is a pointer to the input line that can't be processed.
 210  * *errpos*, if non-NULL, holds a pointer to the position in *line* where
 211  * the problem occurs.
 212  *
 213  * *error_data* is a void pointer to user-supplied data.
 214  *
 215  * ```C
 216  */
 217
 218 typedef void
 219 (*TA_Error_Func)(TA_Error error,
 220                  const char* error_string,
 221                  unsigned int linenum,
 222                  const char* line,
 223                  const char* errpos,
 224                  void* error_data);
 225
 226 /*
 227  * ```
 228  *
 229  */
 230
 231
 232 /*
 233  * Callback: `TA_Info_Func`
 234  * ------------------------
 235  *
 236  * A callback function to access or modify strings in the `name` table; it
 237  * is called in a loop that iterates over all `name` table entries.  If
 238  * defined, [`TA_Info_Post_Func`](#callback-ta_info_post_func) gets executed
 239  * after this loop so that the collected data can be written back to the
 240  * `name` table.
 241  *
 242  * *platform_id*, *encoding_id*, *language_id*, and *name_id* are the
 243  * identifiers of a `name` table entry pointed to by *str* with a length
 244  * pointed to by *str_len* (in bytes; the string has no trailing NULL byte).
 245  * Please refer to the [OpenType specification of the `name` table] for a
 246  * detailed description of the various parameters, in particular which
 247  * encoding is used for a given platform and encoding ID.
 248  *
 249  * [OpenType specification of the `name` table]: https://www.microsoft.com/typography/otspec/name.htm
 250  *
 251  * The string *str* is allocated with the function specified by the
 252  * `alloc-func` field of [`TTF_autohint`](#function-ttf_autohint); the
 253  * application should reallocate the data if necessary, ensuring that the
 254  * string length doesn't exceed 0xFFFF.
 255  *
 256  * *info_data* is a void pointer to user-supplied data.
 257  *
 258  * If an error occurs, return a non-zero value and don't modify *str* and
 259  * *str_len* (such errors are handled as non-fatal).
 260  *
 261  * ```C
 262  */
 263
 264 typedef int
 265 (*TA_Info_Func)(unsigned short platform_id,
 266                 unsigned short encoding_id,
 267                 unsigned short language_id,
 268                 unsigned short name_id,
 269                 unsigned short* str_len,
 270                 unsigned char** str,
 271                 void* info_data);
 272
 273 /*
 274  * ```
 275  *
 276  */
 277
 278
 279 /*
 280  * Callback: `TA_Info_Post_Func`
 281  * -----------------------------
 282  *
 283  * A callback function, giving the application the possibility to access or
 284  * modify strings in the `name` table after
 285  * [`TA_Info_Func`](#callback-ta_info_func) has iterated over all `name`
 286  * table entries.
 287  *
 288  * It is expected that `TA_Info_Func` stores pointers to the `name` table
 289  * entries it wants to access or modify; the only parameter is thus
 290  * *info_data*, which is a void pointer to the user-supplied data already
 291  * provided to `TA_Info_Func`.  Obviously, calling `TA_Info_Post_Func` with
 292  * `TA_Info_Func` undefined has no effect.
 293  *
 294  * The `name` table strings are allocated with the function specified by the
 295  * `alloc-func` field of [`TTF_autohint`](#function-ttf_autohint); the
 296  * application should reallocate the data if necessary, ensuring that no
 297  * string length exceeds 0xFFFF.
 298  *
 299  * If an error occurs, return a non-zero value and don't modify the affected
 300  * string and string length (such errors are handled as non-fatal).
 301  *
 302  * ```C
 303  */
 304
 305 typedef int
 306 (*TA_Info_Post_Func)(void* info_data);
 307
 308 /*
 309  * ```
 310  *
 311  */
 312
 313 /* pandoc-end */
 314
 315
 316 /*
 317  * Error values in addition to the FT_Err_XXX constants from FreeType.
 318  *
 319  * All error values specific to ttfautohint start with `TA_Err_'.
 320  */
 321 #include <ttfautohint-errors.h>
 322
 323
 324 /* pandoc-start */
 325
 326 /*
 327  * Function: `TTF_autohint`
 328  * ------------------------
 329  *
 330  * Read a TrueType font, remove existing bytecode (in the SFNT tables
 331  * `prep`, `fpgm`, `cvt `, and `glyf`), and write a new TrueType font with
 332  * new bytecode based on the autohinting of the FreeType library, optionally
 333  * using a reference font to derive blue zones.
 334  *
 335  * It expects a format string *options* and a variable number of arguments,
 336  * depending on the fields in *options*.  The fields are comma separated;
 337  * whitespace within the format string is not significant, a trailing comma
 338  * is ignored.  Fields are parsed from left to right; if a field occurs
 339  * multiple times, the last field's argument wins.  The same is true for
 340  * fields that are mutually exclusive.  Depending on the field, zero or one
 341  * argument is expected.
 342  *
 343  * Note that fields marked as 'not implemented yet' are subject to change.
 344  *
 345  *
 346  * ### Memory Management
 347  *
 348  * The next two fields are necessary on some platforms if ttfautohint is
 349  * compiled as a shared library, and the application uses a different
 350  * runtime library.  This can happen, for example, on the MS Windows
 351  * platform if your program is written in Python and communicates via [the
 352  * 'ctypes' interface](https://docs.python.org/3/library/ctypes.html) with
 353  * the ttfautohint DLL.
 354  *
 355  * `alloc-func`
 356  * :   A pointer of type [`TA_Alloc_Func`](#function-pointer-ta_alloc_func)
 357  *     specifying a memory allocation function.  It gets used to allocate
 358  *     the buffer given by the `out-buffer` field and the data exposed by
 359  *     the [`TA_Info_Func`](#callback-ta_info_func) callback.  If not set or
 360  *     set to NULL, or if `out-buffer` is not set or set to NULL,
 361  *     standard\ C's `malloc` function is used.
 362  *
 363  * `free-func`
 364  * :   A pointer of type [`TA_Free_Func`](#function-pointer-ta_free_func)
 365  *     specifying a memory deallocation function.  It gets called to free
 366  *     the data exposed by the [`TA_Info_Func`](#callback-ta_info_func)
 367  *     callback after it has been used.  If not set or set to NULL, or if
 368  *     `out_buffer` is not set or set to NULL, standard\ C's `free` function
 369  *     is used.
 370  *
 371  *
 372  * ### I/O
 373  *
 374  * `in-file`
 375  * :   A pointer of type `FILE*` to the data stream of the input font,
 376  *     opened for binary reading.  Mutually exclusive with `in-buffer`.
 377  *
 378  * `in-buffer`
 379  * :   A pointer of type `const char*` to a buffer that contains the input
 380  *     font.  Needs `in-buffer-len`.  Mutually exclusive with `in-file`.
 381  *
 382  * `in-buffer-len`
 383  * :   A value of type `size_t`, giving the length of the input buffer.
 384  *     Needs `in-buffer`.
 385  *
 386  * `out-file`
 387  * :   A pointer of type `FILE*` to the data stream of the output font,
 388  *     opened for binary writing.  Mutually exclusive with `out-buffer`.
 389  *
 390  * `out-buffer`
 391  * :   A pointer of type `char**` to a buffer that contains the output
 392  *     font.  Needs `out-buffer-len`.  Mutually exclusive with `out-file`.
 393  *     The application should deallocate the memory with the function given
 394  *     by `free-func`.
 395  *
 396  * `out-buffer-len`
 397  * :   A pointer of type `size_t*` to a value giving the length of the
 398  *     output buffer.  Needs `out-buffer`.
 399  *
 400  * `control-file`
 401  * :   A pointer of type `FILE*` to the data stream of control instructions.
 402  *     Mutually exclusive with `control-buffer`.
 403  *
 404  *     See '[Control Instructions](#control-instructions)' for the syntax
 405  *     used in such a file or buffer.
 406  *
 407  * `control-buffer`
 408  * :   A pointer of type `const char*` to a buffer that contains control
 409  *     instructions.  Needs `control-buffer-len`.  Mutually exclusive with
 410  *     `control-file`.
 411  *
 412  * `control-buffer-len`
 413  * :   A value of type `size_t`, giving the length of the control
 414  *     instructions buffer.  Needs `control-buffer`.
 415  *
 416  * `reference-file`
 417  * :   A pointer of type `FILE*` to the data stream of the reference font,
 418  *     opened for binary reading.  Mutually exclusive with
 419  *     `reference-buffer`.
 420  *
 421  * `reference-buffer`
 422  * :   A pointer of type `const char*` to a buffer that contains the
 423  *     reference font.  Needs `reference-buffer-len`.  Mutually exclusive
 424  *     with `reference-file`.
 425  *
 426  * `reference-buffer-len`
 427  * :   A value of type `size_t`, giving the length of the reference buffer.
 428  *     Needs `reference-buffer`.
 429  *
 430  * `reference-index`
 431  * :   The face index to be used in the reference font.  The default value
 432  *     is\ 0.
 433  *
 434  * `reference-name`
 435  * :   A string that specifies the name of the reference font.  It is only
 436  *     used to emit a sensible value for the `TTFA` table if `TTFA-info` is
 437  *     set.
 438  *
 439  *
 440  * ### Messages and Callbacks
 441  *
 442  * `progress-callback`
 443  * :   A pointer of type [`TA_Progress_Func`](#callback-ta_progress_func),
 444  *     specifying a callback function for progress reports.  This function
 445  *     gets called after a single glyph has been processed.  If this field
 446  *     is not set or set to NULL, no progress callback function is used.
 447  *
 448  * `progress-callback-data`
 449  * :   A pointer of type `void*` to user data that is passed to the
 450  *     progress callback function.
 451  *
 452  * `error-string`
 453  * :   A pointer of type `unsigned char**` to a string (in UTF-8 encoding)
 454  *     that verbally describes the error code.  You must not change the
 455  *     returned value.
 456  *
 457  * `error-callback`
 458  * :   A pointer of type [`TA_Error_Func`](#callback-ta_error_func),
 459  *     specifying a callback function for error messages.  This function
 460  *     gets called right before `TTF_autohint` exits.  If this field is not
 461  *     set or set to NULL, no error callback function is used.
 462  *
 463  *     Use it as a more sophisticated alternative to `error-string`.
 464  *
 465  * `error-callback-data`
 466  * :   A point of type `void*` to user data that is passed to the error
 467  *     callback function.
 468  *
 469  * `info-callback`
 470  * :   A pointer of type [`TA_Info_Func`](#callback-ta_info_func),
 471  *     specifying a callback function for manipulating the `name` table.
 472  *     This function gets called for each `name` table entry.  If not set or
 473  *     set to NULL, `TA_Info_Func` is not called.
 474  *
 475  * `info-post-callback`
 476  * :   A pointer of type [`TA_Info_Post_Func`](#callback-ta_info_post_func),
 477  *     specifying a callback function for manipulating the `name` table.  It
 478  *     is called after the function specified with `info-callback` has
 479  *     iterated over all `name` table entries.  If not set or set to NULL,
 480  *     `TA_Info_Post_Func` is not called.
 481  *
 482  * `info-callback-data`
 483  * :   A pointer of type `void*` to user data that is passed to the info
 484  *     callback functions.
 485  *
 486  * `debug`
 487  * :   If this integer is set to\ 1, lots of debugging information is print
 488  *     to stderr.  The default value is\ 0.
 489  *
 490  *
 491  * ### General Hinting Options
 492  *
 493  * `hinting-range-min`
 494  * :   An integer (which must be larger than or equal to\ 2) giving the
 495  *     lowest PPEM value used for autohinting.  If this field is not set, it
 496  *     defaults to
 497  *     [`TA_HINTING_RANGE_MIN`](#preprocessor-macros-typedefs-and-enums).
 498  *
 499  * `hinting-range-max`
 500  * :   An integer (which must be larger than or equal to the value of
 501  *     `hinting-range-min`) giving the highest PPEM value used for
 502  *     autohinting.  If this field is not set, it defaults to
 503  *     [`TA_HINTING_RANGE_MAX`](#preprocessor-macros-typedefs-and-enums).
 504  *
 505  * `hinting-limit`
 506  * :   An integer (which must be larger than or equal to the value of
 507  *     `hinting-range-max`) that gives the largest PPEM value at which
 508  *     hinting is applied.  For larger values, hinting is switched off.  If
 509  *     this field is not set, it defaults to
 510  *     [`TA_HINTING_LIMIT`](#preprocessor-macros-typedefs-and-enums).  If it
 511  *     is set to\ 0, no hinting limit is added to the bytecode.
 512  *
 513  * `hint-composites`
 514  * :   If this integer is set to\ 1, composite glyphs get separate hints.
 515  *     This implies adding a special glyph to the font called
 516  *     ['.ttfautohint'](#the-.ttfautohint-glyph).  Setting it to\ 0 (which
 517  *     is the default), the hints of the composite glyphs' components are
 518  *     used.  Adding hints for composite glyphs increases the size of the
 519  *     resulting bytecode a lot, but it might deliver better hinting
 520  *     results.  However, this depends on the processed font and must be
 521  *     checked by inspection.
 522  *
 523  * `adjust-subglyphs`
 524  * :   An integer (1\ for 'on' and 0\ for 'off', which is the default) to
 525  *     specify whether native TrueType hinting of the *input font* shall be
 526  *     applied to all glyphs before passing them to the (internal)
 527  *     autohinter.  The used resolution is the em-size in font units; for
 528  *     most fonts this is 2048ppem.  Use this only if the old hints move or
 529  *     scale subglyphs independently of the output resolution, for example
 530  *     some exotic CJK fonts.
 531  *
 532  *     `pre-hinting` is a deprecated alias name for this option.
 533  *
 534  *
 535  * ### Hinting Algorithms
 536  *
 537  * ttfautohint provides three different algorithms for computing
 538  * horizontal stem widths and the positioning of blue zones.
 539  *
 540  * * `TA_STEM_WIDTH_MODE_NATURAL`: No adjustments to stem
 541  *   widths, discrete blue zone positioning.  This is what FreeType uses for
 542  *   its 'light' (auto-)hinting mode.
 543  *
 544  * * `TA_STEM_WIDTH_MODE_QUANTIZED`: Both stem widths and blue zone
 545  *   positions are slightly quantized to take discrete values.  For
 546  *   example, stem values 50, 51, 72, 76, and 100 would become 50, 74, and
 547  *   100 (or something similar).
 548  *
 549  * * `TA_STEM_WIDTH_MODE_STRONG`: If active, stem widths and blue zones are
 550  *   snapped and positioned to integer pixel values as much as possible.
 551  *
 552  * These values are arguments to ttfautohint's three different hinting mode
 553  * options.
 554  *
 555  * `gray-stem-width-mode`
 556  * :   Specify the stem width algorithm for grayscale rendering.  Possible
 557  *     integer values are `TA_STEM_WIDTH_MODE_NATURAL`,
 558  *     `TA_STEM_WIDTH_MODE_QUANTIZED` (the default), and
 559  *     `TA_STEM_WIDTH_MODE_STRONG`, as discussed above.
 560  *
 561  * `gdi-cleartype-stem-width-mode`
 562  * :   Specify the stem width algorithm for GDI ClearType rendering, this
 563  *     is, the rasterizer version (as returned by the GETINFO bytecode
 564  *     instruction) is in the range 36\ <= version <\ 38 and ClearType is
 565  *     enabled.  Possible integer values are `TA_STEM_WIDTH_MODE_NATURAL`,
 566  *     `TA_STEM_WIDTH_MODE_QUANTIZED`, and `TA_STEM_WIDTH_MODE_STRONG` (the
 567  *     default), as discussed above.
 568  *
 569  * `dw-cleartype-stem-width-mode`
 570  * :   Specify the stem width algorithm for DW ClearType rendering, this is,
 571  *     the rasterizer version (as returned by the GETINFO bytecode
 572  *     instruction) is >=\ 38, ClearType is enabled, and subpixel
 573  *     positioning is enabled also.  Possible integer values are
 574  *     `TA_STEM_WIDTH_MODE_NATURAL`, `TA_STEM_WIDTH_MODE_QUANTIZED` (the
 575  *     default), and `TA_STEM_WIDTH_MODE_STRONG`, as discussed above.
 576  *
 577  * `increase-x-height`
 578  * :   An integer.  For PPEM values in the range 6\ <= PPEM
 579  *     <= `increase-x-height`, round up the font's x\ height much more often
 580  *     than normally (to use the terminology of TrueType's 'Super Round'
 581  *     bytecode instruction, the threshold gets increased from 5/8px to
 582  *     13/16px).  If it is set to\ 0, this feature is switched off.  If this
 583  *     field is not set, it defaults to
 584  *     [`TA_INCREASE_X_HEIGHT`](#preprocessor-macros-typedefs-and-enums).
 585  *     Use this flag to improve the legibility of small font sizes if
 586  *     necessary.
 587  *
 588  * `x-height-snapping-exceptions`
 589  * :   A pointer of type `const char*` to a null-terminated string that
 590  *     gives a list of comma separated PPEM values or value ranges at which
 591  *     no x\ height snapping shall be applied.  A value range has the form
 592  *     *value*~1~`-`*value*~2~, meaning *value*~1~ <= PPEM <= *value*~2~.
 593  *     *value*~1~ or *value*~2~ (or both) can be missing; a missing value is
 594  *     replaced by the beginning or end of the whole interval of valid PPEM
 595  *     values, respectively.  Whitespace is not significant; superfluous
 596  *     commas are ignored, and ranges must be specified in increasing order.
 597  *     For example, the string `"3, 5-7, 9-"` means the values 3, 5, 6, 7,
 598  *     9, 10, 11, 12, etc.  Consequently, if the supplied argument is `"-"`,
 599  *     no x\ height snapping takes place at all.  The default is the empty
 600  *     string (`""`), meaning no snapping exceptions.
 601  *
 602  * `windows-compatibility`
 603  * :   If this integer is set to\ 1, two artificial blue zones are used,
 604  *     positioned at the `usWinAscent` and `usWinDescent` values (from the
 605  *     font's `OS/2` table).  The idea is to help ttfautohint so that the
 606  *     hinted glyphs stay within this horizontal stripe since Windows clips
 607  *     everything falling outside.  The default is\ 0.
 608  *
 609  * `gray-strong-stem-width`
 610  * :   Deprecated.  The argument values 0 and 1 of this field correspond to
 611  *     the argument values `TA_STEM_WIDTH_MODE_QUANTIZED` and
 612  *     `TA_STEM_WIDTH_MODE_STRONG` of the field 'gray-stem-width-mode',
 613  *     respectively.
 614  *
 615  * `gdi-cleartype-strong-stem-width`
 616  * :   Deprecated.  The argument values 0 and 1 of this field correspond to
 617  *     the argument values `TA_STEM_WIDTH_MODE_QUANTIZED` and
 618  *     `TA_STEM_WIDTH_MODE_STRONG` of the field
 619  *     'gdi-cleartype-stem-width-mode', respectively.
 620  *
 621  * `dw-cleartype-strong-stem-width`
 622  * :   Deprecated.  The argument values 0 and 1 of this field correspond to
 623  *     the argument values `TA_STEM_WIDTH_MODE_QUANTIZED` and
 624  *     `TA_STEM_WIDTH_MODE_STRONG` of the field
 625  *     'dw-cleartype-stem-width-mode', respectively.
 626  *
 627  *
 628  * ### Scripts
 629  *
 630  * `default-script`
 631  * :   A string consisting of four lowercase characters that specifies the
 632  *     default script for OpenType features.  After applying all features
 633  *     that are handled specially, use this value for the remaining
 634  *     features.  The default value is `"latn"`; if set to `"none"`, no
 635  *     script is used.  Valid values can be found in the header file
 636  *     `ttfautohint-scripts.h`.
 637  *
 638  * `fallback-script`
 639  * :   A string consisting of four lowercase characters, specifying the
 640  *     default script for glyphs that can't be mapped to a script
 641  *     automatically.  By default, such glyphs are hinted; if option
 642  *     `fallback-scaling` is set, they are scaled only instead.  Valid
 643  *     values can be found in the header file `ttfautohint-scripts.h`.
 644  *
 645  *     Default value is `"none"`, which means hinting without using a
 646  *     script's blue zones if `fallback-scaling` isn't set.  If
 647  *     `fallback_scaling` is set, value `"none"` implies no hinting for
 648  *     unmapped glyphs.
 649  *
 650  * `fallback-scaling`
 651  * :   Set this integer to\ 1 if glyphs handled by the fallback script
 652  *     should be scaled only with the fallback script's scaling value,
 653  *     instead of being hinted with the fallback script's hinting
 654  *     parameters.
 655  *
 656  * `symbol`
 657  * :   Set this integer to\ 1 if you want to process a font that ttfautohint
 658  *     would refuse otherwise because it can't find a single standard
 659  *     character for any of the supported scripts.  ttfautohint then uses a
 660  *     default (hinting) value for the standard stem width instead of
 661  *     deriving it from a script's set of standard characters (for the latin
 662  *     script, one of them is character 'o').  The default value of this
 663  *     option is\ 0.
 664  *
 665  * `fallback-stem-width`
 666  * :   Set the horizontal stem width (hinting) value for all scripts that
 667  *     lack proper standard characters.  The value is given in font units
 668  *     and must be a positive integer.  If not set, or the value is zero,
 669  *     ttfautohint uses a hard-coded default (50\ units at 2048 units per
 670  *     EM, and linearly scaled for other UPEM values, for example 24\ units
 671  *     at 1000 UPEM).
 672  *
 673  *     For symbol fonts (i.e., option `symbol` is given),
 674  *     `fallback-stem-width` has an effect only if `fallback-script` is set
 675  *     also.
 676  *
 677  *
 678  * ### Miscellaneous
 679  *
 680  * `ignore-restrictions`
 681  * :   If the font has set bit\ 1 in the 'fsType' field of the `OS/2` table,
 682  *     the ttfautohint library refuses to process the font since a
 683  *     permission to do that is required from the font's legal owner.  In
 684  *     case you have such a permission you might set the integer argument to
 685  *     value\ 1 to make ttfautohint handle the font.  The default value
 686  *     is\ 0.
 687  *
 688  * `TTFA-info`
 689  * :   If set to\ 1, ttfautohint creates an SFNT table called `TTFA` and
 690  *     fills it with information on the parameters used while calling
 691  *     `TTF_autohint`.  The format of the output data resembles the
 692  *     information at the very beginning of the dump emitted by option
 693  *     `debug`.  The default value is\ 0.
 694  *
 695  *     Main use of this option is for font editing purposes.  For example,
 696  *     after a font editor has added some glyphs, a front-end to
 697  *     `TTF_autohint` can parse `TTFA` and feed the parameters into another
 698  *     call of `TTF_autohint`.  The new glyphs are then hinted while hints
 699  *     of the old glyphs stay unchanged.
 700  *
 701  *     If this option is not set, and the font to be processed contains a
 702  *     `TTFA` table, it gets removed.
 703  *
 704  *     Note that such a `TTFA` table gets ignored by all font rendering
 705  *     engines.  In TrueType Collections, the `TTFA` table is added to the
 706  *     first subfont.
 707  *
 708  * `dehint`
 709  * :   If set to\ 1, remove all hints from the font.  All other hinting
 710  *     options are ignored.
 711  *
 712  * `epoch`
 713  * :   An integer of type `unsigned long long`, defined as the number of
 714  *     seconds (excluding leap seconds) since 01 Jan 1970 00:00:00 UTC.  If
 715  *     set, or if the value is not equal to `ULLONG_MAX`, this epoch gets
 716  *     used instead of the current date and time for the 'modification time'
 717  *     field in the TTF header.  Use this to get [reproducible
 718  *     builds](https://reproducible-builds.org/).
 719  *
 720  *
 721  * ### Remarks
 722  *
 723  *   * Obviously, it is necessary to have an input and an output data
 724  *     stream.  All other options are optional.
 725  *
 726  *   * `hinting-range-min` and `hinting-range-max` specify the range for
 727  *     which the autohinter generates optimized hinting code.  If a PPEM
 728  *     value is smaller than the value of `hinting-range-min`, hinting still
 729  *     takes place but the configuration created for `hinting-range-min` is
 730  *     used.  The analogous action is taken for `hinting-range-max`, only
 731  *     limited by the value given with `hinting-limit`.  The font's `gasp`
 732  *     table is set up to always use grayscale rendering with grid-fitting
 733  *     for standard hinting, and symmetric grid-fitting and symmetric
 734  *     smoothing for horizontal subpixel hinting (ClearType).
 735  *
 736  *   * ttfautohint can process its own output a second time only if option
 737  *     `hint-composites` is not set (or if the font doesn't contain
 738  *     composite glyphs at all).  This limitation might change in the
 739  *     future.
 740  *
 741  * ```C
 742  */
 743
 744 TA_LIB_EXPORT TA_Error
 745 TTF_autohint(const char* options,
 746              ...);
 747
 748 /*
 749  * ```
 750  *
 751  * Macros: `TTFAUTOHINT_MAJOR`, `TTFAUTOHINT_MINOR`, `TTFAUTOHINT_REVISION`
 752  * ------------------------------------------------------------------------
 753  *
 754  * These three macros give the major, minor, and revision number of the
 755  * library, respectively.  See function
 756  * [`TTF_autohint_version`](#function-ttf_autohint_version) for more
 757  * details.
 758  *
 759  * ```C
 760  */
 761
 762 #define TTFAUTOHINT_MAJOR %TTFAUTOHINT_MAJOR%
 763 #define TTFAUTOHINT_MINOR %TTFAUTOHINT_MINOR%
 764 #define TTFAUTOHINT_REVISION %TTFAUTOHINT_REVISION%
 765
 766 /*
 767  * ```
 768  *
 769  * Macro: `TTFAUTOHINT_VERSION`
 770  * ----------------------------
 771  *
 772  * This macro holds the ttfautohint version string.
 773  *
 774  * For tarball releases it has the form *X*.*Y*[.*Z*], with *X*, *Y*,
 775  * and\ *Z* the major, minor, and revision numbers, respectively.  If the
 776  * revision number is zero, it is omitted.  Examples: `2.7`, `2.7.1`.
 777  *
 778  * If compiling directly from the git repository, ttfautohint's bootstrap
 779  * script derives the version number from the `git describe` output,
 780  * appending the number of commits after a tag together with a shortened
 781  * commit ID.  Example: `2.7.1.23-379b`.
 782  *
 783  * See function [`TTF_autohint_version`](#function-ttf_autohint_version) for
 784  * more details.
 785  *
 786  * ```C
 787  */
 788
 789 #define TTFAUTOHINT_VERSION "%TTFAUTOHINT_VERSION%"
 790
 791 /*
 792  * ```
 793  *
 794  * Function: `TTF_autohint_version`
 795  * --------------------------------
 796  *
 797  * Return the ttfautohint version triplet.  This function is useful when
 798  * dynamically linking to the library, since the macros `TTFAUTOHINT_MAJOR`,
 799  * `TTFAUTOHINT_MINOR`, and `TTFAUTOHINT_PATCH` cannot be used in that case.
 800  *
 801  * The returned integer triplet is _not_ the same as the shared library's
 802  * version triplet (which the dynamic linker uses to resolve runtime
 803  * dependencies).  For example, hypothetical ttfautohint versions 2.27 and
 804  * 2.27.1 might both correspond to shared library version 1.0.38 in case
 805  * there are only, say, documentation or packaging differences that don't
 806  * affect the library code.
 807  *
 808  * If the pkg-config configuration file `ttfautohint.pc` is installed in a
 809  * place that pkg-config can find, a call to
 810  *
 811  * ```
 812  *     pkg-config ttfautohint --modversion
 813  * ```
 814  *
 815  * returns the shared library version.
 816  *
 817  * ```C
 818  */
 819
 820 TA_LIB_EXPORT void
 821 TTF_autohint_version(int *major,
 822                      int *minor,
 823                      int *revision);
 824
 825 /*
 826  * ```
 827  *
 828  * Function: `TTF_autohint_version_string`
 829  * ---------------------------------------
 830  *
 831  * Return the ttfautohint version string.  This function is useful when
 832  * dynamically linking to the library, since the macro `TTFAUTOHINT_VERSION`
 833  * cannot be used in that case.
 834  *
 835  * ```C
 836  */
 837
 838 TA_LIB_EXPORT const char*
 839 TTF_autohint_version_string(void);
 840
 841 /*
 842  * ```
 843  *
 844  */
 845
 846 /* pandoc-end */
 847
 848 #ifdef __cplusplus
 849 } /* extern "C" */
 850 #endif
 851
 852 #endif /* TTFAUTOHINT_H_ */
 853
 854 /* end of ttfautohint.h */