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 /* Some default values. */
  27
  28 #define TA_HINTING_RANGE_MIN 8
  29 #define TA_HINTING_RANGE_MAX 1000
  30 #define TA_HINTING_LIMIT 1000
  31
  32 /* Error type. */
  33
  34 typedef int TA_Error;
  35
  36
  37 /*
  38  * A callback function to get progress information.  `curr_idx' gives the
  39  * currently processed glyph index; if it is negative, an error has
  40  * occurred.  `num_glyphs' holds the total number of glyphs in the font
  41  * (this value can't be larger than 65535).
  42  *
  43  * `curr_sfnt' gives the current subfont within a TrueType Collection (TTC),
  44  * and `num_sfnts' the total number of subfonts.  Currently, the ttfautohint
  45  * library only hints glyphs from the `glyf' table used in subfont 0.
  46  *
  47  * If the return value is non-zero, `TTF_autohint' aborts with
  48  * `TA_Err_Canceled'.  Use this for a `Cancel' button or similar features in
  49  * interactive use.
  50  *
  51  * `progress_data' is a void pointer to user supplied data.
  52  */
  53
  54 typedef int
  55 (*TA_Progress_Func)(long curr_idx,
  56                     long num_glyphs,
  57                     long curr_sfnt,
  58                     long num_sfnts,
  59                     void* progress_data);
  60
  61
  62 /*
  63  * A callback function to manipulate strings in the `name' table.
  64  * `platform_id', `encoding_id', `language_id', and `name_id' are the
  65  * identifiers of a name table entry pointed to by `str' with a length
  66  * pointed to by `str_len' (in bytes; the string has no trailing NULL byte).
  67  * Please refer to the OpenType specification for a detailed description of
  68  * the various parameters, in particular which encoding is used for a given
  69  * platform and encoding ID.
  70  *
  71  *   http://www.microsoft.com/typography/otspec/name.htm
  72  *
  73  * `str' is allocated with `malloc'; the application should reallocate the
  74  * data if necessary, ensuring that the string length doesn't exceed 0xFFFF.
  75  *
  76  * `info_data' is a void pointer to user supplied data.
  77  *
  78  * If an error occurs, return a non-zero value and don't modify `str' and
  79  * `str_len' (such errors are handled as non-fatal).
  80  */
  81
  82 typedef int
  83 (*TA_Info_Func)(unsigned short platform_id,
  84                 unsigned short encoding_id,
  85                 unsigned short language_id,
  86                 unsigned short name_id,
  87                 unsigned short* str_len,
  88                 unsigned char** str,
  89                 void* info_data);
  90
  91
  92 /*
  93  * Error values in addition to the FT_Err_XXX constants from FreeType.
  94  *
  95  * All error values specific to ttfautohint start with `TA_Err_'.
  96  */
  97 #include <ttfautohint-errors.h>
  98
  99 /*
 100  * Read a TrueType font, remove existing bytecode (in the SFNT tables
 101  * `prep', `fpgm', `cvt ', and `glyf'), and write a new TrueType font with
 102  * new bytecode based on the autohinting of the FreeType library.
 103  *
 104  * It expects a format string `options' and a variable number of arguments,
 105  * depending on the fields in `options'.  The fields are comma separated;
 106  * whitespace within the format string is not significant, a trailing comma
 107  * is ignored.  Fields are parsed from left to right; if a field occurs
 108  * multiple times, the last field's argument wins.  The same is true for
 109  * fields which are mutually exclusive.  Depending on the field, zero or one
 110  * argument is expected.
 111  *
 112  * Note that fields marked as `not implemented yet' are subject to change.
 113  *
 114  *   in-file
 115  *     A pointer of type `FILE*' to the data stream of the input font,
 116  *     opened for binary reading.  Mutually exclusive with `in-buffer'.
 117  *
 118  *   in-buffer
 119  *     A pointer of type `const char*' to a buffer which contains the input
 120  *     font.  Needs `in-buffer-len'.  Mutually exclusive with `in-file'.
 121  *
 122  *   in-buffer-len
 123  *     A value of type `size_t', giving the length of the input buffer.
 124  *     Needs `in-buffer'.
 125  *
 126  *   out-file
 127  *      A pointer of type `FILE*' to the data stream of the output font,
 128  *      opened for binary writing.  Mutually exclusive with `out-buffer'.
 129  *
 130  *   out-buffer
 131  *     A pointer of type `char**' to a buffer which contains the output
 132  *     font.  Needs `out-buffer-len'.  Mutually exclusive with `out-file'.
 133  *     Deallocate the memory with `free'.
 134  *
 135  *   out-buffer-len
 136  *     A pointer of type `size_t*' to a value giving the length of the
 137  *     output buffer.  Needs `out-buffer'.
 138  *
 139  *   progress-callback
 140  *     A pointer of type `TA_Progress_Func', specifying a callback function
 141  *     for progress reports.  This function gets called after a single glyph
 142  *     has been processed.  If this field is not set or set to NULL, no
 143  *     progress callback function is used.
 144  *
 145  *   progress-callback-data
 146  *     A pointer of type `void*' to user data which is passed to the
 147  *     progress callback function.
 148  *
 149  *   error-string
 150  *     A pointer of type `unsigned char**' to a string (in UTF-8 encoding)
 151  *     which verbally describes the error code.  You must not change the
 152  *     returned value.
 153  *
 154  *   hinting-range-min
 155  *     An integer (which must be larger than or equal to 2) giving the
 156  *     lowest PPEM value used for autohinting.  If this field is not set, it
 157  *     defaults to TA_HINTING_RANGE_MIN.
 158  *
 159  *   hinting-range-max
 160  *     An integer (which must be larger than or equal to the value of
 161  *     `hinting-range-min') giving the highest PPEM value used for
 162  *     autohinting.  If this field is not set, it defaults to
 163  *     TA_HINTING_RANGE_MAX.
 164  *
 165  *   hinting-limit
 166  *     An integer (which must be larger than or equal to the value of
 167  *     `hinting-range-max') which gives the largest PPEM value at which
 168  *     hinting is applied.  For larger values, hinting is switched off.  If
 169  *     this field is not set, it defaults to TA_HINTING_LIMIT.  If it is set
 170  *     to 0, no hinting limit is added to the bytecode.
 171  *
 172  *   pre-hinting
 173  *     An integer (1 for `on' and 0 for `off', which is the default) to
 174  *     specify whether native TrueType hinting shall be applied to all
 175  *     glyphs before passing them to the (internal) autohinter.  The used
 176  *     resolution is the em-size in font units; for most fonts this is
 177  *     2048ppem.  Use this if the hints move or scale subglyphs
 178  *     independently of the output resolution.
 179  *
 180  *   info-callback
 181  *     A pointer of type `TA_Info_Func', specifying a callback function for
 182  *     manipulating the `name' table.  This function gets called for each
 183  *     name table entry.  If not set or set to NULL, the table data stays
 184  *     unmodified.
 185  *
 186  *   info-callback-data
 187  *     A pointer of type `void*' to user data which is passed to the info
 188  *     callback function.
 189  *
 190  *   increase-x-height
 191  *     An integer (1 for `on' and 0 for `off', which is the default).  For
 192  *     PPEM values in the range 5 < PPEM < 15, round up the font's x height
 193  *     much more often than normally if this flag is set.  Use this if holes
 194  *     in letters like `e' get filled, for example.
 195  *
 196  *   x-height-snapping-exceptions
 197  *     A pointer of type `const char*' to a null-terminated string which
 198  *     gives a list of comma separated PPEM values or value ranges at which
 199  *     no x-height snapping shall be applied.  A value range has the form
 200  *     `value1-value2', meaning `value1' <= PPEM <= `value2'.  Whitespace is
 201  *     not significant; a trailing comma is ignored.  If the supplied
 202  *     argument is NULL, no x-height snapping takes place at all.  By
 203  *     default, there are no snapping exceptions.  Not implemented yet.
 204  *
 205  *   ignore-permissions
 206  *     If the font has set bit 1 in the `fsType' field of the `OS/2' table,
 207  *     the ttfautohint library refuses to process the font since a
 208  *     permission to do that is required from the font's legal owner.  In
 209  *     case you have such a permission you might set the integer argument to
 210  *     value 1 to make ttfautohint handle the font.  The default value is 0.
 211  *
 212  *   fallback-script
 213  *     An integer which specifies the default script for glyphs not in the
 214  *     `latin' range.  If set to 1, the `latin' script is used (other
 215  *     scripts are not supported yet).  By default, no script is used (value
 216  *     0; this disables autohinting for such glyphs).
 217  *
 218  *   symbol
 219  *     Set this integer to 1 if you want to process a font which lacks the
 220  *     characters of a supported script, for example, a symbol font.
 221  *     ttfautohint then uses default values for the standard stem width and
 222  *     height instead of deriving these values from a script's key character
 223  *     (for the latin script, it is character `o').  The default value is 0.
 224  *
 225  * Remarks:
 226  *
 227  * o Obviously, it is necessary to have an input and an output data stream.
 228  *   All other options are optional.
 229  *
 230  * o `hinting-range-min' and `hinting-range-max' specify the range for which
 231  *   the autohinter generates optimized hinting code.  If a PPEM value is
 232  *   smaller than the value of `hinting-range-min', hinting still takes
 233  *   place but the configuration created for `hinting-range-min' is used.
 234  *   The analogous action is taken for `hinting-range-max', only limited by
 235  *   the value given with `hinting-limit'.  The font's `gasp' table is set
 236  *   up to always use grayscale rendering with grid-fitting for standard
 237  *   hinting, and symmetric grid-fitting and symmetric smoothing for
 238  *   horizontal subpixel hinting (ClearType).
 239  *
 240  * o ttfautohint can't process a font a second time (well, it can, if the
 241  *   font doesn't contain composite glyphs).  Just think of ttfautohint as
 242  *   being a compiler, a tool which also can't process its created output
 243  *   again.
 244  */
 245
 246 TA_Error
 247 TTF_autohint(const char* options,
 248              ...);
 249
 250 #ifdef __cplusplus
 251 } /* extern "C" */
 252 #endif
 253
 254 #endif /* __TTFAUTOHINT_H__ */
 255
 256 /* end of ttfautohint.h */