Fonts

Allegro provides routines for loading fonts directly from GRX format .fnt files, 8x8 or 8x16 BIOS format .fnt files, from bitmap images, from datafiles or you can import a multiple-range Unicode font by writing a .txt script that specifies a number of different source files for each range of characters.

By default, Allegro can only use bitmapped (non-scalable) fonts. If you want to use TrueType fonts, you will need to use an add-on library which allows you to load them on the fly (like AllegTTF or Glyph Keeper, listed among others at http://www.allegro.cc/) and render them directly, or generate a bitmapped version of a TrueType font with tools like TTF2PCX (http://www.talula.demon.co.uk/ttf2pcx/index.html).


void register_font_file_type(const char *ext, FONT *(*load)(const char *filename, RGB *pal, void *param));

Informs the load_font() functions of a new file type, providing a routine to read fonts in this format. The function you supply must follow the following prototype: 
      FONT *load_my_font(const char *filename, RGB *pal, void *param)
      {
         ...
      }
The pal parameter can optionally be used to return a palette for the FONT. The parameter param can be anything you like: you can use this to pass information to your loading routine, such as for instance the font height, the character range to load or the index number of a font in a datafile. If you choose to write your own font loading code, your function should be prepared to deal with a value of NULL for either of these parameters.
See also: load_font.
FONT *load_font(const char *filename, RGB *pal, void *param);

Loads a font from a file. At present, this supports loading fonts from a GRX format .fnt file, a 8x8 or 8x16 BIOS format .fnt file, a datafile or any bitmap format that can be loaded by load_bitmap().

If the font contains palette information, then the palette is returned in the second parameter, which should be an array of 256 RGB structures (a PALETTE). The pal argument may be NULL. In this case, the palette data, if present, is simply not returned.

The third parameter can be used to pass specific information to a custom loader routine. Normally, you can just leave this as NULL. Note that another way of loading fonts is embedding them into a datafile and using the datafile related functions.

Example: 

      FONT *myfont;
      PALETTE palette;
      ...
      myfont = load_font("my_font.pcx", palette, NULL);
      if (!myfont)
         abort_on_error("Couldn't load font!");
      ...
      textout_centre_ex(screen, myfont, "This is my own pretty font!",
                        SCREEN_W / 2, SCREEN_H / 2, white, black);
      ...
      destroy_font(myfont);

Return value: Returns a pointer to the font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: register_font_file_type, load_bitmap, load_dat_font, load_bios_font, load_grx_font, load_grx_or_bios_font, load_bitmap_font, load_txt_font, destroy_font.
Examples using this: exfont.
void destroy_font(FONT *f);

Frees the memory being used by a font structure. Don't use this on the default global Allegro font or any text routines using it could crash. You should use this only on fonts you have loaded manually after you are done with them, to prevent memory leaks in your program.
See also: load_datafile_object, load_font.
Examples using this: exfont.
void make_trans_font(FONT *f);

This function converts a font to use transparency for drawing. That is, each glyph in the font will be drawn with draw_trans_sprite, so you can use the same blenders as with draw_trans_sprite to draw the font. One common use of this is to load a bitmap font with an alpha channel, and therefore get anti-aliased text output by using Allegro's alpha blender. Here's an example how to do that: 
   FONT *f = load_font("alphafont.tga", NULL, NULL);
   make_trans_font(f);
   set_alpha_blender();
   textprintf_centre_ex(screen, f, 320, 240, -1, -1, "Anti-aliased Font!");
See also: is_trans_font, set_alpha_blender, load_font, draw_trans_sprite.
int is_trans_font(FONT *f)

This function checks if the given font is a color font using draw_trans_sprite to render glyphs.

Return value: Returns TRUE if the font uses transparency, FALSE if it does not.

See also: make_trans_font, is_color_font, is_mono_font.
int is_color_font(FONT *f)

This function checks if the given font is a color font, as opposed to a monochrome font.

Return value: Returns TRUE if the font is a color font, FALSE if it is not.

See also: is_trans_font, is_mono_font.
int is_mono_font(FONT *f)

This function checks if the given font is a mono font, as opposed to a color font.

Return value: Returns TRUE if the font is a monochrome font, FALSE if it is not.

See also: is_trans_font, is_color_font.
int font_has_alpha(FONT *f)

This function goes through all pixels of all glyphs in the font and looks for alpha values.

Return value: Returns TRUE if any alpha pixels are found, else FALSE.

See also: is_trans_font.
int *is_compatible_font(FONT *f1, FONT *f2)

This function compares the two fonts, which you can use to find out if Allegro is capable of merging them.

Return value: Returns TRUE if the two fonts are of the same general type (both are color fonts or both are monochrome fonts, for instance).

See also: merge_fonts, is_trans_font, is_color_font, is_mono_font.
int get_font_ranges(FONT *f)

Use this function to find out the number of character ranges in a font. You should query each of these ranges with get_font_range_begin() and get_font_range_end() to find out what characters are available in the font. Example: 
      FONT *f;
      int range;
      int n;
      ...
      
      range = get_font_ranges(f);
      printf("The font has %d character ranges:\n", range);
      for (n = 0; n < range; n++)
         printf("Range %d from 0x%03x - 0x%03x\n",
                get_font_range_begin(f, n),
                get_font_range_end(f, n));

Return value: Returns the number of continuous character ranges in a font, or -1 if that information is not available.

See also: get_font_range_begin, get_font_range_end, transpose_font.
int get_font_range_begin(FONT *f, int range)

This function allows you to find out the start of a specific character range for a font. You can pass -1 for the `range' parameter if you want to know the start of the whole font range, or a number from 0 to (but not including) get_font_ranges(f) to get the start of a specific character range in the font. Example: 
      printf("The font has a character range of %d - %d\n",
             get_font_range_begin(font, -1),
             get_font_range_end(font, -1));

Return value: Returns the first character in the font range, or -1 if that information is not available.

See also: get_font_ranges, get_font_range_end, transpose_font.
int get_font_range_end(FONT *f, int range)

This function allows you to find out the index to the last character of a character range for a font. You can pass -1 for the range parameter if you want to know the start of the whole font range, or a number from 0 to (but not including) get_font_ranges(f) to get the start of a specific character range in the font. You should check the start and end of all font ranges to see if a specific character is actually available in the font. Not all characters in the range returned by get_font_range_begin(f, -1) and get_font_range_end(f, -1) need to be available! Example: 
      printf("The font has a character range of %d - %d\n",
             get_font_range_begin(font, -1),
             get_font_range_end(font, -1));

Return value: Returns the last character in the font range, or -1 if that information is not available.

See also: get_font_ranges, get_font_range_begin, transpose_font.
FONT *extract_font_range(FONT *f, int begin, int end)

This function extracts a character range from a font and returns a new font that contains only the range of characters selected by this function. You can pass -1 for either the lower or upper bound if you want to select all characters from the start or to the end of the font. Example: 
      FONT *myfont;
      FONT *capitals;
      FONT *fontcopy;
      ...
      /* Create a font of only capital letters */
      capitals = extract_font_range(myfont, 'A', 'Z');

      /* Create a copy of the font */
      fontcopy = extract_font_range(myfont, -1, -1);
      ...
      destroy_font(capitals);
      destroy_font(fontcopy);

Return value: Returns a pointer to the new font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: get_font_range_begin, get_font_range_end, merge_fonts, transpose_font.
Examples using this: exfont.
int transpose_font(FONT *f, int drange)

This function transposes all characters in a font, effectively remapping the font. Example: 
      FONT *myfont;
      FONT *capitals;
      ...
      /* Create a font of only capital letters */
      capitals = extract_font_range(myfont, 'A', 'Z');

      /* Now transpose the characters in the font so that they will be used */
      /*  for the lower case letters a-z */
      transpose_font(capitals, 'a'-'A');
      textout_ex(screen, capitals, "allcaps",
                 100, 100, makecol(255,255,255), 0);

Return value: Returns 0 on success, -1 on failure.

See also: get_font_range_begin, get_font_range_end, merge_fonts, extract_font_range.
FONT *merge_fonts(FONT *f1, FONT *f2)

This function merges the character ranges from two fonts and returns a new font containing all characters in the old fonts. In general, you cannot merge fonts of different types (eg, TrueType fonts and bitmapped fonts), but as a special case, this function can promote a monochrome bitmapped font to a color font and merge those. Example: 
      FONT *myfont;
      FONT *myfancy_font;
      FONT *lower_range;
      FONT *upper_range;
      FONT *capitals;
      FONT *combined_font;
      FONT *tempfont;
      ...
      /* Create a font that contains the capitals from  */
      /* the fancy font but other characters from myfont */
      lower_range = extract_font_range(myfont, -1, 'A'-1);
      upper_range = extract_font_range(myfont, 'Z'+1, -1);
      capitals = extract_font_range(myfancy_font, 'A', 'Z');

      tempfont = merge_fonts(lower_range, capitals);
      combined_font = merge_fonts(tempfont, upper_range);

      /* Clean up temporary fonts */
      destroy_font(lower_range);
      destroy_font(upper_range);
      destroy_font(capitals);
      destroy_font(tempfont);

Return value: Returns a pointer to the new font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: extract_font_range, is_trans_font, is_color_font, is_mono_font.
Examples using this: exfont.
FONT *load_dat_font(const char *filename, RGB *pal, void *param)

Loads a FONT from an Allegro datafile. You can set param parameter to point to an array that holds two strings that identify the font and the palette in the datafile by name. The first string in this list is the name of the font. You can pass NULL here to just load the first font found in the datafile. The second string can be used to specify the name of the palette associated with the font. This is only returned if the pal parameter is not NULL. If you pass NULL for the name of the palette, the last palette found before the font was found is returned. You can also pass NULL for param, which is treated as if you had passed NULL for both strings separately. In this case, the function will simply load the first font it finds from the datafile and the palette that precedes it.

For example, suppose you have a datafile named `fonts.dat' with the following contents: 

      FONT  FONT_1_DATA
      FONT  FONT_2_DATA
      FONT  FONT_3_DATA
      PAL   FONT_1_PALETTE
      PAL   FONT_2_PALETTE
Then the following code will load FONT_1_DATA as a FONT and return FONT_1_PALETTE as the palette: 
      FONT *f;
      PALETTE pal;
      char *names[] = { "FONT_1_DATA", "FONT_1_PALETTE" }
      
      f = load_dat_font("fonts.dat", pal, names);
If instead you want to load the second font, FONT_2, from the datafile, you would use: 
      FONT *f;
      PALETTE pal;
      char *names[] = { "FONT_2_DATA", "FONT_2_PALETTE" }
      
      f = load_dat_font("fonts.dat", pal, names);
If you want to load the third font, but not bother with a palette, use: 
      FONT *f;
      char *names[] = { "FONT_3_DATA", NULL }
      
      f = load_dat_font("fonts.dat", NULL, names);

Return value: Returns a pointer to the font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: register_font_file_type, load_font.
FONT *load_bios_font(const char *filename, RGB *pal, void *param)

Loads a 8x8 or 8x16 BIOS format font. You shouldn't normally call this routine directly.

Return value: Returns a pointer to the font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: register_font_file_type, load_font.
FONT *load_grx_font(const char *filename, RGB *pal, void *param)

Loads a GRX format font. You shouldn't normally call this routine directly.

Return value: Returns a pointer to the font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: register_font_file_type, load_font.
FONT *load_grx_or_bios_font(const char *filename, RGB *pal, void *param)

Loads either a BIOS or GRX format font. You shouldn't normally call this routine directly.

Return value: Returns a pointer to the font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: register_font_file_type, load_font.
FONT *load_bitmap_font(const char *filename, RGB *pal, void *param)

Tries to grab a font from a bitmap. The bitmap can be in any format that load_bitmap understands.

The size of each character is determined by the layout of the image, which should be a rectangular grid containing all the ASCII characters from space (32) up to the tilde (126). The way the characters are separated depends on the color depth of the image file:

Note that in each horizontal row the bounding boxes around the characters should align and have the same height.

Probably the easiest way to get to grips with how this works is to load up the `demo.dat' file and export the TITLE_FONT into a PCX file. Have a look at the resulting picture in your paint program: that is the format a font should be in.

Take care with high and true color fonts: Allegro will convert these to the current color depth when you load the font. If you try to use a font on a bitmap with a different color depth Allegro will do color conversions on the fly, which will be rather slow. For optimal performance you should set the color depth to the color depth you want to use before loading any fonts.

Return value: Returns a pointer to the font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: register_font_file_type, load_font, load_bitmap, set_color_depth, grab_font_from_bitmap.
FONT *grab_font_from_bitmap(BITMAP *bmp)

This function is the work-horse of load_bitmap_font, and can be used to grab a font from a bitmap in memory. You can use this if you want to generate or modify a font at runtime. The bitmap should follow the layout described for load_bitmap_font.

Return value: Returns a pointer to the font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: load_bitmap_font.
FONT *load_txt_font(const char *filename, RGB *pal, void *param)

This function can be used to load scripted fonts. The script file contains a number of lines in the format "filename start end", which specify the source file for that range of characters, the Unicode value of the first character in the range, and the end character in the range (optional, if left out, the entire input file will be grabbed). If the filename is replaced by a hyphen, more characters will be grabbed from the previous input file. For example, the script: 
      ascii.fnt 0x20 0x7F
      - 0xA0 0xFF
      dingbats.fnt 0x1000
would import the first 96 characters from ascii.fnt as the range 0x20-0x7F, the next 96 characters from ascii.fnt as the range 0xA0-0xFF, and the entire contents of dingbats.fnt starting at Unicode position 0x1000.

Return value: Returns a pointer to the font or NULL on error. Remember that you are responsible for destroying the font when you are finished with it to avoid memory leaks.

See also: register_font_file_type, load_font.
Back to contents