lib/ttfautohint.h

   1 /* ttfautohint.h */
   2
   3 /*
   4  * Copyright (C) 2011-2012 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.  Currently, the ttfautohint
  90  * library only hints glyphs from the `glyf` table used in subfont\ 0.
  91  *
  92  * If the return value is non-zero, `TTF_autohint` aborts with
  93  * `TA_Err_Canceled`.  Use this for a 'Cancel' button or similar features in
  94  * interactive use.
  95  *
  96  * *progress_data* is a void pointer to user supplied data.
  97  *
  98  * ```C
  99  */
 100
 101 typedef int
 102 (*TA_Progress_Func)(long curr_idx,
 103                     long num_glyphs,
 104                     long curr_sfnt,
 105                     long num_sfnts,
 106                     void* progress_data);
 107
 108 /*
 109  * ```
 110  *
 111  */
 112
 113
 114 /*
 115  * Callback: `TA_Info_Func`
 116  * ------------------------
 117  *
 118  * A callback function to manipulate strings in the `name` table.
 119  * *platform_id*, *encoding_id*, *language_id*, and *name_id* are the
 120  * identifiers of a `name` table entry pointed to by *str* with a length
 121  * pointed to by *str_len* (in bytes; the string has no trailing NULL byte).
 122  * Please refer to the [OpenType specification] for a detailed description
 123  * of the various parameters, in particular which encoding is used for a
 124  * given platform and encoding ID.
 125  *
 126  * [OpenType specification]: http://www.microsoft.com/typography/otspec/name.htm
 127  *
 128  * The string *str* is allocated with `malloc`; the application should
 129  * reallocate the data if necessary, ensuring that the string length doesn't
 130  * exceed 0xFFFF.
 131  *
 132  * *info_data* is a void pointer to user supplied data.
 133  *
 134  * If an error occurs, return a non-zero value and don't modify *str* and
 135  * *str_len* (such errors are handled as non-fatal).
 136  *
 137  * ```C
 138  */
 139
 140 typedef int
 141 (*TA_Info_Func)(unsigned short platform_id,
 142                 unsigned short encoding_id,
 143                 unsigned short language_id,
 144                 unsigned short name_id,
 145                 unsigned short* str_len,
 146                 unsigned char** str,
 147                 void* info_data);
 148
 149 /*
 150  * ```
 151  *
 152  */
 153
 154 /* pandoc-end */
 155
 156
 157 /*
 158  * Error values in addition to the FT_Err_XXX constants from FreeType.
 159  *
 160  * All error values specific to ttfautohint start with `TA_Err_'.
 161  */
 162 #include <ttfautohint-errors.h>
 163
 164
 165 /* pandoc-start */
 166
 167 /*
 168  * Function: `TTF_autohint`
 169  * ------------------------
 170  *
 171  * Read a TrueType font, remove existing bytecode (in the SFNT tables
 172  * `prep`, `fpgm`, `cvt `, and `glyf`), and write a new TrueType font with
 173  * new bytecode based on the autohinting of the FreeType library.
 174  *
 175  * It expects a format string *options* and a variable number of arguments,
 176  * depending on the fields in *options*.  The fields are comma separated;
 177  * whitespace within the format string is not significant, a trailing comma
 178  * is ignored.  Fields are parsed from left to right; if a field occurs
 179  * multiple times, the last field's argument wins.  The same is true for
 180  * fields which are mutually exclusive.  Depending on the field, zero or one
 181  * argument is expected.
 182  *
 183  * Note that fields marked as 'not implemented yet' are subject to change.
 184  *
 185  * `in-file`
 186  * :   A pointer of type `FILE*` to the data stream of the input font,
 187  *     opened for binary reading.  Mutually exclusive with `in-buffer`.
 188  *
 189  * `in-buffer`
 190  * :   A pointer of type `const char*` to a buffer which contains the input
 191  *     font.  Needs `in-buffer-len`.  Mutually exclusive with `in-file`.
 192  *
 193  * `in-buffer-len`
 194  * :   A value of type `size_t`, giving the length of the input buffer.
 195  *     Needs `in-buffer`.
 196  *
 197  * `out-file`
 198  * :   A pointer of type `FILE*` to the data stream of the output font,
 199  *     opened for binary writing.  Mutually exclusive with `out-buffer`.
 200  *
 201  * `out-buffer`
 202  * :   A pointer of type `char**` to a buffer which contains the output
 203  *     font.  Needs `out-buffer-len`.  Mutually exclusive with `out-file`.
 204  *     Deallocate the memory with `free`.
 205  *
 206  * `out-buffer-len`
 207  * :   A pointer of type `size_t*` to a value giving the length of the
 208  *     output buffer.  Needs `out-buffer`.
 209  *
 210  * `progress-callback`
 211  * :   A pointer of type [`TA_Progress_Func`](#callback-ta_progress_func),
 212  *     specifying a callback function for progress reports.  This function
 213  *     gets called after a single glyph has been processed.  If this field
 214  *     is not set or set to NULL, no progress callback function is used.
 215  *
 216  * `progress-callback-data`
 217  * :   A pointer of type `void*` to user data which is passed to the
 218  *     progress callback function.
 219  *
 220  * `error-string`
 221  * :   A pointer of type `unsigned char**` to a string (in UTF-8 encoding)
 222  *     which verbally describes the error code.  You must not change the
 223  *     returned value.
 224  *
 225  * `hinting-range-min`
 226  * :   An integer (which must be larger than or equal to\ 2) giving the
 227  *     lowest PPEM value used for autohinting.  If this field is not set, it
 228  *     defaults to `TA_HINTING_RANGE_MIN`.
 229  *
 230  * `hinting-range-max`
 231  * :   An integer (which must be larger than or equal to the value of
 232  *     `hinting-range-min`) giving the highest PPEM value used for
 233  *     autohinting.  If this field is not set, it defaults to
 234  *     `TA_HINTING_RANGE_MAX`.
 235  *
 236  * `hinting-limit`
 237  * :   An integer (which must be larger than or equal to the value of
 238  *     `hinting-range-max`) which gives the largest PPEM value at which
 239  *     hinting is applied.  For larger values, hinting is switched off.  If
 240  *     this field is not set, it defaults to `TA_HINTING_LIMIT`.  If it is
 241  *     set to\ 0, no hinting limit is added to the bytecode.
 242  *
 243  * `gray-strong-stem-width`
 244  * :   An integer (1\ for 'on' and 0\ for 'off', which is the default) which
 245  *     specifies whether horizontal stems should be snapped and positioned
 246  *     to integer pixel values for normal grayscale rendering.
 247  *
 248  * `gdi-cleartype-strong-stem-width`
 249  * :   An integer (1\ for 'on', which is the default, and 0\ for 'off') which
 250  *     specifies whether horizontal stems should be snapped and positioned
 251  *     to integer pixel values for GDI ClearType rendering, this is, the
 252  *     rasterizer version (as returned by the GETINFO bytecode instruction)
 253  *     is in the range 36\ <= version <\ 38 and ClearType is enabled.
 254  *
 255  * `dw-cleartype-strong-stem-width`
 256  * :   An integer (1\ for 'on' and 0\ for 'off', which is the default) which
 257  *     specifies whether horizontal stems should be snapped and positioned
 258  *     to integer pixel values for DW ClearType rendering, this is, the
 259  *     rasterizer version (as returned by the GETINFO bytecode instruction)
 260  *     is >=\ 38, ClearType is enabled, and subpixel positioning is enabled
 261  *     also.
 262  *
 263  * `increase-x-height`
 264  * :   An integer.  For PPEM values in the range 6\ <= PPEM
 265  *     <=\ `increase-x-height`, round up the font's x\ height much more often
 266  *     than normally.  If it is set to\ 0, this feature is switched off.  If
 267  *     this field is not set, it defaults to `TA_INCREASE_X_HEIGHT`.  Use
 268  *     this flag to improve the legibility of small font sizes if necessary.
 269  *
 270  * `hint-with-components`
 271  * :   If this integer is set to\ 1 (which is the default), ttfautohint
 272  *     handles composite glyphs as a whole.  This implies adding a special
 273  *     glyph to the font, as documented [here](#the-.ttfautohint-glyph).
 274  *     Setting it to\ 0, the components of composite glyphs are hinted
 275  *     separately.  While separate hinting of subglyphs makes the resulting
 276  *     bytecode much smaller, it might deliver worse results.  However, this
 277  *     depends on the processed font and must be checked by inspection.
 278  *
 279  * `pre-hinting`
 280  * :   An integer (1\ for 'on' and 0\ for 'off', which is the default) to
 281  *     specify whether native TrueType hinting shall be applied to all
 282  *     glyphs before passing them to the (internal) autohinter.  The used
 283  *     resolution is the em-size in font units; for most fonts this is
 284  *     2048ppem.  Use this if the hints move or scale subglyphs
 285  *     independently of the output resolution.
 286  *
 287  * `info-callback`
 288  * :   A pointer of type [`TA_Info_Func`](#callback-ta_info_func),
 289  *     specifying a callback function for manipulating the `name` table.
 290  *     This function gets called for each `name` table entry.  If not set or
 291  *     set to NULL, the table data stays unmodified.
 292  *
 293  * `info-callback-data`
 294  * :   A pointer of type `void*` to user data which is passed to the info
 295  *     callback function.
 296  *
 297  * `x-height-snapping-exceptions`
 298  * :   A pointer of type `const char*` to a null-terminated string which
 299  *     gives a list of comma separated PPEM values or value ranges at which
 300  *     no x-height snapping shall be applied.  A value range has the form
 301  *     *value1*`-`*value2*, meaning *value1* <= PPEM <= *value2*.
 302  *     Whitespace is not significant; a trailing comma is ignored.  If the
 303  *     supplied argument is NULL, no x-height snapping takes place at all.
 304  *     By default, there are no snapping exceptions.  Not implemented yet.
 305  *
 306  * `ignore-restrictions`
 307  * :   If the font has set bit\ 1 in the 'fsType' field of the `OS/2` table,
 308  *     the ttfautohint library refuses to process the font since a
 309  *     permission to do that is required from the font's legal owner.  In
 310  *     case you have such a permission you might set the integer argument to
 311  *     value\ 1 to make ttfautohint handle the font.  The default value
 312  *     is\ 0.
 313  *
 314  * `fallback-script`
 315  * :   An integer which specifies the default script for glyphs not in the
 316  *     'latin' range.  If set to\ 1, the 'latin' script is used (other
 317  *     scripts are not supported yet).  By default, no script is used
 318  *     (value\ 0; this disables autohinting for such glyphs).
 319  *
 320  * `symbol`
 321  * :   Set this integer to\ 1 if you want to process a font which lacks the
 322  *     characters of a supported script, for example, a symbol font.
 323  *     ttfautohint then uses default values for the standard stem width and
 324  *     height instead of deriving these values from a script's key character
 325  *     (for the latin script, it is character 'o').  The default value
 326  *     is\ 0.
 327  *
 328  * `debug`
 329  * :   If this integer is set to\ 1, lots of debugging information is print
 330  *     to stderr.  The default value is\ 0.
 331  *
 332  * Remarks:
 333  *
 334  *   * Obviously, it is necessary to have an input and an output data
 335  *     stream.  All other options are optional.
 336  *
 337  *   * `hinting-range-min` and `hinting-range-max` specify the range for
 338  *     which the autohinter generates optimized hinting code.  If a PPEM
 339  *     value is smaller than the value of `hinting-range-min`, hinting still
 340  *     takes place but the configuration created for `hinting-range-min` is
 341  *     used.  The analogous action is taken for `hinting-range-max`, only
 342  *     limited by the value given with `hinting-limit`.  The font's `gasp`
 343  *     table is set up to always use grayscale rendering with grid-fitting
 344  *     for standard hinting, and symmetric grid-fitting and symmetric
 345  *     smoothing for horizontal subpixel hinting (ClearType).
 346  *
 347  *   * ttfautohint can't process a font a second time (well, it can, if the
 348  *     font doesn't contain composite glyphs).  Just think of ttfautohint as
 349  *     being a compiler, a tool which also can't process its created output
 350  *     again.
 351  *
 352  * ```C
 353  */
 354
 355 TA_Error
 356 TTF_autohint(const char* options,
 357              ...);
 358
 359 /*
 360  * ```
 361  *
 362  */
 363
 364 /* pandoc-end */
 365
 366 #ifdef __cplusplus
 367 } /* extern "C" */
 368 #endif
 369
 370 #endif /* __TTFAUTOHINT_H__ */
 371
 372 /* end of ttfautohint.h */