<-- Back to AG_Intro.3


#include <agar/core.h>
#include <agar/gui.h>


The AG_Text interface uses an underlying font engine to render text. Currently, two font engines are supported: AG_FONT_VECTOR (for rendering any font supported by FreeType) and AG_FONT_BITMAP (for rendering simple pixmap fonts).


A number of settings which affect the rendering functions (see RENDERING section) can be modified at any time, and are organized in a stack of rendering attributes.

void AG_PushTextState (void)

void AG_PopTextState (void)

void AG_TextFont (AG_Font *font)

AG_Font * AG_TextFontLookup (const char *face, int size, Uint flags)

AG_Font * AG_TextFontPct (int size_pct)

AG_Font * AG_TextFontPts (int points)

void AG_TextJustify (enum ag_text_justify mode)

void AG_TextValign (enum ag_text_valign mode)

void AG_TextTabWidth (int pixels)

void AG_TextColor (AG_Color C)

void AG_TextColorRGB (Uint8 r, Uint8 g, Uint8 b)

void AG_TextColorRGBA (Uint8 r, Uint8 g, Uint8 b, Uint8 a)

void AG_TextBGColor (AG_Color C)

void AG_TextBGColorRGB (Uint8 r, Uint8 g, Uint8 b)

void AG_TextBGColorRGBA (Uint8 r, Uint8 g, Uint8 b, Uint8 a)

void AG_TextBGColorRGBA (Uint8 r, Uint8 g, Uint8 b, Uint8 a)

The AG_PushTextState() and AG_PopTextState() functions respectively push and pop the text rendering attribute stack. The attribute stack can hold AG_TEXT_STATES_MAX items (at least 32).

The AG_TextFont() function selects font as the active font.

AG_TextFontLookup() searches the font cache for the given font face, size and flags combination, possibly loading new fonts from disk (scanning all font-path directories). On success, the font is selected as the active font and returned. If no match is found, the function returns NULL.

AG_TextFontPts() sets the size of the active font in points.

AG_TextFontPct() sets the size of the active font, specified as percentage of current font size. An argument of 100% leaves the size unchanged.

