# Creating and using fonts, ClanLib API overview

## Abstract:

ClanLib makes it possible to create your own font in an image file (like TGA, PNG or PCX) or use existing TTF fonts.

This document will demonstrate two different ways to create fonts in ClanLib, and show how to use those in your application. It will also briefly show how to use TTF fonts directly using ClanTTF.

### Creating fonts

You can make your own font by drawing all the letters and numbers in an image file.

There are two types of font creation in ClanLib, the old (hard) and new (easy) way. In the old way you had to use specific palette colors to seperate the letters, while you can use the alpha/transparency in the new way.

#### The new way

To make a font in an image file in the new way, you have to use an image-format which supports alpha/transparency. We suggest that you use TGA or PNG. An image with alpha/transparency uses 32 bit to store each pixel. The 24 bit specifies the RGB color and the rest (8 bit) specifies the alpha/tranparency.

The letters in the image-file are separated by one or several vertical lines with full transparency (that is pixels with an alpha below the trans_limit). The font cutter will then use these transparent lines to cut out the letters, telling it where each letter starts and stops. Note that all letters must be placed beside eachother in one row; you can't place letters below others.

Read this for a tutorial on how to create a font using this method.

When a font is loaded, it is analyzed. If there is no alpha in the image, despite that it has an alpha channel, it stores it as a colorkey surface (palette-color seperated font). So basically, if you have a target image, where only alpha is either 100% on or off, the image will be just as fast as an image that never had an alpha channel. If you use variable alpha-values, the font will be blitted using these values (which is slower, but much nicer than a colorkey surface).

#### The old way

To make a font in an image file in the old way, you have to use an 8-bit format and save your image as 256 index-coloured; the PCX format is perfect for this.

The letters are seperated by straight lines, which are drawn with the last 3 colors of the 256 color-palette. Color number 254 seperates the letters vertically, number 255 separates the lines and color 253 marks the end of the line.

Read this for a tutorial on how to create a font using this method.

### Using fonts

The resource type can look like this:

    // New way:
    font = font.tga(
    		type=font,
    		trans_limit=0.05,
    		x=0, y=0,
    		subtract_width=0,
    		spacelen=4,
    		letters="!'#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_'abcdefghijklmnopqrstuvwxyz{|}~");

    // Old way:
    font = font.pcx(
    		type=font,
    		x=1, y=1,
    		tcol=0,
    		spacelen=6,
    		letters="abcABC12345.,""(){}" );

Common options for the new and old method:

- "type=font" : tells the resource system we're defining a font.
- "x=0, y=0" : defines the top left pixel of your font.
- "spacelen=6" : any letter which you have not defined will be replaced by a blank space of "spacelen" pixels.
- "letters="ABCabc.,""()." : tells the datafile compiler which letters you have defined. This is an important feature, since you don't have to redefine 224 characters if you only need 40 of them. To define a " just type it two times.

Options for the new method:

- "trans_limit=0.05": the amount of the alpha amount allowed where it still considers the pixel to be transparent.
- "subtract_width=0": is the kerning, if it is eg. 5, then 5 pixels will be subtracted from each letter's width.

Options for the old method:

- "tcol=0" : color for transparency.

If you want more information about resources, have a look at the resource overview.

### Loading the fonts at runtime

To load the font in your program, you can use the following C++ code:

      CL_ResourceManager *manager = new CL_ResourceManager("myresources.scr", true);
      CL_Font *font = new CL_Font("font", manager);

### Using TTF fonts with ClanTTF

    #include <ClanLib/ttf.h>

    main(...)
    {
    	...
    	// Setting up ClanLib
    	CL_TTFSetup::init();
    	...
    	CL_Font *font = new CL_Font("my_font", resources);
    	...
    	// End of program, close down
    	CL_TTFSetup::deinit();
    }

In the resource-file, type:

    	myfont = font.ttf (type=TTF);

Where myfont is the name you would use in the program and font.ttf is the file name of the font. For an example of how to do this checkout the Examples/TTF directory.

ClanTTF is still under development, and you might experience some problems with it. This will be better in upcoming releases.

Questions or comments, write to the ClanLib mailing list.