Font addons

al_font_destroy_font

void al_font_destroy_font(ALLEGRO_FONT *f)

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

al_font_grab_font_from_bitmap

ALLEGRO_FONT *al_font_grab_font_from_bitmap(
   ALLEGRO_BITMAP *bmp,
   int ranges_n, int ranges[])

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

al_font_init

void al_font_init(void)

al_font_is_compatible_font

int al_font_is_compatible_font(ALLEGRO_FONT *f1, ALLEGRO_FONT *f2)

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

al_font_load_font

ALLEGRO_FONT *al_font_load_font(const char *filename, void *param)

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

al_font_load_bitmap_font

ALLEGRO_FONT *al_font_load_bitmap_font(const char *fname, void *param)

Import routine for the Allegro bitmap font format.

al_font_register_font_file_type

void al_font_register_font_file_type(const char *ext, ALLEGRO_FONT *(*load)(const char *filename, void *param))

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

al_font_text_height

int al_font_text_height(const ALLEGRO_FONT *f)

Returns the height of a character in the specified font.

al_font_text_width

int al_font_text_width(const ALLEGRO_FONT *f, const char *str, int count)

Calculates the length of a string in a particular font.

al_font_textout

void al_font_textout(const ALLEGRO_FONT *f, int x, int y,
   const char *str, int count)

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.

al_font_textout_centre

void al_font_textout_centre(const ALLEGRO_FONT *f, int x, int y,
   const char *str, int count)

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

al_font_textout_justify

void al_font_textout_justify(const ALLEGRO_FONT *f, int x1, int x2, int y,
   int diff, const char *str)

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

al_font_textout_right

void al_font_textout_right(const ALLEGRO_FONT *f, int x, int y,
   const char *str, int count)

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

al_font_textprintf

void al_font_textprintf(const ALLEGRO_FONT *f, int x, int y,
   const char *format, ...)

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

al_font_textprintf_centre

void al_font_textprintf_centre(const ALLEGRO_FONT *f, int x, int y,
   const char *format, ...)

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

al_font_textprintf_justify

void al_font_textprintf_justify(const ALLEGRO_FONT *f, int x1, int x2, int y,
   int diff, const char *format, ...)

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

al_font_textprintf_right

void al_font_textprintf_right(const ALLEGRO_FONT *f, int x, int y,
   const char *format, ...)

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

al_ttf_get_text_dimensions

void al_ttf_get_text_dimensions(ALLEGRO_FONT const *f, char const *text,
    int count, int *bbx, int *bby, int *bbw, int *bbh, int *ascent,
    int *descent)

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

al_ttf_load_font

ALLEGRO_FONT *al_ttf_load_font(char const *filename, int size, int flags)

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.

Last updated: 2009-03-25 12:35:23 UTC