This directory contains TGA files which are making up the built-in font of Eagle
Mode. Read here how the TGA files are organized and how you can extend the
character set by conversion from standard font files.


The TGA files
=============

Each TGA file defines another range of Unicode characters. Therefore, the names
of the TGA files have the following form:

 <first>-<last>_<width>x<height>_<desc1>_<desc2>.tga

with:

 <first>  - Hexadecimal Unicode of first defined character.
 <last>   - Hexadecimal Unicode of last defined character.
 <width>  - Decimal character width in pixels.
 <height> - Decimal character height in pixels.
 <desc1>  - Description of the Unicode range.
 <desc2>  - Additional description ("original" means painted by me).

(There are two additional files, which are always required: CostlyChar.tga and
UnknownChar.tga. They are outside Unicode)

All characters of a file have the same size. Each file contains the characters
row-by-row. The number of columns is detected automatically.

If files overlap in the range of codes, the behavior is undefined.

The original files do not cover the whole set of Unicode characters. If you want
to add or replace some, then you could either paint them yourself, or you could
convert standard font files using font2em which is described below. Of course,
one day Eagle Mode should be able to use standard font files directly.


font2em
=======

font2em is a small kludgy tool which can be used to convert standard font files
(TTF, PCF, PFB,...) to TGA files for use in Eagle Mode. It is based on the
freetype library.

Here comes a commented example of how to get some Cyrillic and Japanese
characters. But please also read the important hints at the end.

First, compile font2em:

  gcc font2em.c -I/usr/include/freetype2 -lfreetype -o font2em

Now convert some font files:

  ./font2em /usr/share/fonts/truetype/DejaVuSansMono-Bold.ttf tmp1 112
  ./font2em /usr/share/fonts/misc/18x18ja.pcf.gz tmp2 18

The first command creates a subdirectory tmp1 with some TGA files in it,
converted from the DejaVuSansMono-Bold font. The pixel height of characters gets
112 (the width is set automatically). The second command creates tmp2 from a
Japanese font. There the height argument is just used for choosing a nearest
possible height, because the source font is already a bitmap font.

Have a look to files in the created directories tmp1 and tmp2. Search for TGA
files containing characters you want to install, and install them by copying
to the font directory:

  cp tmp1/*Cyrillic*.tga .
  cp tmp2/*CJK*.tga .
  cp tmp2/*Hiragana*.tga .
  cp tmp2/*Katakana*.tga .

Finally remove the temporary stuff:

  rm -r tmp1 tmp2


*** IMPORTANT HINTS ***

- Extending the built-in font is useful only if the system has UTF-8 locale.
  Otherwise Eagle Mode falls back to the 8-bit Latin-1 character set.

- You have to make sure that the installed TGA files do not have a too large
  pixel size, otherwise the font cache of Eagle Mode may not be able to hold
  them, or the font cache may load and unload the files too often. Especially
  CJK sets are problematic. If Eagle Mode often displays grey "Costly" boxes
  instead of correct characters, then you have a problem here, and you should
  recreate your TGA files with a smaller character pixel height. Another chance
  would be to increase the maximum size of the font cache, but currently that
  would have to be made in the source code of Eagle Mode: It's at the end of
  src/emCore/emFontCache.cpp, the variable named emFontCache::MaxMegabytes.

- Only mono spaced fonts (aka fixed fonts) are suitable for conversion.

- font2em is not very good and lacks some options. Especially with vector fonts,
  it may cut off something from extended characters, or it may choose a too
  large character box.


font2em as an emTmpConv plugin?
===============================

Privately, I use font2em also for viewing standard font files in Eagle Mode. But
it's not very nice, and beginners could think TTF files would consist of TGA
images. Anyway, if you want it (please not in distributions), here is the
contents of my plugin file (name it emTmpConv_font2em.emFpPlugin, put it into
$EM_DIR/etc/emCore/FpPlugins, and also put the font2em binary to $EM_DIR/bin):

#%rec:emFpPlugin%#

FileTypes = { ".otf" ".pcf" ".pcf.gz" ".pfa" ".pfb" ".ttf" }
Priority = 0.51
Library = "emTmpConv"
Function = "emTmpConvFpPluginFunc"
Properties = {
 {
  Name="OutFileEnding"
  Value=".dir"
 }
 {
  Name="Command"
  Value="exec \"$EM_DIR/bin/font2em\" \"$INFILE\" \"$OUTFILE\" 32"
 }
}
