.TH vfontas 1 "2019-04-21" "hxtools" "hxtools"
.SH Name
.PP
vfontas \(em a bitmap font file transformation utility
.SH Syntax
.PP
\fBvfontas\fP \fIcommands\fP...
.SS Commands
.PP
\fB\-blankfnt\fP
.PP
\fB\-canvas\fP \fIxsize\fP \fIysize\fP
.PP
\fB\-clearmap\fP
.PP
\fB\-crop\fP \fIxpos\fP \fIypos\fP \fIwidth\fP \fIheight\fP
.PP
\fB\-fliph\fP
.PP
\fB\-flipv\fP
.PP
\fB\-invert\fP
.PP
\fB\-lge\fP
.PP
\fB\-loadclt\fP \fIdirectory/\fP
.PP
\fB\-loadfnt\fP \fImu.fnt\fP
.PP
\fB\-loadhex\fP \fIunicode.hex\fP
.PP
\fB\-loadmap\fP \fIcp437AB.uni\fP
.PP
\fB\-loadpsf\fP \fIter-v32b.psfu\fP
.PP
\fB\-savebdf\fP \fIout.bdf\fP
.PP
\fB\-saveclt\fP \fIoutdir/\fP
.PP
\fB\-savefnt\fP \fIx.fnt\fP
.PP
\fB\-saven1\fP \fInew.sfd\fP
.PP
\fB\-saven2\fP \fInew.sfd\fP
.PP
\fB\-savepbm\fP \fIoutdir/\fP
.PP
\fB\-savepsf\fP \fInew.psfu\fP
.PP
\fB\-savesfd\fP \fInew.sfd\fP
.PP
\fB\-setname\fP \fIname\fP
.PP
\fB\-upscale\fP \fIxscale\fP \fIyscale\fP
.PP
\fB\-xcpi\fP \fIega437.cpi\fP \fIoutdir/\fP
.PP
\fB\-xlat\fP \fIxoffset\fP \fIyoffset\fP
.PP
.SH Description
.PP
vfontas (originally "VGA font file assembler") can transform raster font files
in various ways.
.SH Aspect ratio
.PP
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.
.TS
allbox tab(:);
lB lB lB lB.
T{
Text res
T}:T{
Char size
T}:T{
Resolution
T}:T{
VStretch
T}
.T&
l l l l.
T{
80x25
T}:T{
9x14
T}:T{
720x350
T}:T{
54/35 = 1.54
T}
.T&
l l l l.
T{
40x25
T}:T{
8x8
T}:T{
320x200
T}:T{
6/5 = 1.2
T}
.T&
l l l l.
T{
80x25
T}:T{
8x8
T}:T{
640x200
T}:T{
12/5 = 2.4
T}
.T&
l l l l.
T{
80x25
T}:T{
8x14
T}:T{
640x350
T}:T{
48/35 = 1.37
T}
.T&
l l l l.
T{
80x43
T}:T{
8x8
T}:T{
640x350
T}:T{
48/35 = 1.37
T}
.T&
l l l l.
T{
80x25
T}:T{
9x16
T}:T{
720x400
T}:T{
27/20 = 1.35
T}
.T&
l l l l.
T{
80x30
T}:T{
8x16
T}:T{
640x480
T}:T{
1.0
T}
.T&
l l l l.
T{
80x50
T}:T{
9x8
T}:T{
720x400
T}:T{
27/20 = 1.35
T}
.T&
l l l l.
::x*y:x*y/3*4
.TE
.SH Commands
.SS blankfnt
.PP
Initializes the memory buffer with 256 empty 8x16 glyphs. The primary purpose
for this is with \fBsaveclt\fP to get blank glyph files for hand-editing. For a
differently-sized canvas, combine with \fB\-crop\fP or \fB\-canvas\fP.
.SS canvas
.PP
Enlarges the glyph box to the specified size. (It never shrinks it.)
.SS clearmap
.PP
Discards the in-memory glyph index <-> Unicode mapping table.
.SS crop
.PP
Removes an outer area from the glyph images, shrinking the image in the process.
.SS fliph, flipv
.PP
Mirrors/flips glyphs.
.SS lge
.PP
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.
.SS loadclt
.PP
Reads a directory full of CLT files containing glyphs. CLT is a textgraphical
format to facilitate visual editing with a text console editor.
.SS loadfnt
.PP
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.
.SS loadfnth
.PP
Reads a headerless bitmap font file, using the specified height N and width 8.
The number of characters is then autoderived from the filesize.
.SS loadhex
.PP
Reads a Unifont .hex encoded file.
.SS loadmap
.PP
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.
\fB\-loadmap\fP does not clear the mapping table, which makes it possible to
cumulate mappings from multiple files.
.SS loadpsf
.PP
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.
.SS savebdf
.PP
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.)
.SS saveclt
.PP
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.
.SS savefnt
.PP
Saves the current in-memory glyphs to the given file, using the headerless
format.
.SS savemap
.PP
Saves the current in-memory Unicode mapping table to the given file.
.SS saven1
.PP
N1 was an experiment to try and model the "diagonalization idea" (cf. \-saven2)
by analyzing the original glyph \fIbitmap\fP. 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:
.IP \(bu 4
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.
.IP \(bu 4
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.
.SS saven2
.PP
Similar to \fB\-savesfd\fP, this produces an SFD file, but uses an alternate
vectorizer (aptly named "N2"), which smoothens the jagged edges of a bitmap
font.
.PP
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.
.PP
The defining characteristic of N2 is that it analyzes glyph edges (similar to
those produced by \-savesfd) using a lookaround window of 7 edge segments,
which is used to work on areas of effectively 5x5 pixels. When a 90/270 corner
is found, it will be transformed by adding diagonal edges.
.PP
In comparison to other scalers,
.IP \(bu 4
xBRZ erroneously round the ends of strokes (e.g. the '-' dash), N1/N2 does not.
.IP \(bu 4
While xBRZ is a bitmap-to-bitmap procedure (also limited to 6x magnification
as of writing), N1/N2 converts to vector.
.IP \(bu 4
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 '&'.
.IP \(bu 4
N1/N2 is only specified for monochrome input.
.SS savepsf
.PP
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.
.SS savesfd
.PP
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.
.SS setname
.PP
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.)
.SS upscale
.PP
Performs a linear upscale by an integral factor for all glyphs.
.SS xcpi
.PP
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.
.SS xlat
.PP
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.
.SH Known limits
.PP
The Linux kernel accepts console font glyphs of at most 32x32 in size.
.SH The Consoleet bitmap format
.PP
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.
.PP
.nf
	PCLT
	9 7
	..................
	....##....##..##..
	..##..##..##..##..
	..##..##..####....
	..##..##..##..##..
	....##....##..##..
	..................
.fi
.SH Examples
.PP
Decompose a classic file into editable pictograph text files (with the help
of a Unicode map):
.PP
.RS 4
.nf
mkdir mu; vfontas \-loadfnt /usr/share/kbd/consolefonts/mu.fnt \-loadmap
/usr/share/kbd/unimaps/cp437.uni \-saveclt mu/
.fi
.RE
.PP
To convert a .fnt and scale it up to make it comfortably usable with a FullHD
resolution Linux fbconsole:
.PP
.RS 4
.nf
vfontas \-loadfnt mu.fnt \-loadmap cp437.uni \-canvas 9 16 \-lge \-upscale 2 2
\-savepsf mu.psf
.fi
.RE
.PP
To convert a .fnt to TrueType/OpenType/WOFF (the Fontforge part is
unfortunately manual):
.PP
.RS 4
.nf
vfontas \-loadfnt mux.fnt \-loadmap cp437AB.uni \-canvas 9 16 \-lge \-savesfd
mux.sfd # && fontforge mux.sfd
.fi
.RE
.PP
To convert a .fnt for use under X11 and XTerm (generates sizes 12, 24 and 36,
@96dpi):
.PP
.RS 4
.nf
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"
.fi
.RE
.SH Comparison to earlier vfontas (2005-2018) invocation syntax
.PP
`vfontas \-D out/ \-xf x.fnt` has become `vfontas \-loadfnt x.fnt \-saveclt
out/`.
.PP
`vfontas \-D out/ \-cf x.fnt` has become `vfontas \-loadclt out/ \-savefnt x.fnt`.
.PP
`vfontas \-Ecf x.fnt` has become `vfontas \-blankfnt \-savefnt x.fnt`.
.PP
`vfontas \-G <x.fnt >x.psf` has become `vfontas \-loadfnt x.fnt \-canvas 9 16
\-lge \-savepsf2 x.psf`.
.PP
`vfontas \-W <x.fnt >x.psf` has become `vfontas \-loadfnt x.fnt \-upscale 2 1
\-savepsf2 x.psf`.
.PP
`vfontas \-\-cpi \-D out/ \-f x.cpi/` has become `vfontas \-xcpi x.cpi out/`.
.SH See also
.PP
\fBhxtools\fP(7)