Better documentation

diff --git a/Readme b/Readme
index ff8542898c64d00514bc85921c347987cfd8841e..b8abf114e3ad83d4b8ac4110057b45a764ddc5e3 100644 (file)
--- a/Readme
+++ b/Readme
@@ -9,7 +9,117 @@ libpng 1.2
 C compiler (preferably GCC)
 
 
-Changes
+Command-line options
+
+  -r <low>,<high>
+    Range of characters to convert, specified as unicode code points.  The
+    default is 0,255, matching the ISO-8859-1 (Latin-1) character set.
+
+  -s <pixels>
+    Font size to use.  The default is 10 pixels.
+
+  -l <num>
+    Number of characters to put in one line.  Defaults to autodetect.  Ignored
+    if -p is used.
+
+  -c <pixels>
+    Character cell size.  The special values auto and autorect may be used to
+    choose an autodetected square or rectangle cell, respectively.  Defaults to
+    autodetected square.  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.
+
+  -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.  One-pixel gaps are left between
+    glyphs.  By default glyphs are rendered in a regular grid.  Creating a
+    definition file is recommended, as the resulting image can seem rather
+    messy.
+
+  -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 fields separated with
+spaces.
+
+The first data line contains 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
+
+Subsequent data lines each describe a single glyph and contain eight fields:
+
+  Field 1: the code point 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
+  Fields 6-7: x and y offset of the glyph from its base point
+  Field 8: advance from this glyph to the next
+
+The following ASCII art image illustrates most of these metrics.  Note that in
+some fonts, not all of the glyphs fit completely inside the character box.
+
+                - - - - - - - -     ^
+               | character box |    |
+                                    |
+               |               |    |
+                   o-------o        | ascent
+               |   |       |   |    |
+                   | glyph |        |
+               |   |       |   |    |
+    base point     |       |        |
+             \ |   |       |   |    |
+              \    |       |        |
+           _ __x___|_______|___|____|__ baseline
+  y_offset |       |       |        |
+           v   |   o-------o   |    | descent
+                - - - - - - - -     v
+           
+               |--->
+               x_offset
+
+               |--------------->
+               advance
+
+
+Changelog
+
+next
+- Improve the packing algorithm
+- Non-square cells for grid mode
+- Option to invert colors
 
 0.3
 - Restructure the code

diff --git a/ttf2png.c b/ttf2png.c
index 3685b5a106d9e3f9641051b13df4dfaa8ac5aeb1..b8f48a816c712612049dd21b0ee2b41fc3e83c16 100644 (file)
--- a/ttf2png.c
+++ b/ttf2png.c
@@ -267,18 +267,18 @@ void usage()
                "Distributed under the GNU General Public License\n\n"
                "Usage: ttf2png [options] <TTF file>\n\n"
                "Accepted options (default values in [brackets])\n"
-               "  -r  Range of characters to convert in the format low,high [0,255]\n"
+               "  -r  Range of characters to convert [0,255]\n"
                "  -s  Font size to use, in pixels [10]\n"
                "  -l  Number of characters to put in one line [auto]\n"
                "  -c  Character cell size, in pixels [auto]\n"
                "  -o  Output file name (or - for stdout) [font.png]\n"
                "  -a  Force autohinter\n"
-               "  -t  Render font to alpha channel\n"
+               "  -t  Render glyphs to alpha channel\n"
                "  -i  Invert colors of the glyphs\n"
                "  -v  Increase the level of verbosity\n"
-               "  -e  Use cells in sequence, rather than by code\n"
+               "  -e  Use cells in sequence, without gaps\n"
                "  -p  Pack the glyphs tightly instead of in a grid\n"
-               "  -d  Write a definition to the given file\n"
+               "  -d  File name for writing glyph definitions\n"
                "  -h  Print this message\n");
 }
 
