src/ttfautohint.h

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