The SDL_bmf Library

The SDL_bmf library provides a simple facility for using and manipulating bitmapped fonts within the SDL framework. It has the following features:

• Support for fixed-width and proportionally-spaced fonts.
• Scales fonts to any pixel height.
• Renders text in the color of choice, -or-
• Renders text in a bit pattern copied from a backing bitmap.
• Characters are scaled and colored only if/when first used, and cached for speedy blitting thenceforth.
• Uses XML to simply and portably describe fonts. Fonts can be encoded either as pure XML, or as an XML description file with an associated BMP file containing the character bitmaps.
• Can convert a font from bitmapped format to pure XML and back, thus allowing fonts to be edited with any text editor.

Note: at present, SDL_bmf is alpha software - use at your own risk.

Note 2: SDL_bmf expects font BMP files to have a black background; if yours don't, they won't work properly.

Here are some screenshots of the "bmftest" demo in action:

• Fixed and proportional fonts in various colors.
• A font scaled to many sizes.
• A font displayed with a backing bitmap (sort of tie-dyed looking).
• LARGE characters with a backing bitmap.

All the fonts used in the demo were generated at run time from two files: the LargeFont.bmp file from the SDL_Console package, and the Proportional8.xml file that encodes a cheesy proportional font I built for the demo.

Here's an example of how easy it is to use SDL_bmf: this snippet of loads a font from an XML description (pulling in an auxiliary BMP file if necessary), scales it to 32 pixels, and writes "Hello, world" in blue text at (100,100) on the SDL_Surface "screen":

        SDL_BmapFont font("myfontdesc.xml",32,0x00,0x00,0xFF);
	font.DrawText(screen,100,100,"Hello, world");
  

Requirements

The SDL_bmf package requires James Clark's "expat" XML parser which should build out-of-the-box pretty much anywhere. A C++ wrapper for expat called "expat++" is included with SDL_bmf.

Downloads

Here's the source.

Installation

1. Get, build, and install expat.
2. Unpack the SDL_bmf source in some convenient place.
3. Change the expat++ Makefile to reflect the places where the expat headers and libs are installed.
4. cd expat++ ; make
5. Copy the expat++ library and headers to a handy place.
6. Change the SDL_bmf Makefile to reflect the locations of the expat and expat++ headers and libraries.
7. cd SDL_bmf ; make
8. Run the demo, move the headers and library to some useful place, etc.

Look at the comments in SDL_bmf.h for a pretty complete description of how to use the library.

The fontxml Utility

The fontxml program converts between XML-described BMP files and pure XML, and vice-versa. The advantage to this is that you can convert your enormous bitmap file to an even more enormous -- but much easier to edit -- XML file, edit it in your favorite text editor, and then convert back to the nice compact BMP format for distribution. Run it without arguments to see how to use it.

In order to convert a font to pure XML, fontxml requires an XML font-description file. This file can have one of two formats:

• For a fixed-size font, the XML should look like:

  <FONT type="constant" bmapfile="myfont.bmp" h="16" w="10" rows="8" columns="32"/>

  This just means that each character is 16 pixels tall and 10 pixels wide, and there are 8 rows and 32 columns of characters in the bitmap.

• For a variable-size font, the XML should look like:

        <FONT type="description" bmapfile="myproportional.bmp">
          <CH c="105" x="100" y="0" w="10" h="14"/>
          <CH c="106" x="110" y="0" w="8" h="14" d="3"/>
  	etc.
        </FONT>
      

  This means that the character with ASCII code 105 is at location (100,0) in the bitmap, and is 10x14 pixels. Character code 106 is at location (110,0), is 8x14 pixels, and has a 3-pixel descender. Each character in the bitmap must be described by a CH tag.

When converting from pure XML to BMP, fontxml generates an XML description in the second format (even for fixed-size fonts). This description can be included inside an application as a constant string or a resource to allow SDL_bmf to utilize the BMP file. Since it is trivial to generate the simpler FONT tag for a fixed-size font, fontxml doesn't bother to do that.

Enjoy!