Agar 1.7 Manual

(Printable Version)


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


The AG_Text interface allows Agar GUI widgets to render text using a vector or a bitmap engine. FreeType is used by default if it is available.


Agar maintains a stack of rendering attributes which influence the operation of text rendering and sizing routines. Attributes are set using functions such as AG_TextFont() or AG_TextColor().

Note: The functions below are *not* free-threaded and are only safe to invoke from the draw(), size_request(), size_allocate(), or any event handler of an AG_Widget(3) with the AG_WIDGET_USE_TEXT flag set.

void AG_PushTextState (void)

void AG_CopyTextState (AG_TextState *dst)

void AG_PopTextState (void)

AG_TextState * AG_TEXT_STATE_CUR (void)

void AG_TextFont (AG_Font *font)

AG_Font * AG_TextFontLookup (const char *face, float points, Uint flags)

AG_Font * AG_TextFontPct (int size_pct)

AG_Font * AG_TextFontPctFlags (int size_pct, Uint flags)

AG_Font * AG_TextFontPts (float size)

void AG_TextJustify (enum ag_text_justify mode)

void AG_TextValign (enum ag_text_valign mode)

void AG_TextTabWidth (int pixels)

void AG_TextColor (const 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 (const 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)

void AG_TextColorANSI (enum ag_ansi_color which, const AG_Color *c)

AG_PushTextState() increments the attribute stack pointer and creates a copy of the previous state in the current state. AG_PopTextState() decrements the stack pointer, discarding the current state. AG_CopyTextState() copies the current text state to dst. The text state stack can hold up to AG_TEXT_STATES_MAX elements.

The AG_TEXT_STATE_CUR() macro expands to an expression returning the pointer to the current AG_TextState. In debug mode, an additional validity test is performed.

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

AG_TextFontLookup() checks the font cache for a given combination of face, point size and flags, possibly loading new fonts from disk. On success, the font is set as the active font for the current text state and a pointer to it is returned. If no font was found, AG_TextFontLookup() returns NULL.

AG_TextFontPts() sets the size of the active font in points. If the argument nears 0.0 (is smaller than AG_FONT_PTS_EPSILON) then the AG_Config(3) default "font.size" is used.

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_TextFontPctFlags() allows an alternate font style via flags argument.

AG_TextJustify() selects the justify 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_TextColorANSI() modifies an entry in the 4-bit ANSI color palette. Subsequent calls to AG_TextRender() will display text containing AG_SGR_FG* or AG_SGR_BG* sequences in the specified color (until AG_PopTextState() is called). When the ANSI color palette is first modified, it is copied to the active AG_TextState in a copy-on-write fashion.


AG_Surface * AG_TextRender (const char *text)

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

AG_Surface * AG_TextRenderInternal (const AG_Char *text, const AG_Font *font, const AG_Color *cBg, const AG_Color *cFg)

AG_Glyph * AG_TextRenderGlyph (AG_Driver *drv, const AG_Font *font, const AG_Color *cBg, const AG_Color *cFg, AG_Char ch)

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

void AG_TextSizeInternal (const AG_Char *text, int *w, int *h)

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

void AG_TextSizeMultiInternal (const AG_Char *text, int *w, int *h, Uint **wLines, Uint *nLines)

AG_TextRender() renders the C string text onto a newly-allocated surface. The font, colors and spacings are according to the current rendering attributes (see RENDERING ATTRIBUTES section). The input text may contain UTF-8 characters and ANSI SGR sequences. The first guide (Guide 0) of the surface returned by AG_TextRender() contains Ascent information.

AG_TextRenderInternal() renders onto a new surface text in native AG_Char encoding (which is either an ASCII char, or a 32-bit UCS-4 character in Unicode builds). AG_TextRenderGlyph() returns a pointer to the corresponding AG_Glyph from the cache, which has the following public (read-only) members:
AG_Char chNative character (UCS-4 or ASCII)
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_TextSizeInternal() functions return the minimal bounding box in pixels required for rendering the given text. The AG_TextSizeMulti() and AG_TextSizeMultiInternal() 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)

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 if disableKey is non-NULL, it 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(), if disableKey is non-NULL then a Don't show again option is also provided to the user.

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


AG_Font * AG_FetchFont (const char *face, float size, Uint flags)

void AG_UnusedFont (AG_Font *font)

AG_Font * AG_SetDefaultFont (AG_Font *font)

