News | About | Download | Documentation | Development | Links

Creating and using fonts, ClanLib API overview

Abstract:

ClanLib makes it possible to create your own font in an image file or use existing system fonts. You can then use the fonts to display text to the player, such as FPS counters, dialog boxes, and other such information. ClanLib gives you a great deal of control over how your text is displayed; for more advanced methods, see part two of this overview.

Creating fonts

You can make your own font by drawing all the glyphs (or character images) in an image file. Once that is done, you must tell ClanLib how to seperate the file into individual glyphs. The easiest way to do this is to use alpha-cutting. To create an alpha-cut font, open up your favorite image editor, and create a wide, short, transparent image:

Then type a long string of characters, which will become the characters in your font. Usually this string will look something like this:

The example set of character glyphs above isn't very useful: usually, you will want to include at least the entire alphabet, probably in upper and lower case, all the numbers, and quite a few of the symbols. However, you do not have to, and in some cases, you won't want to. For example, an LCD numerals font might only include 0-9 and the colon.

Once you've typed the string in, you must clean up the image to make certain that there's at least one column of transparency between each character. A common problem is the double-quote character: you may need to add a slightly-visible pixel between the two quote marks to make ClanLib treat it as a single character. Here's a before and after example:

ClanLib uses the same mechanism to load font glyphs as it does to seperate the frames of a sprite from a single file. In fact, a CL_Sprite is used for the glyphs: you can use any sprite creation method to create the glyphs of a font, including palette-cutting, grid-cutting, storing glyphs in individual files, or any combination of the above. See the sprites overview for more information.

Font resources

You should probably already have a resource file or two as part of your game; if you don't, then you're missing out on a lot of flexibility. See the resource overview for more info.

You will need two resources: one for the sprite containing all the glyphs, and one for the font itself. The only one you use directly is the font resource.

Assuming you'd like to create a font called FontA based on an alpha-cut image called font_a.tga, containing the glyphs in the visual example above, your resources should look something like this:

FontA_glyphs = (
	type=sprite,
	image1="font_a.tga",
	image1_method=alpha
);
Font_A = (
	type=font,
	glyphs="FontA_glyphs",
	letters="AaBb1234.,"""
);

Notice that the double quote character inside letters is two double quotes in a row (""); this is how ClanLib distinguishes it from the ending double quote.

The following options for image font resources are supported:

• glyphs="some_glyphs_resource" : The name of the resource of the sprite to extract glyphs from.
• letters="AaBbCc..." : The ASCII characters that are in the font, in the same order as they appear in the sprite.
• spacelen=8 : The width, in pixels, of a space. This value is only used if there is no space character in the font. Usually there isn't: alpha-cutting is the most popular way to make bitmap fonts, but it has no good way of representing a completely transparent glyph, like the space. If there is no space glyph, and spacelen is unspecified, it will use the average width of all the glyphs to get the space width.
• width_offset=-2 : This is used to provide a global offset to the widths of all glyphs. You can set this to a negative value to kern characters together (this may be useful, for example, for italic fonts), or positive to spread characters apart. You can always change this value afterwords using CL_Font::set_width_offset.
• height_offset=3 : This is an offset applied to the height of a given line. ClanLib uses the height of the tallest glyph to determine the height of the line: you can use this option to give it a positive offset, spreading lines apart, or a negative offset, merging lines together. You can always change this afterwords using CL_Font::set_height_offset.
• baseline=3 : This is only useful in the context of CL_TextStyler. See part two of this overview for more information on that class.

You can also use resources for system fonts. This is covered in part two of this overview. You can also create fonts without resources: this is fairly self-explanatory, just involving the constructors of CL_Sprite and CL_Font. Using resources is better though, mmmkay?

Using fonts

If your resources file was named 'resources.scr', then you can load the font into your program from the resource using the following C++ code:

  CL_ResourceManager manager("resources.scr", true); 
  CL_Font font_a("Font_A", &manager);

Once you've done that, you can call CL_Font::draw(int, int, std::string) to print arbitrary text. For example:

  font_a.draw(150, 150, "How many boards would the mongols hoard, if the mongol hordes got bored?\n   --Calvin and Hobbes");

CL_Font will honor all whitespace, such as newlines and spaces, literally. You can also print into a CL_Rect using CL_Font::draw(CL_Rect, std::string). If you do this, the text will be word-wrapped to the width of the rectangle, and will not exceed the rectangle's height:

  CL_Rect bounds_rect(50, 50, 300, 350);
  font_a.draw(bounds_rect, "Gau: I've got treasure!\nSabin & Cyan: Treasure?!?\nGau: It's shiny, shiny, shiny shiny shiny!\nSabin:Could anything be that shiny?");

Spaces are the default word delimiters, but you can also specify other delimiters by passing them as an additional string argument to CL_Font::draw. Spaces are treated differently from other delimiters, however: if space is a delimiter during word wraping, than CL_Font avoids ending lines with spaces, beginning wrapped lines with spaces, and other things to make wrapped text more word-processor-like.

Move on to part two.