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 /* Error type. */
  27
  28 typedef int TA_Error;
  29
  30
  31 /*
  32  * A callback function to get progress information.  `curr_idx' gives the
  33  * currently processed glyph index; if it is negative, an error has
  34  * occurred.  `num_glyphs' holds the total number of glyphs in the font
  35  * (this value can't be larger than 65535).
  36  *
  37  * `curr_sfnt' gives the current subfont within a TrueType Collection (TTC),
  38  * and `num_sfnts' the total number of subfonts.  Currently, the ttfautohint
  39  * library only hints glyphs from the `glyf' table used in subfont 0.
  40  *
  41  * If the return value is non-zero, `TTF_autohint' aborts with
  42  * `TA_Err_Canceled'.  Use this for a `Cancel' button or similar features in
  43  * interactive use.
  44  *
  45  * `progress_data' is a void pointer to user supplied data.
  46  */
  47
  48 typedef int
  49 (*TA_Progress_Func)(long curr_idx,
  50                     long num_glyphs,
  51                     long curr_sfnt,
  52                     long num_sfnts,
  53                     void* progress_data);
  54
  55
  56 /* Error values in addition to the FT_Err_XXX constants from FreeType. */
  57 /* All error values specific to ttfautohint start with `TA_Err_'. */
  58 #include <ttfautohint-errors.h>
  59
  60 /*
  61  * Read a TrueType font, remove existing bytecode (in the SFNT tables
  62  * `prep', `fpgm', `cvt ', and `glyf'), and write a new TrueType font with
  63  * new bytecode based on the autohinting of the FreeType library.
  64  *
  65  * It expects a format string `options' and a variable number of arguments,
  66  * depending on the fields in `options'.  The fields are comma separated;
  67  * whitespace within the format string is not significant, a trailing comma
  68  * is ignored.  Fields are parsed from left to right; if a field occurs
  69  * multiple times, the last field's argument wins.  The same is true for
  70  * fields which are mutually exclusive.  Depending on the field, zero or one
  71  * argument is expected.
  72  *
  73  * Note that fields marked as `not implemented yet' are subject to change.
  74  *
  75  *   in-file                      A pointer of type `FILE*' to the data
  76  *                                stream of the input font, opened for
  77  *                                binary reading.  Mutually exclusive with
  78  *                                `in-buffer'.
  79  *
  80  *   in-buffer                    A pointer of type `const char*' to a
  81  *                                buffer which contains the input font.
  82  *                                Needs `in-buffer-len'.  Mutually exclusive
  83  *                                with `in-file'.
  84  *
  85  *   in-buffer-len                A value of type `size_t', giving the
  86  *                                length of the input buffer.  Needs
  87  *                                `in-buffer'.
  88  *
  89  *   out-file                     A pointer of type `FILE*' to the data
  90  *                                stream of the output font, opened for
  91  *                                binary writing.  Mutually exclusive with
  92  *                                `out-buffer'.
  93  *
  94  *   out-buffer                   A pointer of type `char**' to a buffer
  95  *                                which contains the output font.  Needs
  96  *                                `out-buffer-len'.  Mutually exclusive with
  97  *                                `out-file'.  Deallocate the memory with
  98  *                                `free'.
  99  *
 100  *   out-buffer-len               A pointer of type `size_t*' to a value
 101  *                                giving the length of the output buffer.
 102  *                                Needs `out-buffer'.
 103  *
 104  *   progress-callback            A pointer of type `TA_Progress_Func',
 105  *                                specifying a callback function for
 106  *                                progress reports.  This function gets
 107  *                                called after a single glyph has been
 108  *                                processed.  If this field is not set, no
 109  *                                progress callback function is used.
 110  *
 111  *   progress-callback-data       A pointer of type `void*' to user data
 112  *                                which is passed to the progress callback
 113  *                                function.
 114  *
 115  *   error-string                 A pointer of type `unsigned char**' to a
 116  *                                string (in UTF-8 encoding) which verbally
 117  *                                describes the error code.  You must not
 118  *                                change the returned value.
 119  *
 120  *   hinting-range-min            An integer (which must be larger than or
 121  *                                equal to 2) giving the lowest ppem value
 122  *                                used for autohinting.  If this field is
 123  *                                not set, it defaults to value 8.
 124  *
 125  *   hinting-range-max            An integer (which must be larger than or
 126  *                                equal to the value of `hinting-range-min')
 127  *                                giving the highest ppem value used for
 128  *                                autohinting.  If this field is not set, it
 129  *                                defaults to value 1000.
 130  *
 131  *   pre-hinting                  An integer (1 for `on' and 0 for `off',
 132  *                                which is the default) to specify whether
 133  *                                native TrueType hinting shall be applied
 134  *                                to all glyphs before passing them to the
 135  *                                (internal) autohinter.  The used
 136  *                                resolution is the em-size in font units;
 137  *                                for most fonts this is 2048ppem.  Use this
 138  *                                if the hints move or scale subglyphs
 139  *                                independently of the output resolution.
 140  *                                Not implemented yet.
 141  *
 142  *   increase-x-height            An integer (1 for `on' and 0 for `off',
 143  *                                which is the default).  For PPEM values in
 144  *                                the range 5 < PPEM < 15, round up the
 145  *                                font's x height much more often than
 146  *                                normally if this flag is set.  Use this if
 147  *                                holes in letters like `e' get filled, for
 148  *                                example.
 149  *
 150  *   x-height-snapping-exceptions A pointer of type `const char*' to a
 151  *                                null-terminated string which gives a list
 152  *                                of comma separated ppem values or value
 153  *                                ranges at which no x-height snapping shall
 154  *                                be applied.  A value range has the form
 155  *                                `value1-value2', meaning `value1' <= ppem
 156  *                                <= `value2'.  Whitespace is not
 157  *                                significant; a trailing comma is ignored.
 158  *                                If the supplied argument is NULL, no
 159  *                                x-height snapping takes place at all.  By
 160  *                                default, there are no snapping exceptions.
 161  *                                Not implemented yet.
 162  *
 163  *   ignore-permissions           If the font has set bit 1 in the `fsType'
 164  *                                field of the `OS/2' table, the ttfautohint
 165  *                                library refuses to process the font since
 166  *                                a permission to do that is required from
 167  *                                the font's legal owner.  In case you have
 168  *                                such a permission you might set the
 169  *                                integer argument to value 1 to make
 170  *                                ttfautohint handle the font.
 171  *
 172  *   fallback-script              An integer which specifies the default
 173  *                                script for glyphs not in the `latin'
 174  *                                range.  If set to 1, the `latin' script is
 175  *                                used.  By default, no script is used
 176  *                                (value 0; this disables autohinting for
 177  *                                such glyphs).
 178  *
 179  * Remarks:
 180  *
 181  * o Obviously, it is necessary to have an input and an output data stream.
 182  *   All other options are optional.
 183  *
 184  * o `hinting-range-min' and `hinting-range-max' specify the range for which
 185  *   the autohinter generates optimized hinting code.  If a ppem is smaller
 186  *   than the value of `hinting-range-min', hinting still takes place but
 187  *   the configuration created for `hinting-range-min' is used.  The
 188  *   analogous action is taken for `hinting-range-max'.  The font's `gasp'
 189  *   table is set up to always use grayscale rendering with grid-fitting for
 190  *   standard hinting, and symmetric grid-fitting and symmetric smoothing
 191  *   for horizontal subpixel hinting (ClearType).
 192  */
 193
 194 TA_Error
 195 TTF_autohint(const char* options,
 196              ...);
 197
 198 #ifdef __cplusplus
 199 } /* extern "C" */
 200 #endif
 201
 202 #endif /* __TTFAUTOHINT_H__ */
 203
 204 /* end of ttfautohint.h */