Add ALLEGRO_GLYPH structure and al_get_glyph. (#657)

The structure contains all the info need (including the bitmap)
to draw text. The ttf addon's render_glyph was used to make the
vtable function for the ttf addon.

Author: Trent Gamblin

addons/font/allegro5/allegro_font.h

@@ -47,6 +47,9 @@
 /* Type: ALLEGRO_FONT
 */
 typedef struct ALLEGRO_FONT ALLEGRO_FONT;
+/* Type: ALLEGRO_GLYPH
+*/
+typedef struct ALLEGRO_GLYPH ALLEGRO_GLYPH;
 typedef struct ALLEGRO_FONT_VTABLE ALLEGRO_FONT_VTABLE;
 
 struct ALLEGRO_FONT
@@ -58,6 +61,19 @@ struct ALLEGRO_FONT
    _AL_LIST_ITEM *dtor_item;
 };
 
+struct ALLEGRO_GLYPH
+{
+   ALLEGRO_BITMAP *bitmap;
+   int x;
+   int y;
+   int w;
+   int h;
+   int kerning;
+   int offset_x;
+   int offset_y;
+   int advance;
+};
+
 /* text- and font-related stuff */
 struct ALLEGRO_FONT_VTABLE
 {
@@ -78,7 +94,8 @@ struct ALLEGRO_FONT_VTABLE
       int codepoint, int *bbx, int *bby, int *bbw, int *bbh));      
    ALLEGRO_FONT_METHOD(int, get_glyph_advance, (const ALLEGRO_FONT *font,
       int codepoint1, int codepoint2));
