Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

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

DESCRIPTION

After having called AG_InitCore(3), Agar-GUI applications also need to initialize the graphics facilities. Since some Agar applications may have very specific requirements in terms of the graphics interface, Agar provides a number of options to that effect.

INTERFACE

int AG_InitGraphics (const char *driver)

void AG_QuitGUI (void)

Most common Agar applications will use the AG_InitGraphics() function to initialize the graphics system. If the drivers argument is non-NULL, it specifies a comma-separated list of driver names, in order of preference. If drivers is NULL, Agar selects the "best" drivers available on the current platform (see section below for the list of available driver). If drivers is set to "<OpenGL>" or "<SDL>", Agar selects the "best" drivers with OpenGL or SDL support, respectively, and fails if none are found. Some drivers support extra arguments, for example, the string:

	<SDL>(width=640:height=480:depth=32)

would request a SDL-compatible driver with a 640x480x32 bpp display.

The preferred way to terminate an Agar application is by calling AG_QuitGUI(). This results in a message being sent, leaving an opportunity for the termination process to be interrupted or aborted (e.g., by confirmation dialogs).

To shut down and release resources allocated by Agar without terminating an application, AG_Destroy(3) can be used instead.

AVAILABLE DRIVERS

As of Agar-1.4.0, the available drivers were:

glx	OpenGL rendering via X Window System, using GLX interface. Multiple windows are supported.
wgl	OpenGL rendering via Windows API, using WGL interface. Multiple windows are supported.
sdlfb	Framebuffer rendering via SDL library. Single-window display.
sdlgl	OpenGL rendering via SDL library. Single-window display.

Note that new drivers can be easily implemented through a class registration interface (see AG_Driver(3) for details).

USING SINGLE-WINDOW DRIVERS

int AG_InitVideo (int w, int h, int depth, Uint flags)

int AG_InitVideoSDL (SDL_Surface *display, Uint flags)

int AG_SetVideoSurfaceSDL (SDL_Surface *display)

int AG_ResizeDisplay (int w, int h)

void AG_SetVideoResizeCallback (void (*fn)(Uint w, Uint h)))

The AG_InitVideo() function is an alternative to AG_InitGraphics() which selects only those drivers with no multiple-window support (e.g., sdlfb, sdlgl).

The AG_InitVideoSDL() function initializes the GUI to attach to an existing SDL display surface. Note that if the specified surface has the SDL_OPENGL flag set, the sdlgl driver is selected, otherwise sdlfb is used.

The AG_SetVideoSurfaceSDL() function can be used to reattach to a different (e.g., a newly resized) SDL display surface without reinitializing the GUI.

AG_InitVideoSDL() and AG_SetVideoSurfaceSDL() are only available if Agar has been compiled with SDL support.

The AG_ResizeDisplay() function resizes the video display to the specified dimensions in pixels. AG_SetVideoResizeCallback() registers a callback function which will be invoked whenever the display is resized. Both of these functions are only applicable to single-window drivers.

AG_InitVideo() and AG_InitVideoSDL() both recognize the following flags options:

AG_VIDEO_HWSURFACE	Request a hardware frame buffer (pass SDL_HWSURFACE in SDL mode).
AG_VIDEO_ASYNCBLIT	Enable asynchronous blitting updates (pass SDL_ASYNCBLIT in SDL mode).
AG_VIDEO_ANYFORMAT	Disable emulation of surface depth (pass SDL_ANYFORMAT in SDL mode).
AG_VIDEO_HWPALETTE	Exclusive palette access (pass SDL_HWPALETTE in SDL mode).
AG_VIDEO_DOUBLEBUF	Enable double-buffering in frame buffer mode.
AG_VIDEO_FULLSCREEN	Start up application in full-screen mode
AG_VIDEO_RESIZABLE	If a window manager is available, request that the application be resizable.
AG_VIDEO_NOFRAME	If a window manager is available, disable window decorations.
AG_VIDEO_BGPOPUPMENU	Whenever the user right-clicks on an area not covered by an Agar window, display a standard pop-up menu with the list of active windows.
AG_VIDEO_OPENGL	Require OpenGL mode. If OpenGL is not available, initialization will fail.
AG_VIDEO_OPENGL_OR_SDL	Try OpenGL mode if available, otherwise fallback to SDL frame-buffer mode.
AG_VIDEO_OVERLAY	Run in OpenGL "overlay" mode. In this mode, Agar will never clear the background of the application or swap the GL buffers.

HISTORY

The AG_InitVideo() function first appeared in Agar 1.0. The driver system (see AG_Driver(3)) and the AG_InitGraphics function first appeared in Agar 1.4.0.