Provided by: hxtools_20221119-1_amd64 
Name
vfontas — a bitmap font file transformation utility
Syntax
vfontas commands...
Commands
-blankfnt
-canvas xsize ysize
-clearmap
-crop xpos ypos width height
-fliph
-flipv
-invert
-lge
-lgeu
-lgeuf
-loadbdf ff.bdf
-loadclt directory/
-loadfnt mu.fnt
-loadhex unicode.hex
-loadmap cp437AB.uni
-loadpsf ter-v32b.psfu
-move shiftx shifty
-savebdf out.bdf
-saveclt outdir/
-savefnt x.fnt
-saven1 new.sfd
-saven2 new.sfd
-savepbm outdir/
-savepsf new.psfu
-savesfd new.sfd
-setbold
-setname name
-setprop key value
-upscale xscale yscale
-xcpi ega437.cpi outdir/
-xlat xoffset yoffset
Description
vfontas (originally "VGA font file assembler") can read/write bitmap fonts from/to a
number of formats and transform the glyphs in various ways. vfontas is able to generate
outline fonts from bitmapped fonts.
vfontas does not have a direct integration of or with FontForge, but thanks to the BDF
read/write support on both sides, fonts in formats like FNT and PSF can be made available
to FontForge by vfontas, and, conversely, fonts in formats like FON and TTF can be made
available to vfontas by FontForge.
vfontas offers the CLT bitmap format, wherein glyphs are represented as textgraphical
files to facilitate editing with terminal editors.
Multi-size bitmap fonts are styles
A bitmap font which is offered by its authors in multiple sizes can not only constitute
different sizes, but also visually different styles, similar to what italic fonts are to
regular fonts (e.g. longer descenders, more bulbous terminals, etc.).
When vfontas converts bitmap fonts to vector, the "size" of a bitmap font becomes
"resolution". An 8x8 bitmap font and an 8x16 bitmap font, after conversion to SFD and
other vector formats will have the same height when the user requests such vectorized
forms to be rendered in size 12pt.
Vector font display sizes
Pixel-perfect rendering of a (vectorized) bitmap font requires taking the original size in
px and applying the monitor DPI. A 16px tall font on a system which uses a 96dpi setting
displays well using 12pt or multiples thereof. (16*72/96=12). Here is a cheat table for
some font heights:
┌──────────┬─────────┬────────┬────────┬────────┐
│BM Height │ 96dpi │ x2 │ 120dpi │ x2 │
├──────────┼─────────┼────────┼────────┼────────┤
│13px │ 9.75pt │ 19.5pt │ 7.8pt │ 15.6pt │
├──────────┼─────────┼────────┼────────┼────────┤
│14px │ 10.5pt │ 21pt │ 8.4pt │ 16.8pt │
├──────────┼─────────┼────────┼────────┼────────┤
│15px │ 11.25pt │ 22.5pt │ 9pt │ 18pt │
├──────────┼─────────┼────────┼────────┼────────┤
│16px │ 12pt │ 24pt │ 9.6pt │ 19.2pt │
├──────────┼─────────┼────────┼────────┼────────┤
│18px │ 13.5pt │ 27pt │ 10.8pt │ 21.6pt │
├──────────┼─────────┼────────┼────────┼────────┤
│20px │ 15pt │ 30pt │ 12pt │ 24pt │
├──────────┼─────────┼────────┼────────┼────────┤
│22px │ 16.5pt │ │ 13.2pt │ 26.4pt │
├──────────┼─────────┼────────┼────────┼────────┤
│24px │ 18pt │ │ 14.4pt │ 28.8pt │
├──────────┼─────────┼────────┼────────┼────────┤
│28px │ 21pt │ │ 16.8pt │ │
├──────────┼─────────┼────────┼────────┼────────┤
│32px │ 24pt │ │ 19.2pt │ │
└──────────┴─────────┴────────┴────────┴────────┘
Aspect ratio
CRT screens of the time commonly had an aspect ratio of 4:3, and whatever resolution was
shown would be squeezed into that frame, potentially making the pixels non-square. This
means that bitmap fonts of the time will need a corrective factor for modern display
hardware to be reproduced faithfully. This correction can happen either during conversion
(vfontas has no support for this at present), or at the time of rendering. The font can
either be stretched in the vertical direction or compressed in the horizontal by using the
reciprocal.
┌─────────┬───────────┬────────────┬──────────────┐
│Text res │ Cell size │ Resolution │ VStretch │
├─────────┼───────────┼────────────┼──────────────┤
│40x25 │ 8x8 │ 320x200 │ 6/5 = 1.2 │
├─────────┼───────────┼────────────┼──────────────┤
│80x25 │ 8x8 │ 640x200 │ 12/5 = 2.4 │
├─────────┼───────────┼────────────┼──────────────┤
│80x25 │ 8x14 │ 640x350 │ 48/35 = 1.37 │
├─────────┼───────────┼────────────┼──────────────┤
│80x25 │ 9x14 │ 720x350 │ 54/35 = 1.54 │
├─────────┼───────────┼────────────┼──────────────┤
│80x25 │ 9x16 │ 720x400 │ 27/20 = 1.35 │
├─────────┼───────────┼────────────┼──────────────┤
│80x30 │ 8x16 │ 640x480 │ 1.0 │
├─────────┼───────────┼────────────┼──────────────┤
│80x43 │ 8x8 │ 640x350 │ 48/35 = 1.37 │
├─────────┼───────────┼────────────┼──────────────┤
│80x50 │ 8x8 │ 640x400 │ 6/5 = 1.2 │
├─────────┼───────────┼────────────┼──────────────┤
│ │ │ x*y │ x*y/3*4 │
└─────────┴───────────┴────────────┴──────────────┘
Commands
blankfnt
Initializes the memory buffer with 256 empty 8x16 glyphs. The primary purpose for this is
with saveclt to get blank glyph files for hand-editing. For a differently-sized canvas,
combine with -crop or -canvas.
canvas
Enlarges the glyph box to the specified size. (It never shrinks it.)
clearmap
Discards the in-memory glyph index <-> Unicode mapping table.
crop
Removes an outer area from the glyph images, shrinking the image in the process.
fliph, flipv
Mirrors/flips glyphs.
lge
Applies a "Line Graphics Enable" transformation on glyphs. It copies the pixels in the
second rightmost column to the rightmost column, and does this for glyph indices 0xC0 to
0xDF. In other words, the usefulness of the -lge command is more or less limited to DOS
fonts which have graphic characters in exactly those indices.
lgeu
Applies LGE on the graphic glyphs that are in cp437 and other DOS codepages. It does this
for unicode codepoints rather than glyph indices. This is suitable for all kinds of font
formats, but do make sure a Unicode table is present. (BDF and PSF come with a table, .fnt
does not, so use -loadmap before -lgeu).
lgeuf
Applies LGE on all glyphs from U+2500 thru U+25FF (Unicode "box drawing" and "box
elements" classes), with special handling for the shades at U+2591 thru U+2593. This is
provided as an alternative to the "true DOS look" that lge/lgeu would make.
loadbdf
Reads a BDF (Adobe Glyph Bitmap Distribution Format) font file.
loadclt
Reads a directory full of CLT files containing glyphs. CLT is a textgraphical format to
facilitate visual editing with a text console editor.
loadfnt
Reads a headerless bitmap font file, as typically used for CGA/EGA/VGA/MDA hardware, from
the specified file into memory. 8x8x256 (width/height/glyphs), 8x12x256, 8x14x256,
8x16x256 and 8x16x512 are supported.
loadfnth
Reads a headerless bitmap font file, using the specified height N and width 8. The number
of characters is then autoderived from the filesize.
loadhex
Reads a Unifont .hex encoded file.
loadmap
Reads a glyphindex <-> Unicode codepoint mapping table from the given file into memory.
The format follows the maps from /usr/share/kbd/unimaps, that is, "0x00 U+0000" at its
simplest. Multiple U+ codepoints can be specified in a line. -loadmap does not clear the
mapping table, which makes it possible to cumulate mappings from multiple files.
loadpsf
Reads a PC Screen Font PSF 2 version 0. If the psf file comes with a mapping table, the
current in-memory table will be discarded and replaced with the one from the PSF.
move
Shift all glyphs by the given x/y offsets within their existing glyph box (possibly
truncating them).
savebdf
Saves the font to a Glyph Bitmap Distribution Format file (BDF). This type of file can be
processed further by other tools such as bdftopcf(1) or fontforge(1) to, for example, turn
them into Portable Compiled Format (PCF) or TrueType/OpenType (TTF/OTF) files. (See the
"Examples" section.)
saveclt
Saves the current in-memory glyphs as multiple CLT files to the given directory. CLT is a
textgraphical format to facilitate visual editing with a text console editor.
savefnt
Saves the current in-memory glyphs to the given file, using the headerless format.
savemap
Saves the current in-memory Unicode mapping table to the given file.
saven1
N1 was an experiment to try and model the "diagonalization idea" (cf. -saven2) by
analyzing the original glyph bitmap. Its defining characteristic is a lookaround window of
3x3 pixels, whose contents are mapped to a set of triangles. N1 has some drawbacks over
the newer N2:
• N1 adds diagonals on single-pixel protrusions (e.g. the left end of the horizontal bar
in an 'f' in certain fonts). This is definitely not fixable with a 3x3 window and
would require using 5x5.
• N1 adds triangles between pixels that do not necessarily belong together, such as in
spirals like U+0040 or jampacked glyphs like U+20A7. N2 operates on edges and knows
their direction, and avoids making connections to "pixel islands" at certain angles.
saven2
Similar to -savesfd, this produces an SFD file, but uses an alternate vectorizer (aptly
named "N2"), which smoothens the jagged edges of a bitmap font.
The N2 vectorizer is able to recognize the "stair" pattern of pixels and transform these
sections to 45-degree angles. This diagonalization was originally employed by Arto
Hatanpää (possibly in a long session of manual work) for the "Nouveau IBM" and "Nouveau
IBM Stretch" vector font versions of the IBM VGA 9x16 ROM font.
The defining characteristic of N2 is that it analyzes glyph edges (similar to those
produced by -savesfd) using a lookaround window of +/- 3 edge segments, which is somewhat
comparable to a set of bitmap matrices (of size 7x2, 6x3, 5x4, 4x5, 3x6, 2x7). When a
90/270 corner is found, it will be transformed by adding diagonal edges.
In comparison to other scalers,
• xBRZ erroneously round the ends of strokes (e.g. the '-' dash), N1/N2 does not.
• While xBRZ is a bitmap-to-bitmap procedure (also limited to 6x magnification as of
writing), N1/N2 converts to vector.
• Autotrace/Potrace just is not targeted for low resolution sources (as 8x16 bitmap
fonts are). Either it will convert the bitmap 1:1 with jagged edges, or turn it into
three or so beziers, which is not nearly enough for '&'.
• N1/N2 is only specified for monochrome input.
savepsf
Saves the current in-memory glyphs as a PC Screen Font PSF2.0 file, which can then be
loaded into a Linux text console with setfont(1). The in-memory Unicode mapping table is
added to the PSF.
savesfd
Saves the font to a Spline Font Database file (SFD). This type of file can be processed
further by fontforge(1). A fairly trivial vectorizer is used that maps each pixels to a
square and then collapses shared edges between those to reduce the number of polygons
fontforge has to process.
setbold
For BDF/SFD output: Declare the font as being bold.
setname
Sets a name for the font, which gets emitted for BDF/SFD output. (The other file formats
have no metadata field for a name, so the filename is all you get.)
setprop
Sets a specific property for SFD fonts (also partly used by BDF). Only a limited set of
key names are recognized.
FamilyName
BDF: The value is used for the FAMILY_NAME attribute.
SFD: The value is influential for font selection UIs. A fontface's
regular/medium/bold/italic variants should carry the same FamilyName.
FontName
The PostScript font name. For BDF, this name will be used to construct the X
Logical Font Description (XLFD), i.e. the unwieldly "-misc-FontName-medium-r-
normal--0-0-75-75-c-10-iso10646-1" string.
FullName
BDF: The values is used for the FONT attribute
SFD: The value should be the FamilyName joined by the name of the variant
(Regular/Medium, Bold, Italic, etc.). By convention, the regular/medium variant is
allowed to be represented without a specific variant name. In other words, using
{MyFont; MyFont Bold} or {MyFont Regular; MyFont Bold} as the names for a font
project with two thicknesses is up to the user.
ssf This special property controls the horizontal scaling of all coordinates, but not
the font's em size. The default value is 1/1. This setting is useful for
implementing the correction mentioned in the "Aspect ratio" section. Applying the
80x25@720x400 correction for example requires the use of the value 20/27.
TTFWeight
BDF: for the WEIGHT attribute; should be a numeric value between 1-1000.
Weight BDF: The values is used for the WEIGHT_NAME attribute.
SFD: A non-empty variant name, in lower case. ("medium", "bold", ...)
upscale
Performs a linear upscale by an integral factor for all glyphs.
xcpi
Extracts a multi-font .cpi file (as was typically used on DOS) as separate .fnt files into
the specified directory. This operation does not touch the in-memory glyph buffers or
Unicode mapping table.
xlat
Moves all glyphs around within their canvases by the specified amount. vfontas's
coordinate system has (0,0) in the upper left corner, with positive x going to the right,
and positive y going down.
Known limits
The Linux kernel accepts console font glyphs of at most 32x32 in size.
The Consoleet bitmap format
The Consoleet text bitmap format is very similar to PBM itself. Instead of "P1" as in PBM,
a CLT file begins with "PCLT" on the first line. In the second line, width and height of
the bitmap in pixels is given. What follow is the bitmap data: Each "off" pixel is
represented by the 2-character string ".." Each "on" pixel is represented by the
2-character "##". Each row of pixels is terminated by a newline, like in PBM.
PCLT
9 7
..................
....##....##..##..
..##..##..##..##..
..##..##..####....
..##..##..##..##..
....##....##..##..
..................
Examples
Decompose a classic file into editable pictograph text files (with the help of a Unicode
map):
mkdir mu; vfontas -loadfnt /usr/share/kbd/consolefonts/mu.fnt -loadmap
/usr/share/kbd/unimaps/cp437.uni -saveclt mu/
To convert a .fnt and scale it up to make it comfortably usable with a FullHD resolution
Linux fbconsole:
vfontas -loadfnt mu.fnt -loadmap cp437.uni -canvas 9 16 -lge -upscale 2 2
-savepsf mu.psf
To convert a .fnt to TrueType/OpenType/WOFF (the Fontforge part is unfortunately manual):
vfontas -loadfnt mux.fnt -loadmap cp437AB.uni -canvas 9 16 -lge -savesfd
mux.sfd # && fontforge mux.sfd
To convert a .fnt for use under X11 and XTerm (generates sizes 12, 24 and 36, @96dpi):
for i in 1 2 3; do vfontas -loadfnt mux.fnt -loadmap cp437AB.uni -canvas 9
16 -lge -upscale $i $i -setname Mux -savebdf | bdftopcf | gzip
>~/.fonts/mux$i.pcf.gz; done; xterm -fa "misc Mux:size=24"
Comparison to earlier vfontas (2005-2018) invocation syntax
`vfontas -D out/ -xf x.fnt` has become `vfontas -loadfnt x.fnt -saveclt out/`.
`vfontas -D out/ -cf x.fnt` has become `vfontas -loadclt out/ -savefnt x.fnt`.
`vfontas -Ecf x.fnt` has become `vfontas -blankfnt -savefnt x.fnt`.
`vfontas -G <x.fnt >x.psf` has become `vfontas -loadfnt x.fnt -canvas 9 16 -lge -savepsf2
x.psf`.
`vfontas -W <x.fnt >x.psf` has become `vfontas -loadfnt x.fnt -upscale 2 1 -savepsf2
x.psf`.
`vfontas --cpi -D out/ -f x.cpi/` has become `vfontas -xcpi x.cpi out/`.
See also
hxtools(7)