lib/ttfautohint.h

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