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