Readme

   1 ttf2png - True Type Font to PNG converter
   2 Copyright (c) 2004-2021  Mikko Rasa, Mikkosoft Productions
   3
   4
   5 Software requirements
   6
   7 FreeType 2
   8 libpng 1.6
   9 C compiler (preferably GCC)
  10
  11
  12 Command-line options
  13
  14   -r <low>,<high>
  15     Range of code points to convert, specified as unicode code points.  The
  16     default is 0,255, matching the ISO-8859-1 (Latin-1) character set.  Code
  17     points can be specified as plain numbers, unicode code points (U+xxxx) or
  18     UTF-8 characters.  This option can be specified multiple times to add
  19     more ranges to be converted.
  20
  21   -s <pixels>
  22     Font size to use.  The default is 10 pixels.
  23
  24   -l <num>
  25     Number of glyphs to put in one line.  Defaults to autodetect.  Ignored
  26     if -p is used.
  27
  28   -c <pixels>[x<pixels>]
  29     Character cell size.  If only a single number is given, a square cell is
  30     used.  The special values auto and autorect may be used to choose an
  31     autodetected square or rectangle cell, respectively.  The default is auto.
  32     Ignored if -p is used.
  33
  34   -o <filename>
  35     Output file name.  Use - for stdout; the output is a png image, so it's
  36     best to pipe it somewhere.  The default is font.png.
  37
  38   -a
  39     Force autohinter.  By default native hinting is used if present in the
  40     font.
  41
  42   -t
  43     Render glyphs to alpha channel, with grey channel filled with white.  By
  44     default only the grey channel is used.
  45
  46   -i
  47     Invert colors of the glyphs.  When rendering to alpha channel, only the
  48     alpha channel is inverted.  The default is to render black glyphs on a
  49     white background.
  50
  51   -v
  52     Increase the level of verbosity.
  53
  54   -e
  55     Use cells in sequence, without leaving gaps.  By default the position of
  56     each glyph is determined by its code point.  Ignored if -p is used.
  57
  58   -p
  59     Pack the glyphs tightly in the image.  Small gaps are left between glyphs,
  60     controlled by the -n option.  By default glyphs are rendered in a regular
  61     grid.  Creating a definition file is recommended, as the resulting image
  62     can seem rather messy.
  63
  64   -m <pixels>
  65     Leave a margin around the edges of the generated image.  By default glyphs
  66     can touch the edges.  Only used with -p.
  67
  68   -n <pixels>
  69     Control the amount of padding between glyphs.  The default is 1 pixel.
  70     Only used with -p.
  71
  72   -g
  73     Allow the resulting image to have a non-power-of-two size.  By default the
  74     image size is rounded up to a power of two for maximum compatibility.
  75
  76   -f <num>
  77     Generate a distance field texture.  The argument controls the amount of
  78     oversampling when calculating distances.  Larger values may produce more
  79     accurate results but take longer to process.  Distance fields are always
  80     stored without alpha and with large/positive values indicating the inside
  81     of glyphs; the -t and -i options are ignored.
  82
  83   -b <pixels>
  84     Set the border zone width for distance field.  The default is the square
  85     root of the font size.
  86
  87   -d
  88     File name to write glyph definitions.  See the section below for details.
  89
  90   -h
  91     Print a help message with option summary.
  92
  93
  94 Glyph definition files
  95
  96 Rendering a proportional font correctly requires some positioning and spacing
  97 information, called font metrics.  To that end, ttf2png can write a definition
  98 file alongside the image.
  99
 100 The basic format is line-based.  Empty lines, or those starting with a hash
 101 sign (#), should be ignored.  Data lines consist of a keyword followed by
 102 space-separated fields.
 103
 104 The keyword "font" is followed by five fields with overall information about
 105 the image and the font:
 106
 107   Fields 1-2: width and height of the image
 108   Field 3: nominal size of the font
 109   Fields 4-5: ascent and descent of the font
 110
 111 The keyword "code" is followed by two fields establishing a code point to
 112 glyph mapping:
 113
 114   Field 1: Unicode code point
 115   Field 2: Glyph index
 116
 117 The keyword "metrics" is followed by six fields describing the metrics of a
 118 glyph:
 119
 120   Field 1: the index of the glyph
 121   Fields 2-3: width and height of the glyph
 122   Fields 4-5: x and y offset of the glyph from its base point
 123   Field 6: advance from this glyph to the next
 124
 125 The following ASCII art image illustrates the basic metrics.  The character
 126 box is a conceptual rectangle in which most of the glyphs in the font fit.
 127 Some fonts may contain glyphs that extend outside of the nominal character
 128 box.
 129
 130                 - - - - - - - -     ^
 131                | character box |    |
 132                                     |
 133                |               |    |
 134                    o-------o        | ascent
 135                |   |       |   |    |
 136                    | glyph |        |
 137                |   |       |   |    |
 138     base point     |       |        |
 139              \ |   |       |   |    |
 140               \    |       |        |
 141            _ __x___|_______|___|____|__ baseline
 142   y_offset |       |       |        |
 143            v   |   o-------o   |    | descent
 144                 - - - - - - - -     v
 145
 146                |--->
 147                x_offset
 148
 149                |--------------->
 150                advance
 151
 152 The keyword "glyph" is followed by six field describing the area of the image
 153 used for the glyph:
 154
 155   Field 1: the index of the glyph
 156   Fields 2-3: x and y position of the glyph in the image
 157   Fields 4-5: width and height of the glyph
 158   Field 6: border zone included in the image
 159
 160 The border zone is used with distance field textures to allow the distance
 161 field to extend past the actual glyph.  If a glyph has a border, the origin
 162 point in the metrics refers to the glyph's lower left corner.  Subtract the
 163 border width from both coordinates to obtain the correct rendering position
 164 for the image.
 165
 166 The keyword "kern" is followed by three fields describing kerning between two
 167 glyphs:
 168
 169   Field 1: the index of the left-hand glyph
 170   Field 2: the index of the right-hand glyph
 171   Field 3: kerning distance between the glyphs
 172
 173
 174 Changelog
 175
 176 2.0 "The release I forgot to make three years ago"
 177 - Alternate ways of specifying code point ranges
 178 - Multiple code point ranges can be specified
 179 - Option to generate non-power-of-two images
 180 - Support for distance field generation
 181
 182 1.1
 183 - Controllable margin and padding in packed mode
 184 - Do not generate overly large images in sequential grid mode
 185
 186 1.0
 187 - Improve the packing algorithm
 188 - Non-square cells for grid mode
 189 - Option to invert colors
 190 - Include kerning information in definition file
 191
 192 0.3
 193 - Restructure the code
 194 - Add tight packing mode
 195 - Autodetect cell size and chars-per-line in grid mode
 196
 197 0.2.2
 198 - Write both X and Y offsets of glyphs to the definition file
 199 - Output font ascent and descent to definition file
 200
 201 0.2.1
 202 - Don't create too large image with sequential mode if the range is sparse
 203
 204 0.2
 205 - Added output to stdout
 206 - Clean up code a bit
 207 - Added sequential mode
 208 - Added definition file writing
 209
 210 0.1.1
 211 - Added more verbosity
 212 - Added transparency mode
 213
 214 0.1
 215 - Initial release
 216
 217
 218 License
 219
 220 This program is free software; you can redistribute it and/or
 221 modify it under the terms of the GNU General Public License
 222 as published by the Free Software Foundation; either version 2
 223 of the License, or (at your option) any later version.
 224
 225 This program is distributed in the hope that it will be useful,
 226 but WITHOUT ANY WARRANTY; without even the implied warranty of
 227 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 228 GNU General Public License for more details.
 229
 230 You should have received a copy of the GNU General Public License
 231 along with this program; if not, write to the Free Software
 232 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.