-      
+
+   ALLEGRO_FONT_METHOD(bool, get_glyph, (const ALLEGRO_FONT *f, int prev_codepoint, int codepoint, ALLEGRO_GLYPH *glyph));
 };
 
 enum {
@@ -130,6 +147,7 @@ ALLEGRO_FONT_FUNC(bool, al_get_glyph_dimensions, (const ALLEGRO_FONT *f,
    int codepoint, int *bbx, int *bby, int *bbw, int *bbh));
 ALLEGRO_FONT_FUNC(int, al_get_glyph_advance, (const ALLEGRO_FONT *f,
    int codepoint1, int codepoint2));
+ALLEGRO_FONT_FUNC(bool, al_get_glyph, (const ALLEGRO_FONT *f, int prev_codepoint, int codepoint, ALLEGRO_GLYPH *glyph));
 
 ALLEGRO_FONT_FUNC(void, al_draw_multiline_text, (const ALLEGRO_FONT *font, ALLEGRO_COLOR color, float x, float y, float max_width, float line_height, int flags, const char *text));
 ALLEGRO_FONT_FUNC(void, al_draw_multiline_textf, (const ALLEGRO_FONT *font, ALLEGRO_COLOR color, float x, float y, float max_width, float line_height, int flags, const char *format, ...));

addons/font/font.c

@@ -209,6 +209,27 @@ static int color_render(const ALLEGRO_FONT* f, ALLEGRO_COLOR color,
 }
 
 
+static bool color_get_glyph(const ALLEGRO_FONT *f, int prev_codepoint, int codepoint, ALLEGRO_GLYPH *glyph)
+{
+   ALLEGRO_BITMAP *g = _al_font_color_find_glyph(f, codepoint);
+   if (g) {
+      glyph->bitmap = g;
+      glyph->x = 0;
+      glyph->y = 0;
+      glyph->w = al_get_bitmap_width(g);
+      glyph->h = al_get_bitmap_height(g);
+      glyph->kerning = 0;
+      glyph->offset_x = 0;
+      glyph->offset_y = 0;
+      glyph->advance = glyph->w;
+      return true;
+   }
+   if (f->fallback) {
+      return f->fallback->vtable->get_glyph(f->fallback, prev_codepoint, codepoint, glyph);
+   }
+   return false;
+}
+
 
 /* color_destroy:
  *  (color vtable entry)
@@ -317,7 +338,8 @@ ALLEGRO_FONT_VTABLE _al_font_vtable_color = {
     color_get_text_dimensions,
     color_get_font_ranges,
     color_get_glyph_dimensions,
-    color_get_glyph_advance
+    color_get_glyph_advance,
+    color_get_glyph
 };
 
 

addons/font/text.c

@@ -402,6 +402,12 @@ int al_get_glyph_advance(const ALLEGRO_FONT *f, int codepoint1, int codepoint2)
    return f->vtable->get_glyph_advance(f, codepoint1, codepoint2);
 }
 
+/* Function: al_get_glyph
+ */
+bool al_get_glyph(const ALLEGRO_FONT *f, int prev_codepoint, int codepoint, ALLEGRO_GLYPH *glyph)
+{
+   return f->vtable->get_glyph(f, prev_codepoint, codepoint, glyph);
+};
 
 
 /* This helper function helps splitting an ustr in several delimited parts.

addons/ttf/ttf.c

@@ -495,44 +495,81 @@ static int get_kerning(ALLEGRO_TTF_FONT_DATA const *data, FT_Face face,
 }
 
 
-static int render_glyph(ALLEGRO_FONT const *f, ALLEGRO_COLOR color,
-   int prev_ft_index, int ft_index, int32_t ch, float xpos, float ypos)
+static bool ttf_get_glyph_worker(ALLEGRO_FONT const *f, int prev_ft_index, int ft_index, int prev_codepoint, int codepoint, ALLEGRO_GLYPH *info)
 {
    ALLEGRO_TTF_FONT_DATA *data = f->data;
    FT_Face face = data->face;
    ALLEGRO_TTF_GLYPH_DATA *glyph;
    int advance = 0;
 
    if (!get_glyph(data, ft_index, &glyph)) {
-      if (f->fallback) {
-         al_draw_glyph(f->fallback, color, xpos, ypos, ch);
-         return al_get_glyph_advance(f->fallback, ch,
-            ALLEGRO_NO_KERNING);
-      }
+      if (f->fallback)
+         return f->fallback->vtable->get_glyph(f->fallback, prev_codepoint, codepoint, info);
       else {
          get_glyph(data, 0, &glyph);
          ft_index = 0;
       }
    }
+
    cache_glyph(data, face, ft_index, glyph, false);
 
    advance += get_kerning(data, face, prev_ft_index, ft_index);
 
    if (glyph->page_bitmap) {
-      /* Each glyph has a 1-pixel border all around. */
-      al_draw_tinted_bitmap_region(glyph->page_bitmap, color,
-         glyph->region.x + 1, glyph->region.y + 1,
-         glyph->region.w - 2, glyph->region.h - 2,
-         xpos + glyph->offset_x + advance,
-         ypos + glyph->offset_y, 0);
+      info->bitmap = glyph->page_bitmap;
+      info->x = glyph->region.x + 1;
+      info->y = glyph->region.y + 1;
+      info->w = glyph->region.w - 2;
+      info->h = glyph->region.h - 2;
+      info->kerning = advance;
+      info->offset_x = glyph->offset_x;
+      info->offset_y = glyph->offset_y;
    }
    else if (glyph->region.x > 0) {
       ALLEGRO_ERROR("Glyph %d not on any page.\n", ft_index);
+      return false;
+   }
+   else {
+      info->bitmap = 0;
    }
 
    advance += glyph->advance;
 
-   return advance;
+   info->advance = advance;
+
+   return true;
+}
+
+
+static bool ttf_get_glyph(ALLEGRO_FONT const *f, int prev_codepoint, int codepoint, ALLEGRO_GLYPH *glyph)
+{
+   ALLEGRO_TTF_FONT_DATA *data = f->data;
+   FT_Face face = data->face;
+   int prev_ft_index = (prev_codepoint == -1) ? -1 : FT_Get_Char_Index(face, prev_codepoint);
+   int ft_index = FT_Get_Char_Index(face, codepoint);
+   return ttf_get_glyph_worker(f, prev_ft_index, ft_index, prev_codepoint, codepoint, glyph);
+}
+
+
+static int render_glyph(ALLEGRO_FONT const *f, ALLEGRO_COLOR color,
+   int prev_ft_index, int ft_index, int32_t prev_ch, int32_t ch, float xpos, float ypos)
+{
+   ALLEGRO_GLYPH glyph;
+
+   if (ttf_get_glyph_worker(f, prev_ft_index, ft_index, prev_ch, ch, &glyph) == false)
+      return 0;
+
+   if (glyph.bitmap != NULL) {
+      al_draw_tinted_bitmap_region(
+         glyph.bitmap, color,
+         glyph.x, glyph.y, glyph.w, glyph.h,
+         xpos + glyph.offset_x + glyph.kerning,
+         ypos + glyph.offset_y,
+         0
+      );
+   }
+
+   return glyph.advance;
 }
 
 
