# Text drawing and fonts.

AllegroGL now provides mechanisms for converting Allegro FONTs to a format which is more usable in OpenGL. More...

## Text Drawing and Font conversion

- int allegro_gl_printf (AL_CONST FONT *f, float x, float y, float z, int color, AL_CONST char *format,...)
    Equivalent to:.
- int allegro_gl_printf_ex (AL_CONST FONT *f, float x, float y, float z, AL_CONST char *format,...)
    Prints a formatted string (printf style) on the screen.
- FONT * allegro_gl_convert_allegro_font (FONT *f, int type, float scale)
    Equivalent to:.
- FONT * allegro_gl_convert_allegro_font_ex (FONT *f, int type, float scale, GLint format)
    Converts a regular Allegro FONT to the AGL format for 3D display.
- void allegro_gl_set_font_generation_mode (int mode)
    Set the font generation mode for system fonts.
- FONT * allegro_gl_load_system_font (char *name, int style, int w, int h)
    Short hand for aglf_load_system_font_ex(name, AGL_FONT_TYPE_OUTLINE, style, w, h, 0.0f, 32, 256).
- FONT * allegro_gl_load_system_font_ex (char *name, int type, int style, int w, int h, float depth, int start, int end)
    Loads a system font.
- void allegro_gl_destroy_font (FONT *f)
    void allegro_gl_destroy_font(FONT *usefont)
- size_t allegro_gl_list_font_textures (FONT *f, GLuint *ids, size_t max_num_id)
    List the texture ID of all textures forming the specified font.
- #define AGL_FONT_TYPE_DONT_CARE -1
    Indicates that you don't really care how a font will be converted.
- #define AGL_FONT_TYPE_BITMAP 0
    Indicates that you want fonts to be converted to a bitmap format.
- #define AGL_FONT_TYPE_OUTLINE 1
    Indicates that you want fonts to be converted to an outline format.
- #define AGL_FONT_TYPE_TEXTURED 2
    Indicates that you want fonts to be converted to a texture format.
- #define AGL_FONT_STYLE_BOLD 1
    Creates a font with bold characters.
- #define AGL_FONT_STYLE_BLACK 2
    Creates a font with black (strong bold) characters.
- #define AGL_FONT_STYLE_ITALIC 4
    Creates a font with italicized characters.
- #define AGL_FONT_STYLE_UNDERLINE 8
    Creates a font with underlined characters.
- #define AGL_FONT_STYLE_STRIKEOUT 16
    Creates a font with striked out characters.
- #define AGL_FONT_STYLE_ANTI_ALIASED 32
    Creates a font with anti-aliased characters.
- #define AGL_FONT_POLYGONS 1
    Font generation mode.
- #define AGL_FONT_LINES 2
    Font generation mode.

## Detailed Description

AllegroGL now provides mechanisms for converting Allegro FONTs to a format which is more usable in OpenGL.

You can also load system fonts (such as Arial and Courrier) and draw using those. Allegro FONTs should still work if you use textout, textprintf, etc on them. However, converted Allegro FONTs will not work with these functions. You will have to use AllegroGL functions to work with AllegroGL FONTs.

## Define Documentation

#define AGL_FONT_TYPE_DONT_CARE -1

Indicates that you don't really care how a font will be converted.

AGL will pick the best format for you.

Definition at line 618 of file alleggl.h.

Referenced by allegro_gl_convert_allegro_font_ex().

#define AGL_FONT_TYPE_BITMAP 0

Indicates that you want fonts to be converted to a bitmap format.

Bitmaps are used to represent characters with one bit per pixel, and are usually very slow to draw, as they stall the 3D pipeline. Note that you can't scale, rotate or place text with a z coordinate if you use this style. A display list will be created.

See also:
  allegro_gl_convert_allegro_font(), allegro_gl_printf()

Definition at line 629 of file alleggl.h.

Referenced by allegro_gl_convert_allegro_font_ex(), allegro_gl_destroy_font(), and allegro_gl_printf_ex().

#define AGL_FONT_TYPE_OUTLINE 1

Indicates that you want fonts to be converted to an outline format.

Outlined mode is a vector-style font. Characters are represented by a set of polygons and lines. This style of fonts is fast to draw, and can be scaled, rotated, etc, since they are just vectors. A display list will be created.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL.

See also:
  allegro_gl_convert_allegro_font(), allegro_gl_printf()

Definition at line 641 of file alleggl.h.

Referenced by allegro_gl_convert_allegro_font_ex(), allegro_gl_destroy_font(), allegro_gl_load_system_font(), and allegro_gl_printf_ex().

