.\" Copyright (c) 2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 17, 2007
.Dt AG_CONFIG 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Config
.Nd agar configuration interface
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
.Ed
.Sh DESCRIPTION
The Agar
.Nm
interface provides an
.Xr AG_Variable 3
interface to various Agar parameters which should remain persistent.
Typically, parameters are registered as
.Xr AG_Variable 3
bindings to specific global variables.
.Sh LOCATING FILES
.nr nS 1
.Ft "int"
.Fn AG_ConfigFile "const char *path_key" "const char *name" "const char *extension" "char *dst_path" "size_t dst_len"
.Pp
.nr nS 0
The
.Fn AG_ConfigFile
utility function searches a colon-separated pathname setting (ie.
.Sq load-path )
for a file with the given
.Fa name
and
.Fa extension.
If the file is found, its full pathname is copied into a target
fixed-size buffer
.Fa dst_path
(limited to
.Fa dst_len
bytes).
.Fn AG_ConfigFile
returns 0 on success and -1 on failure.
.Sh CONFIGURATION PARAMETERS
The following parameters are registered by Agar-Core:
.Bl -tag -width "BOOL view.full-screen "
.It Va BOOL initial-run
Application is being ran for the first time (read-only).
.It Va STRING load-path
Directory containing data files for the
.Xr AG_Object 3
virtual filesystem, as well as the
.Nm
data itself.
Default is platform-dependent (ie. for systems with
.Xr getpwuid 3
and
.Xr getuid 3 ,
it is
.Pa $HOME/.(application-name) .
.It Va STRING save-path
Target directory for writing the
.Xr AG_Object 3
virtual filesystem (usually the same as
.Sq load-path ) .
.It Va STRING tmp-path
Directory for temporary files.
.El
.Pp
The following parameters are registered by the Agar-GUI library:
.Pp
.Bl -tag -width "BOOL view.full-screen "
.It Va BOOL view.full-screen
Display is in full-screen mode.
Default = FALSE.
.It Va BOOL view.opengl
OpenGL display mode (Agar must have been compiled with OpenGL support).
Default = FALSE.
.It Va UINT16 view.w
Effective display width in pixels (read-only).
.It Va UINT16 view.h
Effective display height in pixels (read-only).
.It Va UINT16 view.min-w
Minimum display width for application to work.
Default = 320.
.It Va UINT16 view.min-h
Minimum display height for application to work.
Default = 240.
.It Va UINT8 view.depth
Requested color depth in bits per pixel.
Default = 32.
.It Va UINT view.nominal-fps
Target refresh rate (used by
.Xr AG_EventLoopFixedFPS 3 ,
but may be ignored by alternate event loop functions).
Default = 40.
.It Va BOOL input.joysticks
Attach SDL joystick devices and make joystick events available to
GUI widgets.
Default = TRUE.
.It Va BOOL input.composition
Perform composition of multiple characters (e.g., Latin accents) for
keyboard input.
This is not needed with window systems (e.g., X11), which already implement
international keyboard input, but it can be useful with less sophisticated
platforms.
Default = Platform-specific.
.It Va STRING font-path
Directory containing font files used by the
.Xr AG_Text 3
interface, including both FreeType and bitmap fonts.
Default is platform-specific.
.It Va BOOL font.freetype
If Agar-GUI was compiled with FreeType support, this enables use of
FreeType fonts as opposed to bitmap fonts.
Default is 1 if FreeType support available, otherwise 0.
.It Va STRING font.face
Default font file to use where no specific face is requested in
.Xr AG_TextRender 3 .
.It Va INT font.size
Default font size in points.
.It Va UINT font.flags
Default font flags (style, weight).
.El
.Sh EXAMPLES
The following example sets some platform-specific font paths.
.Bd -literal
#ifdef __APPLE__
AG_PrtString(agConfig, "font-path", "%s/Library/Fonts:/Library/Fonts:"
                                    "/System/Library/Fonts",
			            getenv("HOME"));
#elif _WIN32
AG_SetString(agConfig, "font-path", "c:\\windows\\fonts");
#else
AG_PrtString(agConfig, "font-path", "%s/.fonts:"
                                    "/usr/X11R6/lib/X11/fonts/TTF",
                                    getenv("HOME"));
#endif
.Ed
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Object 3 ,
.Xr AG_Text 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.0
.Sh BUGS
The Agar-GUI parameters should be documented in a separate manual page.