@@ -578,10 +615,10 @@ static int ttf_render_char(ALLEGRO_FONT const *f, ALLEGRO_COLOR color,
    FT_Face face = data->face;
    int advance = 0;
    int32_t ch32 = (int32_t) ch;
-   
+
    int ft_index = FT_Get_Char_Index(face, ch32);
-   advance = render_glyph(f, color, -1, ft_index, ch, xpos, ypos);
-   
+   advance = render_glyph(f, color, -1, ft_index, -1, ch, xpos, ypos);
+
    return advance;
 }
 
@@ -591,7 +628,7 @@ static int ttf_char_length(ALLEGRO_FONT const *f, int ch)
    int result;
    ALLEGRO_TTF_FONT_DATA *data = f->data;
    ALLEGRO_TTF_GLYPH_DATA *glyph;
-   FT_Face face = data->face;   
+   FT_Face face = data->face;
    int ft_index = FT_Get_Char_Index(face, ch);
    if (!get_glyph(data, ft_index, &glyph)) {
       if (f->fallback) {
@@ -604,7 +641,7 @@ static int ttf_char_length(ALLEGRO_FONT const *f, int ch)
    }
    cache_glyph(data, face, ft_index, glyph, false);
    result = glyph->region.w - 2;
-     
+
    return result;
 }
 
