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