Provided by: allegro5-doc_5.2.8.0+dfsg-1_all bug

NAME

       al_get_glyph_advance - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro_font.h>

              int al_get_glyph_advance(const ALLEGRO_FONT *f, int codepoint1, int codepoint2)

DESCRIPTION

       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(3alleg5)
       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(3alleg5) 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, 'A', 'l')
                   ___|___
                  /       \
                  -------------
                      /\   -|
                     /  \   |
                    /____\  |
                   /      \ |
                  /        \ \_
                  -------------

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

SINCE

       5.1.12

SEE ALSO

       al_draw_glyph(3alleg5), al_get_glyph_width(3alleg5), al_get_glyph_dimensions(3alleg5).