.\" Copyright (c) 2010-2023 Julien Nadeau Carriere <vedge@csoft.net>
.\" 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 February 18, 2023
.Dt AG_INITGRAPHICS 3
.Os Agar 1.7
.Sh NAME
.Nm AG_InitGraphics
.Nd agar GUI initialization
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(/widgets/AG_DriverGLX.png, "The Xorg/glx driver")
After having initialized the Agar-Core library with
.Xr AG_InitCore 3 ,
Agar-GUI applications must initialize the GUI system.
.Sh AVAILABLE DRIVERS
As of Agar 1.7.0, the standard drivers included in the distribution are:
.Pp
.Bl -tag -width "AG_DriverSDL2MW(3) " -compact
.It Xr AG_DriverCocoa 3
(-d "cocoa")
MacOS X with OpenGL.
Multi-window.
.It Xr AG_DriverDUMMY 3
(-d "dummy")
No-op (prints to the debug console).
.It Xr AG_DriverGLX 3
(-d "glx")
X Windows with OpenGL.
Multi-window.
.It Xr AG_DriverSDLFB 3
(-d "sdlfb")
SDL1 with framebuffer.
Single-window.
.It Xr AG_DriverSDLGL 3
(-d "sdlgl")
SDL1 with OpenGL.
Single-window.
.It Xr AG_DriverSDL2FB 3
(-d "sdl2fb")
SDL2 with framebuffer.
Single-window.
Game controllers and joysticks are supported.
.It Xr AG_DriverSDL2GL 3
(-d "sdl2gl")
SDL2 with OpenGL.
Single-window.
Game controllers and joysticks are supported.
.It Xr AG_DriverSDL2MW 3
(-d "sdl2mw")
SDL2 with OpenGL.
Multi-window.
Game controllers and joysticks are supported.
.It Xr AG_DriverWGL 3
(-d "wgl")
MS Windows with OpenGL.
Multi-window.
.El
.Sh INITIALIZATION
.nr nS 1
.Ft "int"
.Fn AG_InitGraphics "const char *drivers"
.Pp
.Ft "void"
.Fn AG_DestroyGraphics "void"
.Pp
.Ft "int"
.Fn AG_InitGUI "Uint flags"
.Pp
.Ft "void"
.Fn AG_DestroyGUI "void"
.Pp
.nr nS 0
The
.Fn AG_InitGraphics
function initializes the Agar GUI system.
If the
.Fa drivers
argument is NULL (the usual case), Agar selects the "best" driver available
on the current platform.
If
.Fa drivers
is non-NULL, it should be a comma-separated list of drivers in order of
preference.
Special selectors are available to include drivers based on capabilities.
"<OpenGL>" selects any driver with support for OpenGL 1.1 or later.
"<SDL>" any driver based on SDL1, "<SDL2>" any driver based on SDL2
and "<FB>" any driver based on a software framebuffer.
.Pp
The full list of compiled-in drivers may be obtained by calling
.Xr AG_ListDriverNames 3 .
Driver-specific parameters may be specified as a colon-separated list
enclosed in parentheses.
The available options are documented on the driver's respective manual page.
Some examples:
.Bd -literal
sdlgl,sdlfb
<SDL>(width=640:height=480:depth=32)
<SDL2>(width=640:height=480)
<openGL>(stereo=1)
.Ed
.Pp
It is recommended that applications provide a way for the user to specify
alternate drivers, for example
.Xr agartest 1
accepts the
.Op Fl d Ar agar-driver
command-line arguments.
.Pp
The
.Fn AG_DestroyGraphics
routine shuts down and releases all resources allocated by the Agar-GUI
library.
.Pp
Alternatively, the
.Fn AG_InitGUI
function initializes the Agar GUI system, but does not create a driver instance
upon initialization.
The caller may invoke
.Xr AG_DriverOpen 3
to create one or more driver instances.
For example, an X11 application that can talk to multiple X11 servers might call
.Fn AG_DriverOpen
for each X11 connection.
.Sh SEE ALSO
.Xr AG_Core 3 ,
.Xr AG_CustomEventLoop 3 ,
.Xr AG_Driver 3 ,
.Xr AG_EventLoop 3 ,
.Xr AG_InitVideoSDL 3 ,
.Xr AG_Intro 3
.Sh HISTORY
An
.Fn AG_InitVideo
function first appeared in Agar 1.0.
It was replaced by
.Fn AG_InitGraphics
in Agar 1.4.0.