#define AGL_FONT_TYPE_TEXTURED 2

Indicates that you want fonts to be converted to a texture format.

Each character is represented by a textured quad. The texture is common for all characters of the same font, and it will automatically be uploaded to the video card when needed. Drawing text with this type of font is the fastest since only two triangles are needed per character. Textured text can also be scaled and rotated. A display list will be created.

See also:
  allegro_gl_convert_allegro_font(), allegro_gl_printf()

Definition at line 653 of file alleggl.h.

Referenced by allegro_gl_convert_allegro_font_ex(), allegro_gl_destroy_font(), and allegro_gl_printf_ex().

#define AGL_FONT_STYLE_BOLD 1

Creates a font with bold characters.

System fonts only.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL

Definition at line 661 of file alleggl.h.

#define AGL_FONT_STYLE_BLACK 2

Creates a font with black (strong bold) characters.

System fonts only.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL.

Definition at line 666 of file alleggl.h.

#define AGL_FONT_STYLE_ITALIC 4

Creates a font with italicized characters.

System fonts only.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL.

Definition at line 671 of file alleggl.h.

#define AGL_FONT_STYLE_UNDERLINE 8

Creates a font with underlined characters.

System fonts only.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL.

Definition at line 676 of file alleggl.h.

#define AGL_FONT_STYLE_STRIKEOUT 16

Creates a font with striked out characters.

System fonts only.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL.

Definition at line 681 of file alleggl.h.

#define AGL_FONT_STYLE_ANTI_ALIASED 32

Creates a font with anti-aliased characters.

System fonts only. Anti-aliasing may not be available, and no error will be reported if such is the case.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL.

Definition at line 688 of file alleggl.h.

#define AGL_FONT_POLYGONS 1

Font generation mode.

System fonts only. Indicates that you want outline system fonts to be generated using polygons.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL.

See also:
  allegro_gl_load_system_font(), allegro_gl_load_system_font_ex()

Definition at line 696 of file alleggl.h.

#define AGL_FONT_LINES 2

Font generation mode.

System fonts only. Indicates that you want outline system fonts to be generated using lines.

Deprecated:
  Non-textured fonts will be dropped from AllegroGL.

See also:
  allegro_gl_load_system_font(), allegro_gl_load_system_font_ex()

Definition at line 705 of file alleggl.h.

## Function Documentation

int allegro_gl_printf | ( | AL_CONST FONT * | f,
|  | float | x,
|  | float | y,
|  | float | z,
|  | int | color,
|  | AL_CONST char * | format,
|  |  | ... |
| ) |  |  |

Equivalent to:.

       r = getr(color);
       g = getg(color);
       b = getb(color);
       a = geta(color);
       glColor4f(r, g, b, a);
       allegro_gl_printf_ex(f, x, y, z,
                            format, ...);

Note that the current primary color is not preserved.

Definition at line 67 of file aglf.c.

References allegro_gl_printf_ex().

int allegro_gl_printf_ex | ( | AL_CONST FONT * | f,
|  | float | x,
|  | float | y,
|  | float | z,
|  | AL_CONST char * | format,
|  |  | ... |
| ) |  |  |

Prints a formatted string (printf style) on the screen.

Parameters:

  | f | Which font to use.
  | x,y,z | Coordinates to print at. They specify the top-left corner of the text position.
  | format | The format string (see printf() for details)

For bitmap fonts, the raster position is set to (x,y), 'z' is ignored. The current modelview matrix applies to this code so you may want to use glLoadIdentity() beforehand. On the other hand, you can use the modelview matrix to apply transformations to the text. This will only work with textured or vector (outline) fonts. This function only accepts AllegroGL formated fonts, as converted by allegro_gl_convert_allegro_font(), or loaded by allegro_gl_load_system_font() or allegro_gl_load_system_font_ex().

Texturing must be enabled for this function to work with AGL_FONT_TYPE_TEXTURED fonts.

Remember to use `glEnable(GL_TEXTURE_2D)` to enable texturing.

The resulting size may not be what you expect. For bitmaped fonts, there is nothing you can do about this appart changing the font itself. Textured and Vector fonts are more flexible, in that you can use glScale to adjust the size of the characters.

If you need to draw the text without the black backround, we suggest you set up a proper blending mode prior to drawing the text, such as:

         glEnable(GL_BLEND);
         glBlendFunc(GL_ONE, GL_ONE_MINUS_SRC_COLOR);