void AG_TextParseFontSpec (const char *fontspec)

AG_FetchFont() loads (or retrieves from cache) the font corresponding to the specified face, size and flags attributes. Face may refer to either a system-wide font or a file in font-path. size is in points (fractional sizes are permitted). Possible flags include:
#define AG_FONT_THIN           0x00001  /* Wt#100 - Thin */
#define AG_FONT_EXTRALIGHT     0x00002  /* Wt#200 - Extra Light */
#define AG_FONT_LIGHT          0x00004  /* Wt#300 - Light */
#define AG_FONT_REGULAR        0x00008  /* Wt#400 - Regular */
#define AG_FONT_SEMIBOLD       0x00010  /* Wt#600 - Semi Bold */
#define AG_FONT_BOLD           0x00020  /* Wt#700 - Bold */
#define AG_FONT_EXTRABOLD      0x00040  /* Wt#800 - Extra Bold */
#define AG_FONT_BLACK          0x00080  /* Wt#900 - Black */
#define AG_FONT_OBLIQUE        0x00100  /* Style - Oblique */
#define AG_FONT_ITALIC         0x00200  /* Style - Italic */
#define AG_FONT_UPRIGHT_ITALIC 0x00400  /* Style - Upright Italic */
#define AG_FONT_MONOSPACE      0x00800  /* Family - Monospace */
#define AG_FONT_ULTRACONDENSED 0x01000  /* Wd(50%) - Ultra Condensed */
#define AG_FONT_CONDENSED      0x04000  /* Wd(75%) - Condensed */
#define AG_FONT_SEMICONDENSED  0x02000  /* Wd(87.5%) - Semi Condensed */
#define AG_FONT_SEMIEXPANDED   0x08000  /* Wd(112.5%) - Semi Expanded */
#define AG_FONT_EXPANDED       0x10000  /* Wd(125%) - Expanded */
#define AG_FONT_ULTRAEXPANDED  0x20000  /* Wd(200%) - Ultra Expanded */

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 the face or size arguments are NULL then AG_FetchFont() uses the AG_Config(3) defaults `font.face' and `font.size'. AG_FetchFont() returns a pointer to the font object and increments its reference count. If the font cannot be loaded, it 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. A pointer to the previous default font is returned.

AG_TextParseFontSpec() parses a "<Face>[:<Size>][:<Style>]" format specification, loads the matching font and (if successful) sets it as the default font. Exceptionally, it is safe to invoke AG_TextParseFontSpec() before the initial AG_InitGraphics() call so that the default font can be set from a command-line argument. If fontspec is NULL then it's a no-op.

Field separators "," and "/" are also recognized in addition to ":". The Style specification may contain the following characters:
mMonospace (family preference)
cSemi Condensed (width variant)
CCondensed (width variant)
LExtra Light (weight)
lLight (weight)
rRegular (weight)
bBold (weight)
sSemi Bold (weight)
iItalic (style)
oOblique (style)
uUpright italic (style)


int AG_TextParseANSI (const AG_TextState *state, AG_TextANSI *ansi, const AG_Char *s)

int AG_TextExportUnicode_StripANSI (const char *encoding, char *dst, const AG_Char *src, AG_Size dstSize)

AG_TextParseANSI() interprets a possible ANSI sequence attribute in a native (UCS-4) string s and returns 0 if a valid sequence is found, otherwise it returns -1. If a valid sequence is found, AG_TextParseANSI() writes a normalized description of it into the ansi structure and the total length of the sequence in its len field. Stripping ANSI sequences from a string while it is being exported can be done simply by skipping over len characters whenever a valid sequence is found.

AG_TextExportUnicode_StripANSI() converts the contents of the given UCS-4 text buffer to the specified encoding and strips ANSI attribute sequences in the process. "US-ASCII and "UTF-8" encodings are handled internally by Agar. Other encodings are handled through iconv where available. The resulting text is written to the specified buffer dst, which should be of the specified size dstSize, in bytes. The written string is always NUL-terminated.



The AG_Text interface first appeared in Agar 1.0. Rendering attributes were introduced in 1.3.x. Fontconfig support was added in 1.5.x. Upright Italic and width variants were added in 1.6.0. AG_CopyTextState() and AG_TextFontPctFlags() appeared in 1.6.0. Ascent guides included in AG_TextRender() generated surfaces appeared in 1.7.0. ElectronTubeStore