# Font addons

These functions are declared in the following header file.
Link with allegro_font.

    #include <allegro5/allegro_font.h>

## General font routines

### API: ALLEGRO_FONT

A handle identifying any kind of font. Usually you will create it with
[al_load_font] which supports loading all kinds of TrueType fonts supported by
the FreeType library. If you instead pass the filename of a bitmap file, it will
be loaded with [al_load_bitmap] and a font in Allegro's bitmap font format will
be created from it with [al_grab_font_from_bitmap].

### API: al_init_font_addon

Initialise the font addon.

Note that if you intend to load bitmap fonts, you will need to initialise
allegro_image separately (unless you are using another library to load images).

See also: [al_init_image_addon], [al_init_ttf_addon], [al_shutdown_font_addon]

### API: al_shutdown_font_addon

Shut down the font addon. This is done automatically at program exit,
but can be called any time the user wishes as well.

See also: [al_init_font_addon]

### API: al_load_font

Loads a font from disk. This will use [al_load_bitmap_font] if you pass the
name of a known bitmap format, or else [al_load_ttf_font].

See also: [al_destroy_font], [al_init_font_addon]

### API: al_destroy_font

Frees the memory being used by a font structure.

See also: [al_load_font]

### API: al_register_font_loader

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

The extension should include the leading dot ('.') character.
It will be matched case-insensitively.

The `load_font` argument may be NULL to unregister an entry.

Returns true on success, false on error.
Returns false if unregistering an entry that doesn't exist.

See also: [al_init_font_addon]

### API: al_get_font_line_height

Returns the usual height of a line of text in the specified font. For bitmap
fonts this is simply the height of all glyph bitmaps. For truetype fonts it
is whatever the font file specifies. In particular, some special glyphs may be
higher than the height returned here.

See also: [al_get_text_width], [al_get_text_dimensions]

### API: al_get_text_width

Calculates the length of a string in a particular font, in pixels.

See also: [al_get_ustr_width], [al_get_font_line_height],
[al_get_text_dimensions]

### API: al_get_ustr_width

Like [al_get_text_width] but expects an ALLEGRO_USTR.

See also: [al_get_text_width], [al_get_ustr_dimensions]

### 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.

See also: [al_draw_ustr], [al_draw_textf], [al_draw_justified_text]

### API: al_draw_ustr

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

See also: [al_draw_text], [al_draw_justified_ustr]

### API: al_draw_justified_text

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

See also: [al_draw_justified_textf], [al_draw_justified_ustr]

### API: al_draw_justified_ustr

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

See also: [al_draw_justified_text], [al_draw_justified_textf].

### 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.

See also: [al_draw_text], [al_draw_ustr]

### API: al_draw_justified_textf

Like [al_draw_justified_text] and [al_draw_textf].

See also: [al_draw_justified_text], [al_draw_justified_ustr].

### 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  |
                   |        |
    -------------------------

See also: [al_get_text_width], [al_get_font_line_height],
[al_get_ustr_dimensions]

### API: al_get_ustr_dimensions

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

See also: [al_get_text_dimensions]

### API: al_get_allegro_font_version

Returns the (compiled) version of the addon, in the same format as
[al_get_allegro_version].

## Bitmap fonts

### API: al_grab_font_from_bitmap

Creates a new font from an Allegro bitmap. You can delete the bitmap after the
function returns as the font will contain a copy for itself.

Parameters:

- bmp: The bitmap with the glyphs drawn onto it
- n: Number of unicode ranges in the bitmap.
- ranges: 'n' pairs of first and last unicode point to map glyphs to for
  each range.

The bitmap format is as in the following example, which contains three glyphs
for 1, 2 and 3.

    .............
    . 1 .222.333.
    . 1 .  2.  3.
    . 1 .222.333.
    . 1 .2  .  3.
    . 1 .222.333.
    .............

In the above illustration, the dot is for pixels having the background color. It
is determined by the color of the top left pixel in the bitmap. There should be
a border of at least 1 pixel with this color to the bitmap edge and between all
glyphs.

Each glyph is inside a rectangle of pixels not containing the background
color. The height of all glyph rectangles should be the same, but the width
can vary.

The placement of the rectangles does not matter, except that glyphs are scanned
from left to right and top to bottom to match them to the specified unicode
codepoints.

The glyphs will simply be drawn using [al_draw_bitmap], so usually you will want
the rectangles filled with full transparency and the glyphs drawn in opaque
white.

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.)

See also: [al_load_bitmap], [al_grab_font_from_bitmap]

### API: al_load_bitmap_font

Load a bitmap font from. It does this by first calling [al_load_bitmap] and then
[al_grab_font_from_bitmap]. If you want to for example load an old A4 font,
you could load the bitmap yourself, then call [al_convert_mask_to_alpha] on it
and only then pass it to [al_grab_font_from_bitmap].

## TTF fonts

These functions are declared in the following header file.
Link with allegro_ttf.

    #include <allegro5/allegro_ttf.h>

### 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].

### 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.

See also: [al_init_ttf_addon], [al_load_ttf_font_f]

### API: al_load_ttf_font_f

Like [al_load_ttf_font], but the font is read from the file handle. The filename
is only used to find possible additional files next to a font file.

Note: The file handle is owned by the returned ALLEGRO_FONT object and must not
be freed by the caller, as FreeType expects to be able to read from it at a
later time.

### API: al_get_allegro_ttf_version

Returns the (compiled) version of the addon, in the same format as
[al_get_allegro_version].
