Unit al5font

Initialises the font addon.

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

Similarly, if you wish to load truetype-fonts, do not forget to also call al_init_ttf_addon.

Returns

True on success, False on failure.

See also

al_init_image_addon

al_init_ttf_addon

Initializes the TTF addon.

al_shutdown_font_addon

Shuts down the font addon.

Shuts 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

Initialises the font addon.

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

Load a bitmap font from a file. This is done by first calling al_load_bitmap_flags and then al_grab_font_from_bitmap.

If you wanted to load an old A4 font, for example, it would be better to load the bitmap yourself in order to call al_convert_mask_to_alpha on it before passing it to al_grab_font_from_bitmap.

See also

al_load_bitmap_font_flags

Like al_load_bitmap_font but additionally takes a flags parameter.

al_load_font

Loads a font from disk.

al_load_bitmap_flags

Loads an image file into a new ALLEGRO_BITMAPptr.

Like al_load_bitmap_font but additionally takes a flags parameter. The flags parameter is a bitfield containing a combination of the following:

ALLEGRO_NO_PREMULTIPLIED_ALPHA

The same meaning as for al_load_bitmap_flags.

See also

al_load_bitmap_font

Load a bitmap font from a file.

al_load_bitmap_flags

Loads an image file into a new ALLEGRO_BITMAPptr.

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

The flags parameter is passed through to either of those functions. Bitmap and TTF fonts are also affected by the current bitmap flags at the time the font is loaded.

See also

al_destroy_font

Frees the memory being used by a font structure.

al_init_font_addon

Initialises the font addon.

al_load_bitmap_font_flags

Like al_load_bitmap_font but additionally takes a flags parameter.

al_load_ttf_font

Loads a TrueType font from a file using the FreeType library.

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.

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:

VAR
  Ranges: ARRAY [0..1] OF AL_INT = (32, 126);
  TextFont: ALLEGRO_FONTptr;
BEGIN
  TextFont := al_grab_font_from_bitmap (Bitmap, 1, Ranges)
END;

VAR
  Ranges: ARRAY [0..7] OF AL_INT = (
    $0020, $007F,  { ASCII }
    $00A1, $00FF,  { Latin 1 }
    $0100, $017F,  { Extended-A }
    $20AC, $20AC   { Euro }
  );
  TextFont: ALLEGRO_FONTptr;
BEGIN
  TextFont := al_grab_font_from_bitmap (Bitmap, 4, Ranges)
END;

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

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.

See also

al_load_bitmap

Loads an image file into a new ALLEGRO_BITMAPptr.

Creates a monochrome bitmap font (8x8 pixels per character).

This font is primarily intended to be used for displaying information in environments or during early runtime states where no external font data is available or loaded (e.g. for debugging).

The builtin font contains the following unicode character ranges:

0x0020 to 0x007F (ASCII)
0x00A1 to 0x00FF (Latin 1)
0x0100 to 0x017F (Extended A)
0x20AC to 0x20AC (euro currency symbol)

The font memory must be freed the same way as for any other font, using al_destroy_font.

Returns

Nil on an error.

See also

al_load_bitmap_font

Load a bitmap font from a file.

al_destroy_font

Frees the memory being used by a font structure.

Like al_draw_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

See also

al_draw_text

Writes the string str onto the target bitmap at position x, y, using the specified font.

al_draw_justified_ustr

Like al_draw_justified_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

al_draw_multiline_ustr

Like al_draw_multiline_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

Writes the string str onto the target bitmap 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.

It can also be combined with this flag:

• ALLEGRO_ALIGN_INTEGER - Always draw text aligned to an integer pixel position. This was formerly the default behaviour.

