src/ttfautohint.h

   1 /* ttfautohint.h */
   2
   3 /* written 2011 by Werner Lemberg <wl@gnu.org> */
   4
   5 #ifndef __TTFAUTOHINT_H__
   6 #define __TTFAUTOHINT_H__
   7
   8 #include <stdarg.h>
   9
  10
  11 /* Error type. */
  12
  13 typedef int TA_Error;
  14
  15
  16 /*
  17  * A callback function to get progress information.  `curr_idx' gives the
  18  * currently processed glyph index; if it is negative, an error has
  19  * occurred.  `num_glyphs' holds the total number of glyphs in the font
  20  * (this value can't be larger than 65535).
  21  *
  22  * `curr_sfnt' gives the current subfont within a TrueType Collection (TTC),
  23  * and `num_sfnts' the total number of subfonts.  Currently, the ttfautohint
  24  * library only hints glyphs from the `glyf' table used in subfont 0.
  25  *
  26  * `progress_data' is a void pointer to user supplied data.
  27  */
  28
  29 typedef void
  30 (*TA_Progress_Func)(long curr_idx,
  31                     long num_glyphs,
  32                     long curr_sfnt,
  33                     long num_sfnts,
  34                     void *progress_data);
  35
  36
  37 /* Error values in addition to the FT_Err_XXX constants from FreeType. */
  38
  39 #define TA_Err_Ok 0x00
  40 #define TA_Err_Invalid_Stream_Write 0x5F
  41 #define TA_Err_Hinter_Overflow 0xF0
  42
  43
  44 /*
  45  * Read a TrueType font, remove existing bytecode (in the SFNT tables
  46  * `prep', `fpgm', `cvt ', and `glyf'), and write a new TrueType font with
  47  * new bytecode based on the autohinting of the FreeType library.
  48  *
  49  * It expects a format string `options' and a variable number of arguments,
  50  * depending on the fields in `options'.  The fields are comma separated;
  51  * whitespace within the format string is not significant, a trailing comma
  52  * is ignored.  Fields are parsed from left to right; if a field occurs
  53  * multiple times, the last field's argument wins.  Depending on the field,
  54  * zero or one argument is expected.
  55  *
  56  * Note that fields marked as `not implemented yet' are subject to change.
  57  *
  58  *   in-file                      A pointer of type `FILE*' to the data
  59  *                                stream of the input font, opened for
  60  *                                binary reading.
  61  *
  62  *   in-buffer                    A pointer of type `const char*' to a
  63  *                                buffer which contains the input font.
  64  *                                Needs `in-buffer-len'.
  65  *
  66  *   in-buffer-len                A value of type `size_t', giving the
  67  *                                length of the input buffer.  Needs
  68  *                                `in-buffer'.
  69  *
  70  *   out-file                     A pointer of type `FILE*' to the data
  71  *                                stream of the output font, opened for
  72  *                                binary writing.
  73  *
  74  *   out-buffer                   A pointer of type `char**' to a buffer
  75  *                                which contains the output font.  Needs
  76  *                                `out-buffer-len'.  Deallocate the memory
  77  *                                with `free'.
  78  *
  79  *   out-buffer-len               A pointer of type `size_t*' to a value
  80  *                                giving the length of the output buffer.
  81  *                                Needs `out-buffer'.
  82  *
  83  *   progress-callback            A pointer of type `TA_Progress_Func',
  84  *                                specifying a callback function for
  85  *                                progress reports.  This function gets
  86  *                                called after a single glyph has been
  87  *                                processed.  If this field is not set, no
  88  *                                progress callback function is used.  Not
  89  *                                implemented yet.
  90  *
  91  *   progress-callback-data       A pointer of type `void*' to user data
  92  *                                which is passed to the progress callback
  93  *                                function.
  94  *
  95  *   hinting-range-min            An integer (which must be larger than or
  96  *                                equal to 2) giving the lowest ppem value
  97  *                                used for autohinting.  If this field is
  98  *                                not set, it defaults to value 8.
  99  *
 100  *   hinting-range-max            An integer (which must be larger than or
 101  *                                equal to the value of `hinting-range-min')
 102  *                                giving the highest ppem value used for
 103  *                                autohinting.  If this field is not set, it
 104  *                                defaults to value 1000.
 105  *
 106  *   pre-hinting                  Apply native TrueType hinting to all
 107  *                                glyphs before passing them to the
 108  *                                (internal) autohinter.  The used
 109  *                                resolution is the em-size in font units;
 110  *                                for most fonts this is 2048ppem.  Use this
 111  *                                if the hints move or scale subglyphs
 112  *                                independently of the output resolution.
 113  *                                This field has no argument.  Not
 114  *                                implemented yet.
 115  *
 116  *   x-height-snapping-exceptions A pointer of type `const char*' to a
 117  *                                null-terminated string which gives a list
 118  *                                of comma separated ppem values or value
 119  *                                ranges at which no x-height snapping shall
 120  *                                be applied.  A value range has the form
 121  *                                `value1-value2', meaning `value1' <= ppem
 122  *                                <= `value2'.  Whitespace is not
 123  *                                significant; a trailing comma is ignored.
 124  *                                If the supplied argument is NULL, no
 125  *                                x-height snapping takes place at all.  By
 126  *                                default, there are no snapping exceptions.
 127  *                                Not implemented yet.
 128  *
 129  *   ignore-permissions           If the font has set bit 1 in the `fsType'
 130  *                                field of the `OS/2' table, the ttfautohint
 131  *                                library refuses to process the font since
 132  *                                a permission to do that is required from
 133  *                                the font's legal owner.  In case you have
 134  *                                such a permission you might set this
 135  *                                option to make ttfautohint handle the
 136  *                                font.  This field has no argument.  Not
 137  *                                implemented yet.
 138  *
 139  *   latin-fallback               Use the `latin' autohinting module as a
 140  *                                fallback for glyphs not in the `latin'
 141  *                                range.  This field has no argument.  By
 142  *                                default, the `dummy' fallback module is
 143  *                                used.  Not implemented yet.
 144  *
 145  * Remarks:
 146  *
 147  * o Obviously, it is necessary to have an input and an output data stream.
 148  *   All other options are optional.
 149  *
 150  * o `hinting-range-min' and `hinting-range-max' specify the range for which
 151  *   the autohinter generates optimized hinting code.  If a ppem is smaller
 152  *   than the value of `hinting-range-min', hinting still takes place but
 153  *   the configuration created for `hinting-range-min' is used.  The
 154  *   analogous action is taken for `hinting-range-max'.  The font's `gasp'
 155  *   table is set up to always use grayscale rendering with grid-fitting for
 156  *   standard hinting, and symmetric grid-fitting and symmetric smoothing
 157  *   for horizontal subpixel hinting (ClearType).
 158  */
 159
 160 TA_Error
 161 TTF_autohint(const char* options,
 162              ...);
 163
 164 #endif /* __TTFAUTOHINT_H__ */
 165
 166 /* end of ttfautohint.h */