X-Git-Url: http://git.tdb.fi/?p=ttf2png.git;a=blobdiff_plain;f=Readme;h=436e6b35bec11b399be80500296c602c3b069f72;hp=c387b106f9c4ac853e2738640a3df234394cf4bc;hb=HEAD;hpb=78feedfca690b08a94736b9ca1a2bd36964a6f01 diff --git a/Readme b/Readme index c387b10..8a54d01 100644 --- a/Readme +++ b/Readme @@ -1,15 +1,205 @@ ttf2png - True Type Font to PNG converter -Copyright (c) 2004 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 , + 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 + Font size to use. The default is 10 pixels. + + -l + Number of glyphs to put in one line. Defaults to autodetect. Ignored + if -p is used. + + -c [x] + 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 + 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 + Leave a margin around the edges of the generated image. By default glyphs + can touch the edges. Only used with -p. + + -n + 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 + 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 + 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 +- Output font ascent and descent to definition file + +0.2.1 +- Don't create too large image with sequential mode if the range is sparse 0.2 - Added output to stdout