This function does not support newline characters (#10), but you can use al_draw_multiline_text for multi line text output.

See also

al_draw_ustr

Like al_draw_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

al_draw_justified_text

Like al_draw_text, but justifies the string to the region x1-x2.

al_draw_multiline_text

Like al_draw_text, but this function supports drawing multiple lines of text.

Like al_draw_text, but justifies the string to the region x1-x2.

The diff parameter is the maximum amount of horizontal space to allow between words. If justisfying the text would exceed diff pixels, or the string contains less than two words, then the string will be drawn left aligned.

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

• code(ALLEGRO_ALIGN_INTEGER) - Draw text aligned to integer pixel positions.

See also

al_draw_justified_textf

Formatted text output, using a Format style format string.

al_draw_justified_ustr

Like al_draw_justified_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

Like al_draw_justified_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

See also

al_draw_justified_text

Like al_draw_text, but justifies the string to the region x1-x2.

al_draw_justified_textf

Formatted text output, using a Format style format string.

Formatted text output, using a Format style format string. All parameters have the same meaning as with al_draw_text otherwise.

See also

al_draw_text

Writes the string str onto the target bitmap at position x, y, using the specified font.

al_draw_ustr

Like al_draw_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

Formatted text output, using a Format style format string. All parameters have the same meaning as with al_draw_justified_text otherwise.

See also

al_draw_justified_text

Like al_draw_text, but justifies the string to the region x1-x2.

al_draw_justified_ustr

Like al_draw_justified_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

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

See also

al_get_ustr_width

Like al_get_text_width but expects an ALLEGRO_USTR.

al_get_font_line_height

Returns the usual height of a line of text in the specified font.

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.

Like al_get_text_width but expects an ALLEGRO_USTR.

See also

al_get_text_width

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

al_get_ustr_dimensions

Like al_get_text_dimensions, except the text is passed as an ALLEGRO_USTR instead of STRING.

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.

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.

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

See also

al_get_text_width

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

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.

al_get_font_ascent

Returns the ascent of the specified font.

al_get_font_descent

Returns the descent of the specified font.

Returns the ascent of the specified font.

See also

al_get_font_descent

Returns the descent of the specified font.

al_get_font_line_height

Returns the usual height of a line of text in the specified font.

Returns the descent of the specified font.

See also

al_get_font_ascent

Returns the ascent of the specified font.

al_get_font_line_height

Returns the usual height of a line of text in the specified font.

Frees the memory being used by a font structure. Does nothing if passed Nil.

See also

al_load_font

Loads a font from disk.

Like al_get_text_dimensions, except the text is passed as an ALLEGRO_USTR instead of STRING.

See also

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.

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 pixels):

• x, y - Offset to upper left corner of bounding box.

• w, h - Dimensions of bounding box.

Note that glyphs may go to the left and upwards of the X, in which case x and y will have negative values.

See also

al_get_text_width

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

al_get_font_line_height

Returns the usual height of a line of text in the specified font.

al_get_ustr_dimensions

Like al_get_text_dimensions, except the text is passed as an ALLEGRO_USTR instead of STRING.

Gets information about all glyphs contained in a font, as a list of ranges. Ranges have the same format as with al_grab_font_from_bitmap.

Parameters

ranges_count

Is the maximum number of ranges that will be returned.

ranges

Should be an array with room for ranges_count * 2 elements. The even integers are the first unicode point in a range, the odd integers the last unicode point in a range.

Returns

The number of ranges contained in the font (even if it is bigger than ranges_count).

See also

al_grab_font_from_bitmap

Creates a new font from an Allegro bitmap.

Draws the glyph that corresponds with codepoint in the given color using the given font. If font does not have such a glyph, nothing will be drawn.

To draw a string as left to right horizontal text you will need to use al_get_glyph_advance to determine the position of each glyph. For drawing strings in other directions, such as top to down, use al_get_glyph_dimensions to determine the size and position of each glyph.

If you have to draw many glyphs at the same time, use al_hold_bitmap_drawing with True as the parameter, before drawing the glyphs, and then call al_hold_bitmap_drawing again with False as a parameter when done drawing the glyphs to further enhance performance.

See also

al_get_glyph_width

This function returns the width in pixels of the glyph that corresponds with codepoint in the font font.

al_get_glyph_dimensions

Sometimes, the al_get_glyph_width or al_get_glyph_advance functions are not enough for exact glyph placement, so this function returns some additional information, particularly if you want to draw the font vertically.

al_get_glyph_advance

This function returns by how much the x position should be advanced for left to right text drawing when the glyph that corresponds to codepoint1 has been drawn, and the glyph that corresponds to codepoint2 will be the next to be drawn.

This function returns the width in pixels of the glyph that corresponds with codepoint in the font font. Returns zero if the font does not have such a glyph.

See also

al_draw_glyph

Draws the glyph that corresponds with codepoint in the given color using the given font.

al_get_glyph_dimensions

Sometimes, the al_get_glyph_width or al_get_glyph_advance functions are not enough for exact glyph placement, so this function returns some additional information, particularly if you want to draw the font vertically.

al_get_glyph_advance

This function returns by how much the x position should be advanced for left to right text drawing when the glyph that corresponds to codepoint1 has been drawn, and the glyph that corresponds to codepoint2 will be the next to be drawn.

Sometimes, the al_get_glyph_width or al_get_glyph_advance functions are not enough for exact glyph placement, so this function returns some additional information, particularly if you want to draw the font vertically.

The function itself returns True if the character was present in font and False if the character was not present in font.

Returned variables (all in pixel):

• bbx, bby - Offset to upper left corner of bounding box.