If you want to emulate the Allegro drawing mode (no blending at all), then you should use the folowing code instead:

         glDisable(GL_DEPTH_TEST);
         glEnable(GL_BLEND);

         glBlendFunc(GL_DST_COLOR, GL_ZERO);
         allegro_gl_printf();

         glBlendFunc(GL_ONE, GL_ONE);
         allegro_gl_printf();    // Same as the one above!

         glEnable(GL_DEPTH_TEST);

Have a look at NeHe's Tutorial #20 for details on this technique. http://nehe.gamedev.net/

The most flexible way to use fonts, though, is to use alpha textures based on a greyscale font. Set the texture format to `GL_ALPHA4` or `GL_ALPHA8` before creating the (textured) font. Then you can set the colour and blend modes like so:

        glBlendFunc (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
        allegro_gl_printf_ex(my_font, x, y, z, "Hi!")

Returns:
  The number of characters printed.

Definition at line 169 of file aglf.c.

References AGL_FONT_TYPE_BITMAP, AGL_FONT_TYPE_OUTLINE, and AGL_FONT_TYPE_TEXTURED.

Referenced by allegro_gl_printf().

FONT* allegro_gl_convert_allegro_font | ( | FONT * | f,
|  | int | type,
|  | float | scale |
| ) |  |  |

Equivalent to:.

       allegro_gl_convert_allegro_font_ex(f, type, scale, format_state);

Where format_state is the last specified format to allegro_gl_set_texture_format(). If allegro_gl_set_texture_format() was not previously called, AllegroGL will try to determine the texture format automatically.

Deprecated:

Definition at line 623 of file fontconv.c.

References allegro_gl_convert_allegro_font_ex(), and allegro_gl_get_texture_format().

FONT* allegro_gl_convert_allegro_font_ex | ( | FONT * | f,
|  | int | type,
|  | float | scale,
|  | GLint | format |
| ) |  |  |

Converts a regular Allegro FONT to the AGL format for 3D display.

Parameters:

  | f | The Allegro font to convert.
  | type | The font type to convert to. (see AGL_FONT_TYPE_DONT_CARE, AGL_FONT_TYPE_BITMAP, AGL_FONT_TYPE_TEXTURED)
  | scale | The scaling factor (see below).
  | format | The texture internal format to use.

This function will build a texture map and/or a display list that will be automatically uploaded to the video card. You can only convert to bitmap or textured fonts.

You can't convert an Allegro font to a vector font (AGL_FONT_TYPE_OUTLINE) as the logistics of such an operation are quite complex. The original font will NOT be modified.

A valid OpenGL rendering context is required, so you may only call this function after a successful call to set_gfx_mode() with a valid OpenGL mode.

You should destroy the font via allegro_gl_destroy_font() when you are done with it.

Scaling

For AGL_FONT_TYPE_TEXTURED fonts, glyphs in the font need to be mapped to OpenGL coordinates. The scale factor ensures that you get the scaling you need. scale reprents the number of pixels to be mapped to 1.0 OpenGL units. For allegro_gl_convert_font() to behave like AllegroGL 0.0.24 and earlier, you'll need to pass 16.0 as the scale factor.

Alternativaly, you can make all your fonts be 1.0 units high by using:

       allegro_gl_convert_allegro_font(f, AGL_FONT_TYPE_TEXTURED, 1.0/text_height(f));

Note that it is allowed for the scaling factor to be negative, in case your fonts appear upside down.

If you are planning to use your fonts on an orthographic projection where one unit maps to one pixel, then you should pass 1.0 as scale.

The scaling factor has no meaning for AGL_FONT_TYPE_BITMAP fonts, so it's ignored if the conversion will lead to a font of that type.

Format

The format specifies what internal format OpenGL should use for the texture, in the case of AGL_FONT_TYPE_TEXTURED fonts. It has the same semantics as the internalformat parameter of glTexImage2D(). If you would like for AllegroGL to pick a texture format for you, you may supply -1 as the texture format. The default format for monochrome fonts is GL_INTENSITY4. The default format for colored fonts is GL_RGB8.

Returns:
  The converted font, or NULL on error.

Definition at line 688 of file fontconv.c.

References AGL_FONT_TYPE_BITMAP, AGL_FONT_TYPE_DONT_CARE, AGL_FONT_TYPE_OUTLINE, AGL_FONT_TYPE_TEXTURED, AGL_TEXTURE_ALPHA_ONLY, AGL_TEXTURE_FLIP, AGL_TEXTURE_HAS_ALPHA, AGL_TEXTURE_MASKED, AGL_TEXTURE_MIPMAP, allegro_gl_check_texture_ex(), and allegro_gl_make_texture_ex().

Referenced by allegro_gl_convert_allegro_font().

void allegro_gl_set_font_generation_mode | ( | int | mode | ) |

Set the font generation mode for system fonts.

Note: This function is deprecated and will be removed in a future version.

Parameters:

  | mode | Can be either AGL_FONT_POLYGONS or AGL_FONT_LINES. for creating polygonal or line characters. Default is AGL_FONT_POLYGONS.

Subsequent calls to allegro_gl_load_system_font() and allegro_gl_load_system_font_ex() may be affected by this function.

Deprecated:

Definition at line 469 of file aglf.c.

FONT* allegro_gl_load_system_font | ( | char * | name,
|  | int | style,
|  | int | w,
|  | int | h |
| ) |  |  |

Short hand for aglf_load_system_font_ex(name, AGL_FONT_TYPE_OUTLINE, style, w, h, 0.0f, 32, 256).

Note: This function is deprecated and will be removed in a future version.

Deprecated:

Definition at line 485 of file aglf.c.

References AGL_FONT_TYPE_OUTLINE, and allegro_gl_load_system_font_ex().

FONT* allegro_gl_load_system_font_ex | ( | char * | name,
|  | int | type,
|  | int | style,
|  | int | w,
|  | int | h,
|  | float | depth,
|  | int | start,
|  | int | end |
| ) |  |  |

Loads a system font.

Note: This function is deprecated and will be removed in a future version.

Parameters:

  | name | The name of the system font ("Courrier" or "Arial" for example)
  | type | The font type to generate (AGL_FONT_TYPE_DONT_CARE, AGL_FONT_TYPE_BITMAP, AGL_FONT_TYPE_OUTLINE)
  | style | The text decorations of the font to create (AGL_FONT_STYLE_ITALIC, etc - can be or'ed together)
  | w,h | The size of the font characters that will be created.
  | depth | The z-depth of the font. 0.0f is flat, 1.0f is very thick
  | start,end | The range of characters to create from 'start' (included) to 'end' (excluded) in UTF-8 format (ANSI only on Windows).

Note:
  - In AGL_FONT_TYPE_OUTLINE type, some system fonts seem to be unresponsive to the size paramaters (w and h). You cannot depend on either a system font being present, or the font being what you expect - it is possible to have two fonts with the same name but with different graphic data.
  - BITMAP fonts have no depth.
  - The width and height parameters are also system dependent, and may or may not work with the selected font.

Returns:
  The loaded font, or NULL on error.

Deprecated:

Definition at line 526 of file aglf.c.

Referenced by allegro_gl_load_system_font().

void allegro_gl_destroy_font | ( | FONT * | f | ) |

void allegro_gl_destroy_font(FONT *usefont)

Destroys the font.

Parameters:

  | f | The AGL font to be destroyed.

The allocated memory is freed, as well as any display list, or texture objects it uses.

You cannot use that font anymore after calling this function. It's safe to call this function with a NULL pointer; a note will be placed in allegro.log if DEBUGMODE was defined.

If NULL is passed as the font to destroy, then this function returns immediately.

Definition at line 573 of file aglf.c.

References AGL_FONT_TYPE_BITMAP, AGL_FONT_TYPE_OUTLINE, and AGL_FONT_TYPE_TEXTURED.

size_t allegro_gl_list_font_textures | ( | FONT * | f,
|  | GLuint * | ids,
|  | size_t | max_num_id |
| ) |  |  |

List the texture ID of all textures forming the specified font.

The font specified must be an AllegroGL font.

If ids is not NULL, then the ID numbers of all textures used by the font are written to the GLuint array pointed by ids. The size of that array is specified by the max_num_id parameter. This function will never write more than 'max_num_id' values in the ids array.

If f is NULL, then zero is returned and the ids array is never touched.

If the font does not contain any textures (because it is a bitmap or outline font, for example), then zero is returned.

Returns:
  Number of texture IDs that make up this font.

Here are two examples of the use of this function:

       int num_ids = allegro_gl_list_font_textures(font, NULL, 0);

       GLuint *id = malloc(sizeof(GLuint) * num_ids);

       if (!id) {
         //handle error
       }

       allegro_gl_list_font_textures(font, id, num_ids);

       for (i = 0; i < num_ids; i++) {
           glBindTexture(GL_TEXTURE_2D, id[i]);
           // Use this texture
       }

       free(id);

       GLint id[10];  // Reserve a safe number
       GLint num_ids = allegro_gl_list_font_textures(font, id, 10);

Definition at line 689 of file aglf.c.