PNGcustomfont Tutorial

by notthecheatr

So you've read the manual, looked at the examples, and... aren't sure where to begin. So here's a tutorial to make it easier on you. First step is to have an image with each character in the font layed out on a grid. This should be saved in either PNG or BMP format. Now you need to run the PNGcf_gencfg program and tell it about the font. Below I have given an example font. It's a PNG; if you want to load PNGs you'll need fbpng, which you can get from http://www.streetcds.co.uk/fbpng_v1_8_4.tar.gz if you don't already have it (use 7-zip to extract the files and place in the proper locations).

Notice that you must tell the program how many rows and columns of characters in the grid, how tall and wide each character is, etc. You also must give some information about the grid - if the first character in the font does not start at (0,0), where DOES it start? Normally it should start at (0,0), but if not you'll need to know where it does start so you can input this information into PNGcf_gencfg. Also, is there a buffer area of pixels, an actual grid between each character, or do the gridlines between the characters overlap? If there is a buffer of pixels between each character, you'll need to know how many pixels buffer there is. Some fonts might have negative buffers; you'll need to know that, too. Finally, you must know how you plan to display your font. 8-bit fonts use colour indices, and in this case index 0 is transparency. 32-bit fonts may use rgb (255,0,255) for transparency, but if you're using PNGs you may wish to use the alpha channel instead. If your background is always one colour (such as black) you may not use any transparency or alpha blending at all. Of course, you can change the method used in your code too, but it's good to set the default drawing mode here.

In any case, when you input all the information, PNGcf_gencfg will use this information to generate the numbers in a text file which are used by the LoadFont routine to figure out where in the image each character is stored. Of course you can edit this text file later, and you may want to - some characters will be narrower than the grid, and printing looks much nicer with variable-width characters.

By the way you don't have to worry about PNGcf_gencfg - all it does is generates a text file, it won't mess with your font image in any way. If you make a mistake, just run it again!

Now you have a font, now what about the code for loading it? Ah, let's get out our code editor and type in some FreeBasic code. Of course the most important thing is that you must be in graphics mode. Probably you already have a program written and you just want to add font support, so I'll assume I don't need to tell you too much about that. Just remember - your font must use the same colour depth as the mode you are in. You cannot load 8-bit fonts in 32-bit mode or vice-versa. If you need to, convert the font images to the correct colour depth. For this I would recommend the great IrfanView, a free program which EVERYONE who ever does any kind of work with images should use. Of course, you'll need to specify the colour depth in your font INI file as well. In your code, you'll need to declare the variable for loading the font, using "Dim xxxxx As FontType".

Once you're all ready, load the font using LoadFont. You must know the name of the INI file and of course the FontType variable:

LoadFont "testfont.ini", myFont

Also note that if the font is not in the same directory as your program, you will need to change to that directory, since the INI file has the name of the image the font is stored in (unless you use absolute paths inside the INI file, but I would not recommend that). I usually store my fonts in a sub-directory of the program directory called "Fonts" so before loading the font I ChDir to there; if I need to come back to where I was before, I can ChDir back. To figure out where the program directory is, I use a call to ExePath().

Once your font is loaded, you can easily use any of a number of methods to print with it. PrintFont (or PrintUAlphaFont) is the most basic one, but it has a lot of parameters. Since many of these parameters will not change much, or will change very predictably as you print, you may prefer to use the cursor system. First call FSetFont with the font variable as it's parameter (the font should already be loaded), then you can use FPrint to print on the screen. FPrint only takes one parameter, and that of course is the string to print. The cursor will be updated; note that either ASCII 13 or 10 may be used as linefeed characters.

For anything beyond the basics, you should read the manual. Hopefully this can help you get your foot inside the door so you better understand how to work with PNGcustomfont.