• bbw, bbh - Dimensions of bounding box.

These values are the same as al_get_text_dimensions would return for a string of a single character equal to the glyph passed to this function. Note that glyphs may go to the left and upwards of the X, in which case x and y will have negative values.

If you want to draw a string verticallly, for Japanese or as a game effect, then you should leave bby + bbh space between the glyphs in the y direction for a regular placement.

If you want to draw a string horizontally in an extra compact way, then you should leave bbx + bbw space between the glyphs in the x direction for a compact placement.

In the figure below is an example of what bbx and bby may be like for a 2 glyph, and a g glyph of the same font compared to the result of al_get_glyph_width.

   al_get_glyph_width ()    al_get_glyph_width ()
          __|___                   __|__
         /      \                 /     \  
     bbx    bbw                 bbx   bbw    
    <-->+<------>+           <-->+<----->+   X baseline
    ˆ   |        |           ˆ   |       |   
bby |   |        |       bby |   |       |   
    v   |        |           |   |       |   
    +---+--------+           |   |       |
    ˆ   | *****  |           |   |       |
    |   |*    ** |           v   |       |
bbh |   |    **  |       bbh +---+-------+
    |   |  **    |           ˆ   | ***** |
    v   |********|           |   |*     *|
    +---+--------+           |   | ***** |
                             |   |      *|
                             |   | *    *|
                             v   |  **** |
                             +---+-------+

See also

al_draw_glyph

Draws the glyph that corresponds with codepoint in the given color using the given font.

al_get_glyph_width

This function returns the width in pixels of the glyph that corresponds with codepoint in the font font.

al_get_glyph_advance

This function returns by how much the x position should be advanced for left to right text drawing when the glyph that corresponds to codepoint1 has been drawn, and the glyph that corresponds to codepoint2 will be the next to be drawn.

al_get_glyph_advance

This function returns by how much the x position should be advanced for left to right text drawing when the glyph that corresponds to codepoint1 has been drawn, and the glyph that corresponds to codepoint2 will be the next to be drawn.

This function returns by how much the x position should be advanced for left to right text drawing when the glyph that corresponds to codepoint1 has been drawn, and the glyph that corresponds to codepoint2 will be the next to be drawn. This takes into consideration the horizontal advance width of the glyph that corresponds with codepoint1 as well as the kerning between the glyphs of codepoint1 and codepoint2.

Kerning is the process of adjusting the spacing between glyphs in a font, to obtain a more visually pleasing result. Kerning adjusts the space between two individual glyphs with an offset determined by the author of the font.

If you pass ALLEGRO_NO_KERNING as codepoint1 then al_get_glyph_advance will return 0. this can be useful when drawing the first character of a string in a loop.

Pass ALLEGRO_NO_KERNING as codepoint2 to get the horizontal advance width of the glyph that corresponds to codepoint1 without taking any kerning into consideration. This can be used, for example, when drawing the last character of a string in a loop.

This function will return zero if the glyph of codepoint1 is not present in the font. If the glyph of codepoint2 is not present in the font, the horizontal advance width of the glyph that corresponds to codepoint1 without taking any kerning into consideration is returned.

When drawing a string one glyph at the time from the left to the right with kerning, the x position of the glyph should be incremented by the result of al_get_glyph_advance applied to the previous glyph drawn and the next glyph to draw.

Note that the return value of this function is a recommended advance for optimal readability for left to right text determined by the author of the font. However, if you like, you may want to draw the glyphs of the font narrower or wider to each other than what al_get_glyph_advance returns for style or effect.

In the figure below is an example of what the result of al_get_glyph_advance may be like for two glypphs A and l of the same font that has kerning for the "Al" pair, without and with the ALLEGRO_NO_KERNING flag.

al_get_glyph_advance (font, ORD ('A'), ORD ('l'))
     ___|___
    /       \
    -------------
        /\   -|
       /  \   |
      /____\  |
     /      \ |
    /        \ \_
    -------------


al_get_glyph_advance (font, ORD ('A'), ALLEGRO_NO_KERNING)
     ____|____
    /         \
    ---------------
        /\     -|
       /  \     |
      /____\    |
     /      \   |
    /        \   \_
    ---------------

See also

al_draw_glyph

Draws the glyph that corresponds with codepoint in the given color using the given font.

al_get_glyph_width

This function returns the width in pixels of the glyph that corresponds with codepoint in the font font.

al_get_glyph_dimensions

Sometimes, the al_get_glyph_width or al_get_glyph_advance functions are not enough for exact glyph placement, so this function returns some additional information, particularly if you want to draw the font vertically.

