fontconv

fontconv is an application to read Palm fonts (in PDB files) and dump .img files for use by the Franklin eBookMan SDK.

Updated 2/3/2003 to include em-dash and en-dash

Rationale

There are tons of fonts for the Palm handhelds, but only the built-in fonts exist for the Franklin eBookMan. As I was working on EbmDoc, I wanted to find a way to convert my Palm fonts to Franklin's format.

Franklin's GUI API has the function GUI_SetFontGroup to switch the current font group, and provides a tool called fontcompr.exe to convert glyph images into Franklin's font format. The syntax for this command is:

/franklin/SDK/winXX/bin/fontcompr.exe charset fontset datadir fontname [outfile]

Documents in the /franklin/SDK/share/franklin/fonts directory detail how these files are to be set up. I have provided a sample palm.charset that will probably work unmodified for most Western Palm fonts. (Sorry, I am not a font expert, so Japanese, Arabic, Hebrew, etc. guys are on your own! :) fontcompr is very particular about filenames and such; don't try to vary too much from the examples provided or it may not work.

The most important thing is to have the appropriate .img files in place, and that's what fontconv produces. The syntax is:

fontconv [-i] fontfile.pdb [record]

-i dumps information about the fonts contained in fontfile.pdb and exits.

If record is supplied, it dumps font number record (some font files contain multiple fonts). If omitted, the first record (record 0) is dumped.

The output is suitable for piping into an .img file, but note, if you're using Cygwin, and the filesystem is mounted textmode, it will produce a DOS text file, so pipe it through dos2unix first, otherwise fontcompr will complain.

Example:

fontconv myfont.pdb | dos2unix > palmfont.img

Building the default Palm fonts

To build your own fonts, you need the Franklin SDK. It contains the fontcompr.exe tool to generate the actual font file.

The fontconv source code includes image files generated from the standard Palm fonts. I have not included the .PDB files with the source as they are probably copyrighted. To generate the .img files yourself, do the following:

  1. Download Pilot Font Editor. This comes with a Palm application called GetFonts.prc that will cause the on-board Palm fonts to be copied to Fonts.PDB in your backup directory upon a HotSync.
  2. Run fontconv -i Fonts.PDB Mine came back with 4 usable fonts, in slots 0, 1, 2, and 7. If you have something other than a Palm III with PalmOS v3.3, your results may be different. I'll proceed with my results.
  3. Run fontconv Fonts.PDB 0 | dos2unix > palm11.img
  4. Run fontconv Fonts.PDB 1 | dos2unix > palmb11.img
  5. Run fontconv Fonts.PDB 2 | dos2unix > palm14.img
  6. Run fontconv Fonts.PDB 7 | dos2unix > palm15.img

Again, the steps above are only if you want to generate the .img files yourself from scratch; I've included them already so you don't really need to do this.

With all the images in place, and the palm.charset and palm.fontset also in place, you are ready to run fontcompr.exe. Assuming you have all the files in the same directory, and want your Franklin font file to be called Palm.fnt, run the following command:

/franklin/SDK/winXX/bin/fontcompr.exe palm.charset palm.fontset . palm Palm.fnt

Now Palm.fnt is ready to be loaded into the simulator, or moved to your Palm.

Using FONTGROUPs in code

Franklin provides a little documentation on how to use Fontgroups, but assumes you want to statically link them into your programs. The good news is, you don't have to statically link them. GUI_SetFontGroup just wants a pointer to a FONTGROUP, so if you have a font file you generated with fontcompr.exe, and load it into your eBookMan, you can map to it using ebo_mapin (or better yet, use Chris Warren-Smith's ebjlib!). I would think that the file would have to be in RAM to do this. Here's a sample (using ebjlib): 

 const FONT *font;
    File FontFile;

    FontFile.open("Palm.fnt");
    GUI_SetFontGroup((FONTGROUP*)FontFile.getPtr());
    font = GUI_GetFont(11, CTRL_NORMAL);

If Palm.fnt exists, and has an 11-point normal font, it has just been loaded and you can now draw with it.

Other stuff I've learned

There are many quirks I discovered when working with fonts on the eBookMan. Most of this information is pure speculation on my part, since there isn't a lot of documentation available.

Image filenames must have the size as the last thing before the dot. So if you have an image file for an 11-pixel font, it should be called something11.img.

If you define multiple STYLEs in your .fontset file, you must put an entry in the MATRIX section, even if you don't have a separate image file. See the palm.fontset file as an example. No bold image is available for the 14-pixel size, but it is still specified in the MATRIX section, and points to the same image file as the NORMAL style.

This gets interesting in the code. GUI_GetFont will return an error if you try to get a bold version of the font. The way around this, is to either create a copy of the .img file and "fake out" fontcompr.exe, or loop through the FONTGROUP yourself like they do in guifonts.cpp. The FONTGROUP will contain an entry for the unsupported font/style, but the font member will be zero.

The files must be in Unix format (linefeeds only). If not, you will get a message: [image filename]: No error

Font Links