ttf2png - True Type Font to PNG converter
-Copyright (c) 2004-2007 Mikko Rasa, Mikkosoft Productions
+Copyright (c) 2004-2021 Mikko Rasa, Mikkosoft Productions
Software requirements
FreeType 2
-libpng 1.2
+libpng 1.6
C compiler (preferably GCC)
-Changes
+Command-line options
+
+ -r <low>,<high>
+ Range of code points to convert, specified as unicode code points. The
+ default is 0,255, matching the ISO-8859-1 (Latin-1) character set. Code
+ points can be specified as plain numbers, unicode code points (U+xxxx) or
+ UTF-8 characters. This option can be specified multiple times to add
+ more ranges to be converted.
+
+ -s <pixels>
+ Font size to use. The default is 10 pixels.
+
+ -l <num>
+ Number of glyphs to put in one line. Defaults to autodetect. Ignored
+ if -p is used.
+
+ -c <pixels>[x<pixels>]
+ Character cell size. If only a single number is given, a square cell is
+ used. The special values auto and autorect may be used to choose an
+ autodetected square or rectangle cell, respectively. The default is auto.
+ Ignored if -p is used.
+
+ -o <filename>
+ Output file name. Use - for stdout; the output is a png image, so it's
+ best to pipe it somewhere. The default is font.png.
+
+ -a
+ Force autohinter. By default native hinting is used if present in the
+ font.
+
+ -t
+ Render glyphs to alpha channel, with grey channel filled with white. By
+ default only the grey channel is used.
+
+ -i
+ Invert colors of the glyphs. When rendering to alpha channel, only the
+ alpha channel is inverted. The default is to render black glyphs on a
+ white background.
+
+ -v
+ Increase the level of verbosity.
+
+ -e
+ Use cells in sequence, without leaving gaps. By default the position of
+ each glyph is determined by its code point. Ignored if -p is used.
+
+ -p
+ Pack the glyphs tightly in the image. Small gaps are left between glyphs,
+ controlled by the -n option. By default glyphs are rendered in a regular
+ grid. Creating a definition file is recommended, as the resulting image
+ can seem rather messy.
+
+ -m <pixels>
+ Leave a margin around the edges of the generated image. By default glyphs
+ can touch the edges. Only used with -p.
+
+ -n <pixels>
+ Control the amount of padding between glyphs. The default is 1 pixel.
+ Only used with -p.
+
+ -g
+ Allow the resulting image to have a non-power-of-two size. By default the
+ image size is rounded up to a power of two for maximum compatibility.
+
+ -f <num>
+ Generate a distance field texture. The argument controls the amount of
+ oversampling when calculating distances. Larger values may produce more
+ accurate results but take longer to process. Distance fields are always
+ stored without alpha and with large/positive values indicating the inside
+ of glyphs; the -t and -i options are ignored.
+
+ -b <pixels>
+ Set the border zone width for distance field. The default is the square
+ root of the font size.
+
+ -d
+ File name to write glyph definitions. See the section below for details.
+
+ -h
+ Print a help message with option summary.
+
+
+Glyph definition files
+
+Rendering a proportional font correctly requires some positioning and spacing
+information, called font metrics. To that end, ttf2png can write a definition
+file alongside the image.
+
+The basic format is line-based. Empty lines, or those starting with a hash
+sign (#), should be ignored. Data lines consist of a keyword followed by
+space-separated fields.
+
+The keyword "font" is followed by five fields with overall information about
+the image and the font:
+
+ Fields 1-2: width and height of the image
+ Field 3: nominal size of the font
+ Fields 4-5: ascent and descent of the font
+
+The keyword "code" is followed by two fields establishing a code point to
+glyph mapping:
+
+ Field 1: Unicode code point
+ Field 2: Glyph index
+
+The keyword "metrics" is followed by six fields describing the metrics of a
+glyph:
+
+ Field 1: the index of the glyph
+ Fields 2-3: width and height of the glyph
+ Fields 4-5: x and y offset of the glyph from its base point
+ Field 6: advance from this glyph to the next
+
+The following ASCII art image illustrates the basic metrics. The character
+box is a conceptual rectangle in which most of the glyphs in the font fit.
+Some fonts may contain glyphs that extend outside of the nominal character
+box.
+
+ - - - - - - - - ^
+ | character box | |
+ |
+ | | |
+ o-------o | ascent
+ | | | | |
+ | glyph | |
+ | | | | |
+ base point | | |
+ \ | | | | |
+ \ | | |
+ _ __x___|_______|___|____|__ baseline
+ y_offset | | | |
+ v | o-------o | | descent
+ - - - - - - - - v
+
+ |--->
+ x_offset
+
+ |--------------->
+ advance
+
+The keyword "glyph" is followed by six field describing the area of the image
+used for the glyph:
+
+ Field 1: the index of the glyph
+ Fields 2-3: x and y position of the glyph in the image
+ Fields 4-5: width and height of the glyph
+ Field 6: border zone included in the image
+
+The border zone is used with distance field textures to allow the distance
+field to extend past the actual glyph. If a glyph has a border, the origin
+point in the metrics refers to the glyph's lower left corner. Subtract the
+border width from both coordinates to obtain the correct rendering position
+for the image.
+
+The keyword "kern" is followed by three fields describing kerning between two
+glyphs:
+
+ Field 1: the index of the left-hand glyph
+ Field 2: the index of the right-hand glyph
+ Field 3: kerning distance between the glyphs
+
+
+Changelog
+
+2.0 "The release I forgot to make three years ago"
+- Alternate ways of specifying code point ranges
+- Multiple code point ranges can be specified
+- Option to generate non-power-of-two images
+- Support for distance field generation
+
+1.1
+- Controllable margin and padding in packed mode
+- Do not generate overly large images in sequential grid mode
+
+1.0
+- Improve the packing algorithm
+- Non-square cells for grid mode
+- Option to invert colors
+- Include kerning information in definition file
+
+0.3
+- Restructure the code
+- Add tight packing mode
+- Autodetect cell size and chars-per-line in grid mode
0.2.2
- Write both X and Y offsets of glyphs to the definition file
projects / ttf2png.git / blobdiff