@@ -339,6 +339,9 @@ void init_font(Font *font, FT_Face face, unsigned first, unsigned last, int auto
                glyph->offset_y = face->glyph->bitmap_top-bmp->rows;
                glyph->advance = (int)(face->glyph->advance.x+32)/64;
 
+               /* Copy the glyph image since FreeType uses a global buffer, which would
+               be overwritten by the next glyph.  Negative pitch means the scanlines
+               start from the bottom */
                if(bmp->pitch<0)
                {
                        for(y=0; y<bmp->rows; ++y) for(x=0; x<bmp->width; ++x)
@@ -362,6 +365,7 @@ void render_grid(Font *font, unsigned cellw, unsigned cellh, unsigned cpl, int s
        unsigned first, last;
        unsigned maxw = 0, maxh = 0;
 
+       /* Find extremes of the glyph images. */
        for(i=0; i<font->n_glyphs; ++i)
        {
                int y;
@@ -379,6 +383,7 @@ void render_grid(Font *font, unsigned cellw, unsigned cellh, unsigned cpl, int s
 
        if(cellw==0)
        {
+               /* Establish a large enough cell to hold all glyphs in the range. */
                int square = (cellh==cellw);
                cellw = maxw;
                cellh = top-bot;
@@ -402,6 +407,8 @@ void render_grid(Font *font, unsigned cellw, unsigned cellh, unsigned cpl, int s
 
        if(cpl==0)
        {
+               /* Determine number of characters per line, trying to fit all the glyphs
+               in a square image. */
                for(i=1;; i<<=1)
                {
                        cpl = i/cellw;
@@ -462,9 +469,12 @@ void render_packed(Font *font)
        unsigned cx = 0, cy;
        unsigned used_h = 0;
 
+       /* Compute the total area occupied by glyphs and padding. */
        for(i=0; i<font->n_glyphs; ++i)
                area += (font->glyphs[i].image.w+1)*(font->glyphs[i].image.h+1);
 
+       /* Find an image size that's no higher than wide, allowing for some
+       imperfections in the packing. */
        for(font->image.w=1;; font->image.w<<=1)
        {
                font->image.h = (area*5/4)/font->image.w;
@@ -473,6 +483,10 @@ void render_packed(Font *font)
        }
        font->image.h = round_to_pot(font->image.h);
 
+       /* Allocate arrays for storing the image and keeping track of used pixels and
+       glyphs.  Since glyphs are rectangular and the image is filled starting from
+       the top, it's enough to track the number of used pixels at the top of each
+       column. */
        font->image.data = (char *)malloc(font->image.w*font->image.h);
        memset(font->image.data, 255, font->image.w*font->image.h);
        used_pixels = (unsigned *)malloc(font->image.w*sizeof(unsigned));
@@ -488,6 +502,8 @@ void render_packed(Font *font)
                unsigned best_score = 0;
                unsigned target_h = 0;
 
+               /* Find the leftmost free pixel on this row.    Also record the lowest extent of glyphs
+               to the left of the free position. */
                for(; (cx<font->image.w && used_pixels[cx]>cy); ++cx)
                        if(used_pixels[cx]-cy-1>target_h)
                                target_h = used_pixels[cx]-cy-1;
@@ -499,8 +515,10 @@ void render_packed(Font *font)
                        continue;
                }
 
+               /* Count the free pixel at this position. */
                for(w=0; (cx+w<font->image.w && used_pixels[cx+w]<=cy); ++w) ;
 
+               /* Find a suitable glyph to put here. */
                for(i=0; i<font->n_glyphs; ++i)
                {
                        Glyph *g;
@@ -510,6 +528,9 @@ void render_packed(Font *font)
                        {
                                unsigned score;
 
+                               /* Prefer glyphs that would reach exactly as low as the ones left
+                               of here.  This aims to create a straight edge at the bottom for
+                               lining up further glyphs. */
                                score = g->image.h+1;
                                if(g->image.h==target_h)
                                        score *= g->image.w;
@@ -552,6 +573,8 @@ void render_packed(Font *font)
                        used_h = cy+glyph->image.h;
        }
 
+       /* Trim the image to the actually used size, in case the original estimate
+       was too pessimistic. */
        font->image.h = round_to_pot(used_h);
 }
 
@@ -567,7 +590,11 @@ int save_defs(const char *fn, const Font *font)
                return -1;
        }
 
+       fprintf(out, "# Image/font info:\n");
+       fprintf(out, "# width height size ascent descent\n");
        fprintf(out, "%d %d %d %d %d\n", font->image.w, font->image.h, font->size, font->ascent, font->descent);
+       fprintf(out, "\n# Glyph info:\n");
+       fprintf(out, "# code x y width height offset_x offset_y advance\n");
        for(i=0; i<font->n_glyphs; ++i)
        {
                const Glyph *g = &font->glyphs[i];