@@ -617,6 +654,7 @@ static int ttf_render(ALLEGRO_FONT const *f, ALLEGRO_COLOR color,
    int pos = 0;
    int advance = 0;
    int prev_ft_index = -1;
+   int32_t prev_ch = -1;
    int32_t ch;
    bool hold;
 
@@ -625,9 +663,10 @@ static int ttf_render(ALLEGRO_FONT const *f, ALLEGRO_COLOR color,
 
    while ((ch = al_ustr_get_next(text, &pos)) >= 0) {
       int ft_index = FT_Get_Char_Index(face, ch);
-      advance += render_glyph(f, color, prev_ft_index, ft_index, ch,
+      advance += render_glyph(f, color, prev_ft_index, ft_index, prev_ch, ch,
          x + advance, y);
       prev_ft_index = ft_index;
+      prev_ch = ch;
    }
 
    al_hold_bitmap_drawing(hold);
@@ -699,7 +738,7 @@ static void ttf_get_text_dimensions(ALLEGRO_FONT const *f,
 
    *bby = ymin;
    *bbw = x - *bbx;
-   *bbh = ymax - ymin; 
+   *bbh = ymax - ymin;
 }
 
 
@@ -803,7 +842,7 @@ ALLEGRO_FONT *al_load_ttf_font_stretch_f(ALLEGRO_FILE *file,
       al_get_config_value(system_cfg, "ttf", "max_page_size");
     const char* cache_str =
       al_get_config_value(system_cfg, "ttf", "cache_text");
-    const char* skip_cache_misses_str = 
+    const char* skip_cache_misses_str =
       al_get_config_value(system_cfg, "ttf", "skip_cache_misses");
 
     if ((h > 0 && w < 0) || (h < 0 && w > 0)) {
@@ -904,7 +943,7 @@ ALLEGRO_FONT *al_load_ttf_font_stretch_f(ALLEGRO_FILE *file,
 
     _al_vector_init(&data->glyph_ranges, sizeof(ALLEGRO_TTF_GLYPH_RANGE));
     _al_vector_init(&data->page_bitmaps, sizeof(ALLEGRO_BITMAP*));
-    
+
     if (data->skip_cache_misses) {
        cache_glyphs(data, "\0", 1);
     }
@@ -992,7 +1031,7 @@ static bool ttf_get_glyph_dimensions(ALLEGRO_FONT const *f,
 {
    ALLEGRO_TTF_FONT_DATA *data = f->data;
    ALLEGRO_TTF_GLYPH_DATA *glyph;
-   FT_Face face = data->face;   
+   FT_Face face = data->face;
    int ft_index = FT_Get_Char_Index(face, codepoint);
    if (!get_glyph(data, ft_index, &glyph)) {
       if (f->fallback) {
@@ -1009,7 +1048,7 @@ static bool ttf_get_glyph_dimensions(ALLEGRO_FONT const *f,
    *bbw = glyph->region.w - 2;
    *bbh = glyph->region.h - 2;
    *bby = glyph->offset_y;
-      
+
    return true;
 }
 
@@ -1019,10 +1058,10 @@ static int ttf_get_glyph_advance(ALLEGRO_FONT const *f, int codepoint1,
    ALLEGRO_TTF_FONT_DATA *data = f->data;
    FT_Face face = data->face;
    int ft_index = FT_Get_Char_Index(face, codepoint1);
-   ALLEGRO_TTF_GLYPH_DATA *glyph; 
+   ALLEGRO_TTF_GLYPH_DATA *glyph;
    int kerning = 0;
    int advance = 0;
-   
+
    if (codepoint1 == ALLEGRO_NO_KERNING) {
       return 0;
    }
@@ -1037,13 +1076,13 @@ static int ttf_get_glyph_advance(ALLEGRO_FONT const *f, int codepoint1,
       }
    }
    cache_glyph(data, face, ft_index, glyph, false);
-   
-   if (codepoint2 != ALLEGRO_NO_KERNING) { 
+
+   if (codepoint2 != ALLEGRO_NO_KERNING) {
       int ft_index1 = FT_Get_Char_Index(face, codepoint1);
-      int ft_index2 = FT_Get_Char_Index(face, codepoint2); 
+      int ft_index2 = FT_Get_Char_Index(face, codepoint2);
       kerning = get_kerning(data, face, ft_index1, ft_index2);
    }
-   
+
    advance = glyph->advance;
    return advance + kerning;
 }
@@ -1072,6 +1111,7 @@ bool al_init_ttf_addon(void)
    vt.get_font_ranges = ttf_get_font_ranges;
    vt.get_glyph_dimensions = ttf_get_glyph_dimensions;
    vt.get_glyph_advance = ttf_get_glyph_advance;
+   vt.get_glyph = ttf_get_glyph;
 
    al_register_font_loader(".ttf", al_load_ttf_font);
 

docs/src/refman/font.txt

@@ -17,6 +17,39 @@ 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].
 
+### API: ALLEGRO_GLYPH
+
+A structure containing the properties of a character in a font.
+
+~~~~c
+typedef struct ALLEGRO_GLYPH {
+   ALLEGRO_BITMAP *bitmap;   // the bitmap the character is on
+   int x;                    // the x position of the glyph on bitmap
+   int y;                    // the y position of the glyph on bitmap
+   int w;                    // the width of the glyph in pixels
+   int h;                    // the height of the glyph in pixels
+   int kerning;              // pixels of kerning (see below)
+   int offset_x;             // x offset to draw the glyph at
+   int offset_y;             // y offset to draw the glyph at
+   int advance;              // number of pixels to advance after this character
+} ALLEGRO_GLYPH;
+~~~~
+
+bitmap may be a sub-bitmap in the case of color fonts.
+
+kerning should be added to the x position you draw to if you want your text
+kerned and depends on which codepoints [al_get_glyph] was called with.
+
+Glyphs are tightly packed onto the bitmap, so you need to add offset_x and
+offset_y to your draw position for the text to look right.
+
+advance is the number of pixels to add to your x position to advance to the
+next character in a string and includes kerning.
+
+Since: 5.2.1
+
+See also: [al_get_glyph]
+
 ### API: al_init_font_addon
 
 Initialise the font addon.
@@ -739,3 +772,15 @@ See also: [al_load_ttf_font_stretch]
 
 Returns the (compiled) version of the addon, in the same format as
 [al_get_allegro_version].
+
+### API: al_get_glyph
+
+Gets all the information about a glyph, including the bitmap, needed to draw it
+yourself. prev_codepoint is the codepoint in the string before the one you want
+to draw and is used for kerning. codepoint is the character you want to get info
+about. You should clear the 'glyph' structure to 0 with memset before passing it
+to this function for future compatibility.
+
+Since: 5.2.1
+
+See also: [ALLEGRO_GLYPH]