From 3722474e4fb8de564a4952e4cff24b926bc82743 Mon Sep 17 00:00:00 2001 From: Mikko Rasa Date: Fri, 23 Nov 2012 19:08:17 +0200 Subject: [PATCH] Better documentation --- Readme | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++- ttf2png.c | 35 +++++++++++++++-- 2 files changed, 142 insertions(+), 5 deletions(-) diff --git a/Readme b/Readme index ff85428..b8abf11 100644 --- a/Readme +++ b/Readme @@ -9,7 +9,117 @@ libpng 1.2 C compiler (preferably GCC) -Changes +Command-line options + + -r , + 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 + Font size to use. The default is 10 pixels. + + -l + Number of characters to put in one line. Defaults to autodetect. Ignored + if -p is used. + + -c + 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 + 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 3685b5a..b8f48a8 100644 --- a/ttf2png.c +++ b/ttf2png.c @@ -267,18 +267,18 @@ void usage() "Distributed under the GNU General Public License\n\n" "Usage: ttf2png [options] \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; yrows; ++y) for(x=0; xwidth; ++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; in_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; in_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(; (cximage.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+wimage.w && used_pixels[cx+w]<=cy); ++w) ; + /* Find a suitable glyph to put here. */ for(i=0; in_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; in_glyphs; ++i) { const Glyph *g = &font->glyphs[i]; -- 2.45.2