AG_TextJustify() selects the justification mode to use in multi-line rendering:
enum ag_text_justify {

AG_TextValign() selects the vertical alignment mode to use where text is rendered to an area of arbitrary height:
enum ag_text_valign {

AG_TextTabWidth() sets the width of tabs in pixels.

AG_TextColor() sets the text color (see AG_Color(3)). AG_TextColorRGB() and AG_TextColorRGBA() accept individual color components.

Similarly, AG_TextBG*() functions assign a background color for the surfaces returned by the rendering functions.


AG_Surface * AG_TextRender (const char *text)

AG_Surface * AG_TextRenderUCS4 (const Uint32 *text)

AG_Surface * AG_TextRenderf (const char *fmt, ...)

AG_Glyph * AG_TextRenderGlyph (Uint32 uch)

void AG_TextSize (const char *text, int *w, int *h)

void AG_TextSizeUCS4 (const Uint32 *text, int *w, int *h)

void AG_TextSizeMulti (const char *text, int *w, int *h, Uint **wLines, Uint *nLines)

void AG_TextSizeMultiUCS4 (const Uint32 *text, int *w, int *h, Uint **wLines, Uint *nLines)

The AG_TextRender() function renders text to a new, transparent surface. The input text may contain UTF-8 sequences. The AG_TextRenderf() variant accepts printf(3) style arguments.

AG_TextRenderUCS4() renders text in UCS-4 format onto a new surface. AG_TextRenderGlyph() renders the specified UCS-4 encoded Unicode character. The function returns an AG_Glyph structure, which has the following public (read-only) members:
Uint32 chUnicode character (UCS-4 encoded)
AG_Surface *suPixel surface
Uint textureOpenGL texture handle (if OpenGL is in use)
float texcoord[4]OpenGL texture coordinates (if OpenGL is in use
int advanceAmount of translation (in pixels) recommended to follow when rendering text

The AG_TextSize() and AG_TextSizeUCS4() functions return the minimal bounding box in pixels required for rendering the given text. The AG_TextSizeMulti() and AG_TextSizeMultiUCS4() variants also return the number of lines into nLines and the width in pixels of each line in the array wLines (which must be initialized to NULL).


void AG_TextMsg (enum ag_text_msg_title title, const char *format, ...)

void AG_TextMsgS (enum ag_text_msg_title title, const char *msg)

void AG_TextMsgFromError (void)

void AG_TextWarning (const char *disableKey, const char *format, ...)

void AG_TextWarningS (const char *disableKey, const char *msg)

void AG_TextError (const char *format, ...)

void AG_TextErrorS (const char *msg)

void AG_TextInfo (const char *disableKey, const char *format, ...)

void AG_TextInfoS (const char *disableKey, const char *msg)

void AG_TextTmsg (enum ag_text_msg_title title, Uint32 expire, const char *format, ...)

void AG_TextTmsgS (enum ag_text_msg_title title, Uint32 expire, const char *msg)

void AG_TextEditFloat (double *fp, double min, double max, const AG_Unit *unit, const char *format, ...)

void AG_TextEditString (char *buf, size_t len, const char *format, ...)

The AG_TextMsg() function displays a text message window containing the given printf(3) formatted string, and an OK button. title is one of the following:
enum ag_text_msg_title {

AG_TextMsgFromError() displays a standard error message using the value of AG_GetError(3).

AG_TextWarning() displays a standard warning message, but also provides the user with a Don't show again checkbox. The checkbox controls the AG_Config(3) value specified by disableKey.

AG_TextError() displays an error message. It is equivalent to AG_TextMsg() with a AG_MSG_ERROR setting.

AG_TextInfo() displays an informational message. Similar to AG_TextWarning(), a Don't show again option is provided to the user (and the setting is referenced by disableKey).

The AG_TextTmsg() routine is a variant of AG_TextMsg() which displays the message for a specific amount of time, given in milliseconds.

The AG_TextEditFloat() function displays a dialog asking for a floating-point value. The fp argument is a pointer to the variable, while min and max define the acceptable range. Unless unit is NULL, the argument indicates the unit system to use (as in AG_Units(3)).

Similarly, AG_TextEditString() displays a dialog asking for a string, where buf is a pointer to the string buffer, and len is the size of the buffer.


AG_Font * AG_FetchFont (const char *face, int size, int flags)

void AG_UnusedFont (AG_Font *font)

void AG_SetDefaultFont (AG_Font *font)

void AG_SetRTL (int enable)

void AG_TextParseFontSpec (const char *fontspec)

The AG_FetchFont() function retrieves the font corresponding to the specified face and size in points. Acceptable flags include AG_FONT_BOLD and AG_FONT_ITALIC. The font is loaded from file if not currently resident (unless the fontconfig library is available, the font file should reside in one of the directories specified in the font-path setting). If any the parameters are specified as NULL or -1, the AG_Config(3) defaults font.face, font.size and font.flags are used. AG_FetchFont() returns a pointer to the font object, incrementing its reference count. If the font cannot be loaded, the function returns NULL.

The AG_UnusedFont() function decrements the reference count on a font. If the font is no longer referenced, it is destroyed.

AG_SetDefaultFont() sets the specified font object as the default font.

AG_SetRTL() enables or disables right-to-left text mode.

The AG_TextParseFontSpec() function parses a font specification of the form face,size,style (valid separators include :,./) and assigns the default font. This function is typically called prior to AG_InitGraphics() (e.g., to parse alternate fonts specified on the command line).


AG_Config(3), AG_Editable(3), AG_Intro(3), AG_Label(3), AG_Surface(3), AG_Textbox(3), AG_TextElement(3), AG_Widget(3)

Lk The FreeType project

Lk Unicode home page


The AG_Text interface first appeared in Agar 1.0. The stack of rendering attributes was added in Agar 1.3. Right-to-left rendering first appeared in Agar 1.4.1.