Like al_draw_text, but this function supports drawing multiple lines of text. It will break text in lines based on its contents and the max_width parameter. The lines are then layed out vertically depending on the line_height parameter and drawn each as if al_draw_text was called on them.

A newline #10 in the text will cause a "hard" line break after its occurrence in the string. The text after a hard break is placed on a new line. Carriage return #12 is not supported, will not cause a line break, and will likely be drawn as a square or a space depending on the font.

The max_width parameter controls the maximum desired width of the lines. This function will try to introduce a "soft" line break after the longest possible series of words that will fit in max_length when drawn with the given font. A "soft" line break can occur either on a space or tab (#7) character.

However, it is possible that max_width is too small, or the words in text are too long to fit max_width when drawn with font. In that case, the word that is too wide will simply be drawn completely on a line by itself. If you don't want the text that overflows max_width to be visible, then use al_set_clipping_rectangle to clip it off and hide it.

The lines str was split into will each be drawn using the font, x, color and flags parameters, vertically starting at y and with a distance of line_height between them. If line_height is zero (0), the value returned by calling al_get_font_line_height on font will be used as a default instead.

The flags ALLEGRO_ALIGN_LEFT, ALLEGRO_ALIGN_CENTRE, ALLEGRO_ALIGN_RIGHT and ALLEGRO_ALIGN_INTEGER will be honoured by this function.

If you want to calculate the size of what this function will draw without actually drawing it, or if you need a complex and/or custom layout, you can use al_do_multiline_text.

See also

al_do_multiline_text

This function processes the text and splits it into lines as al_draw_multiline_text would, and then calls the callback cb once for every line.

al_draw_multiline_ustr

Like al_draw_multiline_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

al_draw_multiline_textf

Formatted text output, using a Format style format string.

Formatted text output, using a Format style format string. All parameters have the same meaning as with al_draw_multiline_text otherwise.

See also

al_draw_multiline_text

Like al_draw_text, but this function supports drawing multiple lines of text.

al_draw_multiline_ustr

Like al_draw_multiline_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

al_do_multiline_text

This function processes the text and splits it into lines as al_draw_multiline_text would, and then calls the callback cb once for every line.

Like al_draw_multiline_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

See also

al_draw_multiline_text

Like al_draw_text, but this function supports drawing multiple lines of text.

al_draw_multiline_textf

Formatted text output, using a Format style format string.

al_do_multiline_text

This function processes the text and splits it into lines as al_draw_multiline_text would, and then calls the callback cb once for every line.

This function processes the text and splits it into lines as al_draw_multiline_text would, and then calls the callback cb once for every line. This is useful for custom drawing of multiline text, or for calculating the size of multiline text ahead of time. See the documentation on al_draw_multiline_text for an explanation of the splitting algorithm.

For every line that this function splits text into the callback cb will be called once with the following parameters:

• line_num - the number of the line starting from zero and counting up.

• line - a pointer to the beginning character of the line (see below).

• size - the size of the line (0 for empty lines).

• extra - the same pointer that was passed to al_do_multiline_text.

Note that line is not guaranteed to be a NUL-terminated string (i.e. ANSISTRING), but will merely point to a character within text or to an empty string in case of an empty line. If you need a NUL-terminated string, you will have to copy line to a buffer and NUL-terminate it yourself (TODO: Check if it is done by the compiler when using ANSISTRING). You will also have to make your own copy if you need the contents of line after cb has returned, as line is not guaranteed to be valid after that. Remember that in some cases STRING is reference-counted by Pascal/Delphi.

If the callback cb returns False, al_do_multiline_text will stop immediately, otherwise it will continue on to the next line.

See also

al_draw_multiline_text

Like al_draw_text, but this function supports drawing multiple lines of text.

Like al_do_multiline_text, but using ALLEGRO_USTR instead of a STRING for text.

See also

al_draw_multiline_ustr

Like al_draw_multiline_text, except the text is passed as an ALLEGRO_USTR instead of a STRING.

Sets a font which is used instead if a character is not present. Can be chained, but make sure there is no loop as that would crash the application! Pass Nil to remove a fallback font again.

See also

al_get_fallback_font

Retrieves the fallback font for this font or Nil.

al_draw_glyph

Draws the glyph that corresponds with codepoint in the given color using the given font.

al_draw_text

Writes the string str onto the target bitmap at position x, y, using the specified font.

al_get_fallback_font

Retrieves the fallback font for this font or Nil.

Retrieves the fallback font for this font or Nil.

See also

al_set_fallback_font

Sets a font which is used instead if a character is not present.

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.

Callback declaration for al_do_multiline_text.

Callback declaration for al_do_multiline_ustr.