Loading and Unloading Fonts

The character definitions that make up each font are stored in external files called font files. The font files distributed with Fastgraph/Fonts all have names of the form xxxxxxnn.FGF, where xxxxxx is a one- to six-character name describing the font's appearance, and nn is a two-digit value that specifies the font's point size. The point size is the height in pixels from the top of a normal upper case character to the bottom of the lowest descender character in the font. While the font file naming convention provides consistency, font files may have any valid file name.

To display characters with Fastgraph/Fonts, you must first load the contents of a font file into memory. There are two ways to do this -- automatic loading and manual loading. Automatic loading uses the fgf_load() function to allocate memory for the font and read the font file contents into the allocated memory. Manual loading uses the fgf_define() function, which expects your program to perform its own memory management and font file reading. While automatic loading relieves you of these details, manual loading may be preferable if you want to include the font data directly in your program. Most examples we'll present will use automatic loading. In either case, you can have up to 256 font files loaded at the same time.

Both fgf_load() and fgf_define() expect a single parameter. With fgf_load(), the parameter is a null-terminated character string that specifies the font file name. With fgf_define(), the parameter is the name of an array into which your program has read the contents of a font file. If successful, each function returns a font handle between 1 and 256 that you use to reference the font in later operations. A return value of zero from fgf_load() indicates that the font was not loaded because there is not enough memory available for loading the font, the font file wasn't found, or there are no more font handles available. A return value of zero from fgf_define() can only occur if there are no more font handles available. When you successfully load a font, that font becomes the current font.

If your program uses automatic loading, it should unload all fonts (that is, release the memory allocated for the fonts) before it exits. You also may wish to unload a specific font when you're through using that font. The fgf_unload() function is provided for this purpose. It expects a single integer parameter whose value is either a font handle or a negative value. If it is a font handle, only that font is unloaded. If it is negative, all fonts are unloaded.