# Font addons

## API: al_font_destroy_font

Frees the memory being used by a font structure.
This is now wholly handled in the vtable.

## API: al_font_grab_font_from_bitmap

Work horse for grabbing a font from an Allegro bitmap.

Parameters:

- bmp: The bitmap with the glyphs drawn onto it
  (TODO: describe expected format - opaque yellow background,
  fully transparent boxes all of same height but possibly variable
  width, white, possibly anti-aliased glyphs)

- n: Number of unicode ranges in the bitmap.

- ranges: 'n' pairs of first and last unicode point to map glyphs to for
  each range.

Examples:

    int ranges[] = {32, 126};
    al_font_grab_font_from_bitmap(bitmap, 1, ranges)

    int ranges[] = {
        0x0020, 0x007F,  /* ASCII */
        0x00A1, 0x00FF,  /* Latin 1 */
        0x0100, 0x017F,  /* Extended-A */
        0x20AC, 0x20AC}; /* Euro */
    al_font_grab_font_from_bitmap(bitmap, 4, ranges)

The first example will grab glyphs for the 95 standard printable ASCII
characters, beginning with the space character (32) and ending with the
tilde character (126). The second example will map the first 96 glyphs
found in the bitmap to ASCII range, the next 95 glyphs to Latin 1, the
next 128 glyphs to Extended-A, and the last glyph to the Euro character.
(This is just the characters found in the Allegro 4 font.)

## API: al_font_init


## API: al_font_is_compatible_font

Returns non-zero if the two fonts are of similar type.

## API: al_font_load_font

Loads a font from disk. Will try to load a font from a bitmap if all else
fails.

## API: al_font_load_bitmap_font

Import routine for the Allegro bitmap font format.

## API: al_font_register_font_file_type

Informs Allegro of a new font file type, telling it how to load files of
this format.

## API: al_font_text_height

Returns the height of a character in the specified font.

## API: al_font_text_width

Calculates the length of a string in a particular font.

## API: al_font_textout

Writes the null terminated string str onto bmp at position x, y, using 
the specified font, foreground color and background color (-1 is trans).
If color is -1 and a proportional font is in use, it will be drawn
using the colors from the original font bitmap (the one imported into
the grabber program), which allows multicolored text output.
If count is not -1, write only the first 'count' code points.

## API: al_font_textout_centre

Like [al_font_textout], but uses the x coordinate as the centre rather than 
the left of the string.

## API: al_font_textout_justify

Like textout_ex(), but justifies the string to the specified area.

## API: al_font_textout_right

Like [al_font_textout], but uses the x coordinate as the right rather than 
the left of the string.

## API: al_font_textprintf

Formatted text output, using a printf() style format string.

## API: al_font_textprintf_centre

Like [al_font_textprintf], but uses the x coordinate as the centre rather
than the left of the string.

## API: al_font_textprintf_justify

Like [al_font_textprintf], but right justifies the string to the specified
area.

## API: al_font_textprintf_right

Like [al_font_textprintf], but uses the x coordinate as the right rather
than the left of the string.

## API: al_ttf_get_text_dimensions

Sometimes, the [al_font_text_width] and [al_font_text_height]
functions are not enough for exact text placement, so this function
returns some additional information.

Returned variables (all in pixel):
x, y - Offset to upper left corner of bounding box.
w, h - Dimensions of bounding box.
ascent - Ascent of the font.
descent - Descent of the font.

If the X is the position you specify to draw text, the meaning of
ascent and descent and the font height is like in the figure below.
Note that glyphs may go to the left and upwards of the X, in which
case x and y will have negative values.

    X------------------------
        /\         |        |
       /  \        |        |
      /____\       ascent   |
     /      \      |        |
    /        \     |        height
    ----------------        |
                   |        |
                   descent  |
                   |        |
    -------------------------

## API: al_ttf_load_font

Loads a truetype font from a file using the FreeType library. Quoting
from the FreeType FAQ this means support for many different font
formats:

*TrueType, OpenType, Type1, CID, CFF, Windows FON/FNT, X11 PCF, and
others*

The *size* parameter determines the size the font will be rendered at,
specified in pixel. The standard font size is measured in *units per
EM*, if you instead want to specify the size as the total height of
glyphs in pixel, pass it as a negative value.

Note: If you want to display text at multiple sizes, load the font
multiple times with different size parameters.

The only flag supported right now is:

* ALLEGRO_TTF_NO_KERNING - Do not use any kerning even if the font file
  supports it.
