# Font addons

## API: al_destroy_font

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

## API: al_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_init_font_addon

## API: al_load_bitmap_font

## API: al_load_font

Loads a font from disk.

## API: al_load_bitmap_font

Import routine for the Allegro bitmap font format.

## API: al_register_font_extension

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

## API: al_get_font_line_height

Returns the height of a character in the specified font.

## API: al_get_text_width

Calculates the length of a string in a particular font.

## API: al_get_ustr_width

See [al_get_text_width].

## API: al_draw_text

Writes the 0-terminated string `text` onto `bmp` at position `x`, `y`, using 
the specified `font`.

The `flags` parameter can be 0 or one of the following flags:

- ALLEGRO_ALIGN_LEFT - Draw the text left-aligned (same as 0).
- ALLEGRO_ALIGN_CENTRE - Draw the text centered around the given position.
- ALLEGRO_ALIGN_RIGHT - Draw the text right-aligned to the given position.

## API: al_draw_ustr

Like [al_draw_text], except the text is passed as an ALLEGRO_USTR instead of
a 0-terminated char array.

## API: al_draw_justified_text

Like [al_draw_text](), but justifies the string to the specified area.

## API: al_draw_justified_ustr

See [al_draw_justified_text].

## API: al_draw_textf

Formatted text output, using a printf() style format string, all parameters
have the same meaning as with [al_draw_text] otherwise.

## API: al_draw_justified_textf

Like [al_draw_justified_text] and [al_draw_textf].

## API: al_get_text_dimensions

Sometimes, the [al_get_text_width] and [al_get_font_line_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 line 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_get_ustr_dimensions

See [al_get_text_dimensions].

## API: al_load_ttf_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.

## API: al_init_ttf_addon

Call this after [al_init_font_addon] to make [al_load_font] recognize
.ttf and other formats supported by [al_load_ttf_font].
