Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AG_TEXT(3)		 BSD Library Functions Manual		    AG_TEXT(3)

     AG_Text --	agar text rendering interface

     #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 percent-
     age of current font size.	An argument of 100% leaves the size unchanged.

     AG_TextJustify() selects the justification	mode to	use in multi-line ren-

     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 sur-
     faces 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 charac-
     ter.  The function	returns	an AG_Glyph structure, which has the following
     public (read-only)	members:

     Uint32 ch		 Unicode character (UCS-4 encoded)
     AG_Surface	*su	 Pixel surface
     Uint texture	 OpenGL	texture	handle (if OpenGL is in	use)
     float texcoord[4]	 OpenGL	texture	coordinates (if	OpenGL is in use
     int advance	 Amount	of translation (in pixels) recommended to fol-
			 low 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

     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 indi-
     cates 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

     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 spec-
     ified 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	com-
     mand 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)

     The FreeType project:

     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.

BSD				April 24, 2003				   BSD


Want to link to this manual page? Use this URL:

home | help