Unit al5font

Description

Text font management.

See also

al5ttf

Overview

Classes, Interfaces, Objects and Records

Name Description
Record ALLEGRO_FONT A handle identifying any kind of font.

Functions and Procedures

FUNCTION al_load_bitmap_font (CONST filename: AL_STR): ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_load_bitmap_font_flags (CONST filename: AL_STR; flags: AL_INT): ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_load_font (CONST filename: AL_STR; size, flags: AL_INT): ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_grab_font_from_bitmap (bmp: ALLEGRO_BITMAPptr; n: AL_INT; VAR ranges: ARRAY OF AL_INT): ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_create_builtin_font: ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_draw_ustr (CONST font: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x, y: AL_FLOAT; flags: AL_INT; CONST ustr: ALLEGRO_USTRptr); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_draw_text (CONST font: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x, y: AL_FLOAT; flags: AL_INT; CONST str: AL_STR); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_draw_justified_text (CONST font: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x1, x2, y, diff: AL_FLOAT; flags: AL_INT; CONST str: AL_STR); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_draw_justified_ustr (CONST font: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x1, x2, y, diff: AL_FLOAT; flags: AL_INT; CONST str: ALLEGRO_USTRptr); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_get_text_width (CONST font: ALLEGRO_FONTptr; CONST str: AL_STR): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_get_ustr_width (CONST font: ALLEGRO_FONTptr; CONST ustr: ALLEGRO_USTRptr): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_get_font_line_height (CONST font: ALLEGRO_FONTptr): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_get_font_ascent (CONST font: ALLEGRO_FONTptr): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_get_font_descent (CONST font: ALLEGRO_FONTptr): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_destroy_font (font: ALLEGRO_FONTptr); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_get_ustr_dimensions (CONST f: ALLEGRO_FONTptr; CONST str: ALLEGRO_USTRptr; OUT bbx, bby, bbw, bbh: AL_INT); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_get_text_dimensions (CONST f: ALLEGRO_FONTptr; CONST str: AL_STR; VAR bbx, bby, bbw, bbh: AL_INT); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_init_font_addon: AL_BOOL; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_shutdown_font_addon; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_get_allegro_font_version: AL_UINT32; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_get_font_ranges (font: ALLEGRO_FONTptr; ranges_count: AL_INT; VAR ranges: ARRAY OF AL_INT): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
PROCEDURE al_draw_glyph (CONST f: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x, y: AL_FLOAT; codepoint: AL_INT); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
FUNCTION al_get_glyph_advance (CONST f: ALLEGRO_FONTptr; codepoint1, codepoint2: AL_INT): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;

Types

ALLEGRO_FONTptr = ˆALLEGRO_FONT;

Constants

ALLEGRO_NO_KERNING = -1;
ALLEGRO_ALIGN_LEFT = 0;
ALLEGRO_ALIGN_CENTRE = 1;
ALLEGRO_ALIGN_CENTER = 1;
ALLEGRO_ALIGN_RIGHT = 2;
ALLEGRO_ALIGN_INTEGER = 4;

Description

Functions and Procedures

FUNCTION al_load_bitmap_font (CONST filename: AL_STR): ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;

Loads 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
al_load_font
Loads a font from disk.
al_load_bitmap_flags
Loads an image file into a new ALLEGRO_BITMAPptr.
FUNCTION al_load_bitmap_font_flags (CONST filename: AL_STR; flags: AL_INT): ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_load_font (CONST filename: AL_STR; size, flags: AL_INT): ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;

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
al_init_font_addon
Initialise the font addon.
al_register_font_loader
al_load_bitmap_font_flags
al_load_ttf_font
FUNCTION al_grab_font_from_bitmap (bmp: ALLEGRO_BITMAPptr; n: AL_INT; VAR ranges: ARRAY OF AL_INT): ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;

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);
BEGIN
  al_grab_font_from_bitmap (Bitmap, 1, Ranges)
END;

VAR
  Ranges = ARRAY (0..7) OF AL_INT = (
    0x0020, 0x007F,  // ASCII
    0x00A1, 0x00FF,  // Latin 1
    0x0100, 0x017F,  // Extended-A
    0x20AC, 0x20AC   // Euro
  );
BEGIN
  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.
FUNCTION al_create_builtin_font: ALLEGRO_FONTptr; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
PROCEDURE al_draw_ustr (CONST font: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x, y: AL_FLOAT; flags: AL_INT; CONST ustr: ALLEGRO_USTRptr); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
PROCEDURE al_draw_text (CONST font: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x, y: AL_FLOAT; flags: AL_INT; CONST str: AL_STR); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;

Writes the string text 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
al_draw_justified_text
al_draw_multiline_text
PROCEDURE al_draw_justified_text (CONST font: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x1, x2, y, diff: AL_FLOAT; flags: AL_INT; CONST str: AL_STR); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
PROCEDURE al_draw_justified_ustr (CONST font: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x1, x2, y, diff: AL_FLOAT; flags: AL_INT; CONST str: ALLEGRO_USTRptr); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_get_text_width (CONST font: ALLEGRO_FONTptr; CONST str: AL_STR): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_get_ustr_width (CONST font: ALLEGRO_FONTptr; CONST ustr: ALLEGRO_USTRptr): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_get_font_line_height (CONST font: ALLEGRO_FONTptr): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_get_font_ascent (CONST font: ALLEGRO_FONTptr): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_get_font_descent (CONST font: ALLEGRO_FONTptr): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
PROCEDURE al_destroy_font (font: ALLEGRO_FONTptr); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
PROCEDURE al_get_ustr_dimensions (CONST f: ALLEGRO_FONTptr; CONST str: ALLEGRO_USTRptr; OUT bbx, bby, bbw, bbh: AL_INT); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
PROCEDURE al_get_text_dimensions (CONST f: ALLEGRO_FONTptr; CONST str: AL_STR; VAR bbx, bby, bbw, bbh: AL_INT); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_init_font_addon: AL_BOOL; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;

Initialise 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
Initializes the image addon.
al_init_ttf_addon
Initializes the TTF addon.
al_shutdown_font_addon
PROCEDURE al_shutdown_font_addon; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_get_allegro_font_version: AL_UINT32; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;

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

FUNCTION al_get_font_ranges (font: ALLEGRO_FONTptr; ranges_count: AL_INT; VAR ranges: ARRAY OF AL_INT): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;

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.
PROCEDURE al_draw_glyph (CONST f: ALLEGRO_FONTptr; color: ALLEGRO_COLOR; x, y: AL_FLOAT; codepoint: AL_INT); CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 
FUNCTION al_get_glyph_advance (CONST f: ALLEGRO_FONTptr; codepoint1, codepoint2: AL_INT): AL_INT; CDECL; EXTERNAL ALLEGRO_FONT_LIB_NAME;
 

Types

ALLEGRO_FONTptr = ˆALLEGRO_FONT;

Pointer to ALLEGRO_FONT.

Constants

ALLEGRO_NO_KERNING = -1;

TODO: Needs Allegro's file functions.

FONT_LOADER_FUNCTION = FUNCTION (CONST filename: AL_STRptr; size, flags: AL_INT): ALLEGRO_FONTptr; CDECL;

ALLEGRO_ALIGN_LEFT = 0;
 
ALLEGRO_ALIGN_CENTRE = 1;
 
ALLEGRO_ALIGN_CENTER = 1;
 
ALLEGRO_ALIGN_RIGHT = 2;
 
ALLEGRO_ALIGN_INTEGER = 4;
 

Generated by PasDoc 0.14.0. Generated on 2017-01